# utpaat0xsabir/ai-soc-agent architecture

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

- Interactive diagram: https://gitdiagram.com/utpaat0xsabir/ai-soc-agent
- Repository: https://github.com/utpaat0xsabir/ai-soc-agent

## Overview

This repository implements a Wazuh-focused SOC investigation toolkit. Analysts retrieve alerts, correlate them into incidents and service campaigns, investigate evidence (including host-service outcomes and ATT&CK mappings), and generate reports; a separate tool provides single-alert AI analysis. The graph preserves the documented remote SSH evidence path. The README is empty, and sampled excerpts do not expose every orchestration call, so some subsystem links are omitted rather than inferred.

Main entry points: [`incident_investigator.py`](https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/incident_investigator.py) (Incident Investigation), [`wazuh_client.py`](https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/wazuh_client.py) (Alert Retrieval), [`remote_evidence_collector.py`](https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/remote_evidence_collector.py) (Remote Evidence Collection), [`correlation_engine.py`](https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/correlation_engine.py) (Incident Correlation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Alert Collection"]
  node_alert_client["Alert Retrieval<br/>[wazuh_client.py]"]
end

subgraph group_analysis["Correlation and Investigation"]
  node_correlation["Incident Correlation"]
  node_investigation["Incident Investigation"]
  node_outcome["Outcome Verification"]
  node_attack_mapping["ATT&amp;CK Mapping"]
end

subgraph group_evidence["Host Evidence"]
  node_local_evidence["Local Host Evidence"]
  node_remote_collector["Remote Evidence Collection"]
end

subgraph group_presentation["AI and Reporting"]
  node_alert_ai["Single-Alert AI Analysis<br/>[wazuh_ai.py]"]
  node_campaign_ai["Investigation AI Interpretation"]
  node_report["Report Generation"]
end

node_analyst(("SOC Analyst"))
node_wazuh[("Wazuh Indexer")]
node_remote_host(("Monitored Host"))
node_ollama["Ollama"]

node_analyst -->|"initiates investigation"| node_investigation
node_analyst -->|"requests alert analysis"| node_alert_ai
node_wazuh -->|"returns alerts"| node_alert_client
node_investigation -->|"retrieves alerts"| node_alert_client
node_investigation -->|"correlates alerts"| node_correlation
node_correlation -->|"uses client"| node_alert_client
node_investigation -.->|"collects host evidence"| node_local_evidence
node_investigation -->|"verifies outcomes"| node_outcome
node_investigation -->|"maps techniques"| node_attack_mapping
node_remote_collector -->|"collects over SSH"| node_remote_host
node_remote_collector -->|"supplies evidence"| node_investigation
node_alert_ai -->|"requests inference"| node_ollama
node_campaign_ai -.->|"requests inference"| node_ollama
node_investigation -->|"generates report"| node_report

click node_alert_client "https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/wazuh_client.py"
click node_correlation "https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/correlation_engine.py"
click node_investigation "https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/incident_investigator.py"
click node_outcome "https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/incident_investigator.py"
click node_attack_mapping "https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/incident_investigator.py"
click node_local_evidence "https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/incident_investigator.py"
click node_remote_collector "https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/remote_evidence_collector.py"
click node_alert_ai "https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/wazuh_ai.py"
click node_campaign_ai "https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/incident_investigator.py"
click node_report "https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/report_generator.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_alert_client toneBlue
class node_correlation,node_investigation,node_outcome,node_attack_mapping,node_wazuh toneAmber
class node_local_evidence,node_remote_collector toneMint
class node_alert_ai,node_campaign_ai,node_report toneRose
class node_analyst,node_remote_host,node_ollama toneIndigo
```

## Components

### Alert Collection

- [Alert Retrieval](https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/wazuh_client.py): `wazuh_client.py`

### Correlation and Investigation

- [Incident Correlation](https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/correlation_engine.py): `correlation_engine.py`
- [Incident Investigation](https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/incident_investigator.py): `incident_investigator.py`
- [Outcome Verification](https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/incident_investigator.py): `incident_investigator.py`
- [ATT&CK Mapping](https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/incident_investigator.py): `incident_investigator.py`

### Host Evidence

- [Local Host Evidence](https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/incident_investigator.py): `incident_investigator.py`
- [Remote Evidence Collection](https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/remote_evidence_collector.py): `remote_evidence_collector.py`

### AI and Reporting

- [Single-Alert AI Analysis](https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/wazuh_ai.py): `wazuh_ai.py`
- [Investigation AI Interpretation](https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/incident_investigator.py): `incident_investigator.py`
- [Report Generation](https://github.com/utpaat0xsabir/ai-soc-agent/blob/main/report_generator.py): `report_generator.py`

### Other components

- **SOC Analyst**
- **Wazuh Indexer**
- **Monitored Host**
- **Ollama**

## Connections

- SOC Analyst → Incident Investigation: initiates investigation (evidence: `incident_investigator.py`)
- SOC Analyst → Single-Alert AI Analysis: requests alert analysis (evidence: `wazuh_ai.py`)
- Wazuh Indexer → Alert Retrieval: returns alerts (evidence: `wazuh_client.py`)
- Incident Investigation → Alert Retrieval: retrieves alerts (evidence: `incident_investigator.py`)
- Incident Investigation → Incident Correlation: correlates alerts (evidence: `incident_investigator.py`)
- Incident Correlation → Alert Retrieval: uses client (evidence: `correlation_engine.py`)
- Incident Investigation → Local Host Evidence: collects host evidence (evidence: `incident_investigator.py`)
- Incident Investigation → Outcome Verification: verifies outcomes (evidence: `incident_investigator.py`)
- Incident Investigation → ATT&CK Mapping: maps techniques (evidence: `incident_investigator.py`)
- Remote Evidence Collection → Monitored Host: collects over SSH (evidence: `remote_evidence_collector.py`)
- Remote Evidence Collection → Incident Investigation: supplies evidence (evidence: `remote_evidence_collector.py`)
- Single-Alert AI Analysis → Ollama: requests inference (evidence: `wazuh_ai.py`)
- Investigation AI Interpretation → Ollama: requests inference
- Incident Investigation → Report Generation: generates report (evidence: `incident_investigator.py`)