# 7yph0n/ai-driven-soc-investigator architecture

> Architecture diagram of the GitHub repository 7yph0n/ai-driven-soc-investigator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/7yph0n/ai-driven-soc-investigator
- Repository: https://github.com/7yph0n/ai-driven-soc-investigator

## Overview

This is an AI-assisted SOC investigation pipeline. It polls Wazuh alerts, then iterates between LLM decisions and controlled endpoint tools until it reaches a verdict; on conclusion it writes a report and creates an osTicket incident. The map preserves alert intake, investigation and evidence collection, shared state, and reporting/ticketing. Tool excerpts show Velociraptor collection details, but not every action tool; those capabilities are represented at the tools module without asserting its unsampled internal calls.

Main entry points: [`core.py`](https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/core.py) (Investigation Loop), [`Agents/parser.py`](https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/Agents/parser.py) (Decision Parser), [`state_manager.py`](https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/state_manager.py) (Investigation State), [`wazuh_poller_backend.py`](https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/wazuh_poller_backend.py) (Alert Poller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Alert Intake"]
  node_entry["SOC Entrypoint<br/>[main.py]"]
  node_poller["Alert Poller"]
end

subgraph group_investigation["AI Investigation"]
  node_orchestrator["Investigation Loop<br/>[core.py]"]
  node_prompting["Investigation Prompts<br/>[prompts.py]"]
  node_llm["LLM Reasoning<br/>[LLM.py]"]
  node_state[("Investigation State<br/>[state_manager.py]")]
  node_parser["Decision Parser<br/>[parser.py]"]
end

subgraph group_evidence["Endpoint Evidence"]
  node_tools["Investigation Tools<br/>[tools.py]"]
end

subgraph group_outcomes["Incident Outcomes"]
  node_report["Report Generator"]
  node_ticket["Ticket Creator<br/>[ticket_raiser.py]"]
end

node_wazuh[("Wazuh Indexer")]
node_velociraptor[("Velociraptor")]
node_osticket[("osTicket")]

node_entry -->|"starts"| node_orchestrator
node_orchestrator -->|"gets alerts"| node_poller
node_poller -->|"queries alerts"| node_wazuh
node_orchestrator -->|"builds prompts"| node_prompting
node_orchestrator -->|"updates state"| node_state
node_orchestrator -->|"requests analysis"| node_llm
node_llm -->|"reads state"| node_state
node_orchestrator -->|"dispatches decisions"| node_parser
node_parser -->|"records evidence"| node_state
node_parser -->|"executes tool"| node_tools
node_tools -->|"collects evidence"| node_velociraptor
node_orchestrator -->|"writes report"| node_report
node_orchestrator -->|"creates incident"| node_ticket
node_ticket -->|"posts ticket"| node_osticket

click node_entry "https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/main.py"
click node_poller "https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/wazuh_poller_backend.py"
click node_orchestrator "https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/core.py"
click node_prompting "https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/prompts.py"
click node_llm "https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/Agents/LLM.py"
click node_state "https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/state_manager.py"
click node_parser "https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/Agents/parser.py"
click node_tools "https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/Tools/tools.py"
click node_report "https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/report_generator.py"
click node_ticket "https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/Agents/ticket_raiser.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_entry,node_poller toneBlue
class node_orchestrator,node_prompting,node_llm,node_state,node_parser,node_wazuh,node_velociraptor,node_osticket toneAmber
class node_tools toneMint
class node_report,node_ticket toneRose
```

## Components

### Alert Intake

- [SOC Entrypoint](https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/main.py): `main.py`
- [Alert Poller](https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/wazuh_poller_backend.py): `wazuh_poller_backend.py`

### AI Investigation

- [Investigation Loop](https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/core.py): `core.py`
- [Investigation Prompts](https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/prompts.py): `prompts.py`
- [LLM Reasoning](https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/Agents/LLM.py): `Agents/LLM.py`
- [Investigation State](https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/state_manager.py): `state_manager.py`
- [Decision Parser](https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/Agents/parser.py): `Agents/parser.py`

### Endpoint Evidence

- [Investigation Tools](https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/Tools/tools.py): `Tools/tools.py`

### Incident Outcomes

- [Report Generator](https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/report_generator.py): `report_generator.py`
- [Ticket Creator](https://github.com/7yph0n/ai-driven-soc-investigator/blob/main/Agents/ticket_raiser.py): `Agents/ticket_raiser.py`

### Other components

- **Wazuh Indexer**
- **Velociraptor**
- **osTicket**

## Connections

- SOC Entrypoint → Investigation Loop: starts (evidence: `main.py`)
- Investigation Loop → Alert Poller: gets alerts (evidence: `core.py`)
- Alert Poller → Wazuh Indexer: queries alerts (evidence: `wazuh_poller_backend.py`)
- Investigation Loop → Investigation Prompts: builds prompts (evidence: `core.py`)
- Investigation Loop → Investigation State: updates state (evidence: `core.py`)
- Investigation Loop → LLM Reasoning: requests analysis (evidence: `core.py`)
- LLM Reasoning → Investigation State: reads state (evidence: `Agents/LLM.py`)
- Investigation Loop → Decision Parser: dispatches decisions (evidence: `core.py`)
- Decision Parser → Investigation State: records evidence (evidence: `Agents/parser.py`)
- Decision Parser → Investigation Tools: executes tool (evidence: `Agents/parser.py`)
- Investigation Tools → Velociraptor: collects evidence (evidence: `Tools/tools.py`)
- Investigation Loop → Report Generator: writes report (evidence: `core.py`)
- Investigation Loop → Ticket Creator: creates incident (evidence: `core.py`)
- Ticket Creator → osTicket: posts ticket (evidence: `Agents/ticket_raiser.py`)
