SOC Copilot 🛡️

An AI-powered SOC analyst assistant that triages security alerts using Retrieval-Augmented Generation (RAG) over the MITRE ATT&CK knowledge base, powered by Claude.

What It Does

Given a raw security alert, SOC Copilot:

1. Retrieves the most relevant MITRE ATT&CK techniques using semantic search (ChromaDB)
2. Reasons over the alert + retrieved context using Claude to produce a structured triage decision
3. Returns a verdict (CRITICAL/HIGH/MEDIUM/LOW/BENIGN), confidence score, matched techniques, recommended actions, and investigation queries
4. Learns from analyst feedback via a thumbs up/down loop that tracks agent accuracy over time

Architecture

Alert Input
    │
    ▼
┌─────────────────┐
│  ChromaDB (RAG) │  ◄── MITRE ATT&CK (600+ techniques, embedded at ingest)
│  Vector Store   │
└────────┬────────┘
         │ Top-K relevant techniques
         ▼
┌─────────────────┐
│  Claude (LLM)   │  ◄── System prompt with SOC analyst persona
│  Triage Agent   │
└────────┬────────┘
         │ Structured JSON verdict
         ▼
┌─────────────────┐
│   FastAPI       │  ◄── REST API + Swagger UI
│   /triage       │
│   /feedback     │
└─────────────────┘

Tech Stack

Component	Technology
LLM	Anthropic Claude (claude-sonnet)
Vector Store	ChromaDB (local, persistent)
Embeddings	ChromaDB default (all-MiniLM-L6-v2)
API	FastAPI + Uvicorn
Threat Intel	MITRE ATT&CK Enterprise (live fetch)
Language	Python 3.11+

Quickstart

1. Install dependencies

pip install -r requirements.txt

2. Configure environment

cp .env.example .env
# Add your ANTHROPIC_API_KEY to .env

3. Ingest MITRE ATT&CK data (run once)

python -m ingestion.mitre_loader

This fetches ~600 ATT&CK techniques from MITRE's CTI repository and ingests them into ChromaDB.

4. Start the API

uvicorn api.main:app --reload

5. Triage an alert

curl -X POST http://localhost:8000/triage \
  -H "Content-Type: application/json" \
  -d '{
    "alert_text": "Suspicious PowerShell execution detected. Process: powershell.exe -EncodedCommand <base64>. Parent: winword.exe. User: jsmith. Host: CORP-WS-042.",
    "top_k": 5
  }'

6. Submit analyst feedback

curl -X POST http://localhost:8000/feedback \
  -H "Content-Type: application/json" \
  -d '{
    "triage_id": "<id from triage response>",
    "alert_text": "...",
    "agent_verdict": "HIGH",
    "analyst_verdict": "HIGH",
    "analyst_correct": true,
    "analyst_notes": "Confirmed phishing-initiated macro execution"
  }'

7. Check accuracy metrics

curl http://localhost:8000/feedback/accuracy

API Reference

Full Swagger UI available at http://localhost:8000/docs after starting the server.

Endpoint	Method	Description
/triage	POST	Analyze a security alert
/feedback	POST	Record analyst verdict on a triage
/feedback/accuracy	GET	Agent accuracy metrics
/health	GET	Health check

Example Response

{
  "triage_id": "a1b2c3d4-...",
  "verdict": "HIGH",
  "confidence": 0.87,
  "matched_techniques": ["T1059.001", "T1566.001"],
  "attack_chain": "Phishing email with malicious Office macro → PowerShell execution → likely staging for C2 or lateral movement",
  "reasoning": "The parent process winword.exe spawning an encoded PowerShell command is a classic macro-based initial access pattern. The base64 encoding is consistent with obfuscation techniques used to evade detection. This warrants immediate investigation.",
  "recommended_actions": [
    "Isolate host CORP-WS-042 from the network",
    "Collect and decode the base64 PowerShell payload",
    "Review jsmith's email for phishing indicators in the last 24 hours"
  ],
  "false_positive_indicators": [
    "Could be legitimate IT automation if jsmith is in the IT admin group"
  ],
  "investigation_queries": [
    "process_name:powershell.exe parent_process:winword.exe last:1h",
    "user:jsmith email_attachments:*.doc OR *.docm last:24h"
  ]
}

Project Structure

soc-copilot/
├── ingestion/
│   └── mitre_loader.py     # Fetches + ingests MITRE ATT&CK into ChromaDB
├── agent/
│   ├── retriever.py         # RAG retrieval over ChromaDB
│   ├── triage_agent.py      # Claude-powered triage reasoning
│   └── feedback.py          # Analyst feedback store
├── api/
│   └── main.py              # FastAPI application
├── data/                    # ChromaDB persistence + feedback log (gitignored)
├── tests/                   # Test suite
├── requirements.txt
├── .env.example
└── README.md

Roadmap

• Multi-turn interactive chat for alert investigation
• Batch alert processing
• Integration with Splunk / Elastic SIEM via webhook
• Fine-tuning pipeline using accumulated feedback data
• Detection rule generation from confirmed incidents

Key Concepts Demonstrated

• RAG (Retrieval-Augmented Generation): Grounds LLM reasoning in a curated, domain-specific knowledge base rather than relying solely on parametric knowledge
• Vector similarity search: ChromaDB semantic retrieval using embedding cosine similarity
• Structured LLM outputs: Prompting Claude to return validated JSON for programmatic consumption
• Agentic feedback loops: Collecting human-in-the-loop signal to measure and improve agent quality over time
• Production-grade API: FastAPI with Pydantic validation, proper error handling, and OpenAPI docs