How musamnsaeed/ai-soc-assistant works
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 SOC Pipeline · rag_mitre.py MITRE RAG Retrieval · soc_analyst.py SOC Analyst · docker-compose.yml Compose Deployment
Components 13
Telemetry Inputs
- Synthetic Traffic
simulate_soc_traffic.py - Sample Logs
sample_logs.txt - Suricata AI Agent · Interprets Suricata-originated alerts.
suricata_ai_agent.py
SOC Analysis
- SOC Pipeline · Normalizes events, extracts alerts, and coordinates enrichment.
soc_pipeline_v2.py
Threat Context
- Threat Intelligence
threat_intel.py - MITRE RAG Retrieval · Finds relevant ATT&CK context from the local index.
rag_mitre.py - FAISS MITRE Index
faiss_mitre_index/index.faiss - Index Metadata
faiss_mitre_index/index.pkl - Retrieval Diagnostics · Validates MITRE retrieval quality.
diagnose_retrieval.py
Analyst Delivery
- SOC Analyst · Prioritizes findings and recommends response.
soc_analyst.py - Dashboard App
app.py
Container Runtime
- Compose Deployment
docker-compose.yml - Container Image
DockerFile
Connections 15
- 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