# fezairoumaissa100/multi-agent-threat-hunting-system architecture

> Architecture diagram of the GitHub repository fezairoumaissa100/multi-agent-threat-hunting-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fezairoumaissa100/multi-agent-threat-hunting-system
- Repository: https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system

## Overview

This is a Wazuh threat-hunting application: an alert enters a FastAPI/LangGraph investigation, which gathers historical context, conditionally hunts raw logs, and produces a correlated report and risk score. The Next.js dashboard submits alerts and displays streamed progress and results. OpenSearch access is mediated by MCP tools; threat-intelligence checks are an optional capability. The graph follows documented workflow and API relationships; unsampled implementation details are not expanded beyond README-backed capabilities.

Main entry points: [`graph/workflow.py`](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/graph/workflow.py) (LangGraph workflow), [`pfainterface/app/page.tsx`](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/pfainterface/app/page.tsx) (Investigation dashboard), [`mcp/server.py`](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/mcp/server.py) (MCP tool server), [`agents/agent3_context_round1.py`](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/agents/agent3_context_round1.py) (Alert history search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and workflow"]
  node_api_server["FastAPI endpoints<br/>[api_server.py]"]
  node_workflow["LangGraph workflow<br/>[workflow.py]"]
  node_state["Shared SOC state<br/>[state.py]"]
end

subgraph group_investigation["Investigation agents"]
  node_mapping["Index mapping<br/>[agent2_mapping.py]"]
  node_context["Context questions"]
  node_alert_search["Alert history search"]
  node_pattern_analysis["Pattern analysis"]
  node_archive_hunt["Archive hunting<br/>[agent3_hunting.py]"]
  node_correlation["Evidence correlation"]
  node_report["Investigation report<br/>[report_template.md]"]
end

subgraph group_integrations["Data and integrations"]
  node_mcp_server["MCP tool server<br/>[server.py]"]
  node_search_tools["OpenSearch tools"]
  node_os_client["OpenSearch client<br/>[mcp_client.py]"]
  node_opensearch[("OpenSearch")]
  node_intel_tools["Threat intelligence tools"]
end

subgraph group_dashboard["Analyst dashboard"]
  node_dashboard["Investigation dashboard<br/>[page.tsx]"]
  node_alert_input["Alert input<br/>[alert-input.tsx]"]
  node_api_proxy["Next API routes<br/>[route.ts]"]
  node_pipeline_view["Pipeline progress view<br/>[agent-pipeline.tsx]"]
  node_pipeline_node["Pipeline stage display<br/>[pipeline-node.tsx]"]
  node_handoff["State handoffs"]
  node_risk_gauge["Risk gauge<br/>[risk-gauge.tsx]"]
end

node_analyst(("SOC analyst"))
node_threat_intel{{"AbuseIPDB / VirusTotal"}}

node_analyst -->|"submits alert"| node_dashboard
node_dashboard -->|"accepts alert"| node_alert_input
node_dashboard -->|"requests analysis"| node_api_proxy
node_api_proxy -->|"HTTP and SSE"| node_api_server
node_api_server -->|"starts workflow"| node_workflow
node_workflow -->|"runs first"| node_mapping
node_workflow -->|"runs next"| node_context
node_workflow -->|"runs search"| node_alert_search
node_workflow -->|"analyzes context"| node_pattern_analysis
node_workflow -->|"conditionally runs"| node_archive_hunt
node_workflow -->|"correlates evidence"| node_correlation
node_context -->|"provides questions"| node_alert_search
node_alert_search -->|"provides findings"| node_pattern_analysis
node_pattern_analysis -->|"provides hunt questions"| node_archive_hunt
node_pattern_analysis -->|"sets round decision"| node_workflow
node_archive_hunt -->|"provides evidence"| node_correlation
node_correlation -->|"formats report"| node_report
node_mapping -->|"loads mappings"| node_mcp_server
node_alert_search -->|"calls search tool"| node_mcp_server
node_archive_hunt -->|"queries archive"| node_mcp_server
node_mcp_server -->|"registers tools"| node_search_tools
node_search_tools -->|"gets client"| node_os_client
node_os_client -.->|"connects to"| node_opensearch
node_mcp_server -->|"registers tools"| node_intel_tools
node_intel_tools -.->|"checks reputation"| node_threat_intel
node_workflow -->|"uses shared state"| node_state
node_dashboard -->|"renders progress"| node_pipeline_view
node_pipeline_view -->|"renders stages"| node_pipeline_node
node_pipeline_view -->|"renders handoffs"| node_handoff
node_dashboard -->|"shows score"| node_risk_gauge
node_api_server -->|"streams events"| node_dashboard

click node_dashboard "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/pfainterface/app/page.tsx"
click node_alert_input "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/pfainterface/components/dashboard/alert-input.tsx"
click node_api_proxy "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/pfainterface/app/api/analyse/route.ts"
click node_api_server "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/api_server.py"
click node_workflow "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/graph/workflow.py"
click node_state "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/graph/state.py"
click node_mapping "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/agents/agent2_mapping.py"
click node_context "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/agents/agent1_investigation_v2.py"
click node_alert_search "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/agents/agent3_context_round1.py"
click node_pattern_analysis "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/agents/agent1_investigation_v2.py"
click node_archive_hunt "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/agents/agent3_hunting.py"
click node_correlation "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/agents/agent4_correlation.py"
click node_report "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/prompts/report_template.md"
click node_mcp_server "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/mcp/server.py"
click node_search_tools "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/mcp/opensearch_tools.py"
click node_os_client "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/mcp/mcp_client.py"
click node_intel_tools "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/mcp/threat_intel_tools.py"
click node_pipeline_view "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/pfainterface/components/dashboard/agent-pipeline.tsx"
click node_pipeline_node "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/pfainterface/components/dashboard/pipeline-node.tsx"
click node_handoff "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/pfainterface/components/dashboard/pipeline-handoff.tsx"
click node_risk_gauge "https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/pfainterface/components/dashboard/risk-gauge.tsx"

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_api_server,node_workflow,node_state toneBlue
class node_mapping,node_context,node_alert_search,node_pattern_analysis,node_archive_hunt,node_correlation,node_report toneAmber
class node_mcp_server,node_search_tools,node_os_client,node_opensearch,node_intel_tools toneMint
class node_dashboard,node_alert_input,node_api_proxy,node_pipeline_view,node_pipeline_node,node_handoff,node_risk_gauge toneRose
class node_analyst,node_threat_intel toneIndigo
```

## Components

### API and workflow

- [FastAPI endpoints](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/api_server.py): `api_server.py`
- [LangGraph workflow](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/graph/workflow.py): `graph/workflow.py`
- [Shared SOC state](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/graph/state.py): `graph/state.py`

### Investigation agents

- [Index mapping](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/agents/agent2_mapping.py): `agents/agent2_mapping.py`
- [Context questions](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/agents/agent1_investigation_v2.py): `agents/agent1_investigation_v2.py`
- [Alert history search](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/agents/agent3_context_round1.py): `agents/agent3_context_round1.py`
- [Pattern analysis](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/agents/agent1_investigation_v2.py): `agents/agent1_investigation_v2.py`
- [Archive hunting](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/agents/agent3_hunting.py): `agents/agent3_hunting.py`
- [Evidence correlation](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/agents/agent4_correlation.py): `agents/agent4_correlation.py`
- [Investigation report](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/prompts/report_template.md): `prompts/report_template.md`

### Data and integrations

- [MCP tool server](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/mcp/server.py): `mcp/server.py`
- [OpenSearch tools](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/mcp/opensearch_tools.py): `mcp/opensearch_tools.py`
- [OpenSearch client](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/mcp/mcp_client.py): `mcp/mcp_client.py`
- **OpenSearch**
- [Threat intelligence tools](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/mcp/threat_intel_tools.py): `mcp/threat_intel_tools.py`

### Analyst dashboard

- [Investigation dashboard](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/pfainterface/app/page.tsx): `pfainterface/app/page.tsx`
- [Alert input](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/pfainterface/components/dashboard/alert-input.tsx): `pfainterface/components/dashboard/alert-input.tsx`
- [Next API routes](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/pfainterface/app/api/analyse/route.ts): `pfainterface/app/api/analyse/route.ts`
- [Pipeline progress view](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/pfainterface/components/dashboard/agent-pipeline.tsx): `pfainterface/components/dashboard/agent-pipeline.tsx`
- [Pipeline stage display](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/pfainterface/components/dashboard/pipeline-node.tsx): `pfainterface/components/dashboard/pipeline-node.tsx`
- [State handoffs](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/pfainterface/components/dashboard/pipeline-handoff.tsx): `pfainterface/components/dashboard/pipeline-handoff.tsx`
- [Risk gauge](https://github.com/fezairoumaissa100/multi-agent-threat-hunting-system/blob/main/pfainterface/components/dashboard/risk-gauge.tsx): `pfainterface/components/dashboard/risk-gauge.tsx`

### Other components

- **SOC analyst**
- **AbuseIPDB / VirusTotal**

## Connections

- SOC analyst → Investigation dashboard: submits alert (evidence: `README.md`)
- Investigation dashboard → Alert input: accepts alert (evidence: `README.md`)
- Investigation dashboard → Next API routes: requests analysis (evidence: `README.md`)
- Next API routes → FastAPI endpoints: HTTP and SSE (evidence: `README.md`)
- FastAPI endpoints → LangGraph workflow: starts workflow (evidence: `README.md`)
- LangGraph workflow → Index mapping: runs first (evidence: `graph/workflow.py`)
- LangGraph workflow → Context questions: runs next (evidence: `graph/workflow.py`)
- LangGraph workflow → Alert history search: runs search (evidence: `graph/workflow.py`)
- LangGraph workflow → Pattern analysis: analyzes context (evidence: `graph/workflow.py`)
- LangGraph workflow → Archive hunting: conditionally runs (evidence: `graph/workflow.py`)
- LangGraph workflow → Evidence correlation: correlates evidence (evidence: `graph/workflow.py`)
- Context questions → Alert history search: provides questions (evidence: `README.md`)
- Alert history search → Pattern analysis: provides findings (evidence: `README.md`)
- Pattern analysis → Archive hunting: provides hunt questions (evidence: `README.md`)
- Pattern analysis → LangGraph workflow: sets round decision (evidence: `graph/workflow.py`)
- Archive hunting → Evidence correlation: provides evidence (evidence: `README.md`)
- Evidence correlation → Investigation report: formats report (evidence: `README.md`)
- Index mapping → MCP tool server: loads mappings (evidence: `README.md`)
- Alert history search → MCP tool server: calls search tool (evidence: `agents/agent3_context_round1.py`)
- Archive hunting → MCP tool server: queries archive (evidence: `README.md`)
- MCP tool server → OpenSearch tools: registers tools (evidence: `mcp/server.py`)
- OpenSearch tools → OpenSearch client: gets client (evidence: `mcp/opensearch_tools.py`)
- OpenSearch client → OpenSearch: connects to
- MCP tool server → Threat intelligence tools: registers tools (evidence: `mcp/server.py`)
- Threat intelligence tools → AbuseIPDB / VirusTotal: checks reputation (evidence: `README.md`)
- LangGraph workflow → Shared SOC state: uses shared state (evidence: `graph/workflow.py`)
- Investigation dashboard → Pipeline progress view: renders progress (evidence: `README.md`)
- Pipeline progress view → Pipeline stage display: renders stages (evidence: `pfainterface/components/dashboard/agent-pipeline.tsx`)
- Pipeline progress view → State handoffs: renders handoffs (evidence: `pfainterface/components/dashboard/agent-pipeline.tsx`)
- Investigation dashboard → Risk gauge: shows score (evidence: `README.md`)
- FastAPI endpoints → Investigation dashboard: streams events (evidence: `README.md`)
