# musamnsaeed/ai-soc-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/musamnsaeed/ai-soc-assistant
- Repository: https://github.com/musamnsaeed/ai-soc-assistant

## Overview

#### Purpose
This repository implements an AI-assisted Security Operations Center (SOC) workflow: ingest or simulate security logs, identify suspicious activity, enrich findings with threat intelligence and MITRE ATT&CK retrieval, and present analyst-oriented results. The committed FAISS artifacts indicate a local vector-backed MITRE knowledge base.

#### Entry Points and Execution Modes
- `app.py` is the likely interactive/dashboard application entry point.
- `soc_pipeline_v2.py` is the primary end-to-end SOC processing pipeline.
- `suricata_ai_agent.py` and `soc_analyst.py` appear to support agent-driven alert analysis workflows.
- `simulate_soc_traffic.py` provides a synthetic telemetry generation path; `sample_logs.txt` provides static input.
- Container execution is defined by `DockerFile` and `docker-compose.yml`.

#### Telemetry Generation and Intake
The pipeline has two likely input boundaries:
- Synthetic SOC/network event generation in `simulate_soc_traffic.py`.
- File-based log input in `sample_logs.txt`.
- Suricata-focused processing or integration in `suricata_ai_agent.py`.

These sources feed the analysis layer rather than being treated as authoritative threat conclusions. Input normalization, parsing, and alert extraction are expected to be owned by the pipeline/agent layer, principally `soc_pipeline_v2.py`.

#### Detection and Analyst Orchestration
`soc_pipeline_v2.py` is the architectural coordinator for moving events through detection, enrichment, and reporting. `soc_analyst.py` represents the analyst-facing reasoning layer: it likely turns technical alerts into investigation context, prioritization, and recommended response. `suricata_ai_agent.py` is a specialized boundary for Suricata-originated alerts and AI-assisted interpretation.

#### Threat Intelligence and MITRE Retrieval
Threat context is separated into dedicated services:
- `threat_intel.py` provides threat-intelligence enrichment.
- `rag_mitre.py` implements retrieval-augmented access to MITRE ATT&CK content.
- `diagnose_retrieval.py` is the operational/debugging entry point for validating retrieval quality.

The retrieval subsystem persists its local vector index in:
- `faiss_mitre_index/index.faiss`
- `faiss_mitre_index/index.pkl`

This establishes a clear boundary: the SOC workflow queries a local FAISS index for MITRE context rather than embedding MITRE content directly in detection logic.

#### Data and Control Flow
The intended primary flow is:

1. Generate or read security logs (`simulate_soc_traffic.py`, `sample_logs.txt`).
2. Process alerts through SOC orchestration (`soc_pipeline_v2.py`), potentially via the Suricata agent.
3. Enrich suspicious indicators with threat intelligence (`threat_intel.py`).
4. Retrieve relevant MITRE ATT&CK techniques using RAG (`rag_mitre.py` and `faiss_mitre_index/`).
5. Produce analyst-consumable assessment through `soc_analyst.py` and/or `app.py`.

#### Runtime and Infrastructure
Python is the primary runtime, with dependencies declared in `requirements.txt`. The repository supports containerized deployment through `DockerFile` and `docker-compose.yml`. FAISS is a material local infrastructure dependency because the MITRE retrieval index is checked into the repository; no external database or hosted vector service is evidenced by the file tree.

Main entry points: [`soc_pipeline_v2.py`](https://github.com/musamnsaeed/ai-soc-assistant/blob/main/soc_pipeline_v2.py) (SOC Pipeline), [`rag_mitre.py`](https://github.com/musamnsaeed/ai-soc-assistant/blob/main/rag_mitre.py) (MITRE RAG Retrieval), [`soc_analyst.py`](https://github.com/musamnsaeed/ai-soc-assistant/blob/main/soc_analyst.py) (SOC Analyst), [`docker-compose.yml`](https://github.com/musamnsaeed/ai-soc-assistant/blob/main/docker-compose.yml) (Compose Deployment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Telemetry Inputs"]
  node_simulator["Synthetic Traffic<br/>Python generator"]
  node_sample_logs["Sample Logs<br/>static log input<br/>[sample_logs.txt]"]
  node_suricata_agent["Suricata AI Agent<br/>alert adapter"]
end

subgraph group_analysis["SOC Analysis"]
  node_pipeline{{"SOC Pipeline<br/>processing orchestrator<br/>[soc_pipeline_v2.py]"}}
end

subgraph group_knowledge["Threat Context"]
  node_threat_intel["Threat Intelligence<br/>enrichment service<br/>[threat_intel.py]"]
  node_mitre_rag["MITRE RAG Retrieval<br/>retrieval service<br/>[rag_mitre.py]"]
  node_faiss_index[("FAISS MITRE Index<br/>local vector index<br/>[index.faiss]")]
  node_index_metadata["Index Metadata<br/>FAISS metadata<br/>[index.pkl]"]
  node_retrieval_diagnostics["Retrieval Diagnostics<br/>operational tool"]
end

subgraph group_delivery["Analyst Delivery"]
  node_analyst["SOC Analyst<br/>analyst reasoning<br/>[soc_analyst.py]"]
  node_app["Dashboard App<br/>interactive application<br/>[app.py]"]
end

subgraph group_runtime["Container Runtime"]
  node_compose["Compose Deployment<br/>container orchestration<br/>[docker-compose.yml]"]
  node_dockerfile["Container Image<br/>container build"]
end

node_simulator -->|"generated events"| node_pipeline
node_sample_logs -->|"log input"| node_pipeline
node_suricata_agent -->|"Suricata alerts"| node_pipeline
node_pipeline -->|"indicators"| node_threat_intel
node_pipeline -->|"suspicious activity"| node_mitre_rag
node_threat_intel -->|"threat context"| node_analyst
node_mitre_rag -->|"ATT&amp;CK context"| node_analyst
node_pipeline -->|"alerts and findings"| node_analyst
node_analyst -->|"assessment"| node_app
node_mitre_rag -->|"vector search"| node_faiss_index
node_mitre_rag -->|"load metadata"| node_index_metadata
node_retrieval_diagnostics -.->|"validate retrieval"| node_mitre_rag
node_compose -->|"build image"| node_dockerfile
node_compose -.->|"run application"| node_app
node_compose -.->|"run pipeline"| node_pipeline

click node_simulator "https://github.com/musamnsaeed/ai-soc-assistant/blob/main/simulate_soc_traffic.py"
click node_sample_logs "https://github.com/musamnsaeed/ai-soc-assistant/blob/main/sample_logs.txt"
click node_suricata_agent "https://github.com/musamnsaeed/ai-soc-assistant/blob/main/suricata_ai_agent.py"
click node_pipeline "https://github.com/musamnsaeed/ai-soc-assistant/blob/main/soc_pipeline_v2.py"
click node_threat_intel "https://github.com/musamnsaeed/ai-soc-assistant/blob/main/threat_intel.py"
click node_mitre_rag "https://github.com/musamnsaeed/ai-soc-assistant/blob/main/rag_mitre.py"
click node_faiss_index "https://github.com/musamnsaeed/ai-soc-assistant/blob/main/faiss_mitre_index/index.faiss"
click node_index_metadata "https://github.com/musamnsaeed/ai-soc-assistant/blob/main/faiss_mitre_index/index.pkl"
click node_retrieval_diagnostics "https://github.com/musamnsaeed/ai-soc-assistant/blob/main/diagnose_retrieval.py"
click node_analyst "https://github.com/musamnsaeed/ai-soc-assistant/blob/main/soc_analyst.py"
click node_app "https://github.com/musamnsaeed/ai-soc-assistant/blob/main/app.py"
click node_compose "https://github.com/musamnsaeed/ai-soc-assistant/blob/main/docker-compose.yml"
click node_dockerfile "https://github.com/musamnsaeed/ai-soc-assistant/blob/main/DockerFile"

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_simulator,node_sample_logs,node_suricata_agent toneBlue
class node_pipeline toneAmber
class node_threat_intel,node_mitre_rag,node_faiss_index,node_index_metadata,node_retrieval_diagnostics toneMint
class node_analyst,node_app toneRose
class node_compose,node_dockerfile toneIndigo
```

## Components

### Telemetry Inputs

- [Synthetic Traffic](https://github.com/musamnsaeed/ai-soc-assistant/blob/main/simulate_soc_traffic.py): Python generator · `simulate_soc_traffic.py`
- [Sample Logs](https://github.com/musamnsaeed/ai-soc-assistant/blob/main/sample_logs.txt): static log input · `sample_logs.txt`
- [Suricata AI Agent](https://github.com/musamnsaeed/ai-soc-assistant/blob/main/suricata_ai_agent.py): alert adapter · Interprets Suricata-originated alerts. · `suricata_ai_agent.py`

### SOC Analysis

- [SOC Pipeline](https://github.com/musamnsaeed/ai-soc-assistant/blob/main/soc_pipeline_v2.py): processing orchestrator · Normalizes events, extracts alerts, and coordinates enrichment. · `soc_pipeline_v2.py`

### Threat Context

- [Threat Intelligence](https://github.com/musamnsaeed/ai-soc-assistant/blob/main/threat_intel.py): enrichment service · `threat_intel.py`
- [MITRE RAG Retrieval](https://github.com/musamnsaeed/ai-soc-assistant/blob/main/rag_mitre.py): retrieval service · Finds relevant ATT&CK context from the local index. · `rag_mitre.py`
- [FAISS MITRE Index](https://github.com/musamnsaeed/ai-soc-assistant/blob/main/faiss_mitre_index/index.faiss): local vector index · `faiss_mitre_index/index.faiss`
- [Index Metadata](https://github.com/musamnsaeed/ai-soc-assistant/blob/main/faiss_mitre_index/index.pkl): FAISS metadata · `faiss_mitre_index/index.pkl`
- [Retrieval Diagnostics](https://github.com/musamnsaeed/ai-soc-assistant/blob/main/diagnose_retrieval.py): operational tool · Validates MITRE retrieval quality. · `diagnose_retrieval.py`

### Analyst Delivery

- [SOC Analyst](https://github.com/musamnsaeed/ai-soc-assistant/blob/main/soc_analyst.py): analyst reasoning · Prioritizes findings and recommends response. · `soc_analyst.py`
- [Dashboard App](https://github.com/musamnsaeed/ai-soc-assistant/blob/main/app.py): interactive application · `app.py`

### Container Runtime

- [Compose Deployment](https://github.com/musamnsaeed/ai-soc-assistant/blob/main/docker-compose.yml): container orchestration · `docker-compose.yml`
- [Container Image](https://github.com/musamnsaeed/ai-soc-assistant/blob/main/DockerFile): container build · `DockerFile`

## Connections

- Synthetic Traffic → SOC Pipeline: generated events
- Sample Logs → SOC Pipeline: log input
- Suricata AI Agent → SOC Pipeline: Suricata alerts
- SOC Pipeline → Threat Intelligence: indicators
- SOC Pipeline → MITRE RAG Retrieval: suspicious activity
- Threat Intelligence → SOC Analyst: threat context
- MITRE RAG Retrieval → SOC Analyst: ATT&CK context
- SOC Pipeline → SOC Analyst: alerts and findings
- SOC Analyst → Dashboard App: assessment
- MITRE RAG Retrieval → FAISS MITRE Index: vector search
- MITRE RAG Retrieval → Index Metadata: load metadata
- Retrieval Diagnostics → MITRE RAG Retrieval: validate retrieval
- Compose Deployment → Container Image: build image
- Compose Deployment → Dashboard App: run application
- Compose Deployment → SOC Pipeline: run pipeline