# smartdata-polito/cybersleuth_forensic_agent architecture

> Architecture diagram of the GitHub repository smartdata-polito/cybersleuth_forensic_agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smartdata-polito/cybersleuth_forensic_agent
- Repository: https://github.com/smartdata-polito/cybersleuth_forensic_agent

## Overview

Flow Reporter Agent analyzes PCAP events, summarizes TCP flows, then lets a tool-using LangGraph agent research findings and produce a structured forensic report. The benchmark runners initiate event processing; the graph runs flow analysis before the main reasoning loop. Web retrieval, semantic memory, and report formatting are distinct capabilities. Edges are limited to README statements and shown excerpts or SOURCE INDEX references; the separate TShark-expert module has no demonstrated connection to this branch’s graph.

Main entry points: [`src/multi_agent/main_agent/graph.py`](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/graph.py) (Workflow graph), [`src/multi_agent/main_agent/nodes/pcap_flows_reporter.py`](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/nodes/pcap_flows_reporter.py) (Flow reporter), [`src/multi_agent/main_agent/nodes/main_agent.py`](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/nodes/main_agent.py) (Reasoning agent), [`src/browser/online_browser.py`](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/browser/online_browser.py) (Web search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Event analysis"]
  node_benchmark["Benchmark runner<br/>[run_agent.py]"]
  node_web_runner["Web-event runner"]
  node_pcap["PCAP datasets"]
  node_flow_reporter["Flow reporter"]
  node_pcap_tools["PCAP tools"]
  node_flow_analyzer["TCP flow analyzer"]
  node_flow_utils["Flow extraction<br/>[utils.py]"]
  node_tshark_agent["TShark expert tool<br/>[tshark_agent.py]"]
end

subgraph group_agent["Agent orchestration"]
  node_config["Agent settings<br/>[configuration.py]"]
  node_graph["Workflow graph<br/>[graph.py]"]
  node_state["Shared state<br/>[global_state.py]"]
  node_main_agent["Reasoning agent<br/>[main_agent.py]"]
  node_router["Tool-call router<br/>[router.py]"]
  node_tool_executor["Tool executor<br/>[tools.py]"]
end

subgraph group_research["Research and memory"]
  node_web_search["Web search<br/>[online_browser.py]"]
  node_chunking["Document chunking<br/>[chunking_utils.py]"]
  node_summarization["Search summarization"]
  node_search_prompts["Search prompts<br/>[prompts.py]"]
  node_memory_tool["Memory upsert<br/>[upsert_memory.py]"]
end

subgraph group_report["Reporting"]
  node_formatter["Final report formatter<br/>[final_report.py]"]
  node_log_reporter["Log reporter<br/>[log_reporter.py]"]
end

node_analyst(("Analyst"))
node_tshark["TShark"]
node_google["Google Search API"]
node_websites["Web pages"]
node_memory_store[("Semantic memory store")]
node_log_files["Event logs"]

node_analyst -->|"runs benchmark"| node_benchmark
node_analyst -->|"runs web test"| node_web_runner
node_benchmark -->|"builds workflow"| node_graph
node_web_runner -->|"builds workflow"| node_graph
node_benchmark -->|"selects event PCAP"| node_pcap
node_web_runner -->|"selects event PCAP"| node_pcap
node_graph -->|"starts with"| node_flow_reporter
node_graph -->|"then invokes"| node_main_agent
node_graph -->|"dispatches tools"| node_tool_executor
node_graph -->|"routes messages"| node_router
node_flow_reporter -->|"reads event state"| node_state
node_main_agent -->|"reads conversation"| node_state
node_flow_reporter -->|"generates summary"| node_pcap_tools
node_flow_reporter -->|"analyzes flows"| node_flow_analyzer
node_flow_reporter -->|"extracts flow text"| node_flow_utils
node_flow_utils -->|"runs capture commands"| node_tshark
node_main_agent -->|"summarizes capture"| node_pcap_tools
node_main_agent -->|"searches memories"| node_memory_store
node_main_agent -->|"loads settings"| node_config
node_tool_executor -->|"executes upserts"| node_memory_tool
node_memory_tool -->|"writes memories"| node_memory_store
node_tool_executor -->|"runs search"| node_web_search
node_web_search -->|"queries API"| node_google
node_web_search -->|"fetches pages"| node_websites
node_web_search -->|"chunks documents"| node_chunking
node_web_search -->|"summarizes results"| node_summarization
node_summarization -->|"uses prompts"| node_search_prompts
node_tool_executor -->|"formats final answer"| node_formatter
node_analyst -.->|"optional expert analysis"| node_tshark_agent
node_graph -.->|"optional log analysis"| node_log_reporter
node_log_reporter -->|"reads event logs"| node_log_files

click node_benchmark "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/run_agent.py"
click node_web_runner "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/run_agent_web_events.py"
click node_pcap "https://github.com/smartdata-polito/cybersleuth_forensic_agent/tree/main/data"
click node_config "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/configuration.py"
click node_graph "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/graph.py"
click node_state "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/common/global_state.py"
click node_flow_reporter "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/nodes/pcap_flows_reporter.py"
click node_pcap_tools "https://github.com/smartdata-polito/cybersleuth_forensic_agent/tree/main/src/multi_agent/main_agent/tools/pcap"
click node_flow_analyzer "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/pcap_flow_analyzer/pcap_flow_analyzer.py"
click node_flow_utils "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/common/utils.py"
click node_main_agent "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/nodes/main_agent.py"
click node_router "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/nodes/router.py"
click node_tool_executor "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/nodes/tools.py"
click node_web_search "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/browser/online_browser.py"
click node_chunking "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/browser/chunking_utils.py"
click node_summarization "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/browser/summarization_utils.py"
click node_search_prompts "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/browser/prompts.py"
click node_memory_tool "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/tools/memory/upsert_memory.py"
click node_formatter "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/tools/report/final_report.py"
click node_tshark_agent "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/tools/tshark_expert_tool/tshark_agent.py"
click node_log_reporter "https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/log_reporter/log_reporter.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_benchmark,node_web_runner,node_pcap,node_flow_reporter,node_pcap_tools,node_flow_analyzer,node_flow_utils,node_tshark_agent toneBlue
class node_config,node_graph,node_state,node_main_agent,node_router,node_tool_executor,node_memory_store toneAmber
class node_web_search,node_chunking,node_summarization,node_search_prompts,node_memory_tool,node_google toneMint
class node_formatter,node_log_reporter toneRose
class node_analyst,node_tshark,node_websites,node_log_files toneIndigo
```

## Components

### Event analysis

- [Benchmark runner](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/run_agent.py): `src/run_agent.py`
- [Web-event runner](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/run_agent_web_events.py): `src/run_agent_web_events.py`
- [PCAP datasets](https://github.com/smartdata-polito/cybersleuth_forensic_agent/tree/main/data): `data`
- [Flow reporter](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/nodes/pcap_flows_reporter.py): `src/multi_agent/main_agent/nodes/pcap_flows_reporter.py`
- [PCAP tools](https://github.com/smartdata-polito/cybersleuth_forensic_agent/tree/main/src/multi_agent/main_agent/tools/pcap): `src/multi_agent/main_agent/tools/pcap`
- [TCP flow analyzer](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/pcap_flow_analyzer/pcap_flow_analyzer.py): `src/multi_agent/pcap_flow_analyzer/pcap_flow_analyzer.py`
- [Flow extraction](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/common/utils.py): `src/multi_agent/common/utils.py`
- [TShark expert tool](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/tools/tshark_expert_tool/tshark_agent.py): `src/multi_agent/main_agent/tools/tshark_expert_tool/tshark_agent.py`

### Agent orchestration

- [Agent settings](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/configuration.py): `src/configuration.py`
- [Workflow graph](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/graph.py): `src/multi_agent/main_agent/graph.py`
- [Shared state](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/common/global_state.py): `src/multi_agent/common/global_state.py`
- [Reasoning agent](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/nodes/main_agent.py): `src/multi_agent/main_agent/nodes/main_agent.py`
- [Tool-call router](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/nodes/router.py): `src/multi_agent/main_agent/nodes/router.py`
- [Tool executor](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/nodes/tools.py): `src/multi_agent/main_agent/nodes/tools.py`

### Research and memory

- [Web search](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/browser/online_browser.py): `src/browser/online_browser.py`
- [Document chunking](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/browser/chunking_utils.py): `src/browser/chunking_utils.py`
- [Search summarization](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/browser/summarization_utils.py): `src/browser/summarization_utils.py`
- [Search prompts](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/browser/prompts.py): `src/browser/prompts.py`
- [Memory upsert](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/tools/memory/upsert_memory.py): `src/multi_agent/main_agent/tools/memory/upsert_memory.py`

### Reporting

- [Final report formatter](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/main_agent/tools/report/final_report.py): `src/multi_agent/main_agent/tools/report/final_report.py`
- [Log reporter](https://github.com/smartdata-polito/cybersleuth_forensic_agent/blob/main/src/multi_agent/log_reporter/log_reporter.py): `src/multi_agent/log_reporter/log_reporter.py`

### Other components

- **Analyst**
- **TShark**
- **Google Search API**
- **Web pages**
- **Semantic memory store**
- **Event logs**

## Connections

- Analyst → Benchmark runner: runs benchmark (evidence: `README.md`)
- Analyst → Web-event runner: runs web test (evidence: `README.md`)
- Benchmark runner → Workflow graph: builds workflow (evidence: `src/run_agent.py`)
- Web-event runner → Workflow graph: builds workflow (evidence: `src/run_agent_web_events.py`)
- Benchmark runner → PCAP datasets: selects event PCAP (evidence: `README.md`)
- Web-event runner → PCAP datasets: selects event PCAP (evidence: `README.md`)
- Workflow graph → Flow reporter: starts with (evidence: `src/multi_agent/main_agent/graph.py`)
- Workflow graph → Reasoning agent: then invokes (evidence: `src/multi_agent/main_agent/graph.py`)
- Workflow graph → Tool executor: dispatches tools (evidence: `src/multi_agent/main_agent/graph.py`)
- Workflow graph → Tool-call router: routes messages (evidence: `src/multi_agent/main_agent/graph.py`)
- Flow reporter → Shared state: reads event state (evidence: `src/multi_agent/main_agent/nodes/pcap_flows_reporter.py`)
- Reasoning agent → Shared state: reads conversation (evidence: `src/multi_agent/main_agent/nodes/main_agent.py`)
- Flow reporter → PCAP tools: generates summary (evidence: `src/multi_agent/main_agent/nodes/pcap_flows_reporter.py`)
- Flow reporter → TCP flow analyzer: analyzes flows (evidence: `src/multi_agent/main_agent/nodes/pcap_flows_reporter.py`)
- Flow reporter → Flow extraction: extracts flow text (evidence: `src/multi_agent/main_agent/nodes/pcap_flows_reporter.py`)
- Flow extraction → TShark: runs capture commands (evidence: `src/multi_agent/common/utils.py`)
- Reasoning agent → PCAP tools: summarizes capture (evidence: `src/multi_agent/main_agent/nodes/main_agent.py`)
- Reasoning agent → Semantic memory store: searches memories (evidence: `src/multi_agent/main_agent/nodes/main_agent.py`)
- Reasoning agent → Agent settings: loads settings (evidence: `src/multi_agent/main_agent/nodes/main_agent.py`)
- Tool executor → Memory upsert: executes upserts (evidence: `src/multi_agent/main_agent/nodes/tools.py`)
- Memory upsert → Semantic memory store: writes memories (evidence: `src/multi_agent/main_agent/tools/memory/upsert_memory.py`)
- Tool executor → Web search: runs search (evidence: `src/multi_agent/main_agent/nodes/tools.py`)
- Web search → Google Search API: queries API (evidence: `src/browser/online_browser.py`)
- Web search → Web pages: fetches pages (evidence: `src/browser/online_browser.py`)
- Web search → Document chunking: chunks documents (evidence: `src/browser/online_browser.py`)
- Web search → Search summarization: summarizes results (evidence: `src/browser/online_browser.py`)
- Search summarization → Search prompts: uses prompts (evidence: `src/browser/summarization_utils.py`)
- Tool executor → Final report formatter: formats final answer (evidence: `src/multi_agent/main_agent/nodes/tools.py`)
- Analyst → TShark expert tool: optional expert analysis
- Workflow graph → Log reporter: optional log analysis (evidence: `src/multi_agent/main_agent/graph.py`)
- Log reporter → Event logs: reads event logs (evidence: `src/multi_agent/log_reporter/log_reporter.py`)
