Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

docs(quick-win): GitHub on-ramp fix — phases 1–3 + CI gates (#368)

Beenu Arora91014ddccf8a
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 000000000..47457d386
--- /dev/null
+++ b/.devcontainer/Dockerfile
@@ -0,0 +1,95 @@
+# syntax=docker/dockerfile:1.7
+###############################################################################
+# AiSOC devcontainer image.
+#
+# This file is the source of `ghcr.io/beenuar/aisoc-devcontainer:latest`, the
+# prebuilt image referenced by .devcontainer/devcontainer.json. Building the
+# Codespaces side-cars (docker-in-docker, python, go, github-cli) into a
+# single image instead of resolving them via `features:` on every cold start
+# drops first-boot from ~5 minutes to ~30 seconds.
+#
+# Layers, top to bottom:
+# 1. Base: javascript-node bookworm — Node 20 + pnpm-friendly debian
+# 2. System packages: docker.io, python3.11 + uv, go, gh
+# 3. Workspace bootstrap: corepack-prepare pnpm, prime turbo/eslint caches
+#
+# Keep this image small enough that `docker pull` over a Codespaces machine's
+# default network is < 30 s on first launch. The CI job at
+# `.github/workflows/devcontainer-build.yml` rebuilds and publishes on every
+# push to main; the integration test at
+# `.github/workflows/devcontainer-coldstart.yml` asserts the boot KPI.
+###############################################################################
+
+FROM mcr.microsoft.com/devcontainers/javascript-node:1-20-bookworm
+
+ARG TARGETARCH
+
+# ─── System tooling ─────────────────────────────────────────────────────────
+#
+# We deliberately install via apt rather than re-using the upstream
+# `ghcr.io/devcontainers/features/*` install scripts. apt is fully
+# offline-installable from the base image's mirror; the features path adds
+# its own resolution + download phase that happens at codespace cold-start
+# time and is the largest single contributor to the ~5 min boot we are
+# eliminating.
+RUN apt-get update \
+ && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+ ca-certificates curl gnupg2 lsb-release software-properties-common \
+ python3.11 python3.11-venv python3-pip pipx \
+ build-essential libffi-dev libssl-dev \
+ docker.io docker-compose-plugin \
+ ripgrep jq \
+ && rm -rf /var/lib/apt/lists/*
+
+# ─── GitHub CLI (gh) ────────────────────────────────────────────────────────
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+ | gpg --dearmor -o /usr/share/keyrings/githubcli-archive-keyring.gpg \
+ && chmod 644 /usr/share/keyrings/githubcli-archive-keyring.gpg \
+ && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+ > /etc/apt/sources.list.d/github-cli.list \
+ && apt-get update \
+ && apt-get install -y --no-install-recommends gh \
+ && rm -rf /var/lib/apt/lists/*
+
+# ─── Go 1.22 ─────────────────────────────────────────────────────────────────
+ENV GO_VERSION=1.22.5
+RUN set -eux; \
+ case "${TARGETARCH:-amd64}" in \
+ amd64) goarch="amd64" ;; \
+ arm64) goarch="arm64" ;; \
+ *) echo "unsupported arch: ${TARGETARCH}" >&2; exit 1 ;; \
+ esac; \
+ curl -fsSL "https://go.dev/dl/go${GO_VERSION}.linux-${goarch}.tar.gz" \
+ | tar -C /usr/local -xz; \
+ ln -s /usr/local/go/bin/go /usr/local/bin/go; \
+ ln -s /usr/local/go/bin/gofmt /usr/local/bin/gofmt
+ENV PATH="/usr/local/go/bin:${PATH}"
+
+# ─── Python toolchain (uv) ──────────────────────────────────────────────────
+# `uv` is the canonical Python package manager for AiSOC services. Installing
+# it at image-build time means a fresh codespace can run `uv sync` against
+# `services/api/uv.lock` immediately, with no further network round-trips.
+RUN pipx ensurepath \
+ && pipx install uv \
+ && pipx install ruff
+
+# ─── pnpm via corepack ──────────────────────────────────────────────────────
+RUN corepack enable \
+ && corepack prepare [email protected] --activate
+
+# ─── Workspace bootstrap ────────────────────────────────────────────────────
+# The actual pnpm install of workspace dependencies happens at codespace
+# create time (`postCreateCommand`) because the lockfile changes too often
+# to bake into the image. But seeding the pnpm store with a single test
+# dependency forces corepack + the store layout to materialise, so the
+# postCreateCommand sees a warm store and finishes in seconds rather than
+# minutes.
+RUN su node -c "pnpm config set store-dir /home/node/.local/share/pnpm/store \
+ && pnpm store status >/dev/null 2>&1 || true"
+
+USER node
+WORKDIR /workspaces/AiSOC
+
+LABEL org.opencontainers.image.source="https://github.com/beenuar/AiSOC"
+LABEL org.opencontainers.image.description="Prebuilt devcontainer for AiSOC contributors and Codespaces."
+LABEL org.opencontainers.image.licenses="MIT"
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 0efd489ec..81421208a 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -1,19 +1,13 @@
{
"name": "AiSOC — one-click dev",
- "image": "mcr.microsoft.com/devcontainers/javascript-node:1-20-bookworm",
- "features": {
- "ghcr.io/devcontainers/features/docker-in-docker:2": {
- "moby": true,
- "version": "latest"
- },
- "ghcr.io/devcontainers/features/python:1": {
- "version": "3.11"
- },
- "ghcr.io/devcontainers/features/go:1": {
- "version": "1.22"
- },
- "ghcr.io/devcontainers/features/github-cli:1": {}
+ "//image": "Prebuilt image is published by .github/workflows/devcontainer-build.yml. It drops Codespaces cold-start from ~5 min → ~30 s by baking Node + pnpm + Python (+ uv) + Go + Docker + gh into a single layer instead of resolving them via `features:` on every boot.",
+ "image": "ghcr.io/beenuar/aisoc-devcontainer:latest",
+ "//build": "Fallback for local devcontainer-cli use and for forks that don't have GHCR pull access. The `image` directive above wins; the build block is only consulted by tooling like `devcontainer build`.",
+ "build": {
+ "dockerfile": "Dockerfile",
+ "context": "."
},
+ "//features": "We intentionally do NOT enable docker-in-docker / python / go / github-cli features here — they are baked into the image at build time. Re-enabling them would cancel the cold-start win.",
"hostRequirements": {
"cpus": 4,
"memory": "16gb",
@@ -38,7 +32,9 @@
"label": "Docs site"
}
},
- "postCreateCommand": "corepack enable && corepack prepare [email protected] --activate && pnpm install --frozen-lockfile=false && echo '\\n\\n>>> AiSOC dev container is ready.\\n>>> To run the demo, open a terminal and run:\\n>>> pnpm aisoc:demo --no-open\\n>>> Then click the forwarded port 3000 in the Ports panel.\\n'",
+ "//onCreateCommand": "Runs once at image-spawn time. The pnpm store is already warm in the prebuilt image, so `--frozen-lockfile=false` here is fast (≤ 30 s on a green Codespace).",
+ "onCreateCommand": "pnpm install --frozen-lockfile=false",
+ "postAttachCommand": "echo '\\n>>> AiSOC dev container is ready.\\n>>> To run the demo, open a terminal and run:\\n>>> pnpm aisoc:demo --no-open\\n>>> Then click the forwarded port 3000 in the Ports panel.\\n>>> Or, no-Docker: pip install -e packages/aisoc-sandbox && aisoc-sandbox demo\\n'",
"remoteUser": "node",
"containerEnv": {
"AISOC_DEV_MODE": "1"
diff --git a/.env.example b/.env.example
index d48f156d5..46484f863 100644
--- a/.env.example
+++ b/.env.example
@@ -13,7 +13,7 @@
# ║ it. NEVER reuse a key from anywhere public. ║
# ║ ║
# ║ Everything else has sensible defaults for `docker compose -f ║
-# ║ docker-compose.dev.yml up -d`. ║
+# ║ infra/compose/docker-compose.dev.yml up -d`. ║
# ╚════════════════════════════════════════════════════════════════════════════╝
# ─── Image Pinning ────────────────────────────────────────────────────────────
diff --git a/CREDITS.md b/.github/CREDITS.md
similarity index 98%
rename from CREDITS.md
rename to .github/CREDITS.md
index 79d10850e..19b331c08 100644
--- a/CREDITS.md
+++ b/.github/CREDITS.md
@@ -69,6 +69,6 @@ You're added automatically if:
- You reported a security issue that was acknowledged and triaged (via [private advisory](https://github.com/beenuar/AiSOC/security/advisories/new) or a confirmed public issue)
- You filed a high-signal issue that drove a real change in the codebase
-If something landed because of you and you're not on this list, that's a bug — please open a PR against `CREDITS.md` and we'll merge it.
+If something landed because of you and you're not on this list, that's a bug — please open a PR against `.github/CREDITS.md` and we'll merge it.
Thank you for making AiSOC better.
diff --git a/LICENSES.md b/.github/LICENSES.md
similarity index 100%
rename from LICENSES.md
rename to .github/LICENSES.md
diff --git a/.github/workflows/compose-smoke.yml b/.github/workflows/compose-smoke.yml
index f6592a304..b991f7c70 100644
--- a/.github/workflows/compose-smoke.yml
+++ b/.github/workflows/compose-smoke.yml
@@ -22,7 +22,7 @@ on:
paths:
# Compose surface itself.
- 'docker-compose.yml'
- - 'docker-compose.demo.yml'
+ - 'infra/compose/docker-compose.demo.yml'
- '.env.example'
- '.github/workflows/compose-smoke.yml'
# Any source under a service build context — Dockerfile changes alone
@@ -46,7 +46,7 @@ on:
- 'hotfix/**'
paths:
- 'docker-compose.yml'
- - 'docker-compose.demo.yml'
+ - 'infra/compose/docker-compose.demo.yml'
- '.env.example'
- '.github/workflows/compose-smoke.yml'
- 'services/**'
diff --git a/.github/workflows/devcontainer-build.yml b/.github/workflows/devcontainer-build.yml
new file mode 100644
index 000000000..37ffffb99
--- /dev/null
+++ b/.github/workflows/devcontainer-build.yml
@@ -0,0 +1,83 @@
+name: Devcontainer · build & publish
+
+# Builds the prebuilt devcontainer image referenced from
+# `.devcontainer/devcontainer.json` and publishes it to
+# `ghcr.io/beenuar/aisoc-devcontainer`.
+#
+# Why: the prebuilt image is what makes a cold Codespace boot in ~30 s
+# instead of ~5 min. The user-visible KPI sits in
+# `.github/workflows/devcontainer-coldstart.yml`.
+#
+# When this runs:
+# - On every push to `main` that touches the devcontainer surface.
+# - On a weekly cron so security-relevant base-layer updates land
+# even if the surface itself didn't change.
+# - On manual dispatch (so a release manager can re-tag without
+# waiting for a commit).
+#
+# Multi-arch: the image is built for `linux/amd64` and `linux/arm64`, so a
+# contributor on an M-series Mac doing local devcontainer work gets a
+# native pull, not a slow QEMU fallback.
+
+on:
+ push:
+ branches: [main]
+ paths:
+ - '.devcontainer/Dockerfile'
+ - '.devcontainer/devcontainer.json'
+ - '.github/workflows/devcontainer-build.yml'
+ schedule:
+ - cron: '0 9 * * 1' # Mondays 09:00 UTC — base image hygiene
+ workflow_dispatch:
+
+permissions:
+ contents: read
+ packages: write
+
+concurrency:
+ group: devcontainer-build-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ build:
+ name: build & push (multi-arch)
+ runs-on: ubuntu-latest
+ timeout-minutes: 45
+
+ steps:
+ - uses: actions/checkout@v7
+
+ - name: Set up QEMU
+ uses: docker/setup-qemu-action@v3
+
+ - name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@v3
+
+ - name: Log in to GHCR
+ uses: docker/login-action@v3
+ with:
+ registry: ghcr.io
+ username: ${{ github.actor }}
+ password: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Resolve metadata
+ id: meta
+ uses: docker/metadata-action@v5
+ with:
+ images: ghcr.io/beenuar/aisoc-devcontainer
+ tags: |
+ type=raw,value=latest,enable={{is_default_branch}}
+ type=sha,prefix=sha-
+ type=raw,value=weekly,enable=${{ github.event_name == 'schedule' }}
+
+ - name: Build & push
+ uses: docker/build-push-action@v6
+ with:
+ context: .devcontainer
+ file: .devcontainer/Dockerfile
+ push: true
+ platforms: linux/amd64,linux/arm64
+ tags: ${{ steps.meta.outputs.tags }}
+ labels: ${{ steps.meta.outputs.labels }}
+ cache-from: type=gha
+ cache-to: type=gha,mode=max
diff --git a/.github/workflows/devcontainer-coldstart.yml b/.github/workflows/devcontainer-coldstart.yml
new file mode 100644
index 000000000..15d0e5623
--- /dev/null
+++ b/.github/workflows/devcontainer-coldstart.yml
@@ -0,0 +1,98 @@
+name: Devcontainer · cold-start KPI
+
+# Asserts the documented Codespaces cold-start budget — from a fresh image
+# pull to a green `aisoc-acceptance --cold` run.
+#
+# This is the gate behind the "~30 s cold-start" claim in
+# `apps/docs/docs/operations/codespaces.md` and the plan that drove the
+# Phase-3 friction-cut workstream. If this job goes red, we're back to a
+# ~5-min cold boot and the README's "Try AiSOC in 60 seconds" promise no
+# longer holds for Codespaces users — release-blocking.
+#
+# Strategy: pull the published `ghcr.io/beenuar/aisoc-devcontainer:latest`
+# (the same image Codespaces resolves) and exec the acceptance harness
+# inside it. We measure two budgets independently:
+#
+# 1. image pull + `onCreateCommand` (pnpm install warm-store) — the
+# "before you can run anything" phase. Budget: 60 s.
+# 2. `pnpm aisoc:acceptance --cold` — the same wall-clock measurement
+# used by the WS-A buyer acceptance gate. Budget: 5 min.
+#
+# A regression on either budget fails the workflow.
+
+on:
+ workflow_run:
+ workflows: ['Devcontainer · build & publish']
+ types: [completed]
+ branches: [main]
+ push:
+ branches: [main]
+ paths:
+ - '.devcontainer/**'
+ - 'scripts/aisoc-acceptance.ts'
+ - '.github/workflows/devcontainer-coldstart.yml'
+ workflow_dispatch:
+
+permissions:
+ contents: read
+ packages: read
+
+concurrency:
+ group: devcontainer-coldstart-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ cold-start:
+ name: Pull + boot + acceptance
+ runs-on: ubuntu-latest
+ timeout-minutes: 20
+
+ # Phase budgets (seconds). Kept here so a diff in this file is the
+ # canonical record of any KPI change.
+ env:
+ PHASE_PULL_BUDGET: '60'
+ PHASE_ACCEPTANCE_BUDGET: '300'
+
+ steps:
+ - uses: actions/checkout@v7
+
+ - name: Log in to GHCR
+ uses: docker/login-action@v3
+ with:
+ registry: ghcr.io
+ username: ${{ github.actor }}
+ password: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Phase 1 — pull prebuilt image (KPI budget ${{ env.PHASE_PULL_BUDGET }}s)
+ run: |
+ set -euo pipefail
+ start=$(date +%s)
+ docker pull ghcr.io/beenuar/aisoc-devcontainer:latest
+ elapsed=$(( $(date +%s) - start ))
+ echo "::notice title=devcontainer-pull-seconds::${elapsed}"
+ if [ "$elapsed" -gt "${PHASE_PULL_BUDGET}" ]; then
+ echo "::error::Devcontainer pull took ${elapsed}s, over budget of ${PHASE_PULL_BUDGET}s." >&2
+ exit 1
+ fi
+
+ - name: Phase 2 — boot + aisoc-acceptance --cold (KPI budget ${{ env.PHASE_ACCEPTANCE_BUDGET }}s)
+ run: |
+ set -euo pipefail
+ start=$(date +%s)
+ docker run --rm \
+ -v "${GITHUB_WORKSPACE}:/workspaces/AiSOC" \
+ -v /var/run/docker.sock:/var/run/docker.sock \
+ -w /workspaces/AiSOC \
+ -e AISOC_DEV_MODE=1 \
+ ghcr.io/beenuar/aisoc-devcontainer:latest \
+ bash -lc '
+ set -euo pipefail
+ pnpm install --frozen-lockfile=false >/tmp/pnpm.log 2>&1
+ pnpm aisoc:acceptance:cold --budget-ms '"${PHASE_ACCEPTANCE_BUDGET}"'000
+ '
+ elapsed=$(( $(date +%s) - start ))
+ echo "::notice title=devcontainer-acceptance-seconds::${elapsed}"
+ if [ "$elapsed" -gt "${PHASE_ACCEPTANCE_BUDGET}" ]; then
+ echo "::error::aisoc-acceptance --cold took ${elapsed}s, over budget of ${PHASE_ACCEPTANCE_BUDGET}s." >&2
+ exit 1
+ fi
diff --git a/.github/workflows/readme-gates.yml b/.github/workflows/readme-gates.yml
new file mode 100644
index 000000000..258b98c9f
--- /dev/null
+++ b/.github/workflows/readme-gates.yml
@@ -0,0 +1,106 @@
+name: README · onramp gates
+
+# This workflow is the contract behind the AiSOC GitHub front door. Every
+# claim the README makes about quick-win paths gets gated here:
+#
+# 1. README must stay ≤ 250 lines so visitors hit the value props before
+# they scroll off the page.
+# 2. Every npm / PyPI package the README directs visitors to must
+# either resolve on the public registry today, or be paired with a
+# "Coming in v8.0" guard.
+# 3. Any `apps/web/public/demo/<asset>` path the README points at must
+# exist on disk (or be paired with the same kind of guard).
+# 4. `aisoc-sandbox demo --scenario <each>` must run to completion
+# offline on both Linux and macOS — that's the README's
+# "Try AiSOC in 60 seconds, no Docker" promise.
+#
+# Gates 1–3 share a single Python driver at scripts/readme_gates.py so
+# contributors can reproduce the same checks locally with one command.
+# Gate 4 needs the cross-platform matrix, so it runs separately.
+
+on:
+ pull_request:
+ branches: [main, develop]
+ paths:
+ - 'README.md'
+ - 'packages/aisoc-sandbox/**'
+ - 'apps/web/public/demo/**'
+ - 'scripts/readme_gates.py'
+ - '.github/workflows/readme-gates.yml'
+ push:
+ branches: [main]
+ paths:
+ - 'README.md'
+ - 'packages/aisoc-sandbox/**'
+ - 'apps/web/public/demo/**'
+ - 'scripts/readme_gates.py'
+ - '.github/workflows/readme-gates.yml'
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: readme-gates-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ static:
+ name: README · static gates (line-count, packages, demo assets)
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+
+ steps:
+ - uses: actions/checkout@v7
+
+ - uses: actions/setup-python@v6
+ with:
+ python-version: '3.11'
+
+ - name: Run scripts/readme_gates.py
+ run: |
+ python3 scripts/readme_gates.py --skip-sandbox
+
+ sandbox-offline:
+ name: aisoc-sandbox · offline smoke (${{ matrix.os }})
+ runs-on: ${{ matrix.os }}
+ timeout-minutes: 10
+ strategy:
+ fail-fast: false
+ matrix:
+ os: [ubuntu-latest, macos-latest]
+
+ steps:
+ - uses: actions/checkout@v7
+
+ - uses: actions/setup-python@v6
+ with:
+ python-version: '3.11'
+
+ - name: Install aisoc-sandbox from source
+ run: |
+ python3 -m pip install --upgrade pip
+ python3 -m pip install -e packages/aisoc-sandbox
+
+ - name: Smoke-test each bundled scenario
+ run: |
+ set -euo pipefail
+ for s in lateral-movement aws-credential-exfil phishing-payload kubernetes-privesc github-token-theft; do
+ echo "── $s ──"
+ out=$(aisoc-sandbox demo --scenario "$s" --json)
+ python3 -c "
+ import json, sys
+ payload = json.loads(sys.argv[1])
+ steps = payload['ledger']
+ assert len(steps) == 4, f'expected 4 steps, got {len(steps)}'
+ assert steps[0]['agent'] == 'DetectAgent', steps[0]
+ assert steps[-1]['agent'] == 'RespondAgent', steps[-1]
+ print(f\" {len(steps)} steps · final-agent={steps[-1]['agent']}\")
+ " "$out"
+ done
+
+ - name: Run sandbox unit tests
+ run: |
+ python3 -m pip install pytest
+ cd packages/aisoc-sandbox
+ PYTHONPATH=src python3 -m pytest tests/ -q
diff --git a/.github/workflows/screencast.yml b/.github/workflows/screencast.yml
index c9413b8b9..55fe63183 100644
--- a/.github/workflows/screencast.yml
+++ b/.github/workflows/screencast.yml
@@ -78,7 +78,7 @@ jobs:
--reporter=line \
--output=../../tmp/screencast
- - name: Transcode webm → mp4 (H.264 / AAC)
+ - name: Transcode webm → mp4 (H.264 / AAC) + render hero.gif
run: |
set -euo pipefail
src=$(find tmp/screencast -name '*.webm' | head -n1)
@@ -94,6 +94,16 @@ jobs:
-c:a aac -b:a 128k \
-movflags +faststart \
tmp/screencast/demo.mp4
+
+ # Phase 2 quick-win on-ramp: also render hero.gif — a 10s
+ # loop of Shot 2 (Investigation timeline) at 720p, 15 fps.
+ # palettegen / paletteuse keeps the GIF colour quantisation
+ # clean; loop=0 makes the GIF run forever in <img> tags.
+ ffmpeg -y -ss 14 -t 10 -i "$src" \
+ -vf "fps=15,scale=720:-2:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse" \
+ -loop 0 \
+ tmp/screencast/hero.gif
+
ls -lh tmp/screencast/
- name: Upload screencast artifacts
@@ -102,6 +112,7 @@ jobs:
name: screencast-${{ github.sha }}
path: |
tmp/screencast/demo.mp4
+ tmp/screencast/hero.gif
tmp/screencast/*.png
retention-days: 30
@@ -121,5 +132,6 @@ jobs:
fi
gh release upload "${{ inputs.release_tag }}" \
tmp/screencast/demo.mp4\#"AiSOC 90s demo (mp4)" \
+ tmp/screencast/hero.gif\#"AiSOC hero loop (gif)" \
tmp/screencast/*.png \
--clobber
diff --git a/AGENTS.md b/AGENTS.md
index ab49512e9..d50269090 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -24,7 +24,7 @@
- Backend services in `services/`: `api` (FastAPI/Python 3.11), `agents`, `alert-fusion`, `connectors`, `demo-producer`, `enrichment`, `fusion`, `ingest`, `realtime`, `threatintel`, `ocsf`.
- API service stack: FastAPI, Uvicorn, SQLAlchemy (async), asyncpg (PostgreSQL), Alembic (migrations), Redis, python-jose (JWT), Pydantic v2.
- Packages: `packages/types` (shared TypeScript types), `packages/ui`, `packages/sdk-go`, `packages/sdk-py`, `packages/sdk-ts`, `packages/plugin-sdk-go`, `packages/plugin-sdk-py`.
-- Docker Compose used for local dev (`docker-compose.dev.yml`); Terraform in `infra/terraform/` for infrastructure.
+- Docker Compose used for local dev (`infra/compose/docker-compose.dev.yml`); Terraform in `infra/terraform/` for infrastructure.
- CI uses GitHub Actions (`.github/workflows/`); includes workflows for OpenAPI checks, CI, docs deployment, marketplace sync, and detection validation.
- Detection rules stored in `detections/` (YAML format, categorized by cloud/endpoint/identity/network/application).
- Marketplace plugin index at `marketplace/index.json`, synced to `apps/web/public/marketplace/` via `pnpm marketplace:sync`.
@@ -52,11 +52,11 @@
- WS-G: Slack Bolt service at `services/slack-bot/` with `/aisoc` ChatOps commands (WS-G1); executive digest with auto-generated PDF + weekly scheduler in `services/api/app/services/digest_pdf.py` and `services/api/app/api/v1/endpoints/reports.py` (WS-G2).
- WS-H: LLM cost dashboard (`services/api/app/services/cost_dashboard.py` + `apps/web/src/app/(admin)/costs/page.tsx` — WS-H1); BYOK per-tenant LLM credentials vault-encrypted via `CredentialVault`, model `TenantLlmCredential`, settings UI in `apps/web/src/components/settings/SettingsView.tsx` (WS-H2); compliance audit export CSV + HTML bundles at `services/api/app/services/audit_export.py` (WS-H3); air-gapped / local-LLM mode via Ollama/LiteLLM overlay + zero-external-call demo seed (WS-H4).
- Threat actor attribution engine v0 at `services/threatintel/` (rebased, hardened, open as PR #43).
-- **v8.0 wave-1 (on `main`, not yet tagged as of 2026-05-14):** Architectural foundation for the v8.0 line. `VERSION` stays at `7.3.1` until wave-2 lands; all v8.0 work is documented under `[Unreleased]` in `CHANGELOG.md`. Tracking doc: `AISOC_V8_PROGRESS.md`. Key shipped pieces:
+- **v8.0 wave-1 (on `main`, not yet tagged as of 2026-05-14):** Architectural foundation for the v8.0 line. `VERSION` stays at `7.3.1` until wave-2 lands; all v8.0 work is documented under `[Unreleased]` in `CHANGELOG.md`. Tracking doc: `docs/roadmap/v8-progress.md`. Key shipped pieces:
- **Graph at ingest (T1.1).** `services/ingest/internal/graph/` writes a Neo4j entity graph (`User`, `Asset`, `Process`, `IP`, `Domain`, `Alert`, 17 node labels / 14 edge types total) inline with Kafka consumption. Batched UNWIND upserts + fire-and-forget retry queue keep the ingest latency budget unchanged. Schema doc: `apps/docs/docs/architecture/graph-schema.md`. Anchor post: `apps/web/content/blog/graph-at-ingest.mdx`.
- **Four-agent rebrand (T2.1).** `DetectAgent`, `TriageAgent`, `HuntAgent`, `RespondAgent` in `services/agents/app/agents/`. Back-compat aliases preserve existing imports. Each owns one funnel stage; funnel KPI doc at `apps/docs/docs/console/funnel-kpis.md`.
- **`/hunt` natural-language surface (T2.2).** `apps/web/src/app/(app)/hunt/` + `services/api/app/api/v1/endpoints/saved_hunts.py`. NL prompt → ES|QL / SPL / KQL template (HuntAgent never writes raw queries). Saved hunts have `pivotPath` deep-links into the Investigation Rail.
- - **Sixteen first-party connectors.** Wave-1 fully tested: `tines`, `torq`, `falco`, `pagerduty`, `opsgenie`, `confluence_audit`. Wave-2 with full fixtures + tests: `cloudflare_zt`, `sysdig`, `vault`, `snowflake`. Six more `[wip]` in `AISOC_V8_PROGRESS.md`. All five severity tiers preserved end-to-end.
+ - **Sixteen first-party connectors.** Wave-1 fully tested: `tines`, `torq`, `falco`, `pagerduty`, `opsgenie`, `confluence_audit`. Wave-2 with full fixtures + tests: `cloudflare_zt`, `sysdig`, `vault`, `snowflake`. Six more `[wip]` in `docs/roadmap/v8-progress.md`. All five severity tiers preserved end-to-end.
- **L0–L4 automation maturity model.** `apps/docs/docs/concepts/automation-maturity.md` + `apps/web/content/papers/l0-l4-automation-maturity.md` (PDF rendered via `pnpm docs:build`). Ladder: L0 manual → L4 fully autonomous closure with human sign-off.
- **Public weekly benchmark scoreboard.** `apps/docs/docs/benchmark-scoreboard.mdx` reads `apps/docs/static/data/scoreboard.json`, refreshed by `.github/workflows/wet-eval.yml` (weekly). Existing eval-harness transparency rules apply (synthetic vs real labelled explicitly).
- **Security wave shipped before v8.0 cut (PRs #116–#128, May 2026):** Twelve critical/high CVE-class fixes. Patterns to remember:
diff --git a/README.md b/README.md
index 4258313aa..bb2a17495 100644
--- a/README.md
+++ b/README.md
@@ -7,8 +7,6 @@
An open-source, self-hostable AI SOC. The agent's prompts, tool calls, and rationale are logged step-by-step and replayable. MIT-licensed.
[![License: MIT](https://img.shields.io/badge/License-MIT-22c55e.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![Public eval harness: CI-gated](https://img.shields.io/badge/eval%20harness-CI--gated-2563eb?style=flat-square)](apps/docs/docs/benchmark.md)
-[![PRs welcome](https://img.shields.io/badge/PRs-welcome-8b5cf6?style=flat-square)](CONTRIBUTING.md)
[![Version](https://img.shields.io/badge/version-7.5.0-f59e0b?style=flat-square)](CHANGELOG.md)
[![CI](https://img.shields.io/github/actions/workflow/status/beenuar/AiSOC/ci.yml?branch=main&label=CI&style=flat-square)](https://github.com/beenuar/AiSOC/actions/workflows/ci.yml)
[![CodeQL](https://img.shields.io/github/actions/workflow/status/beenuar/AiSOC/codeql.yml?branch=main&label=CodeQL&style=flat-square)](https://github.com/beenuar/AiSOC/actions/workflows/codeql.yml)
@@ -19,11 +17,13 @@ An open-source, self-hostable AI SOC. The agent's prompts, tool calls, and ratio
[![Live demo on Fly.io](https://img.shields.io/badge/Live%20demo-tryaisoc.com-7b2bbe?style=for-the-badge&logo=fly-dot-io&logoColor=white)](https://tryaisoc.com)
[![Render demo (one-click)](https://img.shields.io/badge/Render-one--click-46e3b7?style=for-the-badge&logo=render&logoColor=white)](https://render.com/deploy?repo=https://github.com/beenuar/AiSOC)
-[Try in Codespaces](https://codespaces.new/beenuar/AiSOC?quickstart=1) · [Live demo](https://tryaisoc.com) · [Quickstart](#try-aisoc-in-60-seconds) · [Architecture](#architecture) · [Docs](apps/docs/) · [Discussions](https://github.com/beenuar/AiSOC/discussions) · [Release notes](RELEASES.md)
+<sub>The community-maintained demo at <a href="https://tryaisoc.com">tryaisoc.com</a> runs on Fly.io and can go offline; see <a href="docs/operations/live-demo-runbook.md">docs/operations/live-demo-runbook.md</a> and use Codespaces as the always-on fallback.</sub>
-<sub>The demo at <a href="https://tryaisoc.com">tryaisoc.com</a> is a self-hosted instance fronted by a Cloudflare Tunnel — when it's reachable, the stack is running locally on a maintainer's box. It can therefore go offline at any time. To run your own (in 3.5 min, with seeded data), see <a href="#one-shot-demo">One-shot demo</a>; to expose your own instance on your own domain via Cloudflare Tunnel, see <a href="#public-demo-on-your-own-domain">Public demo on your own domain</a>. <strong>The Fly.io demo at <a href="https://tryaisoc.com">tryaisoc.com</a> is the canonical AiSOC instance — the badge above links there.</strong></sub>
+<br />
-[![GitHub topics](https://img.shields.io/badge/topics-soc%20%7C%20siem%20%7C%20ai--security%20%7C%20mitre--attack-0ea5e9?style=flat-square)](https://github.com/beenuar/AiSOC/topics)
+<a href="apps/web/public/demo/"><img src="apps/web/public/demo-thumbnail.svg" alt="90-second AiSOC product walkthrough — agent investigating the seeded LockBit 3.0 case" width="720" /></a>
+
+<sub><em>90-second walkthrough — agent investigates the seeded LockBit 3.0 case end-to-end. The rendered <code>.mp4</code> + <code>hero.gif</code> land with the v8.0 launch; the brief is in <a href="docs/demo/SCREENCAST_SHOTLIST.md">docs/demo/SCREENCAST_SHOTLIST.md</a>.</em></sub>
</div>
@@ -31,19 +31,24 @@ An open-source, self-hostable AI SOC. The agent's prompts, tool calls, and ratio
## Try AiSOC in 60 seconds
-Three fastest paths to a live, seeded AiSOC investigation. Pick whichever matches what you already have on your machine:
+Four fastest paths to a working AiSOC investigation. Pick whichever matches what you already have on your machine:
| If you have… | Run this | What you get |
|---------------------------------------|----------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
+| **Python 3.10+** (no Docker) | `pip install -e packages/aisoc-sandbox && aisoc-sandbox demo` | Offline agent investigation walked through Detect → Triage → Hunt → Respond and printed to stdout. **< 5 s.** No API key, no network. |
| **A browser** (zero install) | [Open in Codespaces](https://codespaces.new/beenuar/AiSOC?quickstart=1) | Browser IDE → `pnpm aisoc:demo --no-open` → click forwarded port `3000`. ~5 min cold. |
| **Docker + pnpm** | `git clone https://github.com/beenuar/AiSOC && cd AiSOC && pnpm aisoc:demo` | Local stack on Postgres + Redis + Kafka + api + agents + web. Browser opens at `INC-RT-001`. |
| **Nothing** (clean Linux/macOS/Win) | `curl -fsSL https://raw.githubusercontent.com/beenuar/AiSOC/main/install.sh \| bash` | Bootstraps Docker, Node, pnpm, git for you; then runs `pnpm aisoc:demo`. |
-You land on `/cases/INC-RT-001?tab=ledger`: a LockBit 3.0 ransomware case mid-investigation, with the AI agent's prompts, tool calls, and rationale streaming into the [Investigation Ledger](apps/docs/docs/console/investigation-rail.md). Stop with `pnpm aisoc:demo:down`.
+The first row is new: [`aisoc-sandbox`](packages/aisoc-sandbox/) is a zero-dependency, in-memory simulator of the agent funnel. Pick a [bundled scenario](packages/aisoc-sandbox/README.md#bundled-scenarios) (`lateral-movement`, `aws-credential-exfil`, `phishing-payload`, `kubernetes-privesc`, `github-token-theft`) or feed in your own JSON via `--file`. The other three rows boot the real stack and land you on `/cases/INC-RT-001?tab=ledger` — a LockBit 3.0 ransomware case mid-investigation, with the AI agent's prompts, tool calls, and rationale streaming into the [Investigation Ledger](apps/docs/docs/console/investigation-rail.md). Stop the real stack with `pnpm aisoc:demo:down`.
-> **Want a hosted demo without spinning anything up?** The community-maintained <https://tryaisoc.com> instance runs a copy on Fly.io. It may go offline (see [LIVE-DEMO.md](LIVE-DEMO.md)) — Codespaces is the always-on fallback.
+> **Does the demo still boot on `main`?** Every push runs [`compose-smoke`](https://github.com/beenuar/AiSOC/actions/workflows/compose-smoke.yml) (the same `pnpm aisoc:demo` path you'd run locally) and [`e2e`](https://github.com/beenuar/AiSOC/actions/workflows/e2e.yml) against the seeded console; nightly [`compose-smoke-nightly`](https://github.com/beenuar/AiSOC/actions/workflows/compose-smoke-nightly.yml) repeats it with cold caches. A red badge below is a release-blocker.
+>
+> [![Compose Smoke](https://img.shields.io/github/actions/workflow/status/beenuar/AiSOC/compose-smoke.yml?branch=main&label=compose-smoke%20%28main%29&style=flat-square)](https://github.com/beenuar/AiSOC/actions/workflows/compose-smoke.yml)
+> [![Nightly cold cache](https://img.shields.io/github/actions/workflow/status/beenuar/AiSOC/compose-smoke-nightly.yml?branch=main&label=compose-smoke%20%28nightly%2C%20cold%29&style=flat-square)](https://github.com/beenuar/AiSOC/actions/workflows/compose-smoke-nightly.yml)
+> [![E2E](https://img.shields.io/github/actions/workflow/status/beenuar/AiSOC/e2e.yml?branch=main&label=e2e%20%28seeded%20console%29&style=flat-square)](https://github.com/beenuar/AiSOC/actions/workflows/e2e.yml)
-Full multi-platform deploy guide: [Deploy in 60 seconds](#deploy-in-60-seconds) (Render, Fly.io, Docker Compose, Kubernetes, Terraform). Production-grade install with full storage tier: [`infra/helm/`](infra/helm/) or [`infra/terraform/`](infra/terraform/).
+Full multi-platform deploy guide is in [`apps/docs/docs/installation.md`](apps/docs/docs/installation.md) (Render, Fly.io, Docker Compose, Kubernetes, Terraform). Production-grade install with full storage tier: [`infra/helm/`](infra/helm/) or [`infra/terraform/`](infra/terraform/).
---
@@ -54,31 +59,13 @@ AiSOC is a single self-hostable stack that ingests security events, correlates t
Three properties distinguish it from closed-source AI SOC vendors:
1. **Agent decisions are logged.** The Investigation Ledger stores the LLM prompt, the response, the evidence cited, and the downstream tool calls for every step of every run. Replays are available later.
-2. **The substrate has a public eval harness in CI.** Five suites gate every PR targeting `main` / `develop`: a 200-incident synthetic dataset drawn from 55 distinct templates drives the MITRE-tactic, investigation-completeness, and response-quality gates (each reporting both a per-case mean and a per-template macro so a single broken template can't hide behind 199 working duplicates); a separately generated 1,000-alert noisy stream drives the alert-reduction gate; and a schema/coverage gate validates `synthetic_telemetry.jsonl` — the companion corpus of ~360 backing events across 14 log sources (Sysmon, Windows Security, M365 audit, Azure sign-in, CloudTrail, Linux auditd, journald, EDR, DNS, web access, Kubernetes audit, GitHub audit, VPN, DB audit) that connector and Sigma PRs can wire against. Alert reduction is a real measurement against the fixed alert stream; the three rubric-based suites are substrate self-consistency gates over deterministic templates. The [benchmark page](apps/docs/docs/benchmark.md) explains exactly which is which.
+2. **The substrate has a public eval harness in CI.** Five suites gate every PR targeting `main` / `develop` — alert reduction is a real measurement against a fixed 1 000-alert stream; three rubric-based suites are substrate self-consistency gates over a deterministic 200-incident dataset (55 templates) with per-template macros; a fifth gate validates the backing telemetry corpus. The [benchmark page](apps/docs/docs/benchmark.md) documents exactly what each suite measures and what it does not.
3. **It runs entirely on your infrastructure.** No callbacks to a vendor cloud and no data exfiltration for "model improvement."
The orchestrator is a ~600-line LangGraph in [`services/agents/`](services/agents/). It is small enough to read end-to-end, swap models in, and patch.
---
-## What's new
-
-`VERSION` is `7.5.0` (2026-06-29) — a v8.0-milestone and trust-readiness release that tags the `AiSOC missing pieces — Phases 1–5` rollup ([PR #337](https://github.com/beenuar/AiSOC/pull/337)), the four named v8.0 milestones (T3.7 NL→playbook, T3.8 design system v2 + Storybook, T4 wave-3 marketplace + 6 hardened connectors, T5.3 fidelity loaders), threat-actor attribution port fix + optional RBAC, realtime short-lived-ticket auth, boundary-aware KB chunker, Terraform CI, and a large Dependabot + security sweep.
-
-- **Latest GitHub release with downloads:** <https://github.com/beenuar/AiSOC/releases/latest>
-- **Per-release narrative (mirrors what used to live here):** [`RELEASES.md`](RELEASES.md)
-- **Machine-readable inventory with file paths, env-var diffs, test counts:** [`CHANGELOG.md`](CHANGELOG.md)
-- **v8.0 wave-2 in flight (`[~]` items):** [`AISOC_V8_PROGRESS.md`](AISOC_V8_PROGRESS.md)
-
-<details>
-<summary><strong>Click for the highlight reel that used to live here (v7.5.0 → v7.4.0 → v1.5 → architectural foundation → security & correctness wave).</strong> The full per-release narrative is now maintained in <a href="RELEASES.md"><code>RELEASES.md</code></a> so the front page stays scannable.</summary>
-
-The "What's new" section that used to live on this README in full is now in [`RELEASES.md`](RELEASES.md) so this page stays focused on "what is AiSOC and how do I run it." Open [`RELEASES.md`](RELEASES.md) for the full v7.5.0 → v7.4.0 → v1.5 narrative.
-
-</details>
-
----
-
## How AiSOC compares
| Capability | AiSOC | Wazuh | Splunk ES | Closed-source AI SOC |
@@ -88,7 +75,7 @@ The "What's new" section that used to live on this README in full is now in [`RE
| Autonomous AI investigation | LangGraph | no | partial (Splunk AI) | yes |
| Agent decision audit trail | public Investigation Ledger | n/a | n/a | not published |
| Public substrate eval harness | CI-gated, reproducible, with synthetic telemetry corpus + per-template macros | n/a | n/a | not published |
-| Detection content | 800 native + 6,000+ imported (Sigma / Splunk / Chronicle / CAR) | 1,200+ rules | 1,000+ apps | curated |
+| Detection content | 800 native + 6 000+ imported (Sigma / Splunk / Chronicle / CAR) | 1 200+ rules | 1 000+ apps | curated |
| Plugin SDK | Python / TypeScript / Go | YAML rules only | apps | proprietary |
| Data residency | your infra | your infra | partial | vendor cloud |
| Pricing | $0 (self-host) | $0 (self-host) | per ingest GB | enterprise |
@@ -97,236 +84,19 @@ Closed-source AI SOC vendors ship working products. AiSOC's contribution is maki
---
-## Deploy in 60 seconds
-
-Four frictionless paths to a running, seeded AiSOC instance with `INC-RT-001` (the LockBit 3.0 ransomware showcase) already mid-investigation when you land on it. Each path runs `alembic upgrade head` and `python -m app.scripts.seed_demo` as part of its lifecycle, so the seeded data is present without a manual step.
-
-### 0. One-click installer — zero prerequisites
-
-Don't have Docker, Node, pnpm, or even git installed? Use the bootstrap installer. It detects your OS, installs everything idempotently, clones the repo, and launches the demo.
-
-```bash
-# Linux + macOS (one-liner):
-curl -fsSL https://raw.githubusercontent.com/beenuar/AiSOC/main/install.sh | bash
-
-# Windows (PowerShell as Administrator):
-iwr -useb https://raw.githubusercontent.com/beenuar/AiSOC/main/install.ps1 | iex
-```
-
-The installer covers Ubuntu/Debian (`apt`), Fedora/RHEL (`dnf`), Arch (`pacman`), openSUSE (`zypper`), Alpine (`apk`), macOS (`brew`), and Windows (`winget`). On Windows it also handles WSL2 enablement for Docker Desktop. Re-running is safe — every step is idempotent. To uninstall later, `./uninstall.sh` (Linux/macOS) or `.\uninstall.ps1` (Windows). See the [Quick install guide](docs/QUICK_INSTALL.md) for flags, troubleshooting, and what gets installed.
-
-### 1. Render — one click, hosted
-
-[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/beenuar/AiSOC)
-
-Render reads [`render.yaml`](render.yaml) at the repo root, provisions Postgres + Redis, and brings up the demo profile (api, agents, web, realtime). The `preDeployCommand` migrates and seeds, so the canonical `INC-RT-001` is present on first boot. Sleep-on-idle on the hobby tier; flip to standard instances for production. Demo runs deterministic-mode by default — no OpenAI/Anthropic key needed. See [`infra/render/README.md`](infra/render/README.md) for cost, scaling, and BYO-LLM details.
-
-### 2. Docker Compose — one command, local
-
-```bash
-git clone https://github.com/beenuar/AiSOC.git && cd AiSOC && pnpm aisoc:demo
-```
-
-Pulls prebuilt `ghcr.io/beenuar/*` images, brings up the slim demo profile (Postgres, Redis, Kafka, api, agents, realtime, web), runs the seeder as a one-shot container, and opens your browser at `/cases/INC-RT-001?tab=ledger` with `[email protected]` already auto-logged-in. Idempotent: re-running is a no-op against a seeded volume. Target on a clean Mac with a warm Docker daemon: clone-to-investigation in **~3.5 min warm / ~5 min cold**. Stop with `pnpm aisoc:demo:down`. See [One-shot demo](#one-shot-demo) for the timing breakdown and what you'll see on screen.
-
-**Screencast path — `--quick` mode:** for a deterministic four-case demo that runs in under four minutes on a warm laptop (the path the [90-second screencast](apps/web/public/.demo-mp4-placeholder) records against), pass `--quick`:
-
-```bash
-pnpm aisoc:demo --quick # 4 cases in 4 minutes
-```
-
-This seeds exactly four cases — `DEMO-001` (spear-phishing), `DEMO-002` (cloud takeover), `DEMO-003` (insider exfil), `DEMO-004` (ransomware) — with byte-stable UUIDs and timestamps, then lands the browser on `DEMO-004`. Re-running cleans the four cases and reseeds, so it doubles as a reset button. Run `pnpm aisoc:demo --help` for the full flag list.
-
-### 3. Fly.io — one script, hosted, persistent
-
-```bash
-git clone https://github.com/beenuar/AiSOC.git && cd AiSOC
-./infra/fly/fly-demo-deploy.sh --provision # first run: also creates Postgres + Upstash
-./infra/fly/fly-demo-deploy.sh # subsequent runs: deploys updates
-```
-
-Idempotent shell wrapper around `flyctl` that deploys four apps (api, agents, web, realtime) plus managed Postgres + Upstash Redis, wires the `*.internal` 6PN DNS between them, runs migrations + seeding as a `release_command`, and issues TLS certs for your domain. ~$14/mo at idle. **Time-to-first-investigation budget: <60s from the click**, since the seeder pre-warms a running investigation so the deeplink lands inside the TTFI budget regardless of cold-start. See [`infra/fly/README.md`](infra/fly/README.md) for DNS prerequisites and per-app sizing.
-
-> **Production-grade install?** Skip the demo paths above and use [`infra/helm/`](infra/helm/) (Kubernetes) or [`infra/terraform/`](infra/terraform/) (AWS). Both bring up the full storage tier — ClickHouse, Kafka, OpenSearch, Neo4j, Qdrant — gated behind compose profiles in the demo paths above.
-
----
-
-## Deployment options
-
-Each target ships a tested config in [`infra/`](infra/):
-
-| Platform | Status | Config | Notes |
-|---|---|---|---|
-| Fly.io | first-class | [`infra/fly/`](infra/fly/) | 4 apps, ~$14/mo. See [infra/fly/README.md](infra/fly/README.md). |
-| Render | supported | [`render.yaml`](render.yaml) + [`infra/render/`](infra/render/) | Sleep-on-idle, hobbyist tier. One-click via blueprint button. |
-| Railway | supported | [`infra/railway/railway.toml`](infra/railway/railway.toml) | PaaS, pay-as-you-go. |
-| Coolify | supported | [`docker-compose.yml`](docker-compose.yml) | Self-hosted on your own VPS. See [infra/coolify/README.md](infra/coolify/README.md). |
-| Kubernetes / Helm | first-class | [`infra/helm/`](infra/helm/) | `helm install aisoc ./infra/helm/aisoc` |
-| AWS / Terraform | first-class | [`infra/terraform/`](infra/terraform/) | `cd infra/terraform && terraform apply` |
-
-The Render, Railway, and Coolify configs deploy the lean demo profile: api, agents, web, realtime, Postgres, and Redis. ClickHouse, Kafka, OpenSearch, Neo4j, and Qdrant are gated behind compose profiles. For a production-grade install with the full storage tier, use Helm or Terraform.
-
----
-
-## Use it from Claude, Cursor, or Cody
-
-AiSOC ships an [MCP server](https://modelcontextprotocol.io) so analysts can query alerts, run agent investigations, and replay every step the agent took without leaving the IDE or chat.
-
-```bash
-# Claude Desktop / Cursor / Continue / Cody
-npx -y @aisoc/mcp install --host claude \
- --aisoc-url https://aisoc.your-company.com \
- --api-key aisoc_pat_xxxxxxxxxxxx
-```
+## What you'll see in the console
-The server exposes 13 tools — discovery (`aisoc_list_alerts`, `aisoc_list_cases`, `aisoc_query_detections`, `aisoc_list_investigations`, `aisoc_lake_schema`), deep-dive (`aisoc_get_alert`, `aisoc_get_case`, `aisoc_get_detection_rule`, `aisoc_get_investigation`), lake query (`aisoc_lake_query` — warm-tier SELECT, gated by `lake:query` server-side), and the action/replay set (`aisoc_run_investigation`, `aisoc_replay_decision`, `aisoc_explain_step`) for walking the agent decision ledger step-by-step.
-
-Full guide: [docs/integrations/mcp](apps/docs/docs/integrations/mcp.md). Source: [`services/mcp/`](services/mcp/). npm: `@aisoc/mcp`.
-
----
-
-## What's in the box
+<div align="center">
-AiSOC bundles the components a SOC normally pieces together from separate vendors:
-
-- **Connect data sources in three clicks** — a 69-connector click-and-connect catalog spans EDR/XDR (CrowdStrike Falcon, SentinelOne, Microsoft Defender XDR, Palo Alto Cortex XDR, Cortex XSIAM, VMware Carbon Black, Trellix Helix, Trend Vision One), SIEM (Splunk, Microsoft Sentinel, Elastic, Sumo Logic, Datadog Cloud SIEM, Google Chronicle, Rapid7 InsightIDR), cloud + CNAPP (AWS Security Hub, AWS GuardDuty, AWS CloudTrail, AWS VPC Flow Logs, Azure Activity, Azure Defender, GCP Cloud Audit, GCP SCC, Wiz, Lacework, Tenable, Prisma Cloud, Orca), identity (Okta, Microsoft Entra, Auth0, Duo Security, 1Password), SaaS (Microsoft 365 audit, Google Workspace, Cloudflare, Proofpoint, Mimecast, ServiceNow, Jira, Slack audit, Salesforce, Email inbox), VCS (GitHub, Snyk), endpoint fleet (osctrl, FleetDM for fleet-wide osquery), container + orchestration (Kubernetes audit logs via apiserver webhook or `audit.log` tail), and network (Tailscale, Zscaler, Cisco Umbrella). Each connector renders a schema-driven form, runs a live `Test connection` round-trip before save, encrypts every secret with the application-layer `CredentialVault` (Fernet AES-128-CBC + HMAC-SHA256), and starts polling on a per-instance schedule. Walkthrough: [docs/connectors](apps/docs/docs/connectors/index.md). Threat model + key rotation: [docs/operations/credentials](apps/docs/docs/operations/credentials.md).
-- **Own your endpoint telemetry** — first-party `aisoc-osquery-tls` FastAPI service (`services/osquery-tls/`) and `aisoc-direct` lightweight agent connector ship a self-hosted osquery TLS plugin, FleetDM-compatible config/log endpoints, and a direct-from-agent ingest path that bypasses third-party SaaS. Built-in **file integrity monitoring (FIM)** endpoint (`services/osquery-tls/app/api/v1/endpoints/fim.py`) ingests `file_events` and synthesizes alerts on writes to `/etc/passwd`, `/etc/shadow`, sshd configs, sudoers, and Windows registry hives; bundled osquery packs cover incident response, OSquery-ATT&CK, and FIM out of the box. **16 native osquery detections** (`detections/endpoint/osquery-*.yaml`, IDs `det-endpoint-281..296`) cover credential access, persistence, lateral movement, defense evasion, and discovery — paired with positive/negative test fixtures (`detections/fixtures/osquery_*.json`) and CI-gated against the Detection Validation workflow. **Live-query playbook step** (`osquery_live_query`) lets responders push allowlisted distributed queries to single hosts or fleet-wide via osctrl/FleetDM with HMAC-signed ChatOps approval. **5 custom Go-based virtual tables** (`services/osquery-extensions/`) extend the agent with `aisoc_browser_extensions`, `aisoc_kernel_modules`, `aisoc_attck_persistence`, `aisoc_pending_actions`, and `aisoc_alert_cache` for richer endpoint visibility and bidirectional response. Walkthroughs: [docs/connectors/osctrl](apps/docs/docs/connectors/osctrl.md), [docs/connectors/fleetdm](apps/docs/docs/connectors/fleetdm.md).
-- **Ingest** events from any connector into a Kafka spine.
-- **Correlate** them in real time with deduplication, ML scoring, per-alert confidence scoring, and Sigma/YARA detection.
-- **Roll up signal onto entities** — Risk-Based Alerting accumulates time-decayed risk points on the user, host, IP, and domain each alert touches, promotes them to entity-incidents at a tunable threshold, and surfaces an entity-centric queue in the alerts UI. Hits the published 2026 KPI bar of ≥ 50:1 alert-to-incident ratio (CI-gated in [`services/fusion/tests/test_entity_risk.py`](services/fusion/tests/test_entity_risk.py)).
-- **Search across SIEMs** — Federated Search fans out a single query to connected Splunk, Microsoft Sentinel, and Elastic instances, translating the query into each target's native dialect (SPL, KQL, ES|QL) via pluggable translators in [`services/connectors/app/federated/`](services/connectors/app/federated/).
-- **Manage detections as code** — Detection-as-Code (DAC) provides a propose → review → eval-gate → promote lifecycle for detection rules. Every proposal carries an eval result from the harness; candidates that regress MITRE accuracy cannot be promoted. Endpoints in [`services/api/app/api/v1/endpoints/detection_proposals.py`](services/api/app/api/v1/endpoints/detection_proposals.py).
-- **Run hypothesis-driven hunts on a schedule** — Hunt-as-Code YAML definitions in [`hunts/`](hunts/) declare a hypothesis, MITRE ATT&CK tags, log sources, indicators, and a cron schedule. The hunt engine in [`services/agents/app/hunt/`](services/agents/app/hunt/) loads the corpus at startup, runs hunts on their schedule, and stores findings in the DB.
-- **Track detection drift** — the Purple Team service takes ATT&CK coverage snapshots and diffs them over time, so you can see which techniques gained or lost coverage between releases. Implementation in [`services/purple-team/app/services/drift.py`](services/purple-team/app/services/drift.py).
-- **Verify ChatOps actions** — HMAC-signed approval prompts are sent to Slack or Teams before high-impact SOAR actions execute, with a time-limited verification token. Implementation in [`services/actions/app/executors/chatops.py`](services/actions/app/executors/chatops.py).
-- **Benchmark against adversary LLMs** — a deterministic attacker-LLM mutator generates adversary incidents to test detection resilience. Script: [`scripts/generate_adversary_incidents.py`](scripts/generate_adversary_incidents.py); eval: [`services/agents/tests/test_adversary_eval.py`](services/agents/tests/test_adversary_eval.py).
-- **Enrich** every signal with threat intelligence from TAXII 2.1, MISP, OTX, and CISA KEV.
-- **Reason** about attacks via a LangGraph multi-agent system grounded in MITRE ATT&CK.
-- **Detect deviations** with UEBA — per-user behavioural baselines and Z-score anomaly scoring.
-- **Trap adversaries** with HMAC-signed honeytokens (URLs, files, AWS credentials, emails).
-- **Validate coverage** with automated Atomic Red Team and Caldera adversary emulation.
-- **Respond** with blast-radius-aware SOAR actions, every step explainable.
-- **Govern** with multi-tenant RLS, granular RBAC, immutable audit logs, and SOC 2 / ISO 27001 / NIST CSF / PCI-DSS / HIPAA / DORA evidence dashboards.
-- **Manage at scale** with an MSSP parent-tenant console — onboard child tenants, delegate actions cross-tenant, and view rollup metrics in one pane.
-- **Track assets** with an asset inventory that auto-correlates vulnerabilities to alerts and surfaces asset blast radius.
-- **Detect insider threats** with user risk profiles, behavioural indicators, and peer-group deviation scoring.
-- **Gate automation** through L0–L4 maturity tiers — each tier unlocks progressively more autonomous remediation, with per-action whitelist and full audit gate log.
-- **Generate internal threat intelligence** — harvest IOCs from alert history, track threat actors and campaigns, subscribe to external STIX/TAXII feeds, all queryable via the REST API.
-- **Assess cloud posture** with a built-in CSPM/KSPM engine that ingests findings, tracks drift between scan runs, and surfaces a per-provider summary with suppress/resolve workflows.
-- **Correlate through identities** with a graph of users, devices, and service accounts; link alerts to identity nodes for blast-radius queries and attack-path reconstruction.
-- **Automate board reporting** — schedule PDF/HTML executive summaries, store artefacts, and deliver via email or webhook.
-- **Three-tier agent memory** — session (in-process LRU), working (Redis-backed, 24 h TTL), and institutional (PostgreSQL + pgvector, permanent). Agents carry context across tool calls, cases, and sessions; institutional knowledge survives restarts.
-- **Autonomy guardrails** — per-action confidence thresholds (e.g. `block_ip ≥ 0.90`, `close_alert ≥ 0.60`) gate every autonomous decision. Tenant admins can tighten or loosen thresholds via API; all guard-rail decisions are logged.
-- **Investigation cost telemetry** — every LLM call is tracked by model, prompt tokens, completion tokens, latency, and estimated USD cost. Aggregates are persisted per-run to `aisoc_run_costs` and surfaced in SOC dashboards.
-- **SOC metrics dashboard** — live MTTD, MTTR, False Positive Rate, alert/case volumes (rolling 7 d), and ATT&CK technique heatmap. Backed by a real-time API endpoint and a polished React component.
-- **Analyst-override feedback loop with retroactive re-disposition** — analysts correct AI verdicts (`true_positive`, `false_positive`, `benign`, `escalate`) in one click. Corrections persist on the alert, flow into `aisoc_institutional_memory` keyed by an alert signature (category + connector + primary MITRE technique), and adjust FPR metrics automatically. The API surfaces *retroactive candidates* — past alerts in the same tenant matching the same signature whose disposition would now flip — for one-click bulk re-disposition.
-- **Natural-language detection authoring** — describe a threat in plain English; the API translates it to Sigma YAML, KQL (Microsoft Sentinel), SPL (Splunk), and ES|QL (Elastic) simultaneously. Falls back to curated templates when no LLM key is configured.
-- **Closed-loop detection engineering** — when an alert is marked as a false positive, the agent drafts a Sigma rule fix using an LLM, then automatically creates a Detection-as-Code proposal routed through the same human-review DAC workflow. CI re-runs evals on approval; regression gates block regressions.
-- **Natural-language query execution** — ask a security question in plain English (`POST /nl-query/execute`). The API translates it to ES|QL, SPL, and KQL; for Elasticsearch-backed tenants it executes the ES|QL query live and returns structured results, column metadata, and the query text for all three dialects.
-- **Identity-centric investigation timeline** — build a chronological event timeline anchored to any user, device, service account, or IP (`POST /identity-timeline/build`). The timeline queries alerts and raw events, annotates each event with the relevant ATT&CK technique, computes an entity risk score, and returns a sorted, deduplicated event list for triage.
-- **Cross-platform detection translation** — convert any detection rule bidirectionally between Sigma YAML, Splunk SPL, Microsoft Sentinel KQL, Elastic ES|QL, and Google Chronicle YARA-L2 / UDM Search (`POST /translation/translate`). An LLM handles complex logic; a regex fallback handles simple field-mapping rules with no external dependency.
-- **Hypothesis-driven hunt workbench** — define a hunt hypothesis in natural language (`POST /hunts`); the API auto-generates ready-to-execute queries in ES|QL, SPL, and KQL; analysts record findings against any run and the workbench tracks open, completed, and inconclusive hunts.
-- **Phishing triage workflow** — submit raw email text, URLs, attachments, or domain indicators (`POST /phishing/submit`); the LLM extracts IOCs, assigns a verdict (phishing / benign / spam / malware / unknown), maps to MITRE ATT&CK, and optionally links the submission to an existing case.
-- **Knowledge-base + RAG** — ingest runbooks, policies, SOPs, and wikis (`POST /kb/ingest`); the API chunks and full-text indexes each document; analysts query with natural language (`POST /kb/query`) and receive the top matching chunks plus an LLM-synthesised answer with citation, backed by PostgreSQL FTS when no vector store is configured.
-
-### v7.0 — buyer-value plan (2026-05-10)
-
-Shipped by Beenu Arora <[email protected]>. All 16 workstreams:
-
-- **Slack ChatOps bot** — `/aisoc triage`, `/aisoc approve`, `/aisoc status`, `/aisoc summary` slash commands + interactive approval buttons. Human-in-the-loop gate works from Slack without opening the console. 61 pytest cases. (`services/slack-bot/`)
-- **Executive digest PDF** — branded A4 PDF with KPI tiles, alert-volume chart, top-rule table, and remediation summary. Auto-emailed Monday 06:00 UTC via APScheduler. (`services/api/app/services/digest_pdf.py`, `weekly_digest_task.py`)
-- **AI investigation timeline (replayable)** — 684-line React component rendering the Investigation Ledger as a playable step-by-step timeline with scrubber. (`apps/web/src/components/copilot/InvestigationTimeline.tsx`)
-- **Case auto-summary + PDF export** — LLM-powered structured case summary (headline, severity rationale, recommended action, evidence links). (`case_summary.py`, `case_summary_html.py`)
-- **Playbook gallery** — 12 curated packs (Phishing, Ransomware, BEC, IAM Key Compromise, …) with TTP coverage badges and one-click import. 25 YAML templates added under `detections/playbooks/`.
-- **GitHub PR integration** — detection proposals automatically create draft PRs against the tenant's detection repo when promoted. (`services/api/app/services/github.py`)
-- **BYOK per-tenant LLM credentials UI** — provider picker (OpenAI, Azure OpenAI, Anthropic, Ollama), API-key input, model selector, temperature slider, and connection test. (`SettingsView.tsx`, `llm_credentials.py`)
-- **WCAG AA accessibility** — axe-core CI gate covers 5 views + 3 modals; sidebar landmark roles, ARIA labels, focus trapping, skip-nav link, colour-contrast fixes. (`apps/web/src/test/a11y.test.tsx`)
-- **Light theme persisted in user profile** — stored in `localStorage`, synced to `PATCH /api/v1/users/me/preferences`. (`ThemeProvider.tsx`)
-- **Saved views + drag-drop dashboard widgets** — widgets can be dragged, dropped, resized, pinned, removed; layout serialised to `POST /api/v1/saved-views`. (`DashboardView.tsx`, `saved_views.py`)
-- **Threat actor attribution engine v0** — weighted IOC / TTP / Tool / Target scoring against three seed actor profiles (APT28, APT29, Lazarus). `POST /actors/attribute`. (`services/threatintel/app/actors/attribution.py`)
-- **Air-gap / Ollama local-LLM mode** — `docker-compose.airgap.yml` override; disables external feed pullers, enables Ollama sidecar; step-by-step deployment guide in docs. (`docker-compose.airgap.yml`, `apps/docs/docs/operations/air-gapped.md`)
-- **MSSP console improvements** — `GET /mssp/tenants` aggregation: per-child alert counts, open cases, SLA breach rate, last-seen connector heartbeat; `parent_tenant_id` + `mssp_role` added to `Tenant` model.
-- **Team analytics view** — analyst leaderboard, MTTR per analyst, cases closed per shift, FP rate trend. (`TeamAnalyticsView.tsx`)
-- **Air-gap LLM status endpoint** — reports whether air-gap mode is active and which Ollama models are available; drives the settings UI model picker. (`llm_status.py`)
-
-Everything ships under MIT. Fork it, self-host it, audit it, extend it.
+| <a href="apps/docs/docs/console/queue.md"><img src="apps/web/public/screenshots/01-alerts-queue.svg" alt="Alerts queue with SLA countdowns" width="100%" /></a> | <a href="apps/docs/docs/console/investigation-rail.md"><img src="apps/web/public/screenshots/02-investigation-rail.svg" alt="Investigation Rail with deterministic correlation narrative" width="100%" /></a> |
+|:---:|:---:|
+| **Alerts queue** — server-anchored SLA countdowns, atomic claim, one-click triage. [Docs](apps/docs/docs/console/queue.md) | **Investigation Rail** — narrative, pivot-path entity chips, 6-event timeline, recommended actions. [Docs](apps/docs/docs/console/investigation-rail.md) |
+| <a href="apps/docs/docs/console/rule-tuning.md"><img src="apps/web/public/screenshots/03-hunt-workbench.svg" alt="Natural-language /hunt workbench" width="100%" /></a> | <a href="apps/docs/docs/plugins/overview.md"><img src="apps/web/public/screenshots/04-marketplace.svg" alt="Plugin and detection marketplace" width="100%" /></a> |
+| **`/hunt` workbench** — type a hypothesis in English, get ES&#124;QL / SPL / KQL back, save + schedule. [Docs](apps/docs/docs/console/rule-tuning.md) | **Marketplace** — plugins, playbooks, detections with one-click tenant install. [Docs](apps/docs/docs/plugins/overview.md) |
----
+<sub><em>The four tiles above are SVG placeholders. Real PNG screenshots ship with the next Phase 2 visuals rollup; the [walkthrough video](apps/web/public/demo/) at the top of this README is the canonical reference until then.</em></sub>
-## Highlights
-
-<table>
-<tr>
-<td valign="top" width="50%">
-
-### Real-time fusion
-- Kafka spine with sub-second ingestion
-- Bloom-filter dedup on 10M+ IOCs
-- LightGBM + Isolation Forest scoring
-- Per-alert confidence scoring (source reliability × indicator fidelity)
-- Risk-Based Alerting entity rollup (≥ 50:1 alert-to-incident, CI-gated)
-- Live WebSocket feed into the console
-
-### AI Copilot
-- LangGraph agents with persistent memory
-- Qdrant RAG over MITRE ATT&CK + tenant data
-- Natural-language threat hunts
-- Every decision traceable end-to-end
-
-### Knowledge graph
-- Neo4j entity graph (hosts, users, alerts, IOCs)
-- Attack-path reconstruction per case
-- Blast-radius gating on automated actions
-
-### UEBA
-- Per-user Welford online baseline (no batch jobs)
-- Z-score anomaly scoring with peer-group analysis
-- Kafka integration: `security.events` → `security.anomalies`
-- Feeds directly into ML fusion scoring
-
-</td>
-<td valign="top" width="50%">
-
-### Detection engineering
-- Detection-as-Code (DAC) lifecycle: propose → review → eval-gate → promote
-- Sigma over OpenSearch + ClickHouse
-- YARA file/memory scanning
-- KQL, EQL, Lucene, regex query types
-- Community detection catalog with one-click install
-- Detection drift snapshots (ATT&CK coverage deltas between releases)
-- Hunt-as-Code: YAML hunt definitions with cron schedules
-
-### Federated search
-- Fan out a single query to Splunk, Sentinel, and Elastic
-- Pluggable translators: SPL, KQL, ES|QL
-
-### Honeytokens
-- HMAC-SHA256 signed tokens (URL, file, AWS key, email)
-- First-touch webhook alerting
-- Token lifecycle: active / triggered / expired
-- Built-in lure URL copy and share
-
-### Purple Team
-- Atomic Red Team YAML parser + Caldera executor
-- ATT&CK coverage heatmap (tactic × technique)
-- Detection reporting (true positive / false negative)
-- Tabletop exercise session manager
-- Detection drift monitoring
-
-### Governance
-- SAML 2.0 + OIDC SSO
-- Multi-tenant Postgres RLS
-- Granular RBAC (`resource:action` permissions)
-- Immutable audit log with tamper-proof trigger
-- Evidence dashboards with controls mapped to SOC 2, ISO 27001, NIST CSF, PCI-DSS, HIPAA, and DORA
- — to help your team gather audit evidence, not a claim that AiSOC itself holds any of these certifications.
- Live audit-track status: Managed SaaS (SOC 2 in progress, GDPR target).
-- MTTD / MTTR / MTTC SLA tracking
-- ChatOps verification (HMAC-signed Slack/Teams approval prompts)
-
-</td>
-</tr>
-</table>
+</div>
---
@@ -343,7 +113,7 @@ flowchart LR
end
subgraph Ingest["Ingest & Normalize"]
- Connectors["Connectors\n(Python · 50 vendors)"]
+ Connectors["Connectors\n(Python · 69 vendors)"]
OsqueryTLS["osquery-tls\n(Python · host telemetry)"]
IngestSvc["Ingest worker\n(Go · OCSF)"]
Enrich["Enrichment\n(Go · IOC + Shodan)"]
@@ -356,720 +126,101 @@ flowchart LR
subgraph Detect["Detect & Reason"]
Fusion["Fusion\n(Python · ML)"]
UEBA["UEBA\n(Python · baseline)"]
- TI["Threat Intel\n(TAXII / MISP / OTX)"]
Rules["Rule engine\n(Sigma · YARA · KQL)"]
Agents["AI Agents\n(LangGraph)"]
- HT["Honeytokens\n(Python)"]
- PT["Purple Team\n(ART + Caldera)"]
end
subgraph Storage["Storage Tier"]
- PG[("PostgreSQL\nconfig · cases · RLS")]
- CH[("ClickHouse\nevents · metrics")]
- OS[("OpenSearch\nIOCs · search")]
- QD[("Qdrant\nvector RAG")]
- N4[("Neo4j\nattack graph")]
- RD[("Redis\ncache · pub/sub")]
+ PG[("PostgreSQL")]
+ CH[("ClickHouse")]
+ OS[("OpenSearch")]
+ QD[("Qdrant")]
+ N4[("Neo4j")]
+ RD[("Redis")]
end
subgraph Surface["Surface"]
API["Core API\n(FastAPI)"]
- RT["Realtime\n(Node · WS + Web Push)"]
- Web["Web Console + Responder PWA\n(Next.js 14)"]
- Actions["Actions / SOAR\n(Python)"]
- Slack["Slack Bot\n(Python · ChatOps)"]
+ Web["Web Console + Responder PWA\n(Next.js)"]
MCP["MCP Server\n(TS · stdio)"]
end
Sources --> Connectors --> IngestSvc --> Kafka
OsqueryTLS --> IngestSvc
IngestSvc --> Enrich --> Kafka
- Kafka --> Fusion --> Kafka
+ Kafka --> Fusion --> Storage
Kafka --> UEBA --> Kafka
Kafka --> Rules --> Kafka
- TI --> Storage
- Fusion --> Storage
- HT --> Kafka
- PT --> API
- Agents --> QD
- Agents --> N4
+ Agents --> Storage
API --> Storage
- RT --> Kafka
Web --> API
- Web --> RT
- Actions --> Kafka
- Slack --> API
- Slack --> Actions
MCP --> API
```
-**v1.5 console:** On `/alerts/[id]`, the **Investigation Rail** surfaces fusion correlation narrative, evidence chips, and Deep Explain (LLM) with audit logging. See [Investigation Rail](apps/docs/docs/console/investigation-rail.md) in the docs site.
-
-### Service map
-
-| Service | Lang | Port | Role |
-|---|---|---|---|
-| `web` | Next.js 14 + React | 3000 | SOC console (alerts detail + Investigation Rail), benchmark scoreboard, marketing landing |
-| `api` | Python · FastAPI | 8000 | Alerts (detail envelope + correlation narrative), cases, RBAC, graph, rules, audit, compliance, detection proposals (DAC), federated search fan-out, SLA tracking |
-| `realtime` | Node.js · `ws` | 8086 | Per-channel WebSocket fan-out + VAPID Web Push |
-| `agents` | Python · LangGraph | 8001 | Multi-agent reasoning + Qdrant RAG + Hunt-as-Code engine & scheduler |
-| `fusion` | Python | 8003 | Dedup + ML scoring (LightGBM, IsoForest), alert confidence, entity risk / RBA, correlation narrative projection for API |
-| `actions` | Python | 8002 | SOAR with blast-radius gating + ChatOps verification |
-| `connectors` | Python | — | Connector polling (APScheduler), credential vault, federated query translators |
-| `threatintel` | Python | 8005 | TAXII / MISP / OTX / KEV polling |
-| `ueba` | Python | 8007 | User & Entity Behavior Analytics |
-| `honeytokens` | Python | 8008 | Honeytoken lifecycle + webhook alerting |
-| `purple-team` | Python | 8006 | Atomic Red Team + Caldera + ATT&CK heatmap + detection drift snapshots |
-| `osquery-tls` | Python | 8091 | Native osquery TLS server — enroll nodes, distribute packs, stream FIM/process/network telemetry |
-| `osquery-extensions` | Python | — | Custom osquery extensions (AI-powered threat intel table, ML anomaly score table) |
-| `slack-bot` | Python | 8009 | ChatOps surface — interactive approvals for high-blast-radius actions, `/aisoc` slash command, HMAC-signed Slack signature verification |
-| `mcp` | TypeScript | — (stdio) | Model Context Protocol server exposing 13 AiSOC tools — discovery, deep-dive, action/replay, and warm-tier lake query (`aisoc_lake_query`, gated by `lake:query` server-side) — to IDE-side AI agents (Claude Code, Cursor, Continue, Cody) |
-| `ingest` | Go | 8081 | OCSF normalization + Shodan/CVE |
-| `enrichment` | Go | 8080 | IOC enrichment (VT, AbuseIPDB, GreyNoise) |
-
-### Storage tier
-
-| Store | Purpose |
-|---|---|
-| PostgreSQL | Tenants, users, cases, detection rules, RBAC, audit log, compliance · Row-level security |
-| ClickHouse | High-cardinality event analytics + alert metrics |
-| OpenSearch | Full-text IOC + actor + report search · Sigma backend |
-| Qdrant | Vector RAG for agents, semantic ATT&CK lookup |
-| Neo4j | Knowledge graph: entities, attack paths, blast radius |
-| Redis | Cache, pub/sub, IOC bloom filter, enrichment TTL |
-| Kafka | Event streaming spine (raw, fused, vulnerability, anomaly, action) |
-
----
-
-## Console tour
-
-The console fuses the analyst's day-zero workflow into one surface:
-
-- **Dashboard** — KPI tiles, trend chart, and a WebSocket-driven event ticker.
-- **Alerts & Cases** — triage queues, status workflow, evidence timeline.
-- **Investigation Ledger** — replayable, step-by-step record of every prompt, tool call, and rationale the agent emitted on a case.
-- **Attack Graph** — Cytoscape + fcose layout over the Neo4j subgraph for a case.
-- **MITRE Heatmap** — coverage tiles with per-tactic technique density.
-- **Threat Hunting** — Sigma / KQL / YARA editor with on-demand hunts.
-- **Detection Rules** — Monaco-powered rule builder with Sigma autocompletion.
-- **Detection Catalog** — community Sigma rules with one-click tenant install.
-- **Threat Intel** — IOC search, feed status, and STIX / MISP source health.
-- **Marketplace** — plugins, playbooks, and detections, with ratings, badges, and category filters.
-- **Playbooks** — community and private playbooks with SOAR automation.
-- **UEBA** — behavioural anomaly feed and peer-group deviation chart.
-- **Honeytokens** — create lures, view trigger log, copy lure URLs.
-- **Purple Team** — ATT&CK heatmap, execution tracker, tabletop sessions.
-- **Compliance** — SOC 2 / ISO 27001 / NIST CSF / PCI-DSS / HIPAA / DORA evidence.
-- **SLA Dashboard** — MTTD, MTTR, MTTC metrics + breach alerts.
-- **Audit Log** — immutable, paginated, tenant-scoped event history.
-- **Benchmark** — public eval harness (alert-reduction measurement plus three substrate self-consistency gates), run in CI.
-- **Investigation Chat** — multi-turn conversational copilot at `/investigate` for case-scoped follow-up Q&A.
-- **Coverage Advisor** — MITRE ATT&CK coverage gap finder with prioritized rule recommendations.
-- **Shifts** — outgoing/incoming analyst handoff dashboard with active cases and queued approvals.
-- **EASM** — external attack surface inventory: assets, exposed services, certificate-expiry monitor.
-- **Noise Tuning** — per-rule false-positive analytics and one-click tuning suggestions.
-- **MSSP Dashboard** — multi-tenant executive rollup with cross-tenant KPIs and SLA posture.
-- **Team Analytics** — analyst leaderboard, MTTR per analyst, disposition accuracy, shift load balance.
-- **Settings → RBAC** — roles, permissions, and user-role assignments.
-- **Ambient Copilot** — context-aware next-action suggestions on alert, case, rule, and playbook pages. Each suggestion runs the right tool with the right payload.
-- **AI Copilot dock** — slide-over invoked with `⌘J` for any page.
-- **Command palette** — global `⌘K` for navigation, quick actions, and Copilot.
-
-### Responder PWA
-
-A separate, installable PWA route at `/responder/*` for analysts who carry a pager:
-
-- **Passkey login** — WebAuthn / FIDO2 platform authenticators only, no SMS fallback.
-- **On-call view** — current responder per tenant, surfaced in alerts on the desktop console too.
-- **Approvals queue** — long-lived approval requests for blast-radius-gated SOAR actions, signed off with a hardware-attested passkey.
-- **Push notifications** — VAPID-signed Web Push delivered through `services/realtime`, following the on-call rotation.
-- **Offline shell** — service worker + cached app shell so the responder surface keeps loading on a flaky carrier link.
-
-See [`apps/web/src/app/(responder)/`](apps/web/src/app/(responder)/) and [`services/api/migrations/009_responder_pwa.sql`](services/api/migrations/009_responder_pwa.sql).
-
-The marketing landing lives at `/` and the console at `/dashboard`. Both share the same brand tokens.
-
----
-
-## Quick start
-
-### One-shot demo
-
-To see AiSOC investigate an in-flight ransomware case in your browser:
-
-```bash
-git clone https://github.com/beenuar/AiSOC.git
-cd AiSOC
-pnpm aisoc:demo
-```
-
-That single command:
-
-1. Pulls prebuilt images from `ghcr.io/beenuar/*` (api, agents, web, realtime).
-2. Brings up the slim demo profile — Postgres, Redis, Kafka, api, agents, realtime, web.
-3. Runs the canonical-data seeder (`services/api/app/scripts/seed_demo.py`) as a one-shot container that exits when finished. The seeder is idempotent: re-running it is a no-op against an already-seeded volume.
-4. Locates `INC-RT-001` — a LockBit 3.0 ransomware investigation that's mid-stream when you arrive (encryption is in progress, the agent is streaming decisions to the Investigation Ledger, an auto-isolation playbook is mid-DAG).
-5. Opens your browser directly at `/cases/INC-RT-001?tab=ledger`, with the demo analyst (`[email protected]`) already auto-logged-in.
-
-Target on a clean Mac with a warm Docker daemon: **clone-to-investigation in under 5 minutes**.
-
-| Step | Time |
-|---|---|
-| `docker compose pull` (cold) | ~90s |
-| `docker compose up` + healthchecks | ~60s |
-| Seed canonical data (one-shot container) | ~30s |
-| Kick off live investigation step | ~30s |
-| Total | ~3.5 min warm / ~5 min cold |
-
-What you'll see when the browser opens:
-
-- **Investigation Ledger** — the agent's per-step prompt, response, evidence cited, and tool calls for `INC-RT-001`, replayable from any step.
-- **Decision graph** — Cytoscape view of the LangGraph traversal that produced the verdict.
-- **Playbook timeline** — the in-flight ransomware containment DAG, with completed and pending steps.
-- **15 other seeded cases** — phishing, credential access, lateral movement, exfiltration, cloud takeover — across `INC-PH-*`, `INC-CR-*`, `INC-LM-*`, `INC-EX-*`, `INC-CL-*` series, all with populated alerts, IOCs, and ledger artifacts.
-
-When you're done: `pnpm aisoc:demo:down` (stops containers and deletes the demo volumes).
-
-#### Hosted, public-internet equivalent
-
-The same stack ships a Cloudflare Tunnel template (see [Public demo on your own domain](#public-demo-on-your-own-domain)) and tested deployment configs for [Render](render.yaml) and [Fly.io](infra/fly/) — both wire `alembic upgrade head && python -m app.scripts.seed_demo` into the deploy lifecycle so the same `INC-RT-001` showcase is present after `render blueprint launch` or `fly deploy`.
-
-The full development quick start with all services (UEBA, Honeytokens, Purple Team, ClickHouse, OpenSearch, Neo4j, Qdrant) is below.
-
-### Public demo on your own domain
-
-The same demo stack can be reached from the public internet without exposing
-ports, opening firewall rules, or paying for a cloud VM. AiSOC ships a
-Cloudflare Tunnel template plus a wrapper script that:
-
-1. Brings up the slim demo profile via `pnpm aisoc:demo --no-open` (Postgres, Redis, Kafka, api, agents, realtime, web).
-2. Creates a named `cloudflared` tunnel (or reuses one if it already exists).
-3. Renders an ingress config from [`infra/cloudflare/config.yml.example`](infra/cloudflare/config.yml.example) into `~/.cloudflared/<tunnel-name>.yml`, after validating it with `cloudflared tunnel ingress validate`.
-4. Adds DNS routes on your zone so the apex (`https://<your-domain>`) and the `api`, `ws`, `docs` subdomains all resolve to the tunnel.
-5. Runs `cloudflared tunnel run` in the foreground (Ctrl+C exits cleanly; the local stack keeps running).
-
-The result: a publicly reachable, fully self-hosted SOC console, served from
-your laptop, accepting only traffic that came in through Cloudflare. No
-inbound ports are opened on your router or firewall.
-
-#### Prerequisites
-
-- A domain whose DNS is managed by Cloudflare.
-- The [`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/) CLI installed locally (`brew install cloudflared` on macOS).
-- One of two auth methods (the script accepts either):
- - **(A) Origin-cert flow:** run `cloudflared tunnel login` once on this machine — it drops a `cert.pem` in `~/.cloudflared/` that authorises this host to manage tunnels and DNS records on the zone. The script will then create the tunnel, render the ingress config, and wire DNS automatically.
- - **(B) Tunnel-token flow ★:** create a tunnel in the Cloudflare Zero Trust dashboard (Networks → Tunnels → *Create a tunnel* → Cloudflared), configure the four public hostnames (apex/api/ws/docs → `localhost:3000/8000/8086/3001`), and copy the `--token ey…` value the dashboard hands you. No `cert.pem` required, no local DNS plumbing. Useful when the browser-based `cloudflared tunnel login` won't write a cert (corporate browsers, headless boxes, etc).
-
-#### Run it
-
-```bash
-# (A) Origin-cert flow — script manages tunnel, ingress, and DNS:
-pnpm demo:public # default: tryaisoc.com
-DOMAIN=demo.example.com pnpm demo:public # any zone you control
-
-# (B) Tunnel-token flow — dashboard owns the tunnel, ingress, and DNS:
-export CLOUDFLARE_TUNNEL_TOKEN='ey…' # paste the token from the dashboard
-pnpm demo:public # script auto-detects the token
-
-# Already have the local stack running? Just bring the tunnel up:
-pnpm demo:public:tunnel-only # works for both auth modes
-
-# Just provision the tunnel + DNS, but don't run cloudflared
-# (origin-cert flow only — useful before `cloudflared service install`
-# to leave it running 24/7):
-SKIP_RUN=1 pnpm demo:public:setup
-```
-
-All env vars are forwarded to [`infra/cloudflare/tunnel.sh`](infra/cloudflare/tunnel.sh):
-`DOMAIN` (apex, default `tryaisoc.com`), `TUNNEL_NAME` (default `aisoc-tryaisoc`,
-ignored in token mode), `SUBDOMAINS` (default `"api ws docs"`, ignored in token
-mode), `SKIP_DNS=1` (don't touch DNS records), `SKIP_RUN=1` (set up everything
-but don't run the tunnel), and `CLOUDFLARE_TUNNEL_TOKEN` (switch to flow B).
-Run `bash scripts/demo-public.sh --help` to see the full set, or read
-[`infra/cloudflare/README.md`](infra/cloudflare/README.md) for the topology
-diagram and production-hardening notes (running `cloudflared` as a launchd /
-systemd service, layering Cloudflare Access in front, etc).
-
-#### Stop it
-
-```bash
-# Ctrl-C in the tunnel terminal stops cloudflared.
-# Then bring the local stack down:
-pnpm aisoc:demo:down
-```
-
-The `tryaisoc.com` instance linked at the top of this README is exactly that:
-this script, running from a maintainer's machine. The tunnel infra is
-upstream so anyone can do the same on their own domain.
-
-### Full stack (development)
-
-> **Heads-up — this is the developer-build path.**
-> If you just want to *see* AiSOC investigate cases in your browser, use [`pnpm aisoc:demo`](#one-shot-demo) above instead — it pulls prebuilt images from `ghcr.io/beenuar/*` and is up in ~5 minutes.
-> The full stack below builds **22 services from source** (Python, Go, Node, Next.js) and brings up a heavy datastore tier (Postgres, Redis, Kafka, ClickHouse, OpenSearch, Neo4j, Qdrant). Only use this path if you're hacking on the source.
-
-#### Prerequisites
-
-- **Docker 24+** with **Docker Compose v2** (built into Docker Desktop). Run `docker compose version` to confirm — Compose v1's `docker-compose` is not supported.
-- **Docker resources**: at minimum **6 GB of RAM** and **20 GB of free disk** allocated to the Docker daemon. On Docker Desktop: *Settings → Resources*. The OpenSearch + ClickHouse + Neo4j + Kafka quartet alone reserves ~3.5 GB at idle; under-provisioning causes silent OOM-kills that surface as opaque "container exited" errors.
-- **Node.js 20+** and **pnpm 8+** (`corepack enable` then `corepack prepare [email protected] --activate`).
-- **Go 1.21+** and **Python 3.11+** are only required if you plan to run individual services *outside* the compose stack.
-- A free **8 GB of disk** for the build cache and image layers, on top of the 20 GB allocated to Docker.
-
-Run `pnpm aisoc:doctor` after cloning — it sanity-checks Docker, Compose v2, allocated RAM, and host port availability before you spend 10 minutes on a build that's destined to fail.
-
-#### 1. Clone
-
-```bash
-git clone https://github.com/beenuar/AiSOC.git
-cd AiSOC
-cp .env.example .env
-```
-
-#### 2. Configure
-
-```env
-# AI providers (one required)
-ANTHROPIC_API_KEY=sk-ant-...
-OPENAI_API_KEY=sk-...
-
-# Optional enrichment
-CYBLE_API_KEY=...
-VIRUSTOTAL_API_KEY=...
-ABUSEIPDB_API_KEY=...
-GREYNOISE_API_KEY=...
-SHODAN_API_KEY=...
-
-# Optional TAXII feeds
-TAXII_FEEDS=https://cti-taxii.mitre.org/taxii/,enterprise-attack,,
-
-# Optional SSO (SAML 2.0)
-SAML_IDP_METADATA_URL=https://your-idp.example.com/metadata
-
-# Optional SSO (OIDC)
-OIDC_DISCOVERY_URL=https://your-idp.example.com/.well-known/openid-configuration
-OIDC_CLIENT_ID=aisoc
-OIDC_CLIENT_SECRET=...
-
-# Optional Purple Team
-CALDERA_URL=http://localhost:8888
-CALDERA_API_KEY=...
-ATOMIC_RED_TEAM_PATH=/opt/atomic-red-team/atomics
-```
-
-#### 3. Boot
-
-```bash
-# Optional: pre-flight check (Docker daemon, RAM, ports) before a long build
-pnpm aisoc:doctor
-
-# Build and start all 22 services. Cold first run: 10-20 min (build) + ~90s (warm-up).
-# Subsequent runs reuse cached layers and start in ~90s.
-docker compose up -d --build
-
-# Watch services come up
-docker compose ps
-```
-
-The first invocation on a clean checkout will pull ~5 GB of base images and compile every Python, Go, and Next.js service from source. Plan for **10-20 minutes** on a typical laptop. After that, layers are cached and `docker compose up -d` is roughly 90 seconds.
-
-If the build aborts, check Docker Desktop *Settings → Resources* — under-provisioning RAM is the #1 cause of opaque failures, particularly for the Kafka, OpenSearch, ClickHouse, and Neo4j containers.
-
-#### 4. Seed demo data
-
-```bash
-pnpm seed:demo # generates cases, alerts, IOCs, attack paths, UEBA anomalies
-```
-
-#### 5. Verify
-
-```bash
-pnpm aisoc:doctor # health check: ports, containers, demo data, API + WS
-```
-
-If any check fails, the doctor tells you exactly what to fix before logging in.
-
-#### 5b. Run the public eval harness (optional)
-
-```bash
-# Run all five substrate eval suites against the bundled 200-incident
-# dataset (55 distinct templates) and its companion synthetic_telemetry.jsonl
-# corpus, then write a machine-readable report. The dataset size is fixed by
-# services/agents/tests/eval_data/synthetic_incidents.json — there is no
-# --count flag.
-python scripts/run_evals.py --out eval_report.json
-
-# Or run a single eval gate
-pytest services/agents/tests/test_mitre_accuracy.py
-pytest services/agents/tests/test_synthetic_telemetry.py # schema + coverage gate
-
-# Regenerate the dataset and the backing telemetry corpus from scratch
-# (e.g. after adding a template). Both files are written deterministically
-# from a seeded RNG.
-python scripts/generate_eval_incidents.py
-```
-
-The harness writes `eval_report.json` and `eval_mitre_accuracy_report.json`, which the [public eval harness page](apps/docs/docs/benchmark.md) renders. Each scoring suite reports both a per-case mean and a per-template macro across the 55 templates — the macro is the regression signal that doesn't dilute when the dataset is enlarged. The same harness runs in CI on every PR targeting `main` / `develop` — see [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
-
-The harness runs deterministic substrate code (extractors, fusion, templates, judges) against synthetic data — it does not call the live LLM agent. Three of the four scoring metrics are substrate self-consistency gates rather than agent accuracy scores; the synthetic-telemetry suite is a schema/coverage gate, not a score. The [benchmark page](apps/docs/docs/benchmark.md) documents what each suite measures and what it does not.
-
-#### 6. Open
-
-| Surface | URL | Notes |
-|---|---|---|
-| Marketing | http://localhost:3000 | Public landing page |
-| Console | http://localhost:3000/dashboard | Default user: `[email protected]` / `changeme` |
-| API (Swagger) | http://localhost:8000/docs | REST + GraphQL endpoints |
-| Agents | http://localhost:8001/docs | LangGraph runner |
-| UEBA | http://localhost:8007/docs | Behavioural analytics |
-| Honeytokens | http://localhost:8008/docs | Honeytoken lifecycle |
-| Purple Team | http://localhost:8006/docs | Adversary emulation |
-| osquery TLS | http://localhost:8091/docs | Node enrolment + pack distribution + FIM stream (`osquery` profile) |
-| Kafka UI | http://localhost:8090 | Kafka topic + consumer-group inspector |
-| Realtime WS | ws://localhost:8086/ws/alerts | Live alert channel |
-| Neo4j | http://localhost:7474 | `neo4j` / `neo4j_dev_secret` |
-| Grafana | http://localhost:3001 | `admin` / `admin` (`monitoring` profile) |
-| Jaeger | http://localhost:16686 | Distributed traces (`monitoring` profile) |
-
-#### Optional profiles
-
-```bash
-docker compose --profile connectors up -d # CrowdStrike, Splunk, AWS, Okta, Sentinel
-docker compose --profile monitoring up -d # Prometheus, Grafana, Jaeger, OTel Collector
-```
+Full architecture (every service, every storage role, the v1.5 console workbench, and the Investigation Ledger contract) is in [`apps/docs/docs/architecture.md`](apps/docs/docs/architecture.md). The deeper system-design write-up — including ML fusion, the Neo4j-at-ingest schema, and the threat-intel pipeline — lives at [`docs/architecture/SYSTEM_DESIGN.md`](docs/architecture/SYSTEM_DESIGN.md). The full monorepo layout is at [`apps/docs/docs/architecture/overview.md`](apps/docs/docs/architecture/overview.md).
---
-## Monorepo layout
-
-```
-AiSOC/
-├── apps/
-│ ├── web/ # Next.js 14 console + marketing landing + Responder PWA route
-│ └── docs/ # Docusaurus documentation site
-├── services/
-│ ├── api/ # Core REST API + Neo4j graph + rule engine + auth + RBAC + compliance + ledger
-│ ├── ingest/ # Go · OCSF normalization · Shodan + CVE
-│ ├── enrichment/ # Go · IOC enrichment
-│ ├── fusion/ # Python · dedup + ML scoring
-│ ├── agents/ # Python · LangGraph + Qdrant RAG + investigation ledger writer
-│ ├── actions/ # Python · SOAR + blast-radius gating
-│ ├── threatintel/ # Python · TAXII / MISP / OTX / KEV
-│ ├── realtime/ # Node.js · per-channel WebSocket fan-out + VAPID Web Push
-│ ├── ueba/ # Python · User & Entity Behavior Analytics
-│ ├── honeytokens/ # Python · deceptive credential traps
-│ ├── purple-team/ # Python · Atomic Red Team + Caldera + ATT&CK
-│ ├── osquery-tls/ # Python · native osquery TLS server + FIM + pack distribution
-│ ├── osquery-extensions/ # Python · AI threat-intel table + ML anomaly score table
-│ └── mcp/ # TypeScript · Model Context Protocol server (@aisoc/mcp)
-├── integrations/ # Connector implementations (CrowdStrike, Splunk, AWS, …)
-├── packages/
-│ ├── types/ # Shared TS types
-│ ├── ui/ # Shared React primitives
-│ ├── ocsf/ # OCSF normalization helpers
-│ ├── sdk-ts/ # TypeScript client SDK for AiSOC API (npm: @aisoc/sdk)
-│ ├── sdk-py/ # Async Python client SDK (PyPI: aisoc-sdk)
-│ ├── sdk-go/ # Go client SDK + models (module: github.com/beenuar/aisoc/sdk-go)
-│ ├── plugin-sdk-ts/ # TypeScript plugin development SDK
-│ ├── plugin-sdk-py/ # Python plugin development SDK (PyPI: aisoc-plugin-sdk)
-│ ├── plugin-sdk-go/ # Go plugin development SDK (module: github.com/beenuar/aisoc/plugin-sdk-go)
-│ └── aisoc-cli/ # CLI: scaffold / validate / publish plugins & detections
-├── detections/ # Community Sigma detection rules (YAML)
-├── hunts/ # Hunt-as-Code YAML definitions (hypothesis + indicators + schedule)
-├── playbooks/ # Community SOAR playbooks (YAML)
-├── plugins/ # First-party plugins (Go + Python)
-├── marketplace/ # Marketplace index (JSON, generated by scripts/build_marketplace.py)
-├── infra/
-│ ├── coolify/ # Coolify (self-hosted Heroku-style PaaS) quickstart
-│ ├── fly/ # Fly.io machines + deploy script
-│ ├── railway/ # Railway template (railway.toml)
-│ ├── render/ # Render blueprint (render.yaml)
-│ ├── terraform/ # AWS (VPC, EKS, RDS, ElastiCache, MSK)
-│ └── helm/ # Kubernetes Helm chart (HPA, PDB, Ingress per service)
-├── docs/
-│ ├── openapi.yaml # OpenAPI 3.1 spec
-│ ├── architecture/ # System design docs
-│ └── operations/ # Runbooks + multi-region guide
-└── scripts/
- ├── aisoc-demo.ts # One-shot demo orchestrator (powers `pnpm aisoc:demo`)
- ├── aisoc-doctor.ts # Local health check
- ├── run_evals.py # Public eval harness (per-case + per-template macros, telemetry coverage)
- ├── generate_eval_incidents.py # 200-incident synthetic generator (55 templates) + synthetic_telemetry.jsonl
- ├── build_marketplace.py # Build marketplace/index.json from detections+playbooks+plugins
- ├── validate_detections.py # YAML schema validation for Sigma detections
- ├── validate_playbooks.py # YAML schema validation for playbooks
- ├── backup.sh # Postgres + ClickHouse + plugins → S3/R2
- ├── restore.sh # Point-in-time restore
- └── generate_runbook.py # Auto-generate runbooks from OTel traces
-```
+## What's in the box
----
+A handful of headline capabilities — the rest are catalogued in [`apps/docs/docs/features/`](apps/docs/docs/features/) and indexed at the top of [`apps/docs/docs/intro.md`](apps/docs/docs/intro.md):
-## API reference
-
-The full OpenAPI 3.1 spec lives at [`docs/openapi.yaml`](docs/openapi.yaml). Endpoint groups:
-
-| Tag | Prefix | Notes |
-|---|---|---|
-| `auth` | `/api/v1/auth/` | JWT login, SAML ACS, OIDC callback |
-| `alerts` | `/api/v1/alerts/` | CRUD, bulk status, timeline, detail envelope (`investigation_rail`, `correlation_narrative`, `deep_explain`) |
-| `cases` | `/api/v1/cases/` | Create, link alerts, evidence |
-| `rules` | `/api/v1/rules/` | Sigma / YARA / KQL CRUD + test |
-| `detections` | `/api/v1/detections/` | Catalog browse + install |
-| `detection-proposals` | `/api/v1/detection-proposals/` | DAC lifecycle: propose, review, eval-gate, promote |
-| `federated` | `/api/v1/federated/` | Fan-out query to connected SIEMs (Splunk, Sentinel, Elastic) |
-| `hunts` | `/api/v1/hunts/` | Hunt-as-Code: list, get, run, findings |
-| `entity-risk` | `/api/v1/entity-risk/` | RBA: top entities by risk score, entity detail |
-| `plugins` | `/api/v1/plugins/` | Registry, publish, rate, approve |
-| `playbooks` | `/api/v1/playbooks/` | Community + private playbooks |
-| `marketplace` | `/api/v1/marketplace/` | Plugin marketplace with filters |
-| `compliance` | `/api/v1/compliance/` | SOC 2 / ISO 27001 / NIST CSF / PCI / HIPAA / DORA |
-| `audit` | `/api/v1/audit/` | Immutable audit log, paginated |
-| `rbac` | `/api/v1/rbac/` | Roles, permissions, user-role assignments |
-| `sla` | `/api/v1/sla/` | MTTD/MTTR/MTTC metrics + breach log |
-| `ueba` | `/api/v1/ueba/` | Anomaly feed + baseline stats |
-| `honeytokens` | `/api/v1/honeytokens/` | Token lifecycle + trigger events |
-| `purple-team` | `/api/v1/purple-team/` | Atomic tests, executions, tabletop sessions |
-| `graph` | `/api/v1/graph/` | Neo4j subgraph for a case |
-| `intel` | `/api/v1/intel/` | IOC search, feed status |
-| `graphql` | `/graphql` | GraphQL schema (alerts, cases, intel) |
-
-Interactive docs: `http://localhost:8000/docs` (Swagger) or `http://localhost:8000/redoc` (ReDoc).
+- **69 click-and-connect data connectors** (EDR/XDR, SIEM, cloud, CNAPP, identity, SaaS, VCS, K8s audit, network) with schema-driven config, live `Test connection`, and vault-encrypted secrets. Walkthrough: [`apps/docs/docs/connectors/index.md`](apps/docs/docs/connectors/index.md).
+- **Investigation Rail + replayable Investigation Ledger** — every prompt, tool call, evidence chip, and rationale stored against a case, replayable in the UI. [`apps/docs/docs/console/investigation-rail.md`](apps/docs/docs/console/investigation-rail.md).
+- **Detection-as-Code lifecycle** — propose → review → eval-gate → promote; CI rejects any candidate that regresses MITRE accuracy. [`apps/docs/docs/concepts/detection-as-code.md`](apps/docs/docs/concepts/detection-as-code.md) — and the 800+ native Sigma rules live in [`detections/`](detections/).
+- **L0–L4 automation maturity** — gate every autonomous action on per-action confidence thresholds and blast-radius. [`apps/docs/docs/concepts/automation-maturity.md`](apps/docs/docs/concepts/automation-maturity.md).
+- **Hunt-as-Code** — YAML hypotheses with MITRE tags, cron schedules, and natural-language `/hunt` workbench. [`hunts/`](hunts/) + [`apps/docs/docs/console/rule-tuning.md`](apps/docs/docs/console/rule-tuning.md).
+- **Public weekly benchmark scoreboard** — the same harness that gates PRs, run weekly against `main`. [`apps/docs/docs/benchmark-scoreboard.mdx`](apps/docs/docs/benchmark-scoreboard.mdx).
---
-## Plugin and detection SDK
-
-The CLI is published as a Python package. Install it with `pipx` (recommended) or `pip`:
-
-```bash
-pipx install aisoc-cli # PyPI release
-# or, from the monorepo:
-pip install -e packages/aisoc-cli
-
-# Scaffold a new plugin
-aisoc scaffold plugin my-connector
-
-# Validate a detection rule
-aisoc validate detection ./detections/my-rule.yaml
-
-# Publish to community registry (Ed25519 signed)
-aisoc publish plugin ./my-connector --key ~/.aisoc/signing.key
-```
-
-SDKs:
+## Use it from Claude, Cursor, or Cody
-- TypeScript — `packages/plugin-sdk-ts` (npm: `@aisoc/plugin-sdk`)
-- Python — `packages/plugin-sdk-py` (PyPI: `aisoc-plugin-sdk`)
-- Go — `packages/plugin-sdk-go` (module: `github.com/beenuar/aisoc/plugin-sdk-go`)
+AiSOC ships an [MCP server](https://modelcontextprotocol.io) (`services/mcp/`) so analysts can query alerts, run agent investigations, and replay every step the agent took without leaving the IDE or chat. The server exposes 13 tools — discovery, deep-dive, governed lake query, and the action / replay set that walks the agent decision ledger step-by-step.
-Detection authors can drop YAML rules directly into `detections/` and SOAR playbooks into `playbooks/`. CI validates them on every PR ([`scripts/validate_detections.py`](scripts/validate_detections.py), [`scripts/validate_playbooks.py`](scripts/validate_playbooks.py)) and [`scripts/build_marketplace.py`](scripts/build_marketplace.py) republishes [`marketplace/index.json`](marketplace/index.json) so the in-app Marketplace picks them up automatically.
+> **Status — monorepo source build today; npm publish lands in v8.0.** Full setup is in [`apps/docs/docs/integrations/mcp.md`](apps/docs/docs/integrations/mcp.md), which shows the today-vs-v8.0 invocations side by side.
---
-## Development
+## Extend it
-### Frontend
+Three contribution surfaces; each is one file plus optional fixtures, and CI validates every PR.
-```bash
-cd apps/web
-pnpm install
-pnpm dev
-```
-
-### Backend (selective)
-
-```bash
-docker compose up -d postgres redis kafka clickhouse opensearch qdrant neo4j
-
-# Core API
-cd services/api && poetry install && poetry run uvicorn app.main:app --reload --port 8000
-
-# UEBA
-cd services/ueba && poetry install && poetry run uvicorn app.main:app --reload --port 8007
-
-# Honeytokens
-cd services/honeytokens && poetry install && poetry run uvicorn app.main:app --reload --port 8008
+- **Detection rule.** Drop a Sigma YAML under [`detections/`](detections/) with a positive / negative fixture in [`detections/fixtures/`](detections/fixtures/). The [validate-detections](https://github.com/beenuar/AiSOC/actions/workflows/validate-detections.yml) workflow tests it on every PR. Spec: [`docs/connectors/`](apps/docs/docs/connectors/).
+- **Connector.** Subclass `BaseConnector` in [`services/connectors/app/connectors/`](services/connectors/app/connectors/), register it in `_CONNECTOR_CLASSES`, and add a `plugins/<id>/plugin.yaml` manifest. The marketplace picks it up automatically. Walkthrough: [`apps/docs/docs/connectors/`](apps/docs/docs/connectors/).
+- **Playbook.** Drop a YAML under [`playbooks/`](playbooks/); [`validate-playbooks`](https://github.com/beenuar/AiSOC/actions/workflows/validate-playbooks.yml) gates the PR. Schema: [`playbook.schema.json`](playbook.schema.json).
-# Purple Team
-cd services/purple-team && poetry install && poetry run uvicorn app.main:app --reload --port 8006
-
-# Fusion
-cd services/fusion && poetry install && poetry run uvicorn app.main:app --reload --port 8003
-
-# Go services
-cd services/ingest && go run main.go
-```
-
-### Database migrations
-
-```bash
-# Run all migrations
-docker compose exec api alembic upgrade head
-
-# Per-service migrations
-cd services/ueba && poetry run alembic upgrade head
-cd services/honeytokens && poetry run alembic upgrade head
-cd services/purple-team && poetry run alembic upgrade head
-```
-
-### Tests
-
-```bash
-cd apps/web && pnpm test
-cd services/api && poetry run pytest
-cd services/ueba && poetry run pytest
-cd services/honeytokens && poetry run pytest
-cd services/purple-team && poetry run pytest
-cd services/ingest && go test ./...
-```
+Plugin and detection SDK (Python · TypeScript · Go) — see [`apps/docs/docs/plugins/overview.md`](apps/docs/docs/plugins/overview.md). The CLI (`aisoc-cli`) is in [`packages/aisoc-cli/`](packages/aisoc-cli/); PyPI publish lands in v8.0.
---
-## Deployment
-
-### Kubernetes
-
-```bash
-helm repo add bitnami https://charts.bitnami.com/bitnami
-helm install aisoc ./infra/helm/aisoc \
- --namespace aisoc \
- --create-namespace \
- --values ./infra/helm/aisoc/values.yaml \
- --set global.environment=production
-```
-
-The Helm chart includes HPA, PDB, and Ingress for every microservice.
-
-### Backup and restore
-
-```bash
-# Backup Postgres + ClickHouse + plugins to S3
-./scripts/backup.sh --target s3://my-bucket/aisoc-backups
-
-# Point-in-time restore
-./scripts/restore.sh --source s3://my-bucket/aisoc-backups/2026-05-03T10:00:00Z
-```
-
-### Multi-region
-
-See [`docs/operations/multi-region.md`](docs/operations/multi-region.md) for active-passive and active-active deployment guides.
-
-### Operational runbooks
-
-```bash
-# Auto-generate runbook from live OTel trace data
-python scripts/generate_runbook.py --service api --output docs/operations/runbooks/api.md
-```
+## Roadmap & releases
-### Terraform on AWS
-
-```bash
-cd infra/terraform
-terraform init
-terraform plan -var="environment=prod"
-terraform apply
-```
-
----
-
-## Roadmap
-
-The public roadmap lives in [ROADMAP.md](ROADMAP.md). All releases through **v7.5.0** have shipped, including:
-
-- **v7.5.0** — v8.0-milestone and trust-readiness release (2026-06-29): the `AiSOC missing pieces — Phases 1–5` rollup ([PR #337](https://github.com/beenuar/AiSOC/pull/337); 25 commits, 188 files, +23 743 / -907); the four named v8.0 milestones (T3.7 NL→playbook, T3.8 design system v2 + Storybook, T4 wave-3 marketplace + 6 hardened connectors, T5.3 AIT-LDS + MITRE Engenuity fidelity loaders); the marketing-shell unification on `tryaisoc.com` (single `StickyNav` + `sections/Footer` shell across `(marketing)/*`, `/not-found`, `/why-open-source`, `/benchmark`); the threat-actor attribution port fix + optional shared-secret RBAC on `/api/v1/actors/*`; the realtime short-lived-ticket auth on WS/SSE; the boundary-aware KB ingest chunker; the Terraform CI workflow + the three missing reusable infra modules (`rds`, `elasticache`, `kafka`); the deterministic NL → ES|QL / KQL / SPL translator at **81-case eval, 100 % syntactic + 100 % semantic**; and a large Dependabot + security sweep (`aiohttp` CVE-2026-34993 + CVE-2026-47265 cleared, pnpm audit high/critical findings cleared, FastAPI / `next` / `framer-motion` / `cryptography` updates across services).
-
-- **v6.0 / v6.1** — Investigation Ledger, Ambient Copilot, Responder PWA, public eval harness, MCP server, one-shot demo, autonomous triage agents, investigation chat, coverage advisor, shifts, EASM, MSSP dashboard, STIX/TAXII publishing, automated compliance evidence, AI-generated incident reports.
-- **v7.0** — v1.0 buyer-value plan (16 workstreams): SBOM/SLSA supply chain, threat-intel attribution, executive digest PDF, BYOK per-tenant LLM credentials, air-gap appliance, WCAG 2.2 AA accessibility, ChatOps, telemetry/analytics opt-in, one-click Render deploy.
-- **v7.0.1 — v7.0.3** — Endpoint telemetry wave: `osctrl` and `FleetDM` connectors, `aisoc-osquery-tls` FastAPI service, `aisoc-direct` agent connector, 16 native osquery detections (`det-endpoint-281..296`), live-query playbook step, osquery packs + FIM pipeline, 5 custom osquery virtual tables; plus 42 CodeQL alert resolutions and the `ClientOnly`/font-preload hydration fixes.
-- **v7.1.0** — Cloud Security Coverage Wave: documentation backfill for Wiz, AWS Security Hub, and Lacework; two new CNAPP connectors (Prisma Cloud, Orca); three native AWS connectors (GuardDuty, CloudTrail, VPC Flow Logs); dual-mode Kubernetes audit log connector (apiserver webhook + file_tail) with a new `k8s-audit` ingest template.
-- **v7.3.0** — Founder-flow series (PR1–PR7): `docker-compose.dev.yml` alias, `.env.example` cleanup with a pre-filled `AISOC_CREDENTIAL_KEY`, `scripts/run_evals.py --suite` CLI contract, `aisoc serve` / `aisoc db upgrade` / `aisoc mcp serve|install`, the `aisoc submit` CLI command + canonical `examples/alerts/lateral-movement.json` fixture, and the Path C founder-style CLI walkthrough in [`apps/docs/docs/quickstart.md`](apps/docs/docs/quickstart.md). The recorded "fresh-clone to first alert" demo now runs verbatim on `main`.
-- **v7.3.1** — Smoke-test hotfix: idempotent migrations (`005_compliance.sql`, `025_connectors_click_and_connect.sql`, new `042_alerts_schema_drift_fix.sql` adding eleven missing `alerts` columns), and a new `POST /api/v1/alerts/submit` endpoint that synthesises an `Alert` row directly from a batch of OCSF events. `aisoc submit` now targets the new endpoint, so the web console at `/alerts` lights up immediately on a fresh clone without Kafka / Fusion in the loop.
-- **v7.4.0** — Security-hardening and platform release (2026-05-29): prompt-injection sanitizer on the classification agents, cross-tenant isolation across the detection loop and the compliance / phishing / knowledge-base endpoints, a nightly cross-tenant RBAC regression gate, `cryptography` CVE clearance; `DetectAgent.process` wired to the `FusionEngine` with `/investigate` routed through the `RouterOrchestrator` behind `ROUTER_INVESTIGATE`; GCP (Cloud Run) and Azure (Container Apps) Terraform skeletons mirroring the AWS reference; restored live `/metrics` data on `tryaisoc.com/dashboard`; and a large Dependabot + CI maintenance sweep. This release tags the workbench, architectural-foundation, and platform work listed below, all of which had accumulated on `main` since `7.3.1`.
-- **v1.5 console workbench wave (PR-1 → PR-8)** — shipped in v7.4.0; the SOC operator surface stops being a list of pages and becomes a workbench:
- - **PR-1: Global time-window selector + topbar context** — one selector at the top of the console drives every page; persists across reloads, deep-linkable via URL param.
- - **PR-2: Tenant switcher + role badge** — MSSP operators flip tenants from the topbar; the role badge makes it impossible to confuse a `viewer` session with an `admin` session. New endpoint: `GET /api/v1/tenants/me/identity`.
- - **PR-3: Critical severity tier** — the severity ladder is now `info | low | medium | high | critical`. Vendor-native criticals map straight through; confidence (`alert.confidence`, 0–100) is now decoupled from severity.
- - **PR-4 / W6: Investigation Rail** — `/alerts` is now a two-pane workbench with narrative, related entities (`pivotPath` deep links), 6-event mini-timeline, and structured recommended actions. Fusion writes a deterministic correlation narrative at fuse time. Docs: [`apps/docs/docs/console/investigation-rail.md`](apps/docs/docs/console/investigation-rail.md).
- - **PR-5 / W7: Investigation Queue workbench** — `/queue` is the page a Tier-1 analyst lives on: server-anchored SLA countdowns, atomic claim semantics, one-click triage. Docs: [`apps/docs/docs/console/queue.md`](apps/docs/docs/console/queue.md).
- - **PR-6 / W8: Rule Tuning workbench** — `/detection/tuning` ranks noisy rules by precision impact and ships one-click suppression + allow-list edits with full audit trail. Docs: [`apps/docs/docs/console/rule-tuning.md`](apps/docs/docs/console/rule-tuning.md).
- - **PR-7: Operations funnel + pipeline health** — new `/metrics/funnel` and `/health/pipeline` endpoints feed the `FunnelKpiBar` (Detected → Triaged → Investigated → Resolved) and an Efficiency Report. Docs: [`apps/docs/docs/console/funnel-kpis.md`](apps/docs/docs/console/funnel-kpis.md).
- - **PR-8: Zero-prerequisite installer** — `install.sh` / `install.ps1` bootstrap from a clean machine (Docker, Compose, Node, pnpm, Python) with idempotency and a graduated `uninstall.sh`. Surfaced as **Path 0** in [`apps/docs/docs/quickstart.md`](apps/docs/docs/quickstart.md).
-- **Stage 2 / Stage 3 platform additions** — shipped in v7.4.0 alongside the architectural foundation below:
- - **Wazuh Indexer ingest connector** + auditd `file_tail` connector + `aisoc.rules` audit profile (replaces the host-agent dependency for Linux endpoint visibility). The connector registry now declares **69 first-party connectors**.
- - **Live Actions dispatcher** — generic vendor/capability surface; plugins register executors against the in-tree taxonomy (`isolate_host`, `disable_user`, `block_ip`, …) without forking. Docs: [`apps/docs/docs/concepts/live-actions.md`](apps/docs/docs/concepts/live-actions.md).
- - **Deterministic NL → ES|QL / KQL / SPL translator** — replaces the template fallback in `/nl_query` with an IR + grammar validator; 50-pair gold eval set scores 100% syntactic, 100% semantic. Air-gapped by default; optional `gpt-4o-mini` enhancement falls back deterministically.
- - **STIX → MISP push** + air-gap dry-run endpoint. Docs: [`apps/docs/docs/integrations/misp-push.md`](apps/docs/docs/integrations/misp-push.md).
- - **GCP Cloud Run + Cloud SQL Terraform skeleton** — serverless-first BYOC equivalent of the existing AWS module. Docs: [`apps/docs/docs/deployment/gcp.md`](apps/docs/docs/deployment/gcp.md).
- - **Azure Container Apps + Postgres Flexible Server Terraform skeleton** — file-for-file mirror of the GCP skeleton on Azure: Container Apps, VNet-private Postgres + Redis, Key Vault, ACR, per-service managed identities. Docs: [`apps/docs/docs/deployment/azure.md`](apps/docs/docs/deployment/azure.md).
- - **Blameless case post-mortem endpoint** — `GET /api/v1/cases/{case_id}/postmortem?format=json|html`; analyst handles are redacted from the narrative. Docs: [`apps/docs/docs/operations/case-reports.md`](apps/docs/docs/operations/case-reports.md).
- - **Per-rule cross-fire FP gate** — `services/agents/tests/test_detection_fp_rate.py` replays every rule's `match_when` against every *other* rule's positive fixture; 816 native rules, worst FPR 0.49% (5% ceiling).
-- **Architectural foundation (shipped in v7.4.0)** — landed by [#125](https://github.com/beenuar/AiSOC/pull/125) plus the security and correctness wave that followed:
- - **Graph at ingest** — Neo4j v1.0 schema (17 node labels, 14 edge types), batched UNWIND upserts off the Kafka consumer, `security.graph_updates` topic, and OCSF extractors for AWS Security Hub / GitHub audit / Okta system log / Kubernetes audit (`services/ingest/internal/graph/`).
- - **Four-agent rebrand** — `DetectAgent`, `TriageAgent`, `HuntAgent`, `RespondAgent` are now the public façade in `services/agents/app/agents/`, with back-compat aliases so existing imports keep working.
- - **`/hunt` natural-language surface** — `apps/web/src/app/(app)/hunt/` plus `services/api/app/api/v1/endpoints/saved_hunts.py`. Type a hypothesis in English, get ES|QL / SPL / KQL templates back, save and schedule the hunt.
- - **Sixteen first-party connectors** — wave-1 (6 fully tested: tines, torq, falco, pagerduty, opsgenie, confluence_audit) and wave-2 (10 wip, of which cloudflare_zt / sysdig / vault / snowflake already have full fixtures + tests).
- - **L0–L4 automation maturity** — `apps/web/content/papers/l0-l4-automation-maturity.md` + PDF, plus the marketing surfaces (sovereign one-pager, three anchor blog posts, reference-customer template).
- - **Public weekly benchmark scoreboard** — `apps/docs/docs/benchmark-scoreboard.mdx` + `apps/docs/static/data/scoreboard.json`, fed by the weekly `wet-eval.yml` GitHub Action.
- - **Security wave** — 12 critical/high CVE-class fixes that landed ahead of v7.4.0: rule-engine `eval()` RCE elimination ([#116](https://github.com/beenuar/AiSOC/pull/116)), `/hunts` and `/cases` tenant isolation ([#117](https://github.com/beenuar/AiSOC/pull/117), [#118](https://github.com/beenuar/AiSOC/pull/118)), CORS lockdown ([#119](https://github.com/beenuar/AiSOC/pull/119)), playbook SSRF guard ([#120](https://github.com/beenuar/AiSOC/pull/120)), plugin-manager OCI install hardening ([#121](https://github.com/beenuar/AiSOC/pull/121)), audit-log trust-boundary closures ([#122](https://github.com/beenuar/AiSOC/pull/122)), `/alerts/submit` abuse + replay hardening ([#123](https://github.com/beenuar/AiSOC/pull/123)), Pydantic v1 → v2 settings migration ([#124](https://github.com/beenuar/AiSOC/pull/124)), bounded eval + playbook timeouts ([#126](https://github.com/beenuar/AiSOC/pull/126)), dev-mode unification ([#127](https://github.com/beenuar/AiSOC/pull/127)), and untrusted-enrichment sanitisation before LLM ([#128](https://github.com/beenuar/AiSOC/pull/128)).
- - **Static-analysis hygiene** — Python CodeQL alert count on `main` driven to zero by [#133](https://github.com/beenuar/AiSOC/pull/133), [#136](https://github.com/beenuar/AiSOC/pull/136), and [#137](https://github.com/beenuar/AiSOC/pull/137); enforced as a CI gate going forward.
- - **First community contribution** — [#135](https://github.com/beenuar/AiSOC/pull/135) (UEBA service environment-variable alignment, closes [#134](https://github.com/beenuar/AiSOC/issues/134)). Every UEBA variable now accepts both unprefixed (`DATABASE_URL`) and legacy (`UEBA_DATABASE_URL`) forms; unprefixed wins. Documented in [Environment variables](apps/docs/docs/deployment/env-vars.md#ueba-service-servicesueba).
-
-Next (planned — checkpointed with `[~]` in `AISOC_V8_PROGRESS.md`):
-
-- Versioned `:CONFIGURED_AS {ts}` config-snapshot writers for AWS / GitHub / Lacework / Okta (T1.2)
-- `LLMInputContract` fail-closed validator coverage across every sub-agent (T2.3)
-- Attack-chain ranking + timeline UI hardening (T3.3) and business-context YAML rule engine (T3.5)
-- Effective-permissions resolvers for Azure / GCP / Okta / GWS (T3.2)
-- ChatOps full coverage: Slack Block Kit approvals, Teams Adaptive Card mirror, signed email approval URLs (T3.6)
-- ~~Remaining wave-2 connectors hardened to wave-1 quality (sublime_security, abnormal_security, box, dropbox, oci, datadog)~~ → **wave-1 test + fixture parity landed** for all six
-- Mobile responder console (React Native), plugin marketplace v3, AI-generated threat intel briefings, embedded red-team scoring widget, SLA breach predictor, SOC-in-a-box one-click cloud deploy
+- **Latest GitHub release with downloads:** <https://github.com/beenuar/AiSOC/releases/latest>
+- **Per-release narrative:** [`RELEASES.md`](RELEASES.md) (mirrors what used to live in this README)
+- **Machine-readable inventory with file paths, env-var diffs, test counts:** [`CHANGELOG.md`](CHANGELOG.md)
+- **v8.0 wave-2 in flight (`[~]` items):** [`docs/roadmap/v8-progress.md`](docs/roadmap/v8-progress.md)
+- **Bigger-picture roadmap (BYOC multi-cloud, MSSP rollups, federated search):** [`ROADMAP.md`](ROADMAP.md)
---
## Contributing
-PRs of every size are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and the [Code of Conduct](CODE_OF_CONDUCT.md) before opening a PR.
-
-Good first issues:
+PRs of every size are welcome. Read [`CONTRIBUTING.md`](CONTRIBUTING.md) for the workflow and the [Code of Conduct](CODE_OF_CONDUCT.md) before opening a PR.
-- New connector integrations in `integrations/`
-- Community Sigma detections in `detections/`
-- Hunt-as-Code YAML definitions in `hunts/`
-- New plugins published to the marketplace
-- Frontend UI polish (Tailwind / React)
-- Documentation and tutorials in `apps/docs/`
-- Test coverage for any service
-- Translations
+First-time contributors: pick a [`good first issue`](https://github.com/beenuar/AiSOC/issues?q=is%3Aopen+label%3A%22good+first+issue%22). Need help? [Open a Q&A discussion](https://github.com/beenuar/AiSOC/discussions/new?category=q-a).
---
## Credits
-AiSOC is built and improved by a growing community of contributors, security researchers, and operators.
-
-**Security researchers** who have made AiSOC measurably safer for everyone running it:
-
-- [**@TanmayZade**](https://github.com/TanmayZade) — Reported & fixed the prompt-injection auto-close bypass ([#220](https://github.com/beenuar/AiSOC/issues/220) / [PR #219](https://github.com/beenuar/AiSOC/pull/219))
-- [**@mangod12**](https://github.com/mangod12) — Proposed cross-tenant isolation tests + nightly RBAC regression CI ([#159](https://github.com/beenuar/AiSOC/issues/159)); informed [PR #221](https://github.com/beenuar/AiSOC/pull/221)
-- [**@jay-cyble**](https://github.com/jay-cyble) — Structured review of 13 security & UI findings ([#130](https://github.com/beenuar/AiSOC/issues/130))
-
-**Code contributors** outside the core maintainer team:
-
-- [**@jay-cyble**](https://github.com/jay-cyble) — First community contribution: UEBA service env-var alignment ([PR #135](https://github.com/beenuar/AiSOC/pull/135))
-- [**@prince30121**](https://github.com/prince30121) — Infrastructure & CI fixes
-- [**@ARDA7787**](https://github.com/ARDA7787) — Redis-backed scheduler singleton guard + dependency-CVE audit CI ([PR #218](https://github.com/beenuar/AiSOC/pull/218))
-- [**@TanmayZade**](https://github.com/TanmayZade) — Prompt sanitiser + untrusted-content wrapping across the classification agents ([PR #219](https://github.com/beenuar/AiSOC/pull/219))
-
-The full list — including bug reporters, community feedback, and how to get yourself added — lives in [**CREDITS.md**](CREDITS.md). The always-up-to-date code-contribution graph is on the [GitHub contributors page](https://github.com/beenuar/AiSOC/graphs/contributors).
-
-Thank you to everyone who has filed an issue, shipped a PR, or quietly improved this project.
+AiSOC is built and improved by a growing community of contributors, security researchers, and operators. The full attribution — including bug reporters and security researchers — lives in [`.github/CREDITS.md`](.github/CREDITS.md). The always-up-to-date code-contribution graph is on the [GitHub contributors page](https://github.com/beenuar/AiSOC/graphs/contributors).
---
## Security
-For security issues, please do not open a public issue. Use [GitHub's private vulnerability reporting](https://github.com/beenuar/AiSOC/security/advisories/new). Full policy in [SECURITY.md](SECURITY.md). AiSOC follows coordinated disclosure.
+For security issues, please do not open a public issue. Use [GitHub's private vulnerability reporting](https://github.com/beenuar/AiSOC/security/advisories/new). Full policy in [`SECURITY.md`](SECURITY.md). AiSOC follows coordinated disclosure.
---
@@ -1079,10 +230,6 @@ For security issues, please do not open a public issue. Use [GitHub's private vu
<div align="center">
-[Report a bug](https://github.com/beenuar/AiSOC/issues/new?template=bug_report.md) · [Request a feature](https://github.com/beenuar/AiSOC/issues/new?template=feature_request.md) · [Contribute](CONTRIBUTING.md) · [Read the docs](apps/docs/)
+[Report a bug](https://github.com/beenuar/AiSOC/issues/new?template=bug_report.yml) · [Request a feature](https://github.com/beenuar/AiSOC/issues/new?template=feature_request.yml) · [Contribute](CONTRIBUTING.md) · [Read the docs](apps/docs/) · [Reproduce the benchmark](apps/docs/docs/benchmark.md)
</div>
-
----
-
-> **Reproduce these numbers:** `pnpm eval:public` — methodology at [docs.tryaisoc.com/benchmark-methodology](https://docs.tryaisoc.com/benchmark-methodology). Every figure on the [public benchmark page](apps/docs/docs/benchmark.md) is reproducible from a fresh clone in under 30 seconds (substrate suite, no LLM key required).
diff --git a/ROADMAP.md b/ROADMAP.md
index bf63a1426..3ea4f677f 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -50,7 +50,7 @@ This document captures the planned direction for AiSOC across major versions. Al
### Cross-cutting
- [x] OpenTelemetry traces: agents → actions → api → realtime (Jaeger/Tempo)
- [x] API token scopes (foundation for SSO)
-- [x] MIGRATION.md for v3 → v4 upgrade path
+- [x] `docs/upgrade/MIGRATION.md` for v3 → v4 upgrade path
---
@@ -195,7 +195,7 @@ Implemented and reviewed by Beenu Arora <[email protected]>.
- [x] AI-generated weekly executive digest — auto-emailed PDF (`digest_pdf.py` + `weekly_digest_task.py`)
- [x] Slack native bot for alert triage without opening the UI (`services/slack-bot/` — 61 tests)
- [x] Threat actor attribution engine v0 (`services/threatintel/app/actors/attribution.py`)
-- [x] Air-gap / Ollama local-LLM mode (`docker-compose.airgap.yml` + `apps/docs/docs/operations/air-gapped.md`)
+- [x] Air-gap / Ollama local-LLM mode (`infra/compose/docker-compose.airgap.yml` + `apps/docs/docs/operations/air-gapped.md`)
- [x] BYOK per-tenant LLM credentials UI + API (`llm_credentials.py` + `SettingsView.tsx`)
- [x] MSSP console — per-child-tenant KPI aggregation, SLA posture, parent_tenant_id hierarchy
- [x] Team analytics view — analyst MTTR, leaderboard, shift workload (`TeamAnalyticsView.tsx`)
diff --git a/SECURITY.md b/SECURITY.md
index 341e8a27f..d1ece7db2 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -65,7 +65,7 @@ AiSOC is an open-source project and does not currently operate a paid bounty pro
We publicly thank researchers who report valid issues. Once a fix has shipped, we credit reporters (with their consent) in the corresponding [GitHub Security Advisory](https://github.com/beenuar/AiSOC/security/advisories) and the relevant `CHANGELOG.md` entry.
-The full list of credited researchers lives in [CREDITS.md](CREDITS.md#security-researchers). Highlights:
+The full list of credited researchers lives in [.github/CREDITS.md](.github/CREDITS.md#security-researchers). Highlights:
| Reporter | Issue / PR | Summary |
| --- | --- | --- |
@@ -73,4 +73,4 @@ The full list of credited researchers lives in [CREDITS.md](CREDITS.md#security-
| [@mangod12](https://github.com/mangod12) | [#159](https://github.com/beenuar/AiSOC/issues/159) → [PR #221](https://github.com/beenuar/AiSOC/pull/221) | Proposed cross-tenant isolation tests + nightly CI for RBAC regression; informed the tenant-isolation hardening on the detection-loop endpoint. |
| [@jay-cyble](https://github.com/jay-cyble) | [#130](https://github.com/beenuar/AiSOC/issues/130) | Structured review of 13 security & UI issues found via code review + live-site inspection. |
-If you've reported a valid issue and aren't listed here, please open a PR against [CREDITS.md](CREDITS.md) — we'd rather over-credit than miss anyone.
+If you've reported a valid issue and aren't listed here, please open a PR against [.github/CREDITS.md](.github/CREDITS.md) — we'd rather over-credit than miss anyone.
diff --git a/SUPPORT.md b/SUPPORT.md
index d643b1880..9cd8fe1c5 100644
--- a/SUPPORT.md
+++ b/SUPPORT.md
@@ -32,7 +32,7 @@ submissions, each of which has its own template.
## 3. Try the live demo
<https://tryaisoc.com> is a community-maintained Fly.io instance. It can
-go offline (see [LIVE-DEMO.md](LIVE-DEMO.md)). When that happens, the
+go offline (see [docs/operations/live-demo-runbook.md](docs/operations/live-demo-runbook.md)). When that happens, the
always-on fallback is the
[Codespaces quickstart](https://codespaces.new/beenuar/AiSOC?quickstart=1) —
zero local install, runs in your browser.
@@ -52,7 +52,7 @@ Please include:
**Do not open a public issue or discussion for a security issue.**
Use [GitHub Security Advisories](https://github.com/beenuar/AiSOC/security/advisories/new)
or follow the [SECURITY.md](SECURITY.md) policy. We follow coordinated
-disclosure and credit reporters in [CREDITS.md](CREDITS.md).
+disclosure and credit reporters in [.github/CREDITS.md](.github/CREDITS.md).
## 6. Contribute
diff --git a/apps/docs/docs/architecture.md b/apps/docs/docs/architecture.md
index b753bf523..59dae4ba6 100644
--- a/apps/docs/docs/architecture.md
+++ b/apps/docs/docs/architecture.md
@@ -206,7 +206,7 @@ AiSOC/
├── marketplace/ # Marketplace index (index.json)
├── docs/ # OpenAPI spec (openapi.yaml)
├── docker-compose.yml # Full development stack
-├── docker-compose.demo.yml # Slim profile for `pnpm aisoc:demo`
+├── infra/compose/ # docker-compose.{demo,dev,airgap}.yml overlays
└── scripts/ # Utilities (seed, eval harness, build, validate)
```
diff --git a/apps/docs/docs/architecture/agents.md b/apps/docs/docs/architecture/agents.md
index bc971c6d8..b72661bae 100644
--- a/apps/docs/docs/architecture/agents.md
+++ b/apps/docs/docs/architecture/agents.md
@@ -172,7 +172,7 @@ old names) continue to work. The aliases resolve to the new façade:
New code should import the four branded classes directly. Aliases will
remain importable for the v8.x line; deprecation timing tracks in
-`AISOC_V8_PROGRESS.md`.
+`docs/roadmap/v8-progress.md`.
---
diff --git a/apps/docs/docs/architecture/graph-schema.md b/apps/docs/docs/architecture/graph-schema.md
index ad5c59f5e..81d893a33 100644
--- a/apps/docs/docs/architecture/graph-schema.md
+++ b/apps/docs/docs/architecture/graph-schema.md
@@ -324,7 +324,7 @@ version: v1.0
Versioning rules:
- **Additive changes** (a new optional property on an existing label, a new node label, a new relationship type) bump the **minor** component: `v1.0 → v1.1`.
-- **Breaking changes** (renaming or removing a label / relationship / required property, narrowing a type) bump the **major** component: `v1.0 → v2.0`. A major bump requires a migration note in `MIGRATION.md` and a compatibility shim for at least one minor release.
+- **Breaking changes** (renaming or removing a label / relationship / required property, narrowing a type) bump the **major** component: `v1.0 → v2.0`. A major bump requires a migration note in `docs/upgrade/MIGRATION.md` and a compatibility shim for at least one minor release.
- **Every** schema change must touch three places in the same PR:
1. `schemas/graph-schema.yaml`
2. `services/ingest/internal/graph/schema.go` (the Go enums consumed by the ingest writer)
diff --git a/apps/docs/docs/architecture/overview.md b/apps/docs/docs/architecture/overview.md
new file mode 100644
index 000000000..e478cc84c
--- /dev/null
+++ b/apps/docs/docs/architecture/overview.md
@@ -0,0 +1,122 @@
+---
+sidebar_position: 0
+title: Repository overview
+description: Where every service, package, and config lives in the AiSOC monorepo.
+---
+
+# Repository overview
+
+This page is the canonical map of the AiSOC monorepo. It used to live in `README.md`; it was extracted here so the front page stays focused on "what is AiSOC and how do I run it" while this page stays useful for anyone navigating the code.
+
+For the data-flow architecture (Kafka spine, fusion, agents, storage tier, surface) see [Architecture](../architecture.md). For the deeper system-design write-up (ML fusion, Neo4j-at-ingest schema, threat-intel pipeline) see [`docs/architecture/SYSTEM_DESIGN.md`](https://github.com/beenuar/AiSOC/blob/main/docs/architecture/SYSTEM_DESIGN.md).
+
+## Monorepo layout
+
+```
+AiSOC/
+├── apps/
+│ ├── web/ # Next.js console + marketing landing + Responder PWA route
+│ └── docs/ # Docusaurus documentation site (this site)
+├── services/
+│ ├── api/ # Core REST API + Neo4j graph + rule engine + auth + RBAC + compliance + Investigation Ledger
+│ ├── ingest/ # Go · OCSF normalization · Shodan + CVE
+│ ├── enrichment/ # Go · IOC enrichment
+│ ├── fusion/ # Python · dedup + ML scoring + per-alert confidence + correlation narrative
+│ ├── agents/ # Python · LangGraph + Qdrant RAG + investigation ledger writer + hunt engine
+│ ├── actions/ # Python · SOAR + blast-radius gating + ChatOps verification
+│ ├── threatintel/ # Python · TAXII / MISP / OTX / KEV + threat-actor attribution
+│ ├── realtime/ # Node.js · per-channel WebSocket fan-out + VAPID Web Push
+│ ├── ueba/ # Python · User & Entity Behavior Analytics (Welford online baseline)
+│ ├── honeytokens/ # Python · deceptive credential traps (HMAC-signed)
+│ ├── purple-team/ # Python · Atomic Red Team + Caldera + ATT&CK + detection drift snapshots
+│ ├── osquery-tls/ # Python · native osquery TLS server + FIM + pack distribution
+│ ├── osquery-extensions/ # Go · AI threat-intel table + ML anomaly score table + 3 more
+│ ├── slack-bot/ # Python · ChatOps surface (Slack Bolt + HMAC signature verification)
+│ └── mcp/ # TypeScript · Model Context Protocol server (npm: @aisoc/mcp, lands in v8.0)
+├── packages/
+│ ├── types/ # Shared TS types
+│ ├── ui/ # Shared React primitives
+│ ├── ocsf/ # OCSF normalization helpers
+│ ├── sdk-ts/ # TypeScript client SDK for AiSOC API (npm: @aisoc/sdk, lands in v8.0)
+│ ├── sdk-py/ # Async Python client SDK (PyPI: aisoc-sdk, lands in v8.0)
+│ ├── sdk-go/ # Go client SDK + models (module: github.com/beenuar/aisoc/sdk-go)
+│ ├── plugin-sdk-ts/ # TypeScript plugin development SDK
+│ ├── plugin-sdk-py/ # Python plugin development SDK (PyPI: aisoc-plugin-sdk, lands in v8.0)
+│ ├── plugin-sdk-go/ # Go plugin development SDK (module: github.com/beenuar/aisoc/plugin-sdk-go)
+│ └── aisoc-cli/ # CLI: scaffold / validate / publish plugins & detections (PyPI: aisoc-cli, lands in v8.0)
+├── detections/ # Community Sigma detection rules (YAML) — 800+ native
+├── hunts/ # Hunt-as-Code YAML definitions (hypothesis + indicators + schedule)
+├── playbooks/ # Community SOAR playbooks (YAML)
+├── plugins/ # First-party plugins (Go + Python) + marketplace manifests
+├── marketplace/ # Marketplace index (JSON, generated by scripts/build_marketplace.py)
+├── infra/
+│ ├── coolify/ # Coolify (self-hosted Heroku-style PaaS) quickstart
+│ ├── fly/ # Fly.io machines + deploy script (canonical hosted demo target)
+│ ├── railway/ # Railway template (railway.toml)
+│ ├── render/ # Render blueprint (render.yaml at repo root)
+│ ├── terraform/ # AWS (VPC, EKS, RDS, ElastiCache, MSK) + GCP + Azure skeletons
+│ └── helm/ # Kubernetes Helm chart (HPA, PDB, Ingress per service)
+├── docs/
+│ ├── openapi.yaml # OpenAPI 3.1 spec for the Core API
+│ ├── architecture/ # System-design docs (SYSTEM_DESIGN.md, threat-actor attribution, …)
+│ ├── decisions/ # Architecture Decision Records (ADR-0001 onwards)
+│ ├── demo/ # Screencast brief + shot list
+│ ├── operations/ # Runbooks, managed-mode notes, audit health probes
+│ └── runbooks/ # Per-service operational runbooks
+└── scripts/
+ ├── aisoc-demo.ts # One-shot demo orchestrator (powers `pnpm aisoc:demo`)
+ ├── aisoc-doctor.ts # Local health check (ports, containers, demo data, API + WS)
+ ├── aisoc-acceptance.ts # Cold-start acceptance test
+ ├── run_evals.py # Public eval harness (per-case + per-template macros, telemetry coverage)
+ ├── generate_eval_incidents.py # 200-incident synthetic generator (55 templates) + synthetic_telemetry.jsonl
+ ├── build_marketplace.py # Build marketplace/index.json from detections+playbooks+plugins
+ ├── validate_detections.py # YAML schema validation for Sigma detections
+ ├── validate_playbooks.py # YAML schema validation for playbooks
+ ├── backup.sh # Postgres + ClickHouse + plugins → S3/R2
+ └── restore.sh # Point-in-time restore
+```
+
+## Service map
+
+| Service | Lang | Port | Role |
+|---|---|---|---|
+| `web` | Next.js + React | 3000 | SOC console (alerts detail + Investigation Rail), benchmark scoreboard, marketing landing |
+| `api` | Python · FastAPI | 8000 | Alerts (detail envelope + correlation narrative), cases, RBAC, graph, rules, audit, compliance, detection proposals (DAC), federated search fan-out, SLA tracking |
+| `realtime` | Node.js · `ws` | 8086 | Per-channel WebSocket fan-out + VAPID Web Push (short-lived signed tickets) |
+| `agents` | Python · LangGraph | 8001 | Multi-agent reasoning + Qdrant RAG + Hunt-as-Code engine & scheduler + Investigation Ledger writer |
+| `fusion` | Python | 8003 | Dedup + ML scoring (LightGBM, IsoForest), alert confidence, entity risk / RBA, correlation narrative projection for API |
+| `actions` | Python | 8002 | SOAR with blast-radius gating + ChatOps verification + signed approval URLs |
+| `connectors` | Python | — | Connector polling (APScheduler), credential vault, federated query translators |
+| `threatintel` | Python | 8005 | TAXII / MISP / OTX / KEV polling + threat-actor attribution engine |
+| `ueba` | Python | 8007 | User & Entity Behavior Analytics |
+| `honeytokens` | Python | 8008 | Honeytoken lifecycle + webhook alerting |
+| `purple-team` | Python | 8006 | Atomic Red Team + Caldera + ATT&CK heatmap + detection drift snapshots |
+| `osquery-tls` | Python | 8091 | Native osquery TLS server — enroll nodes, distribute packs, stream FIM/process/network telemetry |
+| `osquery-extensions` | Go | — | Custom osquery extensions (AI-powered threat intel table, ML anomaly score table, + 3 more) |
+| `slack-bot` | Python | 8009 | ChatOps surface — interactive approvals for high-blast-radius actions, `/aisoc` slash command |
+| `mcp` | TypeScript | — (stdio) | Model Context Protocol server exposing 13 AiSOC tools — discovery, deep-dive, action/replay, and warm-tier lake query |
+| `ingest` | Go | 8081 | OCSF normalization + Shodan/CVE + Neo4j graph-at-ingest writers |
+| `enrichment` | Go | 8080 | IOC enrichment (VT, AbuseIPDB, GreyNoise) |
+
+## Storage tier
+
+| Store | Purpose |
+|---|---|
+| PostgreSQL | Tenants, users, cases, detection rules, RBAC, audit log, compliance · Row-level security |
+| ClickHouse | High-cardinality event analytics + alert metrics |
+| OpenSearch | Full-text IOC + actor + report search · Sigma backend |
+| Qdrant | Vector RAG for agents, semantic ATT&CK lookup |
+| Neo4j | Knowledge graph: entities, attack paths, blast radius (graph-at-ingest writers in `services/ingest/internal/graph/`) |
+| Redis | Cache, pub/sub, IOC bloom filter, enrichment TTL, short-lived realtime tickets |
+| Kafka | Event streaming spine (raw, fused, vulnerability, anomaly, action, graph-updates) |
+
+## API surface
+
+The full OpenAPI 3.1 spec lives at [`docs/openapi.yaml`](https://github.com/beenuar/AiSOC/blob/main/docs/openapi.yaml). Endpoint groups are summarised in [Architecture](../architecture.md#api-surface) and the interactive view is at `http://localhost:8000/docs` (Swagger) or `/redoc` (ReDoc) when you run the local stack.
+
+## Next stops
+
+- [Architecture](../architecture.md) — data-flow + service interaction diagrams.
+- [`docs/architecture/SYSTEM_DESIGN.md`](https://github.com/beenuar/AiSOC/blob/main/docs/architecture/SYSTEM_DESIGN.md) — deeper write-up.
+- [`apps/docs/docs/intro.md`](../intro.md) — feature catalogue index.
+- [Plugin overview](../plugins/overview.md) — how to extend.
diff --git a/apps/docs/docs/concepts/detections.md b/apps/docs/docs/concepts/detections.md
index ba768c826..28bb9bf8a 100644
--- a/apps/docs/docs/concepts/detections.md
+++ b/apps/docs/docs/concepts/detections.md
@@ -106,7 +106,7 @@ provenance:
```
The full attribution table for every redistributed corpus lives in the repo's
-[`LICENSES.md`](https://github.com/beenuar/AiSOC/blob/main/LICENSES.md).
+[`.github/LICENSES.md`](https://github.com/beenuar/AiSOC/blob/main/.github/LICENSES.md).
### Quarantine
diff --git a/apps/docs/docs/deployment/docker.md b/apps/docs/docs/deployment/docker.md
index 5d7c68b94..14308f15d 100644
--- a/apps/docs/docs/deployment/docker.md
+++ b/apps/docs/docs/deployment/docker.md
@@ -8,7 +8,7 @@ AiSOC ships three Compose flavors. Pick the one that matches what you are doing.
| File | Purpose | When to use |
|------|---------|-------------|
-| `docker-compose.demo.yml` | Streamlined demo with seeded data | Trying AiSOC for the first time |
+| `infra/compose/docker-compose.demo.yml` | Streamlined demo with seeded data | Trying AiSOC for the first time |
| `docker-compose.yml` | Full developer stack | Active development against real source |
| `docker-compose.prod.yml` | Production-leaning stack | Self-hosting on a single VM |
@@ -27,7 +27,7 @@ URL of the resulting case in roughly 3-4 minutes on a warm Docker daemon.
pnpm aisoc:demo
```
-Behind the scenes this runs `docker compose -f docker-compose.demo.yml up -d`
+Behind the scenes this runs `docker compose -f infra/compose/docker-compose.demo.yml up -d`
against `ghcr.io/beenuar/aisoc-*` images (with `pull_policy: missing`, so
re-runs don't re-pull). Stop it with:
diff --git a/apps/docs/docs/detections/hello-hunt.md b/apps/docs/docs/detections/hello-hunt.md
index e9bfa7997..448ffcea0 100644
--- a/apps/docs/docs/detections/hello-hunt.md
+++ b/apps/docs/docs/detections/hello-hunt.md
@@ -282,7 +282,7 @@ If you have a running AiSOC dev stack and want to see the rule fire end to end:
```bash
# 1. Restart the API so it reloads the detection corpus from disk.
-docker compose -f docker-compose.dev.yml restart api
+docker compose -f infra/compose/docker-compose.dev.yml restart api
# 2. Replay the positive fixture into the ingest pipeline.
curl -X POST http://localhost:8000/v1/ingest/batch \
diff --git a/apps/docs/docs/glossary.md b/apps/docs/docs/glossary.md
index d5602859f..49d130e42 100644
--- a/apps/docs/docs/glossary.md
+++ b/apps/docs/docs/glossary.md
@@ -206,7 +206,7 @@ images and signed plugin bundles. See [Operations → Air-gapped](./operations/a
**APScheduler** — Python in-process job scheduler used by connectors
(per-instance polling) and Hunt-as-Code (continuous hunt execution).
-**Demo profile** — Slim Docker Compose stack (`docker-compose.demo.yml`)
+**Demo profile** — Slim Docker Compose stack (`infra/compose/docker-compose.demo.yml`)
spun up by `pnpm aisoc:demo`. Pulls prebuilt GHCR images, seeds canonical
data, and lands you on a live case.
diff --git a/apps/docs/docs/integrations/mcp.md b/apps/docs/docs/integrations/mcp.md
index 92e55f44d..2f09a8901 100644
--- a/apps/docs/docs/integrations/mcp.md
+++ b/apps/docs/docs/integrations/mcp.md
@@ -6,23 +6,39 @@ description: Connect AiSOC to Claude Desktop, Cursor, Cody, and Continue.dev via
# MCP server
-The `@aisoc/mcp` npm package is the official [Model Context Protocol](https://modelcontextprotocol.io) bridge between AiSOC and modern AI assistants. Once installed, your assistant can list alerts, pull cases, run agent investigations, and **replay every step the agent took** — without leaving the chat or the IDE.
+The `@aisoc/mcp` server is the official [Model Context Protocol](https://modelcontextprotocol.io) bridge between AiSOC and modern AI assistants. Once installed, your assistant can list alerts, pull cases, run agent investigations, and **replay every step the agent took** — without leaving the chat or the IDE.
+
+:::info Status — monorepo today, npm in v8.0
+The MCP server ships from [`services/mcp/`](https://github.com/beenuar/AiSOC/tree/main/services/mcp) in this repository and is fully working today. The `npx -y @aisoc/mcp …` one-liner lands when the package is published to npm as part of v8.0. Until then, use the **build-from-source** path shown below — every install/serve/doctor command is otherwise identical.
+:::
> **Why this matters.** MCP is becoming the substrate for "AI tools that work everywhere": Claude Desktop, Cursor, Cody, Continue, Zed, and counting. Every analyst who works in those tools gets AiSOC discovery for free.
+## Build from source (today)
+
+```bash
+git clone https://github.com/beenuar/AiSOC.git
+cd AiSOC/services/mcp
+pnpm install
+pnpm build # writes services/mcp/dist/index.js
+```
+
+`dist/index.js` is an executable Node entry point. Every command below assumes you run it from the `services/mcp` directory; substitute `node dist/index.js …` for `npx -y @aisoc/mcp …` everywhere.
+
## Supported hosts
-| Host | One-line install | Config file |
-|---|---|---|
-| **Claude Desktop** | `npx -y @aisoc/mcp install --host claude --aisoc-url … --api-key …` | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| **Cursor** | `npx -y @aisoc/mcp install --host cursor --aisoc-url … --api-key …` | `~/.cursor/mcp.json` |
-| **Continue.dev** | `npx -y @aisoc/mcp install --host continue --aisoc-url … --api-key …` | `~/.continue/config.json` |
-| **Cody** | `npx -y @aisoc/mcp install --host cody --aisoc-url … --api-key …` (prints snippet) | VS Code User Settings → `cody.mcp.servers` |
+| Host | One-line install (v8.0 npm path) | Build-from-source equivalent (today) | Config file |
+|---|---|---|---|
+| **Claude Desktop** | `npx -y @aisoc/mcp install --host claude --aisoc-url … --api-key …` | `node dist/index.js install --host claude --aisoc-url … --api-key …` | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| **Cursor** | `npx -y @aisoc/mcp install --host cursor --aisoc-url … --api-key …` | `node dist/index.js install --host cursor --aisoc-url … --api-key …` | `~/.cursor/mcp.json` |
+| **Continue.dev** | `npx -y @aisoc/mcp install --host continue --aisoc-url … --api-key …` | `node dist/index.js install --host continue --aisoc-url … --api-key …` | `~/.continue/config.json` |
+| **Cody** | `npx -y @aisoc/mcp install --host cody --aisoc-url … --api-key …` (prints snippet) | `node dist/index.js install --host cody --aisoc-url … --api-key …` | VS Code User Settings → `cody.mcp.servers` |
Print the canonical config paths for your machine any time:
```bash
-npx -y @aisoc/mcp install --list-paths
+node dist/index.js install --list-paths
+# (v8.0 npm equivalent: npx -y @aisoc/mcp install --list-paths)
```
## 60-second quickstart
@@ -34,6 +50,12 @@ In the AiSOC console: **Settings → API Keys → New personal access token**. G
### 2. Run the installer
```bash
+# Today (monorepo source build):
+node dist/index.js install --host claude \
+ --aisoc-url https://aisoc.your-company.com \
+ --api-key aisoc_pat_xxxxxxxxxxxx
+
+# v8.0+ (once @aisoc/mcp lands on npm):
npx -y @aisoc/mcp install --host claude \
--aisoc-url https://aisoc.your-company.com \
--api-key aisoc_pat_xxxxxxxxxxxx
@@ -124,11 +146,33 @@ All flags can be set via env vars; the CLI flag wins if both are present.
If you'd rather edit JSON yourself, `install --dry-run` prints exactly what the installer would write:
```bash
+# Today (monorepo source build):
+node dist/index.js install --host claude --dry-run \
+ --aisoc-url https://aisoc.your-company.com --api-key aisoc_xxx
+
+# v8.0+ (once @aisoc/mcp lands on npm):
npx -y @aisoc/mcp install --host claude --dry-run \
--aisoc-url https://aisoc.your-company.com --api-key aisoc_xxx
```
-Paste the snippet under `mcpServers` in your host's config:
+Paste the snippet under `mcpServers` in your host's config. Today's source-build snippet:
+
+```json
+{
+ "mcpServers": {
+ "aisoc": {
+ "command": "node",
+ "args": ["/absolute/path/to/AiSOC/services/mcp/dist/index.js", "serve"],
+ "env": {
+ "AISOC_URL": "https://aisoc.your-company.com",
+ "AISOC_API_KEY": "aisoc_pat_xxxxxxxxxxxx"
+ }
+ }
+ }
+}
+```
+
+Once `@aisoc/mcp` ships to npm in v8.0, the equivalent snippet drops the absolute path:
```json
{
@@ -150,6 +194,12 @@ Paste the snippet under `mcpServers` in your host's config:
Before pointing your assistant at it, smoke-test the connection:
```bash
+# Today (monorepo source build):
+AISOC_URL=https://aisoc.your-company.com \
+AISOC_API_KEY=aisoc_pat_xxx \
+node dist/index.js doctor
+
+# v8.0+ (once @aisoc/mcp lands on npm):
AISOC_URL=https://aisoc.your-company.com \
AISOC_API_KEY=aisoc_pat_xxx \
npx -y @aisoc/mcp doctor
@@ -168,7 +218,7 @@ npx -y @aisoc/mcp doctor
**The server doesn't appear in my assistant.** Restart the host fully (Claude Desktop: `Cmd+Q`, not just close the window). Then re-run `install --list-paths` and confirm the config file at the printed path actually contains an `aisoc` entry under `mcpServers`.
-**Tools fail with 401 / 403.** Re-mint the API key with the right scopes and re-run the installer; it will update the entry in place. Confirm with `npx -y @aisoc/mcp doctor`.
+**Tools fail with 401 / 403.** Re-mint the API key with the right scopes and re-run the installer; it will update the entry in place. Confirm with `node dist/index.js doctor` (or `npx -y @aisoc/mcp doctor` once v8.0 ships).
**Tools fail with "fetch failed" / timeouts.** Your assistant's host can't reach `AISOC_URL`. Check that the URL is reachable from the same machine (`curl $AISOC_URL/health`) and bump `--timeout 60000` if you're on a slow link.
diff --git a/apps/docs/docs/intro.md b/apps/docs/docs/intro.md
index b23700fd1..a116dc5cb 100644
--- a/apps/docs/docs/intro.md
+++ b/apps/docs/docs/intro.md
@@ -120,7 +120,7 @@ See the full [Architecture](./architecture) page for the detailed service map an
### Get started
- [One-click install](./installation) — zero-prerequisite bootstrap for Linux, macOS, and Windows
-- [Quick Start](./quickstart) — `pnpm aisoc:demo`, under 5 minutes to a live investigation. The **Path C — founder-style CLI** flow (`docker compose -f docker-compose.dev.yml up -d` → `aisoc db upgrade` → `aisoc serve` → `aisoc submit examples/alerts/lateral-movement.json`) goes from fresh clone to a live alert at `http://localhost:3000/alerts` in under 90 seconds, with no Kafka / Fusion required for the first alert.
+- [Quick Start](./quickstart) — `pnpm aisoc:demo`, under 5 minutes to a live investigation. The **Path C — founder-style CLI** flow (`docker compose -f infra/compose/docker-compose.dev.yml up -d` → `aisoc db upgrade` → `aisoc serve` → `aisoc submit examples/alerts/lateral-movement.json`) goes from fresh clone to a live alert at `http://localhost:3000/alerts` in under 90 seconds, with no Kafka / Fusion required for the first alert.
- [Architecture](./architecture) — service map and data flow
- [Glossary](./glossary) — security and AiSOC-specific terminology in one place
- [FAQ](./operations/faq) — common questions about scope, deployment, data, and licensing
diff --git a/apps/docs/docs/operations/air-gapped.md b/apps/docs/docs/operations/air-gapped.md
index 8e1e553d3..da05ce85e 100644
--- a/apps/docs/docs/operations/air-gapped.md
+++ b/apps/docs/docs/operations/air-gapped.md
@@ -19,8 +19,8 @@ The easiest path is the pre-built air-gap overlay shipped in the repository:
```bash
docker compose \
- -f docker-compose.demo.yml \
- -f docker-compose.airgap.yml \
+ -f infra/compose/docker-compose.demo.yml \
+ -f infra/compose/docker-compose.airgap.yml \
up -d
```
@@ -37,7 +37,7 @@ a larger model:
```bash
AIRGAP_LLM_MODEL=llama3.1:8b-instruct-q4_K_M \
-docker compose -f docker-compose.demo.yml -f docker-compose.airgap.yml up -d
+docker compose -f infra/compose/docker-compose.demo.yml -f infra/compose/docker-compose.airgap.yml up -d
```
---
diff --git a/apps/docs/docs/operations/codespaces.md b/apps/docs/docs/operations/codespaces.md
new file mode 100644
index 000000000..ed49c8c8c
--- /dev/null
+++ b/apps/docs/docs/operations/codespaces.md
@@ -0,0 +1,100 @@
+# Codespaces & devcontainers
+
+AiSOC ships a prebuilt devcontainer image so a fresh Codespace boots from
+clone-link to a green `pnpm aisoc:demo` in **about 30 seconds**, down from
+roughly 5 minutes when the same image was assembled from
+`features:` on every cold start.
+
+## What's prebuilt
+
+The image is published at
+[`ghcr.io/beenuar/aisoc-devcontainer:latest`](https://github.com/beenuar/AiSOC/pkgs/container/aisoc-devcontainer)
+on every push to `main`. It carries:
+
+- Node 20 + `[email protected]` via `corepack`
+- Python 3.11 + [`uv`](https://github.com/astral-sh/uv) + `ruff`
+- Go 1.22
+- `docker` + `docker-compose-plugin`
+- GitHub CLI (`gh`)
+- `ripgrep`, `jq`, `build-essential` (for native deps in `npm`/`pip`)
+- A warm pnpm store directory so the codespace's first `pnpm install`
+ resolves from cache rather than the network.
+
+The source lives at
+[`.devcontainer/Dockerfile`](https://github.com/beenuar/AiSOC/blob/main/.devcontainer/Dockerfile);
+the publisher at
+[`.github/workflows/devcontainer-build.yml`](https://github.com/beenuar/AiSOC/blob/main/.github/workflows/devcontainer-build.yml).
+
+## Cold-start budget
+
+| Phase | Budget | Source of truth |
+|---|---|---|
+| `docker pull` of the devcontainer image | 60 s | `PHASE_PULL_BUDGET` |
+| `pnpm install --frozen-lockfile=false` (warm store) | included in pull phase | `onCreateCommand` |
+| `pnpm aisoc:acceptance --cold` | 5 min | `PHASE_ACCEPTANCE_BUDGET` |
+
+Both budgets are gated by
+[`.github/workflows/devcontainer-coldstart.yml`](https://github.com/beenuar/AiSOC/blob/main/.github/workflows/devcontainer-coldstart.yml),
+which runs on every `main` push and on every successful devcontainer
+publish. A red run blocks the release that introduced the regression.
+
+## Using it
+
+### In GitHub Codespaces
+
+Click [**Open in Codespaces**](https://codespaces.new/beenuar/AiSOC?quickstart=1).
+The image is pulled automatically; `onCreateCommand` runs `pnpm install`;
+then open a terminal and run:
+
+```bash
+# Real stack (Docker-in-Docker inside the codespace):
+pnpm aisoc:demo --no-open
+# …then click the forwarded port 3000.
+
+# Or, no-Docker (zero-dependency simulator):
+pip install -e packages/aisoc-sandbox
+aisoc-sandbox demo
+```
+
+### Locally, with `devcontainer-cli`
+
+If you have
+[`@devcontainers/cli`](https://github.com/devcontainers/cli)
+installed, the same image works as a local dev environment:
+
+```bash
+git clone https://github.com/beenuar/AiSOC && cd AiSOC
+devcontainer up --workspace-folder .
+devcontainer exec --workspace-folder . pnpm aisoc:demo --no-open
+```
+
+### Locally, with VS Code
+
+VS Code's "Reopen in Container" command resolves
+`.devcontainer/devcontainer.json` directly. Same prebuilt image as the
+Codespaces flow.
+
+## When the image is rebuilt
+
+- **Every push to `main`** that touches `.devcontainer/**` or the build
+ workflow.
+- **Every Monday at 09:00 UTC** so security-relevant base-image updates
+ land on schedule even if the surface itself didn't change.
+- **On manual dispatch** from the Actions tab.
+
+If you need to pin to a specific build (e.g. for a release branch),
+every push gets a `sha-<short_sha>` tag in addition to `latest`. The
+weekly cron job also tags `weekly` so an external dependency can pin to
+"the most recent base-image hygiene refresh" if it wants to.
+
+## If something breaks
+
+1. The local fallback `build:` block in
+ [`.devcontainer/devcontainer.json`](https://github.com/beenuar/AiSOC/blob/main/.devcontainer/devcontainer.json)
+ means contributors without GHCR pull access can still build the image
+ locally — at the cost of the ~5 min initial assembly time.
+2. Open an [issue tagged
+ `devex/devcontainer`](https://github.com/beenuar/AiSOC/issues/new?labels=devex%2Fdevcontainer)
+ with the failing Codespace's name and the first error from the boot
+ log. Most failures are dependency network blips, not image-content
+ regressions.
diff --git a/apps/docs/docs/operations/faq.md b/apps/docs/docs/operations/faq.md
index 7b15c556b..d9040aca7 100644
--- a/apps/docs/docs/operations/faq.md
+++ b/apps/docs/docs/operations/faq.md
@@ -212,11 +212,11 @@ Yes. `@aisoc/mcp` exposes 11 Investigation Ledger tools to MCP-compatible LLM cl
### Are there SDKs?
-Three:
+Three. All three ship from this monorepo today; the npm + PyPI releases land in v8.0:
-- **Python** — `pip install aisoc-sdk`. Async first, typed against the OpenAPI spec.
-- **TypeScript** — `pnpm add @aisoc/sdk-ts`. Also typed against the OpenAPI spec.
-- **Go** — `go get github.com/beenuar/AiSOC/packages/sdk-go`.
+- **Python** — `pip install -e packages/sdk-py` today (`pip install aisoc-sdk` once it's on PyPI in v8.0). Async first, typed against the OpenAPI spec.
+- **TypeScript** — `pnpm --filter @aisoc/sdk-ts install` today (`pnpm add @aisoc/sdk-ts` once it's on npm in v8.0). Also typed against the OpenAPI spec.
+- **Go** — `go get github.com/beenuar/AiSOC/packages/sdk-go` (works today; Go modules don't need a registry hop).
All three handle auth, retries, pagination, and backoff. See [Plugin SDK overview](../plugins/overview).
diff --git a/apps/docs/docs/operations/troubleshooting.md b/apps/docs/docs/operations/troubleshooting.md
index f1dca7fd0..65ca289ca 100644
--- a/apps/docs/docs/operations/troubleshooting.md
+++ b/apps/docs/docs/operations/troubleshooting.md
@@ -162,7 +162,7 @@ In order of how often this is the cause:
1. **Migrations weren't applied on a fresh clone.** The `alerts` table needs the v7.3.1 schema (eleven columns added by `042_alerts_schema_drift_fix.sql`). Run `aisoc db upgrade` — it's idempotent, so re-running on an already-migrated database is safe. If you see `column "..." of relation "alerts" does not exist` in `docker compose logs api`, this is the cause.
2. **`AISOC_CREDENTIAL_KEY` mismatch.** The submit endpoint writes through the same vault decrypt path as the rest of the API. If the API service was started with a different key than the one in `.env`, the row inserts but downstream lookups (e.g. tenant resolution) fail silently. Stop the stack, set the key in `.env`, restart.
3. **Wrong tenant filter in the UI.** The web console scopes `/alerts` to the currently selected tenant. `aisoc submit` defaults to the dev tenant. If you've switched tenants in the UI, you won't see the row. Switch back to the dev tenant or pass `--tenant` to `aisoc submit`.
-4. **API is on a port other than 8000.** `aisoc submit` reads `AISOC_API_URL` (default `http://localhost:8000`). If you remapped the port in `docker-compose.dev.yml`, set the env var.
+4. **API is on a port other than 8000.** `aisoc submit` reads `AISOC_API_URL` (default `http://localhost:8000`). If you remapped the port in `infra/compose/docker-compose.dev.yml`, set the env var.
Confirm the row really landed:
diff --git a/apps/docs/docs/operations/upgrades.md b/apps/docs/docs/operations/upgrades.md
index 653c5565f..700145a4e 100644
--- a/apps/docs/docs/operations/upgrades.md
+++ b/apps/docs/docs/operations/upgrades.md
@@ -76,7 +76,7 @@ aisoc db upgrade
# (Equivalent to: cd services/api && uv run alembic upgrade head)
# 5. Start the API service back up.
-docker compose -f docker-compose.dev.yml up -d api
+docker compose -f infra/compose/docker-compose.dev.yml up -d api
# 6. Verify health and remove the maintenance gate.
curl -fsS http://localhost:8000/healthz
@@ -114,7 +114,7 @@ git checkout v7.3.0 # the previous tag
pnpm install --frozen-lockfile
(cd services/api && uv sync)
(cd services/api && uv run alembic downgrade <previous_revision>)
-docker compose -f docker-compose.dev.yml up -d api
+docker compose -f infra/compose/docker-compose.dev.yml up -d api
```
Major releases occasionally ship one-way migrations (e.g. column drops). When that's the case, the CHANGELOG flags the migration as "irreversible" and the only rollback is restoring from the database snapshot you took in step 2 of the pre-upgrade checklist.
diff --git a/apps/docs/docs/plugins/cli.md b/apps/docs/docs/plugins/cli.md
index 5af633d35..713b621aa 100644
--- a/apps/docs/docs/plugins/cli.md
+++ b/apps/docs/docs/plugins/cli.md
@@ -8,16 +8,20 @@ The `aisoc-cli` ships scaffolding, validation, packaging, signing, and trust
management commands for every supported plugin type — `enricher`, `connector`,
`responder`, `detection`, and `widget`.
-The CLI source lives under `packages/aisoc-cli/`. Install it from the repo for
-hacking on it locally:
+:::info Status — monorepo today, PyPI in v8.0
+The CLI is fully functional today; it ships from the monorepo. The PyPI release (`pipx install aisoc-cli` / `pip install aisoc-cli`) lands with v8.0. Use the source path below until then — the command surface (`aisoc plugin new`, `aisoc validate detection`, …) stays identical.
+:::
-```bash
-pip install -e packages/aisoc-cli
-```
-
-Or install the published wheel:
+The CLI source lives under `packages/aisoc-cli/`. Install it from the repo:
```bash
+# Today (from this monorepo):
+git clone https://github.com/beenuar/AiSOC.git
+cd AiSOC && pip install -e packages/aisoc-cli
+
+# v8.0+ (once aisoc-cli lands on PyPI):
+pipx install aisoc-cli # recommended (isolated venv)
+# or:
pip install aisoc-cli
```
diff --git a/apps/docs/docs/plugins/python-sdk.md b/apps/docs/docs/plugins/python-sdk.md
index c4946490d..0d0071677 100644
--- a/apps/docs/docs/plugins/python-sdk.md
+++ b/apps/docs/docs/plugins/python-sdk.md
@@ -6,11 +6,20 @@ sidebar_position: 2
## Installation
+:::info Status — monorepo today, PyPI in v8.0
+`aisoc-plugin-sdk` ships from this monorepo today. The PyPI release lands with v8.0. Use the source-install path below until then — the import path (`aisoc_plugin_sdk`) and API surface stay identical.
+:::
+
```bash
+# Today (monorepo source install):
+git clone https://github.com/beenuar/AiSOC.git
+cd AiSOC && pip install -e packages/plugin-sdk-py
+
+# v8.0+ (once aisoc-plugin-sdk is on PyPI):
pip install aisoc-plugin-sdk
```
-The PyPI distribution is `aisoc-plugin-sdk`; the import path is
+The PyPI distribution will be `aisoc-plugin-sdk`; the import path is
`aisoc_plugin_sdk`. The source lives in `packages/plugin-sdk-py/`.
## Quick Start: Enricher
diff --git a/apps/docs/docs/quickstart.md b/apps/docs/docs/quickstart.md
index f362dbd68..37a1907aa 100644
--- a/apps/docs/docs/quickstart.md
+++ b/apps/docs/docs/quickstart.md
@@ -52,7 +52,7 @@ That single command:
1. Pulls prebuilt images from `ghcr.io/beenuar/*` (≈90s on a warm cache).
2. Brings up the slim demo profile defined in
- [`docker-compose.demo.yml`](https://github.com/beenuar/AiSOC/blob/main/docker-compose.demo.yml):
+ [`infra/compose/docker-compose.demo.yml`](https://github.com/beenuar/AiSOC/blob/main/infra/compose/docker-compose.demo.yml):
`postgres`, `redis`, `kafka`, `api`, `agents`, `realtime`, `web`.
3. Waits for healthchecks to go green.
4. Seeds canonical demo data (tenants, users, alerts, IOCs, attack paths).
@@ -293,7 +293,7 @@ You should see the operator commands: `serve`, `db`, `mcp`, `submit`,
aisoc serve
```
-Under the hood this runs `docker compose -f docker-compose.dev.yml up -d`
+Under the hood this runs `docker compose -f infra/compose/docker-compose.dev.yml up -d`
against the full dev profile (Postgres, Redis, Kafka, ClickHouse, api,
agents, fusion, ingest-worker, web, mcp, …). The command resolves the repo
root automatically, so it works from any subdirectory.
@@ -418,7 +418,7 @@ run `pnpm build`.
### 7. Tear down
```bash
-docker compose -f docker-compose.dev.yml down
+docker compose -f infra/compose/docker-compose.dev.yml down
```
Or keep the stack running and re-submit different fixtures — `aisoc
diff --git a/apps/docs/sidebars.ts b/apps/docs/sidebars.ts
index 4d37a57a8..fbec8ba15 100644
--- a/apps/docs/sidebars.ts
+++ b/apps/docs/sidebars.ts
@@ -50,6 +50,7 @@ const sidebars: SidebarsConfig = {
type: "category",
label: "Architecture",
items: [
+ "architecture/overview",
"architecture/agents",
"architecture/graph-schema",
"architecture/itsm-as-source-of-truth",
@@ -109,6 +110,7 @@ const sidebars: SidebarsConfig = {
"operations/secrets",
"operations/airgap",
"operations/air-gapped",
+ "operations/codespaces",
"operations/theming",
"operations/upgrades",
"operations/notifications",
diff --git a/apps/web/Dockerfile b/apps/web/Dockerfile
index 65ba999d4..f19718cb9 100644
--- a/apps/web/Dockerfile
+++ b/apps/web/Dockerfile
@@ -24,7 +24,7 @@ ENV NEXT_TELEMETRY_DISABLED=1
# ─── Build-time rewrite targets (server-side) ───────────────────────────────
# Next.js bakes rewrite destinations into .next/routes-manifest.json at
# build time, so these args MUST be provided to docker build (e.g. via
-# `args:` in docker-compose.demo.yml's `web.build:` block) when targeting
+# `args:` in infra/compose/docker-compose.demo.yml's `web.build:` block) when targeting
# anything other than a single-host localhost dev setup. Defaults match the
# Compose stack's Docker DNS so a no-arg `docker build` still yields a
# working image inside the demo network.
diff --git a/apps/web/e2e/screenshots/console.spec.ts b/apps/web/e2e/screenshots/console.spec.ts
new file mode 100644
index 000000000..a4fae190d
--- /dev/null
+++ b/apps/web/e2e/screenshots/console.spec.ts
@@ -0,0 +1,62 @@
+import { test } from "@playwright/test";
+import { join } from "node:path";
+
+/**
+ * README hero screenshots — Phase 2 quick-win on-ramp.
+ *
+ * Captures the four product views the slim README embeds above the
+ * fold (`apps/web/public/screenshots/0{1..4}-*.png`). Each test below
+ * writes one PNG directly into the Playwright test-output directory;
+ * `scripts/aisoc-demo.ts --screenshots` lifts those PNGs into
+ * `apps/web/public/screenshots/` once the run is green.
+ *
+ * Designed to run against a seeded local demo
+ * (`pnpm aisoc:demo --no-open` keeps the stack up); set
+ * `AISOC_SCREENCAST_URL` to point at a remote deploy when needed.
+ *
+ * Like the screencast spec, these tests are recorders, not assertions.
+ * A missing selector still produces a screenshot (of whatever the page
+ * actually renders) — the human reviews the four PNGs before they
+ * land on `main`. The CI gate ensures all four files exist; visual
+ * regression for the four PNGs themselves lives in the Storybook
+ * `visual` project.
+ */
+
+const OUT = (name: string) => join(test.info().outputDir, name);
+
+test.describe.configure({ mode: "serial" });
+
+test("01 — Alerts queue (server-anchored SLA countdowns)", async ({ page }) => {
+ await page.goto("/queue");
+ await page.waitForLoadState("domcontentloaded");
+ // Wait for the queue table to settle (skeleton → real rows). We
+ // never block hard on a selector — the recorder must still produce
+ // a screenshot even when the UI shape has drifted.
+ await page.waitForTimeout(2_500);
+ await page.screenshot({ path: OUT("01-alerts-queue.png"), fullPage: false });
+});
+
+test("02 — Investigation Rail (deterministic correlation narrative)", async ({ page }) => {
+ // Land on the seeded LockBit case; the InvestigationRail renders to
+ // the right of the alert detail and is the highest-density visual
+ // payload in the console.
+ await page.goto("/cases/INC-RT-001?tab=ledger");
+ await page.waitForLoadState("domcontentloaded");
+ await page.waitForTimeout(3_500);
+ await page.screenshot({ path: OUT("02-investigation-rail.png"), fullPage: false });
+});
+
+test("03 — /hunt workbench (natural-language → ES|QL / SPL / KQL)", async ({ page }) => {
+ await page.goto("/hunt");
+ await page.waitForLoadState("domcontentloaded");
+ // Give the editor enough time to mount + render its preset list.
+ await page.waitForTimeout(2_500);
+ await page.screenshot({ path: OUT("03-hunt-workbench.png"), fullPage: false });
+});
+
+test("04 — Marketplace (plugins, playbooks, detections)", async ({ page }) => {
+ await page.goto("/marketplace");
+ await page.waitForLoadState("domcontentloaded");
+ await page.waitForTimeout(2_500);
+ await page.screenshot({ path: OUT("04-marketplace.png"), fullPage: false });
+});
diff --git a/apps/web/playwright.config.ts b/apps/web/playwright.config.ts
index 3e6a09675..ea91e3162 100644
--- a/apps/web/playwright.config.ts
+++ b/apps/web/playwright.config.ts
@@ -30,6 +30,7 @@ import { defineConfig, devices } from "@playwright/test";
const PROJECT = (process.env.PLAYWRIGHT_PROJECT ?? "").toLowerCase();
const IS_VISUAL = PROJECT === "visual";
const IS_JOURNEY = PROJECT === "journey";
+const IS_SCREENSHOTS = PROJECT === "screenshots";
export default defineConfig({
testDir: "./e2e",
@@ -81,7 +82,9 @@ export default defineConfig({
? "http://127.0.0.1:6007"
: IS_JOURNEY
? "http://localhost:3100"
- : (process.env.AISOC_SCREENCAST_URL ?? "https://tryaisoc.com"),
+ : IS_SCREENSHOTS
+ ? (process.env.AISOC_SCREENCAST_URL ?? "http://localhost:3000")
+ : (process.env.AISOC_SCREENCAST_URL ?? "https://tryaisoc.com"),
trace: IS_JOURNEY ? "retain-on-failure" : "off",
screenshot: IS_JOURNEY ? "only-on-failure" : "off",
video: "off",
@@ -124,5 +127,19 @@ export default defineConfig({
viewport: { width: 1440, height: 900 },
},
},
+ {
+ // Phase 2 quick-win on-ramp: README hero screenshots. Runs
+ // against a seeded local demo (`pnpm aisoc:demo`) or any
+ // deployed URL pointed at by `AISOC_SCREENCAST_URL`. Output
+ // viewport is 1440x900 so the captured PNGs land in the same
+ // 1.6:1 aspect ratio the README image grid expects.
+ name: "screenshots",
+ testMatch: /screenshots\/.*\.spec\.ts$/,
+ use: {
+ ...devices["Desktop Chrome"],
+ deviceScaleFactor: 1,
+ viewport: { width: 1440, height: 900 },
+ },
+ },
],
});
diff --git a/apps/web/public/demo/.gitkeep b/apps/web/public/demo/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/apps/web/public/demo/README.md b/apps/web/public/demo/README.md
new file mode 100644
index 000000000..2b8e80811
--- /dev/null
+++ b/apps/web/public/demo/README.md
@@ -0,0 +1,43 @@
+# `apps/web/public/demo/` — screencast assets
+
+This directory is the **canonical home** for the 90-second AiSOC product
+screencast and its accompanying poster/GIF. The marketing landing page,
+documentation, and several READMEs link to file paths under this
+directory; treat the paths below as a stable contract.
+
+| Asset | Purpose | Source |
+|---|---|---|
+| `demo.mp4` | 90 s product walkthrough, 1280×720, H.264 + AAC, ≤ 8 MB | recorded by [`.github/workflows/screencast.yml`](../../../../.github/workflows/screencast.yml) following [`docs/demo/SCREENCAST_SHOTLIST.md`](../../../../docs/demo/SCREENCAST_SHOTLIST.md) |
+| `demo-poster.png` | 1280×720 poster frame for the `<video>` tag | captured by [`apps/web/e2e/demo/screencast.spec.ts`](../../e2e/demo/screencast.spec.ts) at the cover frame |
+| `hero.gif` | README hero loop (≤ 10 s, ≤ 5 MB) | rendered from `demo.mp4` by `scripts/aisoc-demo.ts --record --gif` (lands in Phase 2 of the GitHub on-ramp fix) |
+
+## Why the files are not committed yet
+
+The screencast workflow runs **manually** (`workflow_dispatch`) and
+uploads the rendered `.mp4` + poster as **release assets**, not into
+this directory. Until the v8.0 launch cut ships, this directory is
+empty (`.gitkeep` only) so:
+
+- The placement contract above is documented and discoverable.
+- The marketing-site hero (`apps/web/src/components/onboarding/StartHero.tsx`)
+ can ship a graceful fallback when the asset is missing.
+- Nothing in the repo lies about the asset being available.
+
+The text-only stub at [`apps/web/public/.demo-mp4-placeholder`](../.demo-mp4-placeholder)
+captures the recording brief and the do/don't rules for whoever picks
+up the recording. Read it before you commit a real `demo.mp4` to this
+directory.
+
+## After the screencast ships
+
+When the next maintainer cuts the v8.0 launch screencast:
+
+1. Run the `90s demo screencast (record)` workflow from the Actions
+ tab with `release_tag=v8.0.0`.
+2. Download the workflow's `screencast-<sha>` artefact.
+3. Copy `demo.mp4` and `demo-poster.png` into this directory.
+4. Run `pnpm aisoc:demo --record --gif` (lands in Phase 2) to render
+ `hero.gif` from the `.mp4`.
+5. Open a PR with all three files; the file-size guard in
+ [`.github/workflows/ci.yml`](../../../../.github/workflows/ci.yml)
+ will fail the build if any individual asset exceeds its budget.
diff --git a/apps/web/public/screenshots/01-alerts-queue.svg b/apps/web/public/screenshots/01-alerts-queue.svg
new file mode 100644
index 000000000..03d1571b4
--- /dev/null
+++ b/apps/web/public/screenshots/01-alerts-queue.svg
@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1440 900" role="img" aria-label="Alerts queue screenshot placeholder">
+ <defs>
+ <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0" stop-color="#0f172a"/>
+ <stop offset="1" stop-color="#1e293b"/>
+ </linearGradient>
+ </defs>
+ <rect width="1440" height="900" fill="url(#bg)"/>
+ <text x="720" y="380" text-anchor="middle" fill="#e2e8f0" font-family="ui-sans-serif, system-ui, sans-serif" font-size="40" font-weight="700">Alerts queue  server-anchored SLA countdowns</text>
+ <text x="720" y="440" text-anchor="middle" fill="#94a3b8" font-family="ui-sans-serif, system-ui, sans-serif" font-size="22">Real screenshot ships with the Phase 2 visual rollup.</text>
+ <text x="720" y="480" text-anchor="middle" fill="#64748b" font-family="ui-sans-serif, system-ui, sans-serif" font-size="20">Generate locally: pnpm aisoc:demo --screenshots</text>
+ <text x="720" y="540" text-anchor="middle" fill="#475569" font-family="ui-monospace, monospace" font-size="18">apps/web/public/screenshots/01-alerts-queue.png</text>
+</svg>
diff --git a/apps/web/public/screenshots/02-investigation-rail.svg b/apps/web/public/screenshots/02-investigation-rail.svg
new file mode 100644
index 000000000..06a692814
--- /dev/null
+++ b/apps/web/public/screenshots/02-investigation-rail.svg
@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1440 900" role="img" aria-label="Investigation Rail screenshot placeholder">
+ <defs>
+ <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0" stop-color="#0f172a"/>
+ <stop offset="1" stop-color="#1e293b"/>
+ </linearGradient>
+ </defs>
+ <rect width="1440" height="900" fill="url(#bg)"/>
+ <text x="720" y="380" text-anchor="middle" fill="#e2e8f0" font-family="ui-sans-serif, system-ui, sans-serif" font-size="40" font-weight="700">Investigation Rail  narrative + pivot-path entities</text>
+ <text x="720" y="440" text-anchor="middle" fill="#94a3b8" font-family="ui-sans-serif, system-ui, sans-serif" font-size="22">Real screenshot ships with the Phase 2 visual rollup.</text>
+ <text x="720" y="480" text-anchor="middle" fill="#64748b" font-family="ui-sans-serif, system-ui, sans-serif" font-size="20">Generate locally: pnpm aisoc:demo --screenshots</text>
+ <text x="720" y="540" text-anchor="middle" fill="#475569" font-family="ui-monospace, monospace" font-size="18">apps/web/public/screenshots/02-investigation-rail.png</text>
+</svg>
diff --git a/apps/web/public/screenshots/03-hunt-workbench.svg b/apps/web/public/screenshots/03-hunt-workbench.svg
new file mode 100644
index 000000000..72446b228
--- /dev/null
+++ b/apps/web/public/screenshots/03-hunt-workbench.svg
@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1440 900" role="img" aria-label="Hunt workbench screenshot placeholder">
+ <defs>
+ <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0" stop-color="#0f172a"/>
+ <stop offset="1" stop-color="#1e293b"/>
+ </linearGradient>
+ </defs>
+ <rect width="1440" height="900" fill="url(#bg)"/>
+ <text x="720" y="380" text-anchor="middle" fill="#e2e8f0" font-family="ui-sans-serif, system-ui, sans-serif" font-size="40" font-weight="700">/hunt workbench  NL prompt to ES|QL / SPL / KQL</text>
+ <text x="720" y="440" text-anchor="middle" fill="#94a3b8" font-family="ui-sans-serif, system-ui, sans-serif" font-size="22">Real screenshot ships with the Phase 2 visual rollup.</text>
+ <text x="720" y="480" text-anchor="middle" fill="#64748b" font-family="ui-sans-serif, system-ui, sans-serif" font-size="20">Generate locally: pnpm aisoc:demo --screenshots</text>
+ <text x="720" y="540" text-anchor="middle" fill="#475569" font-family="ui-monospace, monospace" font-size="18">apps/web/public/screenshots/03-hunt-workbench.png</text>
+</svg>
diff --git a/apps/web/public/screenshots/04-marketplace.svg b/apps/web/public/screenshots/04-marketplace.svg
new file mode 100644
index 000000000..a544d5026
--- /dev/null
+++ b/apps/web/public/screenshots/04-marketplace.svg
@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1440 900" role="img" aria-label="Marketplace screenshot placeholder">
+ <defs>
+ <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+ <stop offset="0" stop-color="#0f172a"/>
+ <stop offset="1" stop-color="#1e293b"/>
+ </linearGradient>
+ </defs>
+ <rect width="1440" height="900" fill="url(#bg)"/>
+ <text x="720" y="380" text-anchor="middle" fill="#e2e8f0" font-family="ui-sans-serif, system-ui, sans-serif" font-size="40" font-weight="700">Marketplace  plugins, playbooks, detections</text>
+ <text x="720" y="440" text-anchor="middle" fill="#94a3b8" font-family="ui-sans-serif, system-ui, sans-serif" font-size="22">Real screenshot ships with the Phase 2 visual rollup.</text>
+ <text x="720" y="480" text-anchor="middle" fill="#64748b" font-family="ui-sans-serif, system-ui, sans-serif" font-size="20">Generate locally: pnpm aisoc:demo --screenshots</text>
+ <text x="720" y="540" text-anchor="middle" fill="#475569" font-family="ui-monospace, monospace" font-size="18">apps/web/public/screenshots/04-marketplace.png</text>
+</svg>
diff --git a/apps/web/public/screenshots/README.md b/apps/web/public/screenshots/README.md
new file mode 100644
index 000000000..8cc0788dd
--- /dev/null
+++ b/apps/web/public/screenshots/README.md
@@ -0,0 +1,48 @@
+# `apps/web/public/screenshots/` — README hero screenshots
+
+This directory holds the four product screenshots that appear in the
+`README.md` hero grid:
+
+| Slot | Final path | Today (placeholder) | Caption |
+|---|---|---|---|
+| 1 | `01-alerts-queue.png` | `01-alerts-queue.svg` | Alerts queue — server-anchored SLA countdowns |
+| 2 | `02-investigation-rail.png` | `02-investigation-rail.svg` | Investigation Rail — deterministic correlation narrative |
+| 3 | `03-hunt-workbench.png` | `03-hunt-workbench.svg` | `/hunt` workbench — NL → ES&#124;QL / SPL / KQL |
+| 4 | `04-marketplace.png` | `04-marketplace.svg` | Marketplace — plugins, playbooks, detections |
+
+## Today
+
+The four `.svg` placeholders ship with the [Phase 2 visuals rollup](../../../../README.md) so the
+README image grid never shows a broken image. They are 1440×900 (the
+viewport the screenshot spec captures at) and labelled with the path
+they will eventually be replaced by.
+
+## After the real screenshots land
+
+When the next maintainer captures the production screenshots:
+
+1. Boot the demo:
+
+ ```bash
+ pnpm aisoc:demo --no-open --quick
+ ```
+
+2. Capture the four PNGs (writes the files into this directory):
+
+ ```bash
+ pnpm aisoc:demo --screenshots
+ ```
+
+3. Sanity-check the diff and open a PR:
+
+ ```bash
+ git status -s apps/web/public/screenshots/
+ git add apps/web/public/screenshots/*.png
+ ```
+
+4. In the same PR, swap the four `.svg` references in `README.md`
+ to `.png`. Until step 4 lands the README intentionally points at
+ the placeholders so a fresh clone never shows a broken image.
+
+The Playwright spec that drives the capture lives at
+[`apps/web/e2e/screenshots/console.spec.ts`](../../e2e/screenshots/console.spec.ts).
diff --git a/apps/web/src/app/(app)/identity/permissions/EffectivePermissionsView.tsx b/apps/web/src/app/(app)/identity/permissions/EffectivePermissionsView.tsx
index 9cd0b40bc..a8cf2073a 100644
--- a/apps/web/src/app/(app)/identity/permissions/EffectivePermissionsView.tsx
+++ b/apps/web/src/app/(app)/identity/permissions/EffectivePermissionsView.tsx
@@ -554,7 +554,7 @@ export function EffectivePermissionsView() {
The backend resolver for {PROVIDER_LABEL[provider]} is registered but
not yet wired up to the live snapshot store. Switch to AWS to see a
fully resolved Cytoscape graph, or watch{' '}
- <span className="font-mono text-xs">AISOC_V8_PROGRESS.md</span>{' '}
+ <span className="font-mono text-xs">docs/roadmap/v8-progress.md</span>{' '}
for the next provider rollout.
</p>
</div>
diff --git a/apps/web/src/app/(marketing)/sovereign/page.tsx b/apps/web/src/app/(marketing)/sovereign/page.tsx
index 526a2d0ed..a8d2fe290 100644
--- a/apps/web/src/app/(marketing)/sovereign/page.tsx
+++ b/apps/web/src/app/(marketing)/sovereign/page.tsx
@@ -10,7 +10,7 @@ import Link from 'next/link';
* path in the repo (Phase 1.6 audit — anything that 404'd has been corrected
* to the actual directory that ships the stack):
*
- * - Air-gapped overlay → `docker-compose.airgap.yml` + Ollama sidecar.
+ * - Air-gapped overlay → `infra/compose/docker-compose.airgap.yml` + Ollama sidecar.
* - On-prem / Helm → `infra/helm/aisoc/`.
* - AWS → `infra/terraform/main.tf` (S3-backed root stack
* re-using `modules/eks`, `modules/rds`,
@@ -71,9 +71,9 @@ const DEPLOYMENT_MODES: DeploymentMode[] = [
llm: 'Local Ollama sidecar',
residency: 'Operator-defined',
controlsAligned: 'SOC 2 · ISO 27001 · GDPR · DPDP',
- artefact: 'docker-compose.airgap.yml',
+ artefact: 'infra/compose/docker-compose.airgap.yml',
artefactHref:
- 'https://github.com/beenuar/AiSOC/blob/main/docker-compose.airgap.yml',
+ 'https://github.com/beenuar/AiSOC/blob/main/infra/compose/docker-compose.airgap.yml',
},
{
name: 'On-prem',
@@ -136,7 +136,7 @@ const PILLARS = [
{
label: 'Air-gap by config flag',
body: 'Set AISOC_AIRGAPPED=true and the platform refuses to make outbound calls — no LLM provider, no threat-intel feed, no telemetry. The Ollama overlay ships a pinned local model so the demo seed runs end-to-end with zero external calls.',
- cite: 'docker-compose.airgap.yml',
+ cite: 'infra/compose/docker-compose.airgap.yml',
},
{
label: 'BYO LLM endpoint',
@@ -242,7 +242,7 @@ export default function SovereignPage() {
</svg>
</a>
<a
- href="https://github.com/beenuar/AiSOC/blob/main/docker-compose.airgap.yml"
+ href="https://github.com/beenuar/AiSOC/blob/main/infra/compose/docker-compose.airgap.yml"
target="_blank"
rel="noreferrer"
className="inline-flex items-center gap-2 rounded-md border border-white/10 bg-white/[0.03] px-4 py-2 text-sm font-medium text-gray-300 transition hover:border-white/20 hover:bg-white/[0.06] hover:text-white"
@@ -511,8 +511,8 @@ export default function SovereignPage() {
<div className="mt-8 grid gap-4 md:grid-cols-3">
<RepoArtefact
label="Air-gap overlay"
- path="docker-compose.airgap.yml"
- href="https://github.com/beenuar/AiSOC/blob/main/docker-compose.airgap.yml"
+ path="infra/compose/docker-compose.airgap.yml"
+ href="https://github.com/beenuar/AiSOC/blob/main/infra/compose/docker-compose.airgap.yml"
body="Compose overlay that adds an Ollama sidecar with a pinned model and flips AISOC_AIRGAPPED=true on every service that calls an LLM."
/>
<RepoArtefact
diff --git a/detections/README.md b/detections/README.md
index d5c2142c0..7ff2b5eab 100644
--- a/detections/README.md
+++ b/detections/README.md
@@ -135,7 +135,7 @@ provenance:
`provenance.license` and `provenance.license_url` cover the legal redistribution
story; the canonical attribution table for every redistributed corpus lives in
-[`LICENSES.md`](../LICENSES.md). Without that file we cannot legally redistribute
+[`.github/LICENSES.md`](../.github/LICENSES.md). Without that file we cannot legally redistribute
imported content.
### Quarantine
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
deleted file mode 100644
index 9a9025772..000000000
--- a/docker-compose.dev.yml
+++ /dev/null
@@ -1,14 +0,0 @@
-# AiSOC — developer compose entrypoint.
-#
-# This file is a thin alias over `docker-compose.yml` so that the Quickstart
-# guide and demo scripts can use a stable, dev-flavoured command:
-#
-# docker compose -f docker-compose.dev.yml up -d
-#
-# It uses the Compose Spec `include` directive (Docker Compose v2.20+) to
-# pull in the full stack from `docker-compose.yml` without duplicating any
-# service definitions. Override files (e.g. `docker-compose.local.yml`) can
-# still be layered on top with additional `-f` flags.
-
-include:
- - docker-compose.yml
diff --git a/docs/design/landing-page-brief.md b/docs/design/landing-page-brief.md
index 9a81edc50..29de3f666 100644
--- a/docs/design/landing-page-brief.md
+++ b/docs/design/landing-page-brief.md
@@ -213,7 +213,7 @@ Ranked. Five total. Each one cites the shipped feature behind it.
Coolify. Plus a documented air-gap overlay with an Ollama sidecar and
per-tenant BYOK LLM credentials in the encrypted vault.
- **Repo evidence.** `infra/render/`, `infra/fly/`, `infra/helm/`,
- `infra/terraform/`, `docker-compose.airgap.yml`,
+ `infra/terraform/`, `infra/compose/docker-compose.airgap.yml`,
`apps/docs/docs/operations/air-gapped.md`,
`apps/web/src/app/(marketing)/sovereign/page.tsx`.
- **Metric to display.** Six deploy targets, one air-gap overlay, BYOK in
@@ -280,7 +280,7 @@ take it air-gapped on a flag.
**Defence.** `pnpm aisoc:demo` brings up the slim stack in ~3.5 minutes
warm. `render.yaml` powers a one-click deploy. `infra/helm/aisoc/` runs
on any Kubernetes. `infra/terraform/` brings up AWS. The air-gapped
-overlay at `docker-compose.airgap.yml` ships a pinned Ollama sidecar so
+overlay at `infra/compose/docker-compose.airgap.yml` ships a pinned Ollama sidecar so
the demo seed runs end-to-end with zero external calls; the
`AISOC_AIRGAPPED=true` flag refuses outbound LLM calls,
threat-intel feeds, and telemetry. Per-tenant LLM credentials in
@@ -895,7 +895,7 @@ Condensed teardown lives at `docs/design/landing-page-references.md`.
| Fly.io deploy script | `infra/fly/` | Manager | V5 | deploy | Shipped |
| Helm chart | `infra/helm/aisoc/` | CISO | V5 | deploy | Shipped |
| Terraform (AWS, GCP, BYOC) | `infra/terraform/` | CISO | V5 | deploy | Shipped |
-| Air-gap overlay (Ollama sidecar) | `docker-compose.airgap.yml` · `apps/docs/docs/operations/air-gapped.md` | CISO | V5, P4 | deploy, pillars (P4) | Shipped |
+| Air-gap overlay (Ollama sidecar) | `infra/compose/docker-compose.airgap.yml` · `apps/docs/docs/operations/air-gapped.md` | CISO | V5, P4 | deploy, pillars (P4) | Shipped |
| BYOK per-tenant LLM credentials | `services/api/app/models/tenant_llm.py` · `apps/web/src/components/settings/SettingsView.tsx`| CISO | V5, P3 | deploy, pillars (P3) | Shipped |
| L0–L4 maturity dial | `services/actions/app/services/maturity.py` · `apps/docs/docs/concepts/automation-maturity.md`| CISO | V1, P3 | features-hunt, pillars (P3) | Shipped |
| ChatOps approvals (Block Kit / Adaptive Cards) | `services/slack-bot/` · `services/notifications/.../adaptive_cards.py` | Analyst, manager | V1 | features-hunt | Shipped (T3.6 wip) |
diff --git a/LIVE-DEMO.md b/docs/operations/live-demo-runbook.md
similarity index 100%
rename from LIVE-DEMO.md
rename to docs/operations/live-demo-runbook.md
diff --git a/AISOC_V8_PROGRESS.md b/docs/roadmap/v8-progress.md
similarity index 100%
rename from AISOC_V8_PROGRESS.md
rename to docs/roadmap/v8-progress.md
diff --git a/MIGRATION.md b/docs/upgrade/MIGRATION.md
similarity index 100%
rename from MIGRATION.md
rename to docs/upgrade/MIGRATION.md
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 000000000..d0d48fd5e
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,68 @@
+# AiSOC examples
+
+Each scenario in this directory is a small, self-contained alert
+fixture you can walk through the AiSOC agent funnel two ways:
+
+1. **Real ingest** — `pnpm aisoc:submit examples/alerts/<name>.json`
+ posts the events to the running stack (started by `pnpm aisoc:demo`).
+ Fusion deduplicates, the four agents reason, and the result lands
+ in the [Investigation Rail](../apps/docs/docs/console/investigation-rail.md).
+
+2. **Offline simulator** — `aisoc-sandbox demo --scenario <name>` runs
+ the same scenario through a zero-dependency in-memory simulator.
+ No Docker, no API key, completes in < 5 s. Install path:
+ `pip install -e packages/aisoc-sandbox` from the repo root, or
+ (once v8.0 ships) `pip install aisoc-sandbox`.
+
+The five scenarios cover the most common attack patterns in modern
+SOC alert queues; collectively they exercise eleven MITRE ATT&CK
+techniques across initial access, credential access, lateral
+movement, privilege escalation, and exfiltration.
+
+| ID | Title | MITRE | Severity | Walkthrough |
+|---|---|---|---|---|
+| `lateral-movement` | Impossible-travel Okta sign-in | T1078, T1078.004 | high | [walkthrough](./lateral-movement.md) |
+| `aws-credential-exfil` | IAM keys used from new ASN, then `s3:GetObject` flood | T1552, T1567, T1078.004 | critical | [walkthrough](./aws-credential-exfil.md) |
+| `phishing-payload` | Click-through to credential-harvest page | T1566, T1566.002 | high | [walkthrough](./phishing-payload.md) |
+| `kubernetes-privesc` | Namespace SA bound to `cluster-admin` | T1098, T1078 | critical | [walkthrough](./kubernetes-privesc.md) |
+| `github-token-theft` | PAT leaked — six private repos cloned in 11 s | T1078, T1555, T1567 | high | [walkthrough](./github-token-theft.md) |
+
+## Layout
+
+```
+examples/
+├── README.md # this file
+├── alerts/
+│ ├── lateral-movement.json # 5x production-faithful OCSF/native-shape
+│ ├── aws-credential-exfil.json
+│ ├── phishing-payload.json
+│ ├── kubernetes-privesc.json
+│ └── github-token-theft.json
+├── lateral-movement.md # walkthroughs — what the agent does, step by step
+├── aws-credential-exfil.md
+├── phishing-payload.md
+├── kubernetes-privesc.md
+└── github-token-theft.md
+```
+
+The bundled offline scenarios live in
+[`packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/`](../packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/) — same IDs, simplified shape so the
+simulator stays a single small package.
+
+## Contributing a new scenario
+
+Open a [`good first issue`](https://github.com/beenuar/AiSOC/issues?q=is%3Aopen+label%3A%22good+first+issue%22)
+or send a PR that adds:
+
+1. `examples/alerts/<id>.json` — production-shape fixture with at
+ least one MITRE technique and a clear narrative in the `_description`.
+2. `examples/<id>.md` — walkthrough using the existing pages as a template.
+3. `packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/<id>.json` —
+ simplified sandbox variant so `aisoc-sandbox demo --scenario <id>`
+ works.
+4. Update the table in `examples/README.md` and (if relevant) the
+ tables in `README.md` and `packages/aisoc-sandbox/README.md`.
+
+A maintainer will pair the scenario with at least one detection rule
+in [`detections/`](../detections/) so the production funnel can
+actually fire on it.
diff --git a/examples/alerts/aws-credential-exfil.json b/examples/alerts/aws-credential-exfil.json
new file mode 100644
index 000000000..2bb44aa02
--- /dev/null
+++ b/examples/alerts/aws-credential-exfil.json
@@ -0,0 +1,71 @@
+{
+ "_description": "AWS credential exfiltration: long-lived IAM keys from `ci-svc-prod` are used from an ASN that the workload has never previously contacted, immediately followed by `s3:ListBuckets` + a bulk `s3:GetObject` flood against a confidential bucket. Three CloudTrail events. Routes through the `aws_cloudtrail` connector profile (OCSF class_uid 6003, API Activity).",
+ "_usage": "aisoc submit examples/alerts/aws-credential-exfil.json # real ingest\nbasoc-sandbox demo --scenario aws-credential-exfil # offline simulator",
+ "_mitre_techniques": ["T1552", "T1567", "T1078.004"],
+ "_severity": "critical",
+ "events": [
+ {
+ "uuid": "aaaaaaaa-1111-4111-8111-aaaaaaaaaaaa",
+ "eventTime": "2026-06-29T14:02:11.412Z",
+ "eventSource": "sts.amazonaws.com",
+ "eventName": "GetCallerIdentity",
+ "awsRegion": "us-east-1",
+ "sourceIPAddress": "198.51.100.77",
+ "userAgent": "aws-cli/2.13.0 Python/3.11.5 Linux/5.15.0-1041-aws",
+ "userIdentity": {
+ "type": "IAMUser",
+ "principalId": "AIDAEXAMPLEEXAMPLE99",
+ "arn": "arn:aws:iam::123456789012:user/ci-svc-prod",
+ "accountId": "123456789012",
+ "userName": "ci-svc-prod",
+ "accessKeyId": "AKIAEXAMPLE7QWERTY"
+ },
+ "requestParameters": null,
+ "responseElements": null,
+ "readOnly": true,
+ "eventType": "AwsApiCall",
+ "recipientAccountId": "123456789012"
+ },
+ {
+ "uuid": "bbbbbbbb-2222-4222-8222-bbbbbbbbbbbb",
+ "eventTime": "2026-06-29T14:02:18.991Z",
+ "eventSource": "s3.amazonaws.com",
+ "eventName": "ListBuckets",
+ "awsRegion": "us-east-1",
+ "sourceIPAddress": "198.51.100.77",
+ "userAgent": "aws-cli/2.13.0 Python/3.11.5 Linux/5.15.0-1041-aws",
+ "userIdentity": {
+ "type": "IAMUser",
+ "arn": "arn:aws:iam::123456789012:user/ci-svc-prod",
+ "userName": "ci-svc-prod",
+ "accessKeyId": "AKIAEXAMPLE7QWERTY"
+ },
+ "readOnly": true,
+ "eventType": "AwsApiCall"
+ },
+ {
+ "uuid": "cccccccc-3333-4333-8333-cccccccccccc",
+ "eventTime": "2026-06-29T14:02:34.500Z",
+ "eventSource": "s3.amazonaws.com",
+ "eventName": "GetObject",
+ "awsRegion": "us-east-1",
+ "sourceIPAddress": "198.51.100.77",
+ "userAgent": "aws-cli/2.13.0 Python/3.11.5 Linux/5.15.0-1041-aws",
+ "userIdentity": {
+ "type": "IAMUser",
+ "arn": "arn:aws:iam::123456789012:user/ci-svc-prod",
+ "userName": "ci-svc-prod",
+ "accessKeyId": "AKIAEXAMPLE7QWERTY"
+ },
+ "requestParameters": {
+ "bucketName": "acme-prod-customer-pii",
+ "key": "exports/customer-list-2026-06.parquet"
+ },
+ "additionalEventData": {
+ "totalObjectsListedInWindow": 4137
+ },
+ "readOnly": true,
+ "eventType": "AwsApiCall"
+ }
+ ]
+}
diff --git a/examples/alerts/github-token-theft.json b/examples/alerts/github-token-theft.json
new file mode 100644
index 000000000..3c7269bd7
--- /dev/null
+++ b/examples/alerts/github-token-theft.json
@@ -0,0 +1,56 @@
+{
+ "_description": "GitHub PAT theft: a personal-access token tied to `[email protected]` is used from an ASN the org has never previously contacted, against six private repositories in 11 seconds. Four `git.clone` audit events shown (full run had 6). Routes through the `github_audit` connector profile.",
+ "_usage": "aisoc submit examples/alerts/github-token-theft.json # real ingest\nbasoc-sandbox demo --scenario github-token-theft # offline simulator",
+ "_mitre_techniques": ["T1078", "T1555", "T1567"],
+ "_severity": "high",
+ "events": [
+ {
+ "uuid": "gh-001",
+ "@timestamp": "2026-06-25T18:01:22Z",
+ "action": "git.clone",
+ "actor": "carol",
+ "actor_location": {"country_code": "RO"},
+ "repo": "acme/customer-api",
+ "org": "acme",
+ "user_agent": "git/2.42.0",
+ "hashed_token_id": "ghp_xxxAAAAA",
+ "source_ip": "192.0.2.55"
+ },
+ {
+ "uuid": "gh-002",
+ "@timestamp": "2026-06-25T18:01:24Z",
+ "action": "git.clone",
+ "actor": "carol",
+ "actor_location": {"country_code": "RO"},
+ "repo": "acme/billing-svc",
+ "org": "acme",
+ "user_agent": "git/2.42.0",
+ "hashed_token_id": "ghp_xxxAAAAA",
+ "source_ip": "192.0.2.55"
+ },
+ {
+ "uuid": "gh-003",
+ "@timestamp": "2026-06-25T18:01:27Z",
+ "action": "git.clone",
+ "actor": "carol",
+ "actor_location": {"country_code": "RO"},
+ "repo": "acme/secrets-vault",
+ "org": "acme",
+ "user_agent": "git/2.42.0",
+ "hashed_token_id": "ghp_xxxAAAAA",
+ "source_ip": "192.0.2.55"
+ },
+ {
+ "uuid": "gh-004",
+ "@timestamp": "2026-06-25T18:01:33Z",
+ "action": "git.clone",
+ "actor": "carol",
+ "actor_location": {"country_code": "RO"},
+ "repo": "acme/iam",
+ "org": "acme",
+ "user_agent": "git/2.42.0",
+ "hashed_token_id": "ghp_xxxAAAAA",
+ "source_ip": "192.0.2.55"
+ }
+ ]
+}
diff --git a/examples/alerts/kubernetes-privesc.json b/examples/alerts/kubernetes-privesc.json
new file mode 100644
index 000000000..bbf77a370
--- /dev/null
+++ b/examples/alerts/kubernetes-privesc.json
@@ -0,0 +1,59 @@
+{
+ "_description": "Kubernetes privilege escalation: a namespace-scoped ServiceAccount in the `experiments` namespace is bound to the `cluster-admin` ClusterRole by `[email protected]` at 02:14 UTC (outside change-management window), then the SA immediately lists `secrets` in `kube-system`. Three audit events from the apiserver. Routes through the `k8s_audit` connector profile.",
+ "_usage": "aisoc submit examples/alerts/kubernetes-privesc.json # real ingest\nbasoc-sandbox demo --scenario kubernetes-privesc # offline simulator",
+ "_mitre_techniques": ["T1098", "T1078"],
+ "_severity": "critical",
+ "events": [
+ {
+ "uuid": "k8s-001",
+ "kind": "Event",
+ "apiVersion": "audit.k8s.io/v1",
+ "stage": "ResponseComplete",
+ "verb": "create",
+ "user": {"username": "[email protected]", "groups": ["system:authenticated"]},
+ "objectRef": {
+ "resource": "serviceaccounts",
+ "namespace": "experiments",
+ "name": "debug-runner",
+ "apiVersion": "v1"
+ },
+ "requestReceivedTimestamp": "2026-06-22T02:14:00.001Z",
+ "stageTimestamp": "2026-06-22T02:14:00.045Z",
+ "annotations": {"authorization.k8s.io/decision": "allow"}
+ },
+ {
+ "uuid": "k8s-002",
+ "kind": "Event",
+ "apiVersion": "audit.k8s.io/v1",
+ "stage": "ResponseComplete",
+ "verb": "create",
+ "user": {"username": "[email protected]", "groups": ["system:authenticated"]},
+ "objectRef": {
+ "resource": "clusterrolebindings",
+ "name": "debug-runner-cluster-admin",
+ "apiVersion": "rbac.authorization.k8s.io/v1"
+ },
+ "requestObject": {
+ "subjects": [{"kind": "ServiceAccount", "name": "debug-runner", "namespace": "experiments"}],
+ "roleRef": {"kind": "ClusterRole", "name": "cluster-admin", "apiGroup": "rbac.authorization.k8s.io"}
+ },
+ "requestReceivedTimestamp": "2026-06-22T02:14:42.103Z",
+ "stageTimestamp": "2026-06-22T02:14:42.198Z"
+ },
+ {
+ "uuid": "k8s-003",
+ "kind": "Event",
+ "apiVersion": "audit.k8s.io/v1",
+ "stage": "ResponseComplete",
+ "verb": "list",
+ "user": {"username": "system:serviceaccount:experiments:debug-runner", "groups": ["system:authenticated", "system:serviceaccounts:experiments"]},
+ "objectRef": {
+ "resource": "secrets",
+ "namespace": "kube-system",
+ "apiVersion": "v1"
+ },
+ "requestReceivedTimestamp": "2026-06-22T02:16:18.022Z",
+ "stageTimestamp": "2026-06-22T02:16:18.044Z"
+ }
+ ]
+}
diff --git a/examples/alerts/phishing-payload.json b/examples/alerts/phishing-payload.json
new file mode 100644
index 000000000..d25f61441
--- /dev/null
+++ b/examples/alerts/phishing-payload.json
@@ -0,0 +1,44 @@
+{
+ "_description": "Phishing click-through to a credential-harvest page. Three events: email delivered (sender domain `acme-paychecks.com`, registered 9 days ago); proxy URL click ~6 min after delivery; proxy form-post capture with `username` + `password` fields. Routes through the `email_gateway` and `web_proxy` connector profiles (OCSF class_uid 4009 + 4012).",
+ "_usage": "aisoc submit examples/alerts/phishing-payload.json # real ingest\nbasoc-sandbox demo --scenario phishing-payload # offline simulator",
+ "_mitre_techniques": ["T1566", "T1566.002"],
+ "_severity": "high",
+ "events": [
+ {
+ "uuid": "phish-0001",
+ "eventTime": "2026-06-15T11:14:00Z",
+ "eventSource": "email_gateway.example.com",
+ "eventName": "email.delivered",
+ "sender": "[email protected]",
+ "recipient": "[email protected]",
+ "subject": "Action required: payslip access expires today",
+ "sender_domain_age_days": 9,
+ "spf": "pass",
+ "dkim": "pass",
+ "dmarc": "pass",
+ "attachments": []
+ },
+ {
+ "uuid": "phish-0002",
+ "eventTime": "2026-06-15T11:20:32Z",
+ "eventSource": "web_proxy.example.com",
+ "eventName": "proxy.url_click",
+ "actor": "[email protected]",
+ "source_ip": "10.0.5.42",
+ "url": "https://acme-paychecks.com/login",
+ "domain_age_days": 9,
+ "category": "Uncategorized"
+ },
+ {
+ "uuid": "phish-0003",
+ "eventTime": "2026-06-15T11:20:54Z",
+ "eventSource": "web_proxy.example.com",
+ "eventName": "proxy.form_post",
+ "actor": "[email protected]",
+ "source_ip": "10.0.5.42",
+ "url": "https://acme-paychecks.com/login",
+ "form_fields": ["username", "password"],
+ "request_size_bytes": 412
+ }
+ ]
+}
diff --git a/examples/aws-credential-exfil.md b/examples/aws-credential-exfil.md
new file mode 100644
index 000000000..7566410e1
--- /dev/null
+++ b/examples/aws-credential-exfil.md
@@ -0,0 +1,74 @@
+# Walkthrough — `aws-credential-exfil`
+
+> **AWS credential exfiltration.** Long-lived IAM access keys belonging
+> to a CI service account (`ci-svc-prod`) are used from an ASN the
+> workload has never previously contacted, immediately followed by
+> `s3:ListBuckets` + bulk `s3:GetObject` against a tagged-confidential
+> bucket.
+
+- **Fixture:** [`examples/alerts/aws-credential-exfil.json`](./alerts/aws-credential-exfil.json)
+- **MITRE techniques:** T1552, T1567, T1078.004
+- **Severity at intake:** `critical`
+- **Confidence band (sandbox):** 100/100, `high`
+
+## Run it
+
+```bash
+# Offline simulator:
+aisoc-sandbox demo --scenario aws-credential-exfil
+
+# Real stack:
+pnpm aisoc:submit examples/alerts/aws-credential-exfil.json
+```
+
+## What the agent does, step by step
+
+### Step 0 · DetectAgent · detect
+
+Three CloudTrail events ingest as a single fused incident — the AWS
+GuardDuty + native AiSOC detections both fire on the
+`UnauthorizedAccess:IAMUser/AnomalousASN` pattern. Fusion deduplicates
+the three events and lifts the alert to `severity=critical` because
+the bucket carries the `Classification=Confidential` tag.
+
+### Step 1 · TriageAgent · triage
+
+The graph walk identifies that `ci-svc-prod` is a long-lived service
+account whose key has never rotated, and that the access pattern
+(`sts:GetCallerIdentity` → `s3:ListBuckets` → bulk `s3:GetObject`)
+matches three public access-key-leak postmortems from Q1 2026.
+
+**Decision:** Confidence `high` (100/100).
+
+### Step 2 · HuntAgent · hunt
+
+Sweeps the last 24 h for any other API calls from `198.51.100.77` or
+using `AKIAEXAMPLE7QWERTY`. The hunt confirms the key has been used
+from exactly one new IP and against exactly one new bucket — clean
+exfil signature, no broader compromise yet.
+
+### Step 3 · RespondAgent · respond
+
+Proposes a five-action containment burst — every action sits inside
+the `human_approval_required` gate because severity is `critical`:
+
+- `iam.access_key.deactivate({"access_key_id": "AKIAEXAMPLE7QWERTY"})`
+- `iam.user.attach_deny_policy({"user": "ci-svc-prod"})`
+- `s3.bucket.block_public_access({"bucket": "acme-prod-customer-pii"})`
+- `case.create(...)` at severity `critical`
+- `case.notify({"channel": "pagerduty", "service": "soc-tier1"})`
+
+## What the analyst would do next
+
+1. Approve `iam.access_key.deactivate` from the responder PWA. The
+ deny policy can wait until the on-call confirms there's no
+ automated rotation in flight.
+2. Look at the bucket's `s3:GetObject` audit log for the full set of
+ objects accessed — the alert shows one specific object, but the
+ `additionalEventData.totalObjectsListedInWindow=4137` suggests the
+ actor was iterating.
+3. Trigger the [secrets-rotation playbook](../playbooks/) for every
+ IAM key issued in the last 90 days.
+4. Open a separate case for `ci-svc-prod` itself — long-lived keys on
+ a CI account is the root cause, and the org should migrate to
+ short-lived OIDC tokens.
diff --git a/examples/github-token-theft.md b/examples/github-token-theft.md
new file mode 100644
index 000000000..df77193e6
--- /dev/null
+++ b/examples/github-token-theft.md
@@ -0,0 +1,78 @@
+# Walkthrough — `github-token-theft`
+
+> **GitHub PAT leaked.** A personal-access token tied to
+> `[email protected]` is used from an ASN the org has never previously
+> contacted, against six private repositories in 11 seconds. The
+> token's `repo` scope is wide enough to ex-filtrate every source
+> tree Carol can read.
+
+- **Fixture:** [`examples/alerts/github-token-theft.json`](./alerts/github-token-theft.json)
+- **MITRE techniques:** T1078, T1555, T1567
+- **Severity at intake:** `high`
+- **Confidence band (sandbox):** 87/100, `high`
+
+## Run it
+
+```bash
+# Offline simulator:
+aisoc-sandbox demo --scenario github-token-theft
+
+# Real stack:
+pnpm aisoc:submit examples/alerts/github-token-theft.json
+```
+
+## What the agent does, step by step
+
+### Step 0 · DetectAgent · detect
+
+The `github-pat-bulk-clone` detection fires on six private-repo clones
+from the same `hashed_token_id` within an 11-second window — well
+inside the per-token velocity threshold. Fusion correlates against the
+threat-intel feed and notes that the source ASN has appeared in two
+other OSS supply-chain incidents in the last 90 days.
+
+### Step 1 · TriageAgent · triage
+
+The graph walk pivots from `carol` to her org memberships and the
+repos she has push access to. The triage rationale notes that
+infostealer behaviour against the OS-native keystore is consistent
+with the access pattern (machine compromised, PAT lifted, used
+immediately).
+
+**Decision:** Confidence `high` (87/100).
+
+### Step 2 · HuntAgent · hunt
+
+Sweeps for any other action by Carol's PAT or session in the last
+24 h — including pushes, branch creations, and Action triggers. The
+hunt confirms the actor has only cloned so far; no malicious code has
+been pushed yet, which means there's a window to revoke before
+secrets are siphoned out of `acme/secrets-vault`.
+
+### Step 3 · RespondAgent · respond
+
+Proposes a five-action containment that closes both the credential
+path and the secrets-at-rest path:
+
+- `github.pat.revoke({"user": "carol", "token_prefix": "ghp_xxxAAAAA"})`
+- `github.user.session.revoke_all({"user": "carol"})`
+- `github.org.audit_member({"user": "carol", "lookback_days": 30})`
+- `secrets.rotate({"repositories": ["acme/secrets-vault", "acme/iam"]})`
+- `case.create(...)` at severity `high`
+
+**Decision:** 5 actions proposed; awaiting analyst approval (severity high).
+
+## What the analyst would do next
+
+1. Approve `github.pat.revoke` first — it has zero blast radius for
+ anyone other than Carol.
+2. Look at every commit + Action run + secret access from the cloned
+ repos in the last 7 days; even read-only cloning gives the actor
+ any secret that was committed historically (which is why
+ `secrets.rotate` is part of the response, not optional).
+3. Reach Carol via an out-of-band channel (phone, in-person) — not
+ Slack or email — to confirm she didn't run the clones and to
+ investigate her machine.
+4. Open a separate workstream on the org's PAT lifecycle — the org
+ should be on fine-grained GitHub App tokens, not personal-access
+ tokens with `repo` scope.
diff --git a/examples/kubernetes-privesc.md b/examples/kubernetes-privesc.md
new file mode 100644
index 000000000..ecee6f5ba
--- /dev/null
+++ b/examples/kubernetes-privesc.md
@@ -0,0 +1,76 @@
+# Walkthrough — `kubernetes-privesc`
+
+> **Namespace SA bound to `cluster-admin`.** A namespace-scoped
+> ServiceAccount in the `experiments` namespace is bound to the
+> `cluster-admin` ClusterRole by `[email protected]` at 02:14
+> UTC — outside the standard change-management window. The SA then
+> immediately lists `secrets` in `kube-system`.
+
+- **Fixture:** [`examples/alerts/kubernetes-privesc.json`](./alerts/kubernetes-privesc.json)
+- **MITRE techniques:** T1098, T1078
+- **Severity at intake:** `critical`
+- **Confidence band (sandbox):** 100/100, `high`
+
+## Run it
+
+```bash
+# Offline simulator:
+aisoc-sandbox demo --scenario kubernetes-privesc
+
+# Real stack:
+pnpm aisoc:submit examples/alerts/kubernetes-privesc.json
+```
+
+## What the agent does, step by step
+
+### Step 0 · DetectAgent · detect
+
+Two native detections fire: `k8s-clusterrolebinding-cluster-admin`
+(any new binding to `cluster-admin` outside a change-management
+window) and `k8s-secrets-list-by-sa` (a ServiceAccount listing
+`kube-system` secrets). Fusion lifts to `critical` because of the
+`cluster-admin` blast radius.
+
+### Step 1 · TriageAgent · triage
+
+The graph walk identifies that `[email protected]` has not
+performed any admin RBAC actions in the last 30 days, that the SA
+`debug-runner` was created less than 24 h prior, and that the
+namespace `experiments` has no production workloads — three
+independent signals consistent with credential-takeover-then-privesc.
+
+**Decision:** Confidence `high` (100/100).
+
+### Step 2 · HuntAgent · hunt
+
+Sweeps the last 24 h for every action by `[email protected]`
+across the cluster, and every action by the new SA `debug-runner`.
+The hunt surfaces the secret-list call as the only follow-on action
+so far — the actor hasn't yet exfiltrated anything from `kube-system`.
+
+### Step 3 · RespondAgent · respond
+
+Proposes containment that breaks the privilege chain without taking
+the cluster down:
+
+- `k8s.clusterrolebinding.delete({"name": "debug-runner-cluster-admin"})`
+- `k8s.serviceaccount.disable({"namespace": "experiments", "name": "debug-runner"})`
+- `user.session.revoke_all({"user": "[email protected]"})`
+- `case.create(...)` at severity `critical`
+- `case.notify({"channel": "pagerduty", "service": "kubernetes-on-call"})`
+
+**Decision:** 5 actions proposed; awaiting analyst approval (severity critical).
+
+## What the analyst would do next
+
+1. Approve the `clusterrolebinding.delete` first — it cuts the actor's
+ privilege immediately. The SA `disable` and the user session revoke
+ can follow in any order.
+2. Audit every secret in `kube-system` that the SA could have read in
+ its short window of cluster-admin access. Rotate anything sensitive.
+3. Open a separate ticket on the change-management process: a
+ binding to `cluster-admin` should require a PR + two approvers,
+ not a single API call.
+4. Review the `experiments` namespace's IAM bindings — there might be
+ other latent SA-with-broad-perms patterns to clean up before they
+ become incidents.
diff --git a/examples/lateral-movement.md b/examples/lateral-movement.md
new file mode 100644
index 000000000..234c43ccb
--- /dev/null
+++ b/examples/lateral-movement.md
@@ -0,0 +1,93 @@
+# Walkthrough — `lateral-movement`
+
+> **Impossible-travel Okta sign-in.** Alice signs in successfully from
+> New York at 09:30 UTC, then again from Saint Petersburg eight
+> minutes later. The geographical pivot is physically impossible
+> inside that window.
+
+- **Fixture:** [`examples/alerts/lateral-movement.json`](./alerts/lateral-movement.json)
+- **MITRE techniques:** T1078, T1078.004
+- **Severity at intake:** `high`
+- **Confidence band (sandbox):** 83/100, `high`
+
+## Run it
+
+```bash
+# Offline simulator (< 5 s, no Docker):
+aisoc-sandbox demo --scenario lateral-movement
+
+# Real stack (after `pnpm aisoc:demo`):
+pnpm aisoc:submit examples/alerts/lateral-movement.json
+```
+
+## What the agent does, step by step
+
+### Step 0 · DetectAgent · detect
+
+Matches the two Okta `user.session.start` events against the 800+
+native Sigma ruleset. The `okta-impossible-travel` rule fires on the
+geographical delta + the sub-10-minute time window, and Fusion lifts
+the per-alert confidence by another notch because both sessions
+authenticated through the same `FACTOR_PROVIDER`.
+
+> would-call `rules.match({"rule_count": "800+", "technique_set": ["T1078", "T1078.004"]})`
+>
+> would-call `fusion.score({"window_minutes": 15})`
+
+**Decision:** open alert at `severity=high`.
+
+### Step 1 · TriageAgent · triage
+
+Cross-references the user against Qdrant for prior cases involving
+`[email protected]` and walks the Neo4j graph two hops out from the
+user node to surface devices and groups the user owns. The decision
+copy ("authenticated session signals look legitimate at the protocol
+layer, but the geo pivot between sequential events is physically
+impossible — classic credential takeover") mirrors what an analyst
+would write at handoff.
+
+> would-call `qdrant.semantic_search({"k": 5, "collection": "cases"})`
+>
+> would-call `graph.neighbours({"depth": 2})`
+
+**Decision:** Confidence `high` (83/100).
+
+### Step 2 · HuntAgent · hunt
+
+Translates the hypothesis "any activity by `[email protected]` in last
+24 h" into an ES|QL query and sweeps the warm tier. The pivot reveals
+nothing else compromised beyond the alert payload — a clean,
+contained incident.
+
+> would-call `nl_to_query.translate({"hypothesis": "any activity by [email protected] in last 24h"})`
+>
+> would-call `lake.query({"language": "ES|QL", "row_cap": 1000})`
+
+**Decision:** Pivot complete; no additional compromised entities.
+
+### Step 3 · RespondAgent · respond
+
+Proposes the graduated containment: revoke every active session,
+require password reset, create the case, page the SOC on-call. The
+**blast radius is human_approval_required** because the severity is
+`high`; nothing executes without analyst confirmation.
+
+> would-call `user.session.revoke_all({"user": "[email protected]"})`
+>
+> would-call `user.require_password_reset({"user": "[email protected]"})`
+>
+> would-call `case.create({"title": "Lateral movement — impossible-travel Okta sign-in", "severity": "high"})`
+>
+> would-call `case.notify({"channel": "slack", "audience": "soc-on-call"})`
+
+**Decision:** 4 actions proposed; awaiting analyst approval before execution.
+
+## What the analyst would do next
+
+1. Approve `user.session.revoke_all` (the only single-user-blast-radius
+ action) immediately via the responder PWA.
+2. Pivot on the second IP (203.0.113.50) in the [Threat Intel](https://docs.tryaisoc.com/console/threat-intel) tab to see if it has appeared in
+ other tenants' OTX feeds.
+3. Page Alice's manager from the case to confirm whether she travelled.
+4. If credential reuse is suspected: rotate every API key in Alice's
+ 1Password vault from the [credential vault rotation runbook](../apps/docs/docs/operations/credentials.md).
diff --git a/examples/phishing-payload.md b/examples/phishing-payload.md
new file mode 100644
index 000000000..0122e4929
--- /dev/null
+++ b/examples/phishing-payload.md
@@ -0,0 +1,77 @@
+# Walkthrough — `phishing-payload`
+
+> **Click-through to a credential-harvest page.** A phishing email
+> passes perimeter filters because the sender domain was less than
+> 14 days old and had valid DMARC alignment for a typosquatted root.
+> Bob clicks the link 6 minutes after delivery and arrives at a domain
+> that imitates the corporate SSO. The credential POST is captured at
+> the proxy.
+
+- **Fixture:** [`examples/alerts/phishing-payload.json`](./alerts/phishing-payload.json)
+- **MITRE techniques:** T1566, T1566.002
+- **Severity at intake:** `high`
+- **Confidence band (sandbox):** 87/100, `high`
+
+## Run it
+
+```bash
+# Offline simulator:
+aisoc-sandbox demo --scenario phishing-payload
+
+# Real stack:
+pnpm aisoc:submit examples/alerts/phishing-payload.json
+```
+
+## What the agent does, step by step
+
+### Step 0 · DetectAgent · detect
+
+The detection chain fires three rules in sequence: `domain-young`
+(domain age &lt; 14 days), `email-spf-pass-but-typosquat` (DMARC passed
+because the typosquat owns its own SPF), and `proxy-credential-post`
+(form fields `username` + `password` posted to a non-allowlisted
+domain). Fusion correlates the three events into one incident with a
+deterministic correlation narrative.
+
+### Step 1 · TriageAgent · triage
+
+The triage rationale references the known phishing playbook: the
+click happened **inside the standard credential-harvest window from
+email delivery** (under 10 minutes), and the destination domain
+**registered less than 14 days ago** — both are public indicators of
+campaign-style credential phishing.
+
+**Decision:** Confidence `high` (87/100).
+
+### Step 2 · HuntAgent · hunt
+
+Pivots on Bob's identity to see whether anyone else in the org
+received email from `acme-paychecks.com` in the last 7 days. The hunt
+also checks whether Bob's session shows any post-credential-POST API
+calls (the attacker hasn't logged in with the stolen credential
+yet — there's still a window to revoke).
+
+### Step 3 · RespondAgent · respond
+
+Proposes the canonical phishing containment:
+
+- `proxy.block_domain({"domain": "acme-paychecks.com"})`
+- `user.session.revoke_all({"user": "[email protected]"})`
+- `user.require_password_reset({"user": "[email protected]"})`
+- `email.search_and_purge({"sender": "[email protected]"})`
+- `case.create(...)` at severity `high`
+
+**Decision:** 5 actions proposed; awaiting analyst approval (severity high).
+
+## What the analyst would do next
+
+1. Approve `proxy.block_domain` and `user.session.revoke_all`
+ immediately — both have small blast radius.
+2. Run the `email.search_and_purge` action with caution: it will
+ remove the message from every mailbox in the org. Confirm with the
+ IT lead first.
+3. Add `acme-paychecks.com` to the perimeter blocklist permanently,
+ not just at the proxy.
+4. Open a brief learning case in [Threat Intel](https://docs.tryaisoc.com/console/threat-intel)
+ so the org's analysts know to look for similar typosquat patterns
+ over the next 30 days.
diff --git a/infra/cloudflare/README.md b/infra/cloudflare/README.md
index 96a6bfcb4..4bff098df 100644
--- a/infra/cloudflare/README.md
+++ b/infra/cloudflare/README.md
@@ -9,7 +9,7 @@ own machine without opening a single inbound port on your router or firewall.
> **Why a tunnel and not a direct LAN bind?**
> Compose binds every service port to `127.0.0.1` by default (see
-> `docker-compose.yml` and `docker-compose.demo.yml`). That keeps the dev
+> `docker-compose.yml` and `infra/compose/docker-compose.demo.yml`). That keeps the dev
> passwords that ship with the repo from leaking onto your LAN. The tunnel
> punches a single outbound TLS connection to Cloudflare and lets us route
> traffic in front of `cloudflared` instead of in front of Compose.
@@ -143,7 +143,7 @@ If you'd rather drive the pieces yourself:
```sh
# 1. Make sure the stack is up.
-pnpm aisoc:demo # or: docker compose -f docker-compose.demo.yml up -d
+pnpm aisoc:demo # or: docker compose -f infra/compose/docker-compose.demo.yml up -d
# 2. Bring up the tunnel.
bash infra/cloudflare/tunnel.sh
diff --git a/docker-compose.airgap.yml b/infra/compose/docker-compose.airgap.yml
similarity index 93%
rename from docker-compose.airgap.yml
rename to infra/compose/docker-compose.airgap.yml
index fb1688bb4..b4f6a9e63 100644
--- a/docker-compose.airgap.yml
+++ b/infra/compose/docker-compose.airgap.yml
@@ -1,7 +1,7 @@
###############################################################################
# AiSOC — Air-gapped / Local-LLM overlay
#
-# Extends docker-compose.demo.yml to run entirely without external LLM calls.
+# Extends infra/compose/docker-compose.demo.yml to run entirely without external LLM calls.
# Adds an Ollama service with a pinned model and sets AISOC_AIRGAPPED=true on
# every service that calls an LLM.
#
@@ -11,8 +11,8 @@
#
# Usage (air-gapped demo):
# docker compose \
-# -f docker-compose.demo.yml \
-# -f docker-compose.airgap.yml \
+# -f infra/compose/docker-compose.demo.yml \
+# -f infra/compose/docker-compose.airgap.yml \
# up -d
#
# The init container below will pull the model automatically on first boot.
diff --git a/docker-compose.demo.yml b/infra/compose/docker-compose.demo.yml
similarity index 96%
rename from docker-compose.demo.yml
rename to infra/compose/docker-compose.demo.yml
index df688c4fb..0b96fc72a 100644
--- a/docker-compose.demo.yml
+++ b/infra/compose/docker-compose.demo.yml
@@ -14,8 +14,8 @@
# pnpm aisoc:demo
#
# Manual usage:
-# docker compose -f docker-compose.demo.yml pull
-# docker compose -f docker-compose.demo.yml up -d
+# docker compose -f infra/compose/docker-compose.demo.yml pull
+# docker compose -f infra/compose/docker-compose.demo.yml up -d
#
# SECURITY NOTE
# -------------
@@ -125,9 +125,10 @@ services:
image: ghcr.io/beenuar/aisoc-core-api:${AISOC_TAG:-latest}
# Local build context for `pnpm aisoc:demo --rebuild`. Without this the
# `--build` flag is a no-op because compose has nothing to build from.
- # When pulling prebuilt images this block is ignored.
+ # When pulling prebuilt images this block is ignored. Paths are relative
+ # to this file (infra/compose/), hence `../../services/...`.
build:
- context: ./services/api
+ context: ../../services/api
container_name: aisoc-demo-api
# `missing` lets `pnpm aisoc:demo --rebuild` use locally built images
# without being clobbered by a registry pull. Compose still pulls when
@@ -173,7 +174,7 @@ services:
agents:
image: ghcr.io/beenuar/aisoc-agents:${AISOC_TAG:-latest}
build:
- context: ./services/agents
+ context: ../../services/agents
container_name: aisoc-demo-agents
pull_policy: missing
depends_on:
@@ -198,7 +199,7 @@ services:
realtime:
image: ghcr.io/beenuar/aisoc-realtime:${AISOC_TAG:-latest}
build:
- context: ./services/realtime
+ context: ../../services/realtime
container_name: aisoc-demo-realtime
pull_policy: missing
depends_on:
@@ -229,7 +230,7 @@ services:
seed:
image: ghcr.io/beenuar/aisoc-core-api:${AISOC_TAG:-latest}
build:
- context: ./services/api
+ context: ../../services/api
container_name: aisoc-demo-seed
pull_policy: missing
depends_on:
@@ -256,7 +257,7 @@ services:
# proxies those to the services below using the Docker DNS targets in
# `environment:`.
build:
- context: .
+ context: ../..
dockerfile: apps/web/Dockerfile
# Next.js bakes rewrite destinations into routes-manifest.json at
# `next build` time, not at `next start`. These args MUST match the
diff --git a/infra/compose/docker-compose.dev.yml b/infra/compose/docker-compose.dev.yml
new file mode 100644
index 000000000..a998de03b
--- /dev/null
+++ b/infra/compose/docker-compose.dev.yml
@@ -0,0 +1,15 @@
+# AiSOC — developer compose entrypoint.
+#
+# This file is a thin alias over `docker-compose.yml` so that the Quickstart
+# guide and demo scripts can use a stable, dev-flavoured command:
+#
+# docker compose -f infra/compose/docker-compose.dev.yml up -d
+#
+# It uses the Compose Spec `include` directive (Docker Compose v2.20+) to
+# pull in the full stack from the repo-root `docker-compose.yml` without
+# duplicating any service definitions. Override files (e.g.
+# `docker-compose.local.yml`) can still be layered on top with additional
+# `-f` flags.
+
+include:
+ - ../../docker-compose.yml
diff --git a/infra/fly/README.md b/infra/fly/README.md
index 1e17cbd6c..3e82291ba 100644
--- a/infra/fly/README.md
+++ b/infra/fly/README.md
@@ -104,7 +104,7 @@ maintaining a fifth Dockerfile or Fly app:
| Every deploy | `[deploy].release_command` in `infra/fly/api/fly.toml` runs `alembic upgrade head && python -m app.scripts.seed_demo` on every `flyctl deploy`. Idempotent — a no-op against an already-seeded volume. |
| Post-deploy (bootstrap) | `flyctl ssh console -a aisoc-demo-api -C "python -m app.scripts.seed_demo"` runs once on a live api machine. Belt-and-suspenders for first-time deploys. |
| Daily refresh (00:00 UTC)| A scheduled Fly machine on the `aisoc-demo-api` app, named `aisoc-demo-seed-cron`, boots from the same api image, runs the same command, and exits. |
-| Local recovery | `python -m app.scripts.seed_demo` inside the api container of a `docker-compose -f docker-compose.demo.yml` stack — same module, same idempotency. |
+| Local recovery | `python -m app.scripts.seed_demo` inside the api container of a `docker-compose -f infra/compose/docker-compose.demo.yml` stack — same module, same idempotency. |
The canonical implementation lives in
[`services/api/app/scripts/seed_demo.py`](../../services/api/app/scripts/seed_demo.py).
diff --git a/install.sh b/install.sh
index d5399fbf6..b5d28573d 100755
--- a/install.sh
+++ b/install.sh
@@ -727,7 +727,7 @@ ensure_repo() {
# ─── Step 6: .env bootstrap ──────────────────────────────────────────────────
ensure_env_file() {
- # docker-compose.demo.yml hardcodes its own dev passwords (see SECURITY NOTE
+ # infra/compose/docker-compose.demo.yml hardcodes its own dev passwords (see SECURITY NOTE
# in that file), so .env isn't actually load-bearing for the demo. But
# several apps and scripts do read .env, so we make sure it exists with
# the example defaults to avoid spurious "key not found" warnings.
diff --git a/package.json b/package.json
index bc6491266..c6cea91bc 100644
--- a/package.json
+++ b/package.json
@@ -37,8 +37,8 @@
"aisoc:lab": "bash scripts/lab.sh",
"aisoc:doctor": "tsx scripts/aisoc-doctor.ts",
"aisoc:demo": "tsx scripts/aisoc-demo.ts",
- "aisoc:demo:down": "docker compose -f docker-compose.demo.yml down -v",
- "aisoc:demo:logs": "docker compose -f docker-compose.demo.yml logs -f",
+ "aisoc:demo:down": "docker compose -f infra/compose/docker-compose.demo.yml down -v",
+ "aisoc:demo:logs": "docker compose -f infra/compose/docker-compose.demo.yml logs -f",
"aisoc:acceptance": "tsx scripts/aisoc-acceptance.ts",
"aisoc:acceptance:cold": "tsx scripts/aisoc-acceptance.ts --cold",
"demo:public": "bash scripts/demo-public.sh",
diff --git a/packages/aisoc-cli/README.md b/packages/aisoc-cli/README.md
index 7f9c80712..0aeb52546 100644
--- a/packages/aisoc-cli/README.md
+++ b/packages/aisoc-cli/README.md
@@ -2,15 +2,19 @@
Developer CLI for building, validating, and publishing AiSOC plugins and detection rules.
+> **Status — monorepo today, PyPI in v8.0.** The CLI ships from this monorepo and is fully functional today. The PyPI release lands with v8.0. The CLI name (`aisoc`) and command surface stay identical once it ships.
+
## Installation
```bash
-pip install aisoc-cli
-```
+# Today (from this monorepo):
+git clone https://github.com/beenuar/AiSOC.git
+cd AiSOC && pip install -e packages/aisoc-cli
-Or from source:
-```bash
-pip install -e packages/aisoc-cli
+# v8.0+ (once aisoc-cli lands on PyPI):
+pipx install aisoc-cli # recommended (isolated venv)
+# or:
+pip install aisoc-cli
```
## Commands
diff --git a/packages/aisoc-cli/src/aisoc_cli/main.py b/packages/aisoc-cli/src/aisoc_cli/main.py
index 9f40c4d50..3b66e9fc7 100644
--- a/packages/aisoc-cli/src/aisoc_cli/main.py
+++ b/packages/aisoc-cli/src/aisoc_cli/main.py
@@ -470,15 +470,15 @@ def _find_repo_root(start: Path | None = None) -> Path:
"""Walk up from ``start`` (default: cwd) looking for a docker-compose root.
A repo root here is any directory containing either ``docker-compose.yml``
- or ``docker-compose.dev.yml``. Falls back to the current working directory
- if no match is found, so the underlying ``docker compose`` invocation can
- still produce a sensible error message.
+ or ``infra/compose/docker-compose.dev.yml``. Falls back to the current
+ working directory if no match is found, so the underlying
+ ``docker compose`` invocation can still produce a sensible error message.
"""
current = (start or Path.cwd()).resolve()
for candidate in [current, *current.parents]:
if (candidate / "docker-compose.yml").exists() or (
- candidate / "docker-compose.dev.yml"
- ).exists():
+ candidate / "infra" / "compose" / "docker-compose.dev.yml"
+ ).exists() or (candidate / "docker-compose.dev.yml").exists():
return candidate
return current
@@ -486,12 +486,16 @@ def _find_repo_root(start: Path | None = None) -> Path:
def _compose_file_arg(repo_root: Path) -> list[str]:
"""Pick the right ``-f`` arg for docker compose.
- Prefers ``docker-compose.dev.yml`` (the dev-aliased entry point) when
- present, otherwise falls back to the base ``docker-compose.yml``.
+ Prefers ``infra/compose/docker-compose.dev.yml`` (the dev-aliased entry
+ point in the post-tidy layout) when present, then the legacy root path,
+ otherwise falls back to the base ``docker-compose.yml``.
"""
- dev = repo_root / "docker-compose.dev.yml"
- if dev.exists():
- return ["-f", str(dev)]
+ new_dev = repo_root / "infra" / "compose" / "docker-compose.dev.yml"
+ if new_dev.exists():
+ return ["-f", str(new_dev)]
+ legacy_dev = repo_root / "docker-compose.dev.yml"
+ if legacy_dev.exists():
+ return ["-f", str(legacy_dev)]
return ["-f", str(repo_root / "docker-compose.yml")]
@@ -527,9 +531,10 @@ def serve(detach: bool, build: bool) -> None:
"""Start the AiSOC dev stack via docker compose.
Resolves the closest docker-compose root walking up from the cwd, prefers
- ``docker-compose.dev.yml`` if it exists, and shells out to
- ``docker compose -f <file> up``. Treat this as the founder-style
- one-liner equivalent of the documented ``docker compose up -d``.
+ ``infra/compose/docker-compose.dev.yml`` if it exists (legacy root path is
+ still honoured), and shells out to ``docker compose -f <file> up``. Treat
+ this as the founder-style one-liner equivalent of the documented
+ ``docker compose up -d``.
"""
_require_docker()
repo_root = _find_repo_root()
diff --git a/packages/aisoc-cli/tests/test_ops_commands.py b/packages/aisoc-cli/tests/test_ops_commands.py
index 9fa91fbbd..1384cfef3 100644
--- a/packages/aisoc-cli/tests/test_ops_commands.py
+++ b/packages/aisoc-cli/tests/test_ops_commands.py
@@ -33,8 +33,10 @@ def runner() -> CliRunner:
def fake_repo(tmp_path: Path) -> Path:
"""A minimal repo root with both compose files and a built MCP dist."""
(tmp_path / "docker-compose.yml").write_text("services: {}\n")
- (tmp_path / "docker-compose.dev.yml").write_text(
- "include:\n - path: docker-compose.yml\n"
+ compose_dir = tmp_path / "infra" / "compose"
+ compose_dir.mkdir(parents=True)
+ (compose_dir / "docker-compose.dev.yml").write_text(
+ "include:\n - path: ../../docker-compose.yml\n"
)
mcp_dist = tmp_path / "services" / "mcp" / "dist"
mcp_dist.mkdir(parents=True)
diff --git a/packages/aisoc-sandbox/README.md b/packages/aisoc-sandbox/README.md
new file mode 100644
index 000000000..c7c2331b9
--- /dev/null
+++ b/packages/aisoc-sandbox/README.md
@@ -0,0 +1,127 @@
+# aisoc-sandbox
+
+> Run an AiSOC agent investigation **offline in under 30 seconds**. No Docker, no API key, no network.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-22c55e.svg)](https://github.com/beenuar/AiSOC/blob/main/LICENSE)
+[![PyPI release](https://img.shields.io/badge/pypi-coming%20in%20v8.0-f59e0b)](https://github.com/beenuar/AiSOC/blob/main/CHANGELOG.md)
+
+`aisoc-sandbox` is the quickest possible on-ramp to [AiSOC](https://github.com/beenuar/AiSOC). It walks one alert fixture through a four-stage agent funnel — **Detect → Triage → Hunt → Respond** — using a deterministic offline reasoner in place of a real LLM, and prints the resulting Investigation Ledger to your terminal.
+
+It is the simulator-equivalent of the production [`services/agents/`](https://github.com/beenuar/AiSOC/tree/main/services/agents) graph, collapsed into a single zero-dependency Python package. **When you're ready to run the real stack: `pnpm aisoc:demo` from a fresh clone of [AiSOC](https://github.com/beenuar/AiSOC).**
+
+## Why this exists
+
+The production AiSOC stack needs Postgres, Kafka, Redis, an LLM API key, and ~5 minutes to boot. That's the right cost for a buyer evaluating against their own alert data — but it's the wrong cost for a developer who just wants to see how the agent reasons before they commit their evening.
+
+This package collapses the boot time to **< 5 seconds** and the disk footprint to **< 50 KB**. The trade-off is that the reasoning is deterministic and the tools are simulated (not executed); see "Differences from the production stack" below.
+
+## Install
+
+```bash
+# Today (from this monorepo):
+git clone https://github.com/beenuar/AiSOC.git
+cd AiSOC && pip install -e packages/aisoc-sandbox
+
+# v8.0+ (once aisoc-sandbox lands on PyPI):
+pip install aisoc-sandbox
+# or, for one-off use without polluting your site-packages:
+pipx run aisoc-sandbox demo
+```
+
+Python 3.10+ on Linux / macOS / Windows. Zero runtime dependencies.
+
+## Quick start
+
+```bash
+# Walk the default scenario (lateral-movement) through the funnel
+aisoc-sandbox demo
+
+# Pick a different bundled scenario
+aisoc-sandbox demo --scenario aws-credential-exfil
+
+# Use your own scenario JSON
+aisoc-sandbox demo --file ./my-alert.json
+
+# Machine-readable output
+aisoc-sandbox demo --scenario phishing-payload --json | jq
+
+# What scenarios are bundled?
+aisoc-sandbox scenarios
+```
+
+## Bundled scenarios
+
+Five scenarios ship with the package; each one is a single JSON file under [`src/aisoc_sandbox/scenarios/`](./src/aisoc_sandbox/scenarios) and is small enough to read end-to-end:
+
+| ID | Title | MITRE | Severity |
+|---|---|---|---|
+| `lateral-movement` | Impossible-travel Okta sign-in | T1078, T1078.004 | high |
+| `aws-credential-exfil` | IAM keys used from new ASN, then `s3:GetObject` flood | T1552, T1567, T1078.004 | critical |
+| `phishing-payload` | Click-through to credential-harvest page | T1566, T1566.002 | high |
+| `kubernetes-privesc` | Namespace SA bound to `cluster-admin` | T1098, T1078 | critical |
+| `github-token-theft` | PAT leaked, six private repos cloned in 11 s | T1078, T1555, T1567 | high |
+
+## What you'll see
+
+Each `aisoc-sandbox demo` run emits a four-step ledger:
+
+```
+Investigation Ledger
+ 4 steps · 12 ms total · synthetic offline run (no LLM, no Docker)
+
+Step 0 DETECT DetectAgent (3 ms)
+ Action Match incoming events against detection ruleset
+ Rationale 2 event(s) ingested; matched detection ruleset against MITRE techniques T1078, T1078.004.
+ · events_ingested: 2
+ · mitre_techniques: ['T1078', 'T1078.004']
+ · severity_at_intake: high
+ · entity:user: [email protected]
+ → would-call rules.match({"rule_count": "800+", ...})
+ → would-call fusion.score({"window_minutes": 15})
+ Decision Open alert at severity=high
+
+Step 1 TRIAGE TriageAgent (3 ms)
+ Action Score alert confidence + cross-reference with prior cases
+ Rationale Authenticated session signals look legitimate at the protocol layer, but the geo pivot between sequential events is physically impossible — classic credential takeover.
+ ...
+```
+
+The shape mirrors the production Investigation Rail at [`/alerts/[id]`](https://github.com/beenuar/AiSOC/blob/main/apps/docs/docs/console/investigation-rail.md). The four stages, the evidence chips, and the "Decision" lines are the same — only the LLM rationale and tool execution are simulated.
+
+## Library use
+
+The package's surface is small enough to embed:
+
+```python
+from aisoc_sandbox import load_scenario, run_investigation
+
+scenario = load_scenario("aws-credential-exfil")
+ledger = run_investigation(scenario)
+
+# Iterate the steps
+for step in ledger:
+ print(step.step, step.agent, step.action, step.decision)
+
+# Or render to a stream (TTY-aware colour)
+ledger.render_human()
+
+# Or serialise
+print(ledger.to_json())
+```
+
+## Differences from the production stack
+
+| | `aisoc-sandbox` | Production `services/agents/` |
+|---|---|---|
+| LLM | Deterministic template-driven stub | OpenAI / Anthropic / Ollama via LiteLLM |
+| Tool calls | Simulated as "would-call(name, args)" | Dispatched to connector / action services |
+| Persistence | In-memory; one CLI invocation | Postgres `investigation_events` table |
+| Latency | Synthetic per-stage numbers | Real LLM + tool latency |
+| Boot time | < 5 s | ~5 min cold, ~3.5 min warm |
+| Dependencies | None | Postgres + Kafka + Redis + LLM API key |
+
+This is on purpose. The sandbox is the **on-ramp**, not a replacement: it gives you 30-second visibility into how the funnel hangs together so you can decide whether the full demo is worth the 5-minute boot.
+
+## License
+
+MIT — see the [repo LICENSE](https://github.com/beenuar/AiSOC/blob/main/LICENSE).
diff --git a/packages/aisoc-sandbox/pyproject.toml b/packages/aisoc-sandbox/pyproject.toml
new file mode 100644
index 000000000..f485ddb6e
--- /dev/null
+++ b/packages/aisoc-sandbox/pyproject.toml
@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aisoc-sandbox"
+version = "0.1.0"
+description = "Run an AiSOC agent investigation offline in under 30 seconds. No Docker, no API key."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "AiSOC contributors" }]
+keywords = ["aisoc", "soc", "security", "agent", "investigation", "ledger", "offline"]
+classifiers = [
+ "Development Status :: 4 - Beta",
+ "Intended Audience :: Information Technology",
+ "License :: OSI Approved :: MIT License",
+ "Programming Language :: Python :: 3",
+ "Programming Language :: Python :: 3 :: Only",
+ "Programming Language :: Python :: 3.10",
+ "Programming Language :: Python :: 3.11",
+ "Programming Language :: Python :: 3.12",
+ "Topic :: Security",
+]
+
+# Zero runtime dependencies on purpose. The whole point of the sandbox
+# is that `pip install aisoc-sandbox && aisoc-sandbox demo` works on a
+# clean machine inside 30 seconds.
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+ "pytest>=8.0",
+ "pytest-cov>=4.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/beenuar/AiSOC"
+Documentation = "https://docs.tryaisoc.com"
+Source = "https://github.com/beenuar/AiSOC/tree/main/packages/aisoc-sandbox"
+Issues = "https://github.com/beenuar/AiSOC/issues"
+Changelog = "https://github.com/beenuar/AiSOC/blob/main/CHANGELOG.md"
+
+[project.scripts]
+aisoc-sandbox = "aisoc_sandbox.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+aisoc_sandbox = ["scenarios/*.json", "py.typed"]
+
+[tool.pytest.ini_options]
+addopts = "-ra --strict-markers"
+testpaths = ["tests"]
diff --git a/packages/aisoc-sandbox/src/aisoc_sandbox/__init__.py b/packages/aisoc-sandbox/src/aisoc_sandbox/__init__.py
new file mode 100644
index 000000000..5a78a8cf9
--- /dev/null
+++ b/packages/aisoc-sandbox/src/aisoc_sandbox/__init__.py
@@ -0,0 +1,42 @@
+"""aisoc-sandbox: run an AiSOC agent investigation offline in under 30 seconds.
+
+This package is the quickest possible on-ramp to AiSOC: no Docker, no
+Postgres / Kafka / Redis, no API key, no network — `aisoc-sandbox demo`
+walks one alert fixture through a Detect → Triage → Hunt → Respond
+agent funnel and prints a step-by-step Investigation Ledger to stdout.
+
+It is a deterministic, in-memory simulator of the production stack at
+[`services/agents/`](https://github.com/beenuar/AiSOC/tree/main/services/agents).
+The shape of the ledger, the funnel stages, the decision metadata, and
+the recommended actions all mirror what the real four-agent system in
+the monorepo emits. The simulator is intentionally NOT the production
+graph: the production graph requires Postgres + Kafka + an LLM API
+key, and a 30-second offline demo cannot afford any of those.
+
+When you're ready to run the real stack: `pnpm aisoc:demo`.
+
+Public entry points:
+
+ - :class:`Investigation` — one investigation run.
+ - :class:`Ledger` — the step-by-step record.
+ - :func:`load_scenario` — load a built-in or user-supplied scenario.
+ - :func:`run_investigation` — high-level orchestrator (used by the CLI).
+"""
+
+from __future__ import annotations
+
+from .investigation import Investigation, run_investigation
+from .ledger import Ledger, LedgerStep
+from .scenarios import Scenario, available_scenarios, load_scenario
+
+__all__ = [
+ "Investigation",
+ "Ledger",
+ "LedgerStep",
+ "Scenario",
+ "available_scenarios",
+ "load_scenario",
+ "run_investigation",
+]
+
+__version__ = "0.1.0"
diff --git a/packages/aisoc-sandbox/src/aisoc_sandbox/cli.py b/packages/aisoc-sandbox/src/aisoc_sandbox/cli.py
new file mode 100644
index 000000000..f28ed8f77
--- /dev/null
+++ b/packages/aisoc-sandbox/src/aisoc_sandbox/cli.py
@@ -0,0 +1,153 @@
+"""aisoc-sandbox — command-line entry point.
+
+The two visible subcommands are ``demo`` and ``scenarios``:
+
+ * ``aisoc-sandbox demo`` runs one full Detect → Triage → Hunt →
+ Respond funnel against a bundled or user-supplied scenario and
+ prints the Investigation Ledger to stdout. ``--json`` switches
+ the output to a machine-readable form.
+
+ * ``aisoc-sandbox scenarios`` lists the bundled scenarios so a user
+ can pick one with ``--scenario <id>`` without reading the docs.
+
+Exit codes follow UNIX convention:
+
+ 0 success — investigation ran and the ledger was emitted.
+ 2 invalid arguments (bad scenario id, missing file, etc).
+ 3 internal error during the run.
+
+There is no networked path in this CLI. If you `strace` it you should
+see exactly one ``read`` of the scenario file, zero ``connect`` syscalls.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from typing import Sequence
+
+from . import __version__
+from .investigation import run_investigation
+from .ledger import Ledger
+from .scenarios import available_scenarios, emit_scenario_index, load_scenario
+
+
+_PROG = "aisoc-sandbox"
+_DESCRIPTION = (
+ "Run an AiSOC agent investigation offline in under 30 seconds. "
+ "No Docker, no API key, no network."
+)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+ p = argparse.ArgumentParser(
+ prog=_PROG,
+ description=_DESCRIPTION,
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog=(
+ "Examples:\n"
+ " aisoc-sandbox demo\n"
+ " aisoc-sandbox demo --scenario aws-credential-exfil\n"
+ " aisoc-sandbox demo --file my-alert.json --json\n"
+ " aisoc-sandbox scenarios\n"
+ ),
+ )
+ p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+ sub = p.add_subparsers(dest="command", required=True, metavar="<command>")
+
+ demo = sub.add_parser(
+ "demo",
+ help="Walk one scenario through the Detect → Triage → Hunt → Respond funnel.",
+ )
+ demo.add_argument(
+ "--scenario",
+ choices=available_scenarios(),
+ default="lateral-movement",
+ help="Bundled scenario id (default: %(default)s).",
+ )
+ demo.add_argument(
+ "--file",
+ metavar="PATH",
+ help="Path to a custom scenario JSON. Overrides --scenario when set.",
+ )
+ demo.add_argument(
+ "--json",
+ action="store_true",
+ help="Emit the ledger as a JSON document instead of the human view.",
+ )
+
+ sub.add_parser(
+ "scenarios",
+ help="List the bundled scenarios and exit.",
+ )
+ return p
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+ parser = _build_parser()
+ args = parser.parse_args(argv)
+
+ if args.command == "scenarios":
+ emit_scenario_index()
+ return 0
+
+ if args.command == "demo":
+ try:
+ scenario = load_scenario(args.scenario, file=args.file)
+ except (FileNotFoundError, ValueError) as exc:
+ print(f"{_PROG}: error: {exc}", file=sys.stderr)
+ return 2
+
+ ledger = Ledger()
+ started = time.perf_counter()
+ try:
+ run_investigation(scenario, ledger=ledger)
+ except Exception as exc: # noqa: BLE001 — surface to the user, exit 3.
+ print(f"{_PROG}: investigation crashed: {exc}", file=sys.stderr)
+ return 3
+ elapsed_ms = int((time.perf_counter() - started) * 1000)
+
+ if args.json:
+ payload = {
+ "tool": _PROG,
+ "version": __version__,
+ "scenario": scenario.to_dict(),
+ "ledger": ledger.to_dict(),
+ "elapsed_ms": elapsed_ms,
+ }
+ print(json.dumps(payload, indent=2, ensure_ascii=False))
+ return 0
+
+ # Human view: brief preamble, then the rendered ledger.
+ _print_preamble(scenario)
+ ledger.render_human()
+ print(
+ f"Ran {len(ledger)} steps in {elapsed_ms} ms.\n"
+ "Ready for the real stack? `pnpm aisoc:demo` from a fresh clone of\n"
+ " https://github.com/beenuar/AiSOC\n"
+ )
+ return 0
+
+ # argparse refused to leave us here, but Pylance doesn't know that.
+ parser.print_help()
+ return 2
+
+
+def _print_preamble(scenario: object) -> None:
+ sc = scenario # narrow for the type-checker
+ # We don't depend on rich so the package stays zero-dep. The
+ # output uses plain text + ANSI; piping to a file produces clean
+ # text via Ledger.render_human's TTY-aware colour code.
+ print(f"\nScenario: {sc.id}")
+ print(f"Title: {sc.title}")
+ if sc.narrative:
+ print(f"Narrative: {sc.narrative}")
+ if sc.mitre_techniques:
+ print(f"MITRE: {', '.join(sc.mitre_techniques)}")
+ print(f"Severity: {sc.severity}\n")
+
+
+if __name__ == "__main__": # pragma: no cover — covered by smoke test.
+ sys.exit(main())
diff --git a/packages/aisoc-sandbox/src/aisoc_sandbox/investigation.py b/packages/aisoc-sandbox/src/aisoc_sandbox/investigation.py
new file mode 100644
index 000000000..cde9504ef
--- /dev/null
+++ b/packages/aisoc-sandbox/src/aisoc_sandbox/investigation.py
@@ -0,0 +1,287 @@
+"""The four-stage investigation funnel — Detect → Triage → Hunt → Respond.
+
+This module is the simulator-equivalent of
+[`services/agents/app/agents/`](https://github.com/beenuar/AiSOC/tree/main/services/agents/app/agents)
+collapsed into one file. It exists so a reader can read the whole
+funnel in 5 minutes and see exactly what every step does.
+
+Each stage is implemented as a free function that takes the
+:class:`Scenario` and the :class:`Ledger` (which it appends to). The
+:class:`Investigation` class wires them up; :func:`run_investigation`
+is the CLI's high-level entry point.
+
+The "LLM" used here is :class:`DeterministicReasoner`, a tiny
+template-driven stub. The real agents call out to OpenAI / Anthropic /
+Ollama via LiteLLM with a guarded prompt contract — see
+``services/agents/app/services/llm_safety.py``. The sandbox does not
+make any network calls.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from .ledger import Ledger
+from .scenarios import Scenario
+
+
+class DeterministicReasoner:
+ """Deterministic, offline stand-in for the real LLM.
+
+ Returns canned but contextual rationales keyed off the scenario's
+ MITRE techniques. The output deliberately reads like a real LLM
+ response (one sentence, present tense, references the evidence)
+ so a buyer comparing the sandbox to the live demo can't tell the
+ rendered ledger apart at a glance — except the latencies are
+ smaller and the byte-stable output makes the demo reproducible.
+ """
+
+ _RATIONALES: dict[str, str] = {
+ "T1078": "Authenticated session signals look legitimate at the protocol layer, but the geo pivot between sequential events is physically impossible — classic credential takeover.",
+ "T1078.004": "Cloud account use without a paired federated-IDP factor and from an unrecognised ASN suggests the credential is being replayed from the attacker's environment.",
+ "T1110": "Brute-force or password-spray pattern: the time-density of failed authentications exceeds the per-tenant Welford-online baseline by more than three standard deviations.",
+ "T1566": "Phishing landed: the click happened inside the standard credential-harvest window from email delivery, and the destination domain registered less than 14 days ago.",
+ "T1567": "Exfiltration over a web service: outbound volume to an uncategorised cloud endpoint dominates the host's egress for the hour and clusters with known dropbox-style staging.",
+ "T1098": "Privilege escalation via account manipulation: a role-binding change happened outside the normal change-management window and the actor has no recent admin activity.",
+ "T1496": "Resource hijacking signature: CPU saturation co-occurs with outbound mining-pool connections and the workload's parent isn't the orchestrator that normally spawns it.",
+ "T1486": "Mass-file-write entropy matches the known LockBit signature; file-extension churn rate ≥ 80/sec across multiple directories.",
+ "T1059": "Command-and-scripting interpreter ran a base64-decoded script that the host's allowlist would have blocked under the org's WDAC policy.",
+ "T1552": "Credentials accessed in plaintext from a session-token cache that should have been encrypted-at-rest under the platform's KMS profile.",
+ "T1555": "Credential store dump detected — the access pattern matches known infostealer behaviour against the OS-native keystore.",
+ "T1071": "Application-layer C2 channel: the beacon interval is jittered around a 60-second mean with a constant-volume header, consistent with malleable-profile traffic.",
+ }
+ _GENERIC = "Behaviour pattern matches a known MITRE technique and exceeds the baseline confidence threshold."
+
+ def explain(self, *, technique: str | None) -> str:
+ if technique is None:
+ return self._GENERIC
+ # The real agents sometimes get a sub-technique (T1078.004) and
+ # sometimes the parent (T1078); fall back to the parent if the
+ # specific one isn't in the table.
+ if technique in self._RATIONALES:
+ return self._RATIONALES[technique]
+ parent = technique.split(".", 1)[0]
+ return self._RATIONALES.get(parent, self._GENERIC)
+
+
+@dataclass
+class Investigation:
+ """One investigation run."""
+
+ scenario: Scenario
+ ledger: Ledger
+ reasoner: DeterministicReasoner
+
+ def run(self) -> Ledger:
+ """Walk the four-stage funnel; populate the ledger."""
+
+ _stage_detect(self.scenario, self.ledger, self.reasoner)
+ _stage_triage(self.scenario, self.ledger, self.reasoner)
+ _stage_hunt(self.scenario, self.ledger, self.reasoner)
+ _stage_respond(self.scenario, self.ledger, self.reasoner)
+ return self.ledger
+
+
+# ---------------------------------------------------------------------------
+# Stage 1 — Detect. "Did something happen?"
+# ---------------------------------------------------------------------------
+
+def _stage_detect(s: Scenario, ledger: Ledger, _r: DeterministicReasoner) -> None:
+ t0 = time.perf_counter()
+ ledger.append(
+ agent="DetectAgent",
+ funnel_stage="detect",
+ action="Match incoming events against detection ruleset",
+ rationale=(
+ f"{len(s.events)} event(s) ingested; matched detection ruleset"
+ f" against MITRE techniques {', '.join(s.mitre_techniques) or '(none)'}."
+ ),
+ evidence={
+ "events_ingested": len(s.events),
+ "mitre_techniques": s.mitre_techniques,
+ "severity_at_intake": s.severity,
+ **{f"entity:{k}": v for k, v in s.entities.items()},
+ },
+ tool_calls=[
+ {"name": "rules.match", "args": {"rule_count": "800+", "technique_set": s.mitre_techniques}},
+ {"name": "fusion.score", "args": {"window_minutes": 15}},
+ ],
+ decision=f"Open alert at severity={s.severity}",
+ latency_ms=_ms(t0),
+ )
+
+
+# ---------------------------------------------------------------------------
+# Stage 2 — Triage. "Is it real, and how confident are we?"
+# ---------------------------------------------------------------------------
+
+def _stage_triage(s: Scenario, ledger: Ledger, r: DeterministicReasoner) -> None:
+ t0 = time.perf_counter()
+ primary_technique = s.mitre_techniques[0] if s.mitre_techniques else None
+ rationale = r.explain(technique=primary_technique)
+
+ confidence = _confidence_band(severity=s.severity, technique_count=len(s.mitre_techniques))
+ ledger.append(
+ agent="TriageAgent",
+ funnel_stage="triage",
+ action="Score alert confidence + cross-reference with prior cases",
+ rationale=rationale,
+ evidence={
+ "primary_technique": primary_technique,
+ "related_cases_30d": _synthetic_related_cases(s.id),
+ "rba_entity_risk": _synthetic_entity_risk(s.entities),
+ },
+ tool_calls=[
+ {"name": "qdrant.semantic_search", "args": {"k": 5, "collection": "cases"}},
+ {"name": "graph.neighbours", "args": {"depth": 2}},
+ ],
+ decision=f"Confidence: {confidence['band']} ({confidence['score']}/100)",
+ latency_ms=_ms(t0),
+ )
+
+
+# ---------------------------------------------------------------------------
+# Stage 3 — Hunt. "Did the same actor touch anything else?"
+# ---------------------------------------------------------------------------
+
+def _stage_hunt(s: Scenario, ledger: Ledger, _r: DeterministicReasoner) -> None:
+ t0 = time.perf_counter()
+ technique = s.mitre_techniques[0] if s.mitre_techniques else "T0000"
+
+ ledger.append(
+ agent="HuntAgent",
+ funnel_stage="hunt",
+ action="Pivot from primary entity across the data lake",
+ rationale=(
+ "Sweep for the primary entity across the last 24 h of warm-tier"
+ f" events; correlate against MITRE technique {technique}."
+ ),
+ evidence={
+ "pivot_entities": list(s.entities.values()),
+ "lookback_hours": 24,
+ "hunt_query_languages": ["ES|QL", "SPL", "KQL"],
+ "matches_found": _synthetic_hunt_matches(s.id),
+ },
+ tool_calls=[
+ {"name": "nl_to_query.translate", "args": {"hypothesis": f"any activity by {next(iter(s.entities.values()), 'actor')} in last 24h"}},
+ {"name": "lake.query", "args": {"language": "ES|QL", "row_cap": 1000}},
+ ],
+ decision="Pivot complete; no additional compromised entities surfaced beyond the alert payload.",
+ latency_ms=_ms(t0),
+ )
+
+
+# ---------------------------------------------------------------------------
+# Stage 4 — Respond. "What do we do about it, and at what blast radius?"
+# ---------------------------------------------------------------------------
+
+def _stage_respond(s: Scenario, ledger: Ledger, _r: DeterministicReasoner) -> None:
+ t0 = time.perf_counter()
+ actions = s.recommended_actions or _default_actions(s)
+ ledger.append(
+ agent="RespondAgent",
+ funnel_stage="respond",
+ action="Propose graduated response under blast-radius gate",
+ rationale=(
+ "Recommend the least-invasive containment that closes the"
+ " confidence-weighted risk; escalate only with human"
+ " approval for high-blast-radius actions (per L0–L4 model)."
+ ),
+ evidence={
+ "automation_maturity_tier": _automation_tier(s.severity),
+ "blast_radius_gate": "human_approval_required" if s.severity in ("high", "critical") else "auto_below_high",
+ "recommended_action_count": len(actions),
+ },
+ tool_calls=actions,
+ decision=(
+ f"{len(actions)} action(s) proposed; "
+ + (
+ "awaiting analyst approval before execution."
+ if s.severity in ("high", "critical")
+ else "auto-execute eligible under current L0–L4 tier."
+ )
+ ),
+ latency_ms=_ms(t0),
+ )
+
+
+# ---------------------------------------------------------------------------
+# Helpers — keep the stage functions readable above.
+# ---------------------------------------------------------------------------
+
+def _ms(t0: float) -> int:
+ return int((time.perf_counter() - t0) * 1000)
+
+
+def _confidence_band(*, severity: str, technique_count: int) -> dict[str, Any]:
+ base = {"info": 30, "low": 45, "medium": 60, "high": 75, "critical": 88}[severity]
+ score = min(100, base + 4 * technique_count)
+ band = "low" if score < 50 else "medium" if score < 75 else "high"
+ return {"score": score, "band": band}
+
+
+def _synthetic_related_cases(sid: str) -> int:
+ # Stable per-scenario but believable. Production fetches from
+ # Qdrant; we just hash the id.
+ return abs(hash(sid)) % 7
+
+
+def _synthetic_entity_risk(entities: dict[str, str]) -> dict[str, int]:
+ # Risk score 0-100 per entity. Deterministic.
+ return {k: 30 + (abs(hash(v)) % 60) for k, v in entities.items()}
+
+
+def _synthetic_hunt_matches(sid: str) -> int:
+ return abs(hash(f"hunt:{sid}")) % 4
+
+
+def _automation_tier(severity: str) -> str:
+ return {
+ "info": "L4 — fully autonomous closure",
+ "low": "L3 — auto-respond with audit",
+ "medium": "L2 — proposed actions, human confirms",
+ "high": "L1 — recommendations only, human executes",
+ "critical": "L1 — recommendations only, human executes",
+ }[severity]
+
+
+def _default_actions(s: Scenario) -> list[dict[str, Any]]:
+ primary = next(iter(s.entities.values()), None)
+ return [
+ {"name": "case.create", "args": {"title": s.title, "severity": s.severity}},
+ {
+ "name": "user.suspend" if primary else "alert.acknowledge",
+ "args": {"user": primary} if primary else {"reason": "no entity to act on"},
+ },
+ {"name": "case.notify", "args": {"channel": "slack", "audience": "soc-on-call"}},
+ ]
+
+
+# ---------------------------------------------------------------------------
+# High-level orchestrator used by the CLI.
+# ---------------------------------------------------------------------------
+
+def run_investigation(scenario: Scenario, *, ledger: Ledger | None = None) -> Ledger:
+ """Run the four-stage funnel against ``scenario`` and return the ledger.
+
+ Args:
+ scenario: The :class:`Scenario` to investigate.
+ ledger: Optional pre-existing ledger to append to. If omitted,
+ a fresh one is created.
+
+ Returns:
+ The populated :class:`Ledger`.
+ """
+
+ # NB: we use `is None` rather than `ledger or Ledger()` because
+ # `Ledger.__len__` returns 0 for empty ledgers, which makes a fresh
+ # `Ledger()` falsy under `or` and silently swaps in a throwaway
+ # instance — the caller's ledger then never gets mutated.
+ inv = Investigation(
+ scenario=scenario,
+ ledger=ledger if ledger is not None else Ledger(),
+ reasoner=DeterministicReasoner(),
+ )
+ return inv.run()
diff --git a/packages/aisoc-sandbox/src/aisoc_sandbox/ledger.py b/packages/aisoc-sandbox/src/aisoc_sandbox/ledger.py
new file mode 100644
index 000000000..8dc1832af
--- /dev/null
+++ b/packages/aisoc-sandbox/src/aisoc_sandbox/ledger.py
@@ -0,0 +1,160 @@
+"""Investigation Ledger — the step-by-step record of one investigation run.
+
+The shape here mirrors the production `investigation_events` ledger
+written by [`services/agents/`](https://github.com/beenuar/AiSOC/tree/main/services/agents)
+so that an analyst who learns the sandbox can read a real ledger
+without re-learning the schema. Differences from production:
+
+ * No persistence. The ledger lives in memory for the duration of
+ one CLI invocation; the production ledger writes to Postgres.
+ * No prompt/response capture. The sandbox uses a deterministic stub
+ in place of the real LLM, so `prompt` / `response` fields hold a
+ short descriptor of the decision rather than the full LLM text.
+ * No tool dispatch. Tool calls are simulated as
+ "would-call(<name>, <args>)" entries so the funnel still reads
+ naturally without spinning up the connector / action stack.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Iterable
+
+
+@dataclass
+class LedgerStep:
+ """One step in the investigation funnel.
+
+ Attributes:
+ step: 0-indexed step number across the whole run.
+ agent: Which of the four production agents emitted this step.
+ One of: `DetectAgent`, `TriageAgent`, `HuntAgent`,
+ `RespondAgent`, or `Orchestrator` (the funnel wrapper).
+ funnel_stage: The four-stage automation maturity funnel:
+ `detect | triage | hunt | respond`.
+ action: A human-readable verb (e.g. "Correlate authentication
+ events", "Compute confidence band", "Recommend response").
+ rationale: One sentence summarising why the agent did this.
+ evidence: Key/value evidence chips. Maps to the production
+ Investigation Rail's "Related entities" panel.
+ tool_calls: Tools the agent would invoke (sandboxed; not
+ executed). Each entry is `{"name": ..., "args": {...}}`.
+ decision: Optional summary of the step's outcome — confidence
+ band, recommended action, or routing decision.
+ latency_ms: Wall-clock duration of the step inside the
+ simulator. Production ledger captures real LLM latency;
+ the sandbox uses synthetic deterministic numbers.
+ timestamp_utc: ISO-8601 timestamp at step emission.
+ """
+
+ step: int
+ agent: str
+ funnel_stage: str
+ action: str
+ rationale: str
+ evidence: dict[str, Any] = field(default_factory=dict)
+ tool_calls: list[dict[str, Any]] = field(default_factory=list)
+ decision: str | None = None
+ latency_ms: int = 0
+ timestamp_utc: str = ""
+
+ def to_dict(self) -> dict[str, Any]:
+ return asdict(self)
+
+
+class Ledger:
+ """Append-only ordered list of :class:`LedgerStep` entries."""
+
+ def __init__(self) -> None:
+ self._steps: list[LedgerStep] = []
+
+ def __iter__(self) -> Iterable[LedgerStep]:
+ return iter(self._steps)
+
+ def __len__(self) -> int:
+ return len(self._steps)
+
+ def append(
+ self,
+ *,
+ agent: str,
+ funnel_stage: str,
+ action: str,
+ rationale: str,
+ evidence: dict[str, Any] | None = None,
+ tool_calls: list[dict[str, Any]] | None = None,
+ decision: str | None = None,
+ latency_ms: int = 0,
+ ) -> LedgerStep:
+ step = LedgerStep(
+ step=len(self._steps),
+ agent=agent,
+ funnel_stage=funnel_stage,
+ action=action,
+ rationale=rationale,
+ evidence=evidence or {},
+ tool_calls=tool_calls or [],
+ decision=decision,
+ latency_ms=latency_ms,
+ timestamp_utc=datetime.now(timezone.utc).isoformat(),
+ )
+ self._steps.append(step)
+ return step
+
+ def to_dict(self) -> list[dict[str, Any]]:
+ return [s.to_dict() for s in self._steps]
+
+ def to_json(self, *, indent: int = 2) -> str:
+ return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False)
+
+ def render_human(self, *, out: Any = None) -> None:
+ """Render the ledger to a stream in the format buyers see in /alerts/[id].
+
+ Plain text so it copies cleanly into a GitHub issue, a Slack
+ message, or a screenshot. Colour codes are skipped when stdout
+ isn't a TTY (e.g., piping to a file).
+ """
+
+ if out is None:
+ out = sys.stdout
+ use_colour = bool(getattr(out, "isatty", lambda: False)())
+
+ def c(code: str, text: str) -> str:
+ return f"\x1b[{code}m{text}\x1b[0m" if use_colour else text
+
+ # Header so a reader who scrolled past the boot logs can still
+ # tell what they're looking at.
+ out.write(c("1;36", "Investigation Ledger") + "\n")
+ out.write(
+ f" {len(self._steps)} steps · "
+ f"{sum(s.latency_ms for s in self._steps)} ms total · "
+ "synthetic offline run (no LLM, no Docker)\n\n"
+ )
+
+ for s in self._steps:
+ stage_label = {
+ "detect": c("34", "DETECT"),
+ "triage": c("33", "TRIAGE"),
+ "hunt": c("35", "HUNT"),
+ "respond": c("32", "RESPOND"),
+ }.get(s.funnel_stage, s.funnel_stage.upper())
+ out.write(
+ f"{c('1', f'Step {s.step:>2}')} {stage_label} "
+ f"{c('2', s.agent)} {c('2', f'({s.latency_ms} ms)')}\n"
+ )
+ out.write(f" Action {s.action}\n")
+ out.write(f" Rationale {s.rationale}\n")
+ if s.evidence:
+ for k, v in s.evidence.items():
+ out.write(f" · {k}: {v}\n")
+ for tc in s.tool_calls:
+ out.write(
+ f" → would-call {c('36', tc['name'])}"
+ f"({json.dumps(tc.get('args', {}), default=str)})\n"
+ )
+ if s.decision:
+ out.write(f" {c('1', 'Decision')} {s.decision}\n")
+ out.write("\n")
diff --git a/packages/aisoc-sandbox/src/aisoc_sandbox/py.typed b/packages/aisoc-sandbox/src/aisoc_sandbox/py.typed
new file mode 100644
index 000000000..e69de29bb
diff --git a/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios.py b/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios.py
new file mode 100644
index 000000000..c3d9b4b40
--- /dev/null
+++ b/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios.py
@@ -0,0 +1,137 @@
+"""Scenarios — alert fixtures the sandbox can investigate.
+
+A :class:`Scenario` is the input to one investigation run. The
+sandbox ships five built-ins under ``src/aisoc_sandbox/scenarios/``
+that mirror the (deliberately broader) production fixture set under
+[`examples/`](https://github.com/beenuar/AiSOC/tree/main/examples). A
+user can also supply an arbitrary JSON file from disk via
+``aisoc-sandbox demo --file <path>`` if they want to walk their own
+alert through the funnel.
+
+The schema is intentionally minimal — just enough for the funnel to
+have something to talk about. Every field is optional except
+``id`` / ``title`` / ``mitre_techniques`` / ``events``; missing
+optionals are filled in from defaults by :func:`load_scenario`.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict, dataclass, field
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class Scenario:
+ """An alert fixture the sandbox can investigate.
+
+ Attributes:
+ id: Stable scenario identifier (e.g. ``lateral-movement``).
+ title: Human-readable headline (e.g. "Lateral movement —
+ impossible-travel Okta sign-in").
+ narrative: One-paragraph synopsis the sandbox prints before it
+ walks the funnel.
+ severity: ``info | low | medium | high | critical``.
+ mitre_techniques: List of ATT&CK technique IDs.
+ entities: Optional dict of entity-type → identifier (e.g.
+ ``{"user": "[email protected]", "asset_a": "host-12"}``).
+ Used to populate evidence chips in the rendered ledger.
+ events: List of raw events the alert was synthesised from.
+ Treated as opaque blobs by the simulator.
+ recommended_actions: Pre-baked actions the RespondAgent
+ "would" propose. Each is ``{"name": ..., "args": {...}}``.
+ """
+
+ id: str
+ title: str
+ narrative: str = ""
+ severity: str = "medium"
+ mitre_techniques: list[str] = field(default_factory=list)
+ entities: dict[str, str] = field(default_factory=dict)
+ events: list[dict[str, Any]] = field(default_factory=list)
+ recommended_actions: list[dict[str, Any]] = field(default_factory=list)
+
+ def to_dict(self) -> dict[str, Any]:
+ return asdict(self)
+
+
+_SEVERITY_TIERS = {"info", "low", "medium", "high", "critical"}
+
+
+def _validate(payload: dict[str, Any], *, source: str) -> Scenario:
+ missing = [k for k in ("id", "title") if k not in payload]
+ if missing:
+ raise ValueError(
+ f"Scenario {source!r} is missing required keys: {', '.join(missing)}"
+ )
+ sev = payload.get("severity", "medium")
+ if sev not in _SEVERITY_TIERS:
+ raise ValueError(
+ f"Scenario {source!r} severity={sev!r} must be one of "
+ f"{sorted(_SEVERITY_TIERS)}"
+ )
+ return Scenario(
+ id=str(payload["id"]),
+ title=str(payload["title"]),
+ narrative=str(payload.get("narrative", "")),
+ severity=sev,
+ mitre_techniques=list(payload.get("mitre_techniques", [])),
+ entities=dict(payload.get("entities", {})),
+ events=list(payload.get("events", [])),
+ recommended_actions=list(payload.get("recommended_actions", [])),
+ )
+
+
+def available_scenarios() -> list[str]:
+ """Return the IDs of every bundled scenario, sorted."""
+
+ pkg = resources.files("aisoc_sandbox").joinpath("scenarios")
+ return sorted(
+ p.name.removesuffix(".json")
+ for p in pkg.iterdir()
+ if p.name.endswith(".json")
+ )
+
+
+def load_scenario(scenario_id: str | None = None, *, file: str | None = None) -> Scenario:
+ """Load a bundled scenario by ID, or an arbitrary scenario from disk.
+
+ Args:
+ scenario_id: One of :func:`available_scenarios`. Ignored if
+ ``file`` is set.
+ file: Path to a user-supplied scenario JSON. Takes precedence
+ over ``scenario_id``.
+
+ Returns:
+ The loaded :class:`Scenario`.
+ """
+
+ if file is not None:
+ path = Path(file).expanduser().resolve()
+ if not path.exists():
+ raise FileNotFoundError(f"Scenario file not found: {path}")
+ with path.open("r", encoding="utf-8") as fp:
+ return _validate(json.load(fp), source=str(path))
+
+ sid = scenario_id or "lateral-movement"
+ if sid not in available_scenarios():
+ raise ValueError(
+ f"Unknown scenario {sid!r}. Available: {', '.join(available_scenarios())}"
+ )
+ pkg = resources.files("aisoc_sandbox").joinpath("scenarios", f"{sid}.json")
+ with pkg.open("r", encoding="utf-8") as fp:
+ return _validate(json.load(fp), source=f"<bundled:{sid}>")
+
+
+def emit_scenario_index(*, out: Any = None) -> None:
+ """Print the bundled scenarios in a copy-pasteable form."""
+
+ if out is None:
+ out = sys.stdout
+ out.write("Bundled scenarios (use --scenario <id>):\n")
+ for sid in available_scenarios():
+ sc = load_scenario(sid)
+ out.write(f" {sid:<35} {sc.title}\n")
diff --git a/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/aws-credential-exfil.json b/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/aws-credential-exfil.json
new file mode 100644
index 000000000..65e50a1b1
--- /dev/null
+++ b/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/aws-credential-exfil.json
@@ -0,0 +1,48 @@
+{
+ "id": "aws-credential-exfil",
+ "title": "AWS credential exfiltration — IAM keys used from new ASN",
+ "narrative": "Long-lived IAM access keys belonging to a CI service account are used from an ASN the workload has never previously contacted, immediately followed by `s3:ListBuckets` + bulk `s3:GetObject` of a tagged-confidential bucket. Pattern matches public access-key-leak postmortems from Q1 2026.",
+ "severity": "critical",
+ "mitre_techniques": ["T1552", "T1567", "T1078.004"],
+ "entities": {
+ "user": "[email protected]",
+ "iam_key_id": "AKIAEXAMPLE7QWERTY",
+ "source_ip": "198.51.100.77",
+ "asset": "s3://acme-prod-customer-pii",
+ "asn": "AS12345"
+ },
+ "events": [
+ {
+ "uuid": "aaaaaaaa-1111-4111-8111-aaaaaaaaaaaa",
+ "published": "2026-06-29T14:02:11.412Z",
+ "eventType": "AwsApiCall",
+ "actor": "[email protected]",
+ "action": "sts:GetCallerIdentity",
+ "source_ip": "198.51.100.77"
+ },
+ {
+ "uuid": "bbbbbbbb-2222-4222-8222-bbbbbbbbbbbb",
+ "published": "2026-06-29T14:02:18.991Z",
+ "eventType": "AwsApiCall",
+ "actor": "[email protected]",
+ "action": "s3:ListBuckets",
+ "source_ip": "198.51.100.77"
+ },
+ {
+ "uuid": "cccccccc-3333-4333-8333-cccccccccccc",
+ "published": "2026-06-29T14:02:34.500Z",
+ "eventType": "AwsApiCall",
+ "actor": "[email protected]",
+ "action": "s3:GetObject",
+ "bucket": "acme-prod-customer-pii",
+ "objects_listed": 4137
+ }
+ ],
+ "recommended_actions": [
+ {"name": "iam.access_key.deactivate", "args": {"access_key_id": "AKIAEXAMPLE7QWERTY"}},
+ {"name": "iam.user.attach_deny_policy", "args": {"user": "ci-svc-prod"}},
+ {"name": "s3.bucket.block_public_access", "args": {"bucket": "acme-prod-customer-pii"}},
+ {"name": "case.create", "args": {"title": "AWS credential exfiltration — IAM keys used from new ASN", "severity": "critical"}},
+ {"name": "case.notify", "args": {"channel": "pagerduty", "service": "soc-tier1"}}
+ ]
+}
diff --git a/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/github-token-theft.json b/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/github-token-theft.json
new file mode 100644
index 000000000..24ceff465
--- /dev/null
+++ b/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/github-token-theft.json
@@ -0,0 +1,58 @@
+{
+ "id": "github-token-theft",
+ "title": "GitHub PAT leaked — token used to clone six private repos in 11 seconds",
+ "narrative": "A personal-access token tied to `[email protected]` is suddenly used from an ASN that has never touched the org before, against six private repositories in 11 seconds. The token's `repo` scope is wide enough to ex-filtrate every source tree the user can read.",
+ "severity": "high",
+ "mitre_techniques": ["T1078", "T1555", "T1567"],
+ "entities": {
+ "user": "[email protected]",
+ "token_prefix": "ghp_xxxAAAAA",
+ "source_ip": "192.0.2.55",
+ "repositories": "acme/customer-api, acme/billing-svc, acme/secrets-vault, acme/iam, acme/devops, acme/ml-models"
+ },
+ "events": [
+ {
+ "uuid": "gh-001",
+ "published": "2026-06-25T18:01:22Z",
+ "eventType": "github.audit",
+ "action": "git.clone",
+ "actor": "carol",
+ "repository": "acme/customer-api",
+ "source_ip": "192.0.2.55"
+ },
+ {
+ "uuid": "gh-002",
+ "published": "2026-06-25T18:01:24Z",
+ "eventType": "github.audit",
+ "action": "git.clone",
+ "actor": "carol",
+ "repository": "acme/billing-svc",
+ "source_ip": "192.0.2.55"
+ },
+ {
+ "uuid": "gh-003",
+ "published": "2026-06-25T18:01:27Z",
+ "eventType": "github.audit",
+ "action": "git.clone",
+ "actor": "carol",
+ "repository": "acme/secrets-vault",
+ "source_ip": "192.0.2.55"
+ },
+ {
+ "uuid": "gh-004",
+ "published": "2026-06-25T18:01:33Z",
+ "eventType": "github.audit",
+ "action": "git.clone",
+ "actor": "carol",
+ "repository": "acme/iam",
+ "source_ip": "192.0.2.55"
+ }
+ ],
+ "recommended_actions": [
+ {"name": "github.pat.revoke", "args": {"user": "carol", "token_prefix": "ghp_xxxAAAAA"}},
+ {"name": "github.user.session.revoke_all", "args": {"user": "carol"}},
+ {"name": "github.org.audit_member", "args": {"user": "carol", "lookback_days": 30}},
+ {"name": "secrets.rotate", "args": {"repositories": ["acme/secrets-vault", "acme/iam"]}},
+ {"name": "case.create", "args": {"title": "GitHub PAT leaked — six private repos cloned in 11 s", "severity": "high"}}
+ ]
+}
diff --git a/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/kubernetes-privesc.json b/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/kubernetes-privesc.json
new file mode 100644
index 000000000..63ecdbd46
--- /dev/null
+++ b/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/kubernetes-privesc.json
@@ -0,0 +1,51 @@
+{
+ "id": "kubernetes-privesc",
+ "title": "Kubernetes privilege escalation — namespace-scoped SA bound to cluster-admin",
+ "narrative": "A namespace-scoped ServiceAccount was bound to the `cluster-admin` ClusterRole outside the standard change-management window. The binding was created by a user account that has no recent admin activity, and the SA in question was created less than 24 hours prior.",
+ "severity": "critical",
+ "mitre_techniques": ["T1098", "T1078"],
+ "entities": {
+ "user": "[email protected]",
+ "service_account": "system:serviceaccount:experiments:debug-runner",
+ "cluster_role": "cluster-admin",
+ "asset": "kube-cluster://prod-eks-east-1",
+ "namespace": "experiments"
+ },
+ "events": [
+ {
+ "uuid": "k8s-001",
+ "published": "2026-06-22T02:14:00Z",
+ "eventType": "kubernetes.audit",
+ "actor": "[email protected]",
+ "verb": "create",
+ "objectRef": "serviceaccounts/debug-runner",
+ "namespace": "experiments"
+ },
+ {
+ "uuid": "k8s-002",
+ "published": "2026-06-22T02:14:42Z",
+ "eventType": "kubernetes.audit",
+ "actor": "[email protected]",
+ "verb": "create",
+ "objectRef": "clusterrolebindings/debug-runner-cluster-admin",
+ "roleRef": "ClusterRole/cluster-admin",
+ "subject": "system:serviceaccount:experiments:debug-runner"
+ },
+ {
+ "uuid": "k8s-003",
+ "published": "2026-06-22T02:16:18Z",
+ "eventType": "kubernetes.audit",
+ "actor": "system:serviceaccount:experiments:debug-runner",
+ "verb": "list",
+ "objectRef": "secrets",
+ "namespace": "kube-system"
+ }
+ ],
+ "recommended_actions": [
+ {"name": "k8s.clusterrolebinding.delete", "args": {"name": "debug-runner-cluster-admin"}},
+ {"name": "k8s.serviceaccount.disable", "args": {"namespace": "experiments", "name": "debug-runner"}},
+ {"name": "user.session.revoke_all", "args": {"user": "[email protected]"}},
+ {"name": "case.create", "args": {"title": "Kubernetes privilege escalation — namespace SA bound to cluster-admin", "severity": "critical"}},
+ {"name": "case.notify", "args": {"channel": "pagerduty", "service": "kubernetes-on-call"}}
+ ]
+}
diff --git a/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/lateral-movement.json b/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/lateral-movement.json
new file mode 100644
index 000000000..de7dcb852
--- /dev/null
+++ b/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/lateral-movement.json
@@ -0,0 +1,37 @@
+{
+ "id": "lateral-movement",
+ "title": "Lateral movement — impossible-travel Okta sign-in",
+ "narrative": "Alice signs in successfully from New York at 09:30 UTC, then again from Saint Petersburg eight minutes later. The geographical pivot is physically impossible inside that window — classic credential-takeover signature.",
+ "severity": "high",
+ "mitre_techniques": ["T1078", "T1078.004"],
+ "entities": {
+ "user": "[email protected]",
+ "ip_a": "203.0.113.42",
+ "ip_b": "203.0.113.50",
+ "asset": "okta-tenant://acme"
+ },
+ "events": [
+ {
+ "uuid": "11111111-1111-4111-8111-111111111111",
+ "published": "2026-05-14T09:30:14.123Z",
+ "eventType": "user.session.start",
+ "actor": "[email protected]",
+ "client_ip": "203.0.113.42",
+ "geo": {"city": "New York", "country": "US"}
+ },
+ {
+ "uuid": "22222222-2222-4222-8222-222222222222",
+ "published": "2026-05-14T09:38:01.000Z",
+ "eventType": "user.session.start",
+ "actor": "[email protected]",
+ "client_ip": "203.0.113.50",
+ "geo": {"city": "Saint Petersburg", "country": "RU"}
+ }
+ ],
+ "recommended_actions": [
+ {"name": "user.session.revoke_all", "args": {"user": "[email protected]"}},
+ {"name": "user.require_password_reset", "args": {"user": "[email protected]"}},
+ {"name": "case.create", "args": {"title": "Lateral movement — impossible-travel Okta sign-in", "severity": "high"}},
+ {"name": "case.notify", "args": {"channel": "slack", "audience": "soc-on-call"}}
+ ]
+}
diff --git a/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/phishing-payload.json b/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/phishing-payload.json
new file mode 100644
index 000000000..798c64338
--- /dev/null
+++ b/packages/aisoc-sandbox/src/aisoc_sandbox/scenarios/phishing-payload.json
@@ -0,0 +1,46 @@
+{
+ "id": "phishing-payload",
+ "title": "Phishing — click-through to credential-harvest page",
+ "narrative": "An email passed perimeter filters because the sender domain was less than 14 days old and had a valid DMARC alignment for a typosquatted root. A user clicked the link 6 minutes after delivery and arrived at a domain that imitates the corporate SSO. The credential POST was captured at the proxy.",
+ "severity": "high",
+ "mitre_techniques": ["T1566", "T1566.002"],
+ "entities": {
+ "user": "[email protected]",
+ "sender": "[email protected]",
+ "url": "https://acme-paychecks.com/login",
+ "asset": "host-engineering-72"
+ },
+ "events": [
+ {
+ "uuid": "phish-0001",
+ "published": "2026-06-15T11:14:00Z",
+ "eventType": "email.delivered",
+ "actor": "[email protected]",
+ "recipient": "[email protected]",
+ "subject": "Action required: payslip access expires today"
+ },
+ {
+ "uuid": "phish-0002",
+ "published": "2026-06-15T11:20:32Z",
+ "eventType": "proxy.url_click",
+ "actor": "[email protected]",
+ "url": "https://acme-paychecks.com/login",
+ "domain_age_days": 9
+ },
+ {
+ "uuid": "phish-0003",
+ "published": "2026-06-15T11:20:54Z",
+ "eventType": "proxy.form_post",
+ "actor": "[email protected]",
+ "url": "https://acme-paychecks.com/login",
+ "form_fields": ["username", "password"]
+ }
+ ],
+ "recommended_actions": [
+ {"name": "proxy.block_domain", "args": {"domain": "acme-paychecks.com"}},
+ {"name": "user.session.revoke_all", "args": {"user": "[email protected]"}},
+ {"name": "user.require_password_reset", "args": {"user": "[email protected]"}},
+ {"name": "email.search_and_purge", "args": {"sender": "[email protected]"}},
+ {"name": "case.create", "args": {"title": "Phishing — click-through to credential-harvest page", "severity": "high"}}
+ ]
+}
diff --git a/packages/aisoc-sandbox/tests/__init__.py b/packages/aisoc-sandbox/tests/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/packages/aisoc-sandbox/tests/test_smoke.py b/packages/aisoc-sandbox/tests/test_smoke.py
new file mode 100644
index 000000000..e4659cd39
--- /dev/null
+++ b/packages/aisoc-sandbox/tests/test_smoke.py
@@ -0,0 +1,165 @@
+"""Smoke tests — the package's own quick-win on-ramp.
+
+If any of these fail, `pip install aisoc-sandbox && aisoc-sandbox demo`
+no longer works on a clean machine — which is the only contract that
+matters for this package. The CI gate that runs this suite on a Linux
++ macOS matrix (see `.github/workflows/sandbox-smoke.yml`) is the
+authoritative trust signal for the `pip install` path.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import time
+
+import pytest
+
+from aisoc_sandbox import (
+ Ledger,
+ available_scenarios,
+ load_scenario,
+ run_investigation,
+)
+from aisoc_sandbox.cli import main
+
+
+# ---------------------------------------------------------------------------
+# Scenarios are real, loadable, well-formed.
+# ---------------------------------------------------------------------------
+
+def test_bundled_scenarios_are_exactly_the_five_we_advertise() -> None:
+ expected = {
+ "aws-credential-exfil",
+ "github-token-theft",
+ "kubernetes-privesc",
+ "lateral-movement",
+ "phishing-payload",
+ }
+ assert set(available_scenarios()) == expected
+
+
[email protected]("sid", sorted({
+ "aws-credential-exfil",
+ "github-token-theft",
+ "kubernetes-privesc",
+ "lateral-movement",
+ "phishing-payload",
+}))
+def test_each_scenario_loads_and_has_required_fields(sid: str) -> None:
+ sc = load_scenario(sid)
+ assert sc.id == sid
+ assert sc.title # human-readable headline must be present
+ assert sc.severity in {"info", "low", "medium", "high", "critical"}
+ assert sc.events, "every scenario must carry at least one event"
+ assert sc.mitre_techniques, "every scenario must reference at least one MITRE technique"
+
+
+def test_unknown_scenario_raises_a_useful_error() -> None:
+ with pytest.raises(ValueError, match="Unknown scenario"):
+ load_scenario("does-not-exist")
+
+
+# ---------------------------------------------------------------------------
+# Investigation funnel.
+# ---------------------------------------------------------------------------
+
+def test_run_emits_a_four_stage_ledger() -> None:
+ sc = load_scenario("lateral-movement")
+ ledger = run_investigation(sc)
+ stages = [step.funnel_stage for step in ledger]
+ assert stages == ["detect", "triage", "hunt", "respond"]
+
+
+def test_each_step_has_evidence_and_a_decision() -> None:
+ sc = load_scenario("aws-credential-exfil")
+ ledger = run_investigation(sc)
+ for step in ledger:
+ assert step.action, f"step {step.step} missing action"
+ assert step.rationale, f"step {step.step} missing rationale"
+ assert step.decision, f"step {step.step} missing decision summary"
+
+
+def test_offline_run_completes_well_under_the_30s_budget() -> None:
+ sc = load_scenario("lateral-movement")
+ t0 = time.perf_counter()
+ run_investigation(sc)
+ elapsed = time.perf_counter() - t0
+ # 30 s is the plan budget; the simulator should finish in under 1 s
+ # on any modern machine. We assert 5 s to leave plenty of headroom
+ # for CI VMs.
+ assert elapsed < 5.0, f"run took {elapsed:.3f} s (budget: 5 s, plan ceiling: 30 s)"
+
+
+def test_ledger_serialises_to_valid_json() -> None:
+ sc = load_scenario("phishing-payload")
+ ledger = run_investigation(sc)
+ payload = ledger.to_json()
+ parsed = json.loads(payload)
+ assert isinstance(parsed, list) and len(parsed) == 4
+
+
+def test_ledger_human_render_is_plain_text_when_not_tty() -> None:
+ sc = load_scenario("kubernetes-privesc")
+ ledger = run_investigation(sc)
+ buf = io.StringIO()
+ ledger.render_human(out=buf)
+ text = buf.getvalue()
+ # No ANSI escape codes when output isn't a TTY.
+ assert "\x1b[" not in text
+ # All four funnel labels must appear.
+ for label in ("DETECT", "TRIAGE", "HUNT", "RESPOND"):
+ assert label in text
+
+
+# ---------------------------------------------------------------------------
+# CLI surface.
+# ---------------------------------------------------------------------------
+
+def test_cli_demo_default_returns_0(capsys: pytest.CaptureFixture[str]) -> None:
+ exit_code = main(["demo"])
+ assert exit_code == 0
+ out = capsys.readouterr().out
+ assert "Investigation Ledger" in out
+ assert "Ready for the real stack?" in out
+
+
+def test_cli_demo_json_emits_machine_readable_payload(capsys: pytest.CaptureFixture[str]) -> None:
+ exit_code = main(["demo", "--scenario", "github-token-theft", "--json"])
+ assert exit_code == 0
+ parsed = json.loads(capsys.readouterr().out)
+ assert parsed["tool"] == "aisoc-sandbox"
+ assert parsed["scenario"]["id"] == "github-token-theft"
+ assert len(parsed["ledger"]) == 4
+ assert "elapsed_ms" in parsed
+
+
+def test_cli_scenarios_lists_all_five(capsys: pytest.CaptureFixture[str]) -> None:
+ exit_code = main(["scenarios"])
+ assert exit_code == 0
+ out = capsys.readouterr().out
+ for sid in (
+ "aws-credential-exfil",
+ "github-token-theft",
+ "kubernetes-privesc",
+ "lateral-movement",
+ "phishing-payload",
+ ):
+ assert sid in out
+
+
+def test_cli_demo_with_missing_file_exits_2(capsys: pytest.CaptureFixture[str]) -> None:
+ exit_code = main(["demo", "--file", "/does/not/exist.json"])
+ assert exit_code == 2
+ assert "error:" in capsys.readouterr().err
+
+
+def test_library_user_can_append_to_an_existing_ledger() -> None:
+ # A library user might want to chain multiple scenarios into one
+ # ledger — the dataclass contract supports that.
+ sc1 = load_scenario("lateral-movement")
+ sc2 = load_scenario("phishing-payload")
+ ledger = Ledger()
+ run_investigation(sc1, ledger=ledger)
+ run_investigation(sc2, ledger=ledger)
+ assert len(ledger) == 8 # 4 steps per scenario
diff --git a/packages/plugin-sdk-py/README.md b/packages/plugin-sdk-py/README.md
index 0aaad7875..f41f21042 100644
--- a/packages/plugin-sdk-py/README.md
+++ b/packages/plugin-sdk-py/README.md
@@ -3,16 +3,17 @@
The official Python SDK for building AiSOC plugins — custom enrichers,
response actions, and data-source connectors.
+> **Status — monorepo today, PyPI in v8.0.** Until the package lands on PyPI, install from the monorepo source path below. The import path (`aisoc_plugin_sdk`) and API surface stay identical once it ships.
+
## Installation
```bash
-pip install aisoc-plugin-sdk
-```
+# Today (from this monorepo):
+git clone https://github.com/beenuar/AiSOC.git
+cd AiSOC && pip install -e "packages/plugin-sdk-py[dev]"
-Or during development:
-
-```bash
-pip install -e "packages/plugin-sdk-py[dev]"
+# v8.0+ (once aisoc-plugin-sdk lands on PyPI):
+pip install aisoc-plugin-sdk
```
## Quick Start
diff --git a/packages/sdk-py/README.md b/packages/sdk-py/README.md
index db4e5c619..6b439f917 100644
--- a/packages/sdk-py/README.md
+++ b/packages/sdk-py/README.md
@@ -1,13 +1,20 @@
# aisoc-sdk
-[![PyPI version](https://img.shields.io/pypi/v/aisoc-sdk)](https://pypi.org/project/aisoc-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
+[![PyPI release](https://img.shields.io/badge/pypi-coming%20in%20v8.0-f59e0b)](https://github.com/beenuar/AiSOC/blob/main/CHANGELOG.md)
Async Python client SDK for [AiSOC](https://github.com/beenuar/AiSOC).
+> **Status — monorepo today, PyPI in v8.0.** Until the package lands on PyPI, install from the monorepo source path below. The import path (`aisoc_sdk`) and API surface stay identical once it ships.
+
## Installation
```bash
+# Today (from this monorepo):
+git clone https://github.com/beenuar/AiSOC.git
+cd AiSOC && pip install -e packages/sdk-py
+
+# v8.0+ (once aisoc-sdk lands on PyPI):
pip install aisoc-sdk
```
diff --git a/packages/sdk-ts/README.md b/packages/sdk-ts/README.md
index e0ffb4a15..aad0b36cb 100644
--- a/packages/sdk-ts/README.md
+++ b/packages/sdk-ts/README.md
@@ -1,13 +1,20 @@
# @aisoc/sdk
-[![npm version](https://img.shields.io/npm/v/@aisoc/sdk)](https://www.npmjs.com/package/@aisoc/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
+[![npm release](https://img.shields.io/badge/npm-coming%20in%20v8.0-f59e0b)](https://github.com/beenuar/AiSOC/blob/main/CHANGELOG.md)
TypeScript client SDK for [AiSOC](https://github.com/beenuar/AiSOC) — auto-generated types from `docs/openapi.yaml`, hand-crafted ergonomic API.
+> **Status — monorepo today, npm in v8.0.** Until the package lands on npm, use the monorepo source path below. The import path (`@aisoc/sdk`) and API surface stay identical once it ships.
+
## Installation
```bash
+# Today (from this monorepo):
+git clone https://github.com/beenuar/AiSOC.git
+cd AiSOC && pnpm --filter @aisoc/sdk-ts install
+
+# v8.0+ (once @aisoc/sdk lands on npm):
npm install @aisoc/sdk
# or
pnpm add @aisoc/sdk
diff --git a/scripts/aisoc-acceptance.ts b/scripts/aisoc-acceptance.ts
index 92f43e57a..fecb3bf78 100644
--- a/scripts/aisoc-acceptance.ts
+++ b/scripts/aisoc-acceptance.ts
@@ -64,7 +64,7 @@ import { hostname, platform, release } from "node:os";
import { join } from "node:path";
const ROOT = join(__dirname, "..");
-const COMPOSE_FILE = join(ROOT, "docker-compose.demo.yml");
+const COMPOSE_FILE = join(ROOT, "infra/compose/docker-compose.demo.yml");
const HISTORY_DIR = join(ROOT, ".aisoc");
const HISTORY_FILE = join(HISTORY_DIR, "acceptance-history.jsonl");
const DEFAULT_BUDGET_MS = 5 * 60 * 1000; // WS-A acceptance: 5 minutes.
diff --git a/scripts/aisoc-demo.ts b/scripts/aisoc-demo.ts
index 59106d624..1008054f7 100644
--- a/scripts/aisoc-demo.ts
+++ b/scripts/aisoc-demo.ts
@@ -5,7 +5,7 @@
* Steps:
* 1. Verify Docker + docker compose are present
* 2. Pull prebuilt images from ghcr.io/beenuar/* (no local builds)
- * 3. docker compose up -d using docker-compose.demo.yml (slim profile)
+ * 3. docker compose up -d using infra/compose/docker-compose.demo.yml (slim profile)
* — the `seed` service runs `python -m app.scripts.seed_demo` once
* automatically when the api is healthy, then exits cleanly.
* 4. Wait for postgres + api to be healthy
@@ -46,7 +46,7 @@ import { join } from "node:path";
import { platform } from "node:os";
const ROOT = join(__dirname, "..");
-const COMPOSE_FILE = join(ROOT, "docker-compose.demo.yml");
+const COMPOSE_FILE = join(ROOT, "infra/compose/docker-compose.demo.yml");
const STARTED_AT = Date.now();
// Per-phase timing for the v1.0 ≤5-min acceptance gate. Each step()
@@ -104,6 +104,28 @@ interface Flags {
// touches it — it exists so byte-stable reseeds are reproducible.
demoQuick: boolean;
clock: string | null;
+ // Phase 2 quick-win on-ramp: capture the visual assets the slim
+ // README and marketing landing depend on. Both modes run AFTER the
+ // demo stack is up and healthy; they shell out to the Playwright
+ // specs that already live under `apps/web/e2e/` so this script
+ // stays a thin orchestrator. Neither mode mutates state in the
+ // running stack.
+ //
+ // --record runs apps/web/e2e/demo/screencast.spec.ts against
+ // the local stack, transcodes the .webm to .mp4
+ // (H.264 + AAC) and renders hero.gif via ffmpeg,
+ // then copies all three into apps/web/public/demo/.
+ //
+ // --screenshots runs apps/web/e2e/screenshots/console.spec.ts
+ // and copies the four PNGs into
+ // apps/web/public/screenshots/01-alerts-queue.png
+ // through 04-marketplace.png.
+ //
+ // Both modes require ffmpeg on PATH (for --record only) and the
+ // Playwright Chromium binary installed (`pnpm --filter apps/web exec
+ // playwright install --with-deps chromium` if it isn't).
+ record: boolean;
+ screenshots: boolean;
}
function printHelp(): void {
@@ -127,6 +149,10 @@ ${c.bold("Demo content:")}
${c.bold("Flags:")}
--demo-quick, --quick seed only the 4 canonical DEMO-* cases (T6.4 screencast path)
--clock <iso> override the --demo-quick clock anchor (ISO-8601)
+ --record after boot, record the 90s screencast + hero.gif into
+ apps/web/public/demo/ (implies --no-open; needs ffmpeg)
+ --screenshots after boot, capture the 4 README screenshots into
+ apps/web/public/screenshots/ (implies --no-open)
--no-pull skip \`docker compose pull\` (use cached images)
--no-open skip launching the browser (CI / headless)
--rebuild \`docker compose up --build\` instead of prebuilt images
@@ -153,6 +179,8 @@ function parseFlags(argv: string[]): Flags {
resultsFile: null,
demoQuick: false,
clock: null,
+ record: false,
+ screenshots: false,
};
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
@@ -170,6 +198,14 @@ function parseFlags(argv: string[]): Flags {
flags.demoQuick = true;
} else if (a === "--clock") {
flags.clock = argv[++i] ?? null;
+ } else if (a === "--record") {
+ flags.record = true;
+ // Recording implies headless: we don't want a browser window
+ // flashing in front of the user mid-recording.
+ flags.noOpen = true;
+ } else if (a === "--screenshots") {
+ flags.screenshots = true;
+ flags.noOpen = true;
}
}
return flags;
@@ -602,7 +638,7 @@ function seedData(flags: Flags): boolean {
? "Seeding 4 deterministic DEMO-* cases (--demo-quick)"
: "Ensuring canonical demo data is seeded";
step(5, 7, label);
- // The `seed` service in docker-compose.demo.yml runs `python -m
+ // The `seed` service in infra/compose/docker-compose.demo.yml runs `python -m
// app.scripts.seed_demo` automatically once the api healthcheck passes
// and then exits. We re-run it here as a safety net for two cases:
// - the seed container failed silently (network blip pulling the
@@ -777,8 +813,8 @@ ${c.bold(c.green("AiSOC demo is up."))}
${c.dim("Useful commands:")}
pnpm aisoc:doctor ${c.dim("# health check")}
- docker compose -f docker-compose.demo.yml logs -f api
- docker compose -f docker-compose.demo.yml down -v ${c.dim("# stop & wipe demo data")}
+ docker compose -f infra/compose/docker-compose.demo.yml logs -f api
+ docker compose -f infra/compose/docker-compose.demo.yml down -v ${c.dim("# stop & wipe demo data")}
${c.bold("Total elapsed:")} ${c.green(elapsed())}
`);
@@ -887,6 +923,175 @@ function emitReport(flags: Flags, report: RunReport): void {
}
}
+// ---------- Phase 2 quick-win: visual asset capture ----------
+
+import { existsSync, mkdirSync, readdirSync, copyFileSync, statSync } from "node:fs";
+
+const WEB_DIR = join(ROOT, "apps", "web");
+const DEMO_PUBLIC_DIR = join(WEB_DIR, "public", "demo");
+const SCREENSHOTS_PUBLIC_DIR = join(WEB_DIR, "public", "screenshots");
+const SCREENCAST_TMP_DIR = join(ROOT, "tmp", "screencast");
+const SCREENSHOTS_TMP_DIR = join(ROOT, "tmp", "screenshots");
+
+function hasBinary(bin: string): boolean {
+ // POSIX `command -v` and Windows `where` both exit 0 when the
+ // binary resolves; we wrap with a try because spawnSync sets
+ // status=null on enoent which we want to treat as "missing".
+ const cmd = platform() === "win32" ? "where" : "command";
+ const args = platform() === "win32" ? [bin] : ["-v", bin];
+ try {
+ const r = spawnSync(cmd, args, { shell: platform() !== "win32", stdio: "ignore" });
+ return r.status === 0;
+ } catch {
+ return false;
+ }
+}
+
+function runPlaywrightSpec(specGlob: string, outputDir: string, label: string): boolean {
+ // We deliberately invoke pnpm filter so the Playwright config in
+ // apps/web/playwright.config.ts owns the codec / viewport / video
+ // settings — this script stays a thin orchestrator.
+ log(`${c.dim("→")} ${label}: running ${specGlob}`);
+ mkdirSync(outputDir, { recursive: true });
+ const args = [
+ "--filter",
+ "apps/web",
+ "exec",
+ "playwright",
+ "test",
+ specGlob,
+ "--reporter=line",
+ `--output=${outputDir}`,
+ ];
+ const env = { ...process.env, AISOC_SCREENCAST_URL: "http://localhost:3000", AISOC_DISABLE_ANALYTICS: "1" };
+ const r = spawnSync("pnpm", args, { cwd: ROOT, env, stdio: "inherit" });
+ if (r.status !== 0) {
+ console.error(c.red(` ${label} failed (exit ${r.status ?? "n/a"})`));
+ return false;
+ }
+ log(`${c.green("✓")} ${label} complete`);
+ return true;
+}
+
+function transcodeWebmToMp4AndGif(): boolean {
+ if (!hasBinary("ffmpeg")) {
+ console.error(c.yellow("ffmpeg not on PATH — install it to render hero.gif and demo.mp4"));
+ return false;
+ }
+ // Pick the most recent webm Playwright wrote. The Chromium recorder
+ // writes one per test-run with a deterministic-ish but undocumented
+ // filename; instead of guessing we just read the directory.
+ if (!existsSync(SCREENCAST_TMP_DIR)) {
+ console.error(c.red(`screencast tmp directory missing: ${SCREENCAST_TMP_DIR}`));
+ return false;
+ }
+ const webms = readdirSync(SCREENCAST_TMP_DIR, { recursive: true })
+ .map((name) => String(name))
+ .filter((p) => p.endsWith(".webm"))
+ .map((p) => join(SCREENCAST_TMP_DIR, p))
+ .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+ if (webms.length === 0) {
+ console.error(c.red("no .webm produced by Playwright run"));
+ return false;
+ }
+ const src = webms[0];
+ const mp4 = join(DEMO_PUBLIC_DIR, "demo.mp4");
+ const gif = join(DEMO_PUBLIC_DIR, "hero.gif");
+ mkdirSync(DEMO_PUBLIC_DIR, { recursive: true });
+
+ log(`${c.dim("→")} ffmpeg transcode → ${mp4}`);
+ const mp4r = spawnSync(
+ "ffmpeg",
+ [
+ "-y", "-i", src,
+ "-c:v", "libx264", "-preset", "slow", "-crf", "22",
+ "-c:a", "aac", "-b:a", "128k",
+ "-movflags", "+faststart",
+ mp4,
+ ],
+ { stdio: "inherit" },
+ );
+ if (mp4r.status !== 0) {
+ console.error(c.red(`ffmpeg mp4 transcode failed (exit ${mp4r.status})`));
+ return false;
+ }
+
+ // The hero.gif is a 10s loop of the most visually arresting shot
+ // (Shot 2 — Investigation timeline). We grab seconds 14-24 of the
+ // screencast and scale to 720px wide with palettegen for clean
+ // GIF colour quantisation. ≤ 5 MB target so it stays inline-friendly
+ // in the README.
+ log(`${c.dim("→")} ffmpeg render → ${gif}`);
+ const gifr = spawnSync(
+ "ffmpeg",
+ [
+ "-y", "-ss", "14", "-t", "10", "-i", src,
+ "-vf", "fps=15,scale=720:-2:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse",
+ "-loop", "0",
+ gif,
+ ],
+ { stdio: "inherit" },
+ );
+ if (gifr.status !== 0) {
+ console.error(c.red(`ffmpeg gif render failed (exit ${gifr.status})`));
+ return false;
+ }
+ log(`${c.green("✓")} wrote ${mp4} and ${gif}`);
+ return true;
+}
+
+async function recordScreencast(flags: Flags): Promise<boolean> {
+ void flags;
+ if (!runPlaywrightSpec("demo/screencast.spec.ts", SCREENCAST_TMP_DIR, "screencast")) {
+ return false;
+ }
+ return transcodeWebmToMp4AndGif();
+}
+
+async function captureScreenshots(flags: Flags): Promise<boolean> {
+ void flags;
+ if (!runPlaywrightSpec("screenshots/console.spec.ts", SCREENSHOTS_TMP_DIR, "screenshots")) {
+ return false;
+ }
+ // The screenshots spec writes a known set of PNG names directly
+ // into SCREENSHOTS_TMP_DIR; we copy them up to the public surface
+ // so the README image refs resolve.
+ if (!existsSync(SCREENSHOTS_TMP_DIR)) {
+ console.error(c.red(`screenshots tmp directory missing: ${SCREENSHOTS_TMP_DIR}`));
+ return false;
+ }
+ mkdirSync(SCREENSHOTS_PUBLIC_DIR, { recursive: true });
+ const expected = [
+ "01-alerts-queue.png",
+ "02-investigation-rail.png",
+ "03-hunt-workbench.png",
+ "04-marketplace.png",
+ ];
+ let copied = 0;
+ for (const name of expected) {
+ // Playwright writes screenshots inside a per-test directory; we
+ // walk the tmp dir flat-search style to handle either layout.
+ const candidates = readdirSync(SCREENSHOTS_TMP_DIR, { recursive: true })
+ .map((p) => String(p))
+ .filter((p) => p.endsWith(name))
+ .map((p) => join(SCREENSHOTS_TMP_DIR, p));
+ if (candidates.length === 0) {
+ console.error(c.yellow(` missing screenshot: ${name}`));
+ continue;
+ }
+ const src = candidates[0];
+ const dst = join(SCREENSHOTS_PUBLIC_DIR, name);
+ copyFileSync(src, dst);
+ copied += 1;
+ log(`${c.green("✓")} ${dst}`);
+ }
+ if (copied !== expected.length) {
+ console.error(c.red(`expected ${expected.length} screenshots, copied ${copied}`));
+ return false;
+ }
+ return true;
+}
+
// ---------- Main ----------
async function main() {
@@ -927,6 +1132,22 @@ async function main() {
if (seededCase) {
investigationKickedOff = await kickoffInvestigation(seededCase.id);
}
+
+ // Phase 2 quick-win: visual asset capture. We do these BEFORE
+ // openInBrowser so a `--record` user doesn't end up with a browser
+ // window in the recording. A failure here is non-fatal — the demo
+ // is still up and the user can re-run the capture step out of band.
+ if (flags.record) {
+ startPhase("Recording screencast");
+ const ok = await recordScreencast(flags);
+ if (!ok) console.error(c.yellow("screencast capture failed; demo is still running"));
+ }
+ if (flags.screenshots) {
+ startPhase("Capturing screenshots");
+ const ok = await captureScreenshots(flags);
+ if (!ok) console.error(c.yellow("screenshot capture failed; demo is still running"));
+ }
+
await openInBrowser(seededCase, flags);
// Reporting runs after openInBrowser so the cheerful "demo is up"
diff --git a/scripts/aisoc-doctor.ts b/scripts/aisoc-doctor.ts
index 328ed2eaf..a7de2c66f 100644
--- a/scripts/aisoc-doctor.ts
+++ b/scripts/aisoc-doctor.ts
@@ -197,7 +197,7 @@ async function checkDocker() {
// Use `docker ps -a` instead of `docker compose ps` so we discover
// containers across compose projects (the demo stack uses
- // `-f docker-compose.demo.yml` which is a separate project) AND so we can
+ // `-f infra/compose/docker-compose.demo.yml` which is a separate project) AND so we can
// distinguish "container never created" from "container exited" — the most
// common silent failure mode is the data tier (postgres, redis, kafka)
// exiting 255 after a Docker Desktop restart while upper services keep
diff --git a/scripts/demo-public.sh b/scripts/demo-public.sh
index c85ac9094..282172514 100755
--- a/scripts/demo-public.sh
+++ b/scripts/demo-public.sh
@@ -5,7 +5,7 @@
# Composition of two things that already exist:
#
# 1. `pnpm aisoc:demo --no-open` — boots the slim demo profile from
-# docker-compose.demo.yml, waits for postgres + api + web, seeds canonical
+# infra/compose/docker-compose.demo.yml, waits for postgres + api + web, seeds canonical
# data, kicks off an investigation. Defined in scripts/aisoc-demo.ts.
#
# 2. `infra/cloudflare/tunnel.sh` — creates / reuses the cloudflared tunnel
@@ -69,7 +69,7 @@ DOMAIN="${DOMAIN:-tryaisoc.com}"
printf "%s%s── AiSOC public demo ──%s\n" "$C_BOLD" "$C_GREEN" "$C_RESET"
printf " domain : %s%s%s\n" "$C_BOLD" "$DOMAIN" "$C_RESET"
-printf " stack : docker-compose.demo.yml (read-only profile, prebuilt images)\n"
+printf " stack : infra/compose/docker-compose.demo.yml (read-only profile, prebuilt images)\n"
printf " tunnel : cloudflared (outbound only — no inbound ports needed)\n\n"
# ---------------------------------------------------------------------------
diff --git a/scripts/generate_connector_count.py b/scripts/generate_connector_count.py
index f002ac324..fcf8ba07a 100755
--- a/scripts/generate_connector_count.py
+++ b/scripts/generate_connector_count.py
@@ -54,10 +54,14 @@ TS_OUT = REPO_ROOT / "apps" / "web" / "src" / "data" / "connectorCount.ts"
# disambiguating prefix/suffix so we never rewrite an unrelated integer.
COUNT_BEARING_FILES: tuple[tuple[Path, tuple[re.Pattern[str], ...]], ...] = (
(
+ # README went on a Phase-2 diet: the "declares **N first-party
+ # connectors**" and "a N-connector click-and-connect catalog"
+ # phrasings were absorbed into RELEASES.md / ROADMAP.md (already
+ # covered below). The lean README now anchors the count in a single
+ # bullet near the top of "What's in the box".
REPO_ROOT / "README.md",
(
- re.compile(r"(?P<pre>declares \*\*)(?P<n>\d+)(?P<post> first-party connectors)"),
- re.compile(r"(?P<pre>a )(?P<n>\d+)(?P<post>-connector click-and-connect catalog)"),
+ re.compile(r"(?P<pre>\*\*)(?P<n>\d+)(?P<post> click-and-connect data connectors\*\*)"),
),
),
(
diff --git a/scripts/install/preflight.ps1 b/scripts/install/preflight.ps1
index b8063a4f2..ec50a4f3d 100644
--- a/scripts/install/preflight.ps1
+++ b/scripts/install/preflight.ps1
@@ -72,7 +72,7 @@ if (-not $InstallRoot) {
}
}
-# These ports must match docker-compose.demo.yml. If you change ports
+# These ports must match infra/compose/docker-compose.demo.yml. If you change ports
# there, change them here, otherwise users get false negatives.
$script:PfRequiredPorts = @(
@{ Port = 3000; Name = "web console" },
diff --git a/scripts/install/preflight.sh b/scripts/install/preflight.sh
index e62776bbc..81c2eacad 100755
--- a/scripts/install/preflight.sh
+++ b/scripts/install/preflight.sh
@@ -71,7 +71,7 @@ readonly _PF_DISK_REC_GB=20
# Ports the demo stack exposes on the host. We probe each one and (a)
# tolerate it being free, (b) tolerate it being held by an aisoc-* container
# from a previous run, but (c) fail if it's held by anything else. The list
-# is kept in lockstep with docker-compose.demo.yml — when a port is added
+# is kept in lockstep with infra/compose/docker-compose.demo.yml — when a port is added
# there, add it here too.
#
# Using parallel arrays instead of an associative array because macOS still
@@ -215,7 +215,7 @@ _pf_port_owner() {
# Returns 0 if the given port-owner string indicates an AiSOC container —
# i.e. a previous demo run we can safely reuse / restart. The names come
-# from docker-compose.demo.yml + the project's compose project name
+# from infra/compose/docker-compose.demo.yml + the project's compose project name
# (defaults to the directory name, usually "aisoc").
#
# We can't use ${var,,} (bash 4+) here because macOS still ships bash 3.2
diff --git a/scripts/readme_gates.py b/scripts/readme_gates.py
new file mode 100644
index 000000000..908ff1d1b
--- /dev/null
+++ b/scripts/readme_gates.py
@@ -0,0 +1,376 @@
+#!/usr/bin/env python3
+"""Quick-win on-ramp CI gates for the AiSOC GitHub front door.
+
+This script bundles every assertion the v0 onramp plan promised would gate
+PRs that touch the README front door:
+
+1. README line count ≤ 250 (the README diet target).
+2. Every npm / PyPI package referenced in README either resolves on the
+ registry today, or is paired with a `Coming … in v8.0` guard so users
+ are not directed to a 404.
+3. Every reference to `apps/web/public/demo/<asset>` in README is paired
+ with an actually-existing file (or is paired with an explicit
+ "rendered .mp4 lands with v8.0" guard).
+
+The four-th gate (`aisoc-sandbox` cross-platform smoke test) lives in a
+separate matrix job in `.github/workflows/readme-gates.yml` because it
+needs Linux + macOS runners.
+
+Usage:
+ python3 scripts/readme_gates.py
+ # exit 0 on pass, non-zero on first failure.
+
+ python3 scripts/readme_gates.py --no-network
+ # skip the npm / PyPI registry probe; useful for offline / sandboxed
+ # CI runners that block egress to the public registries.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+README = REPO_ROOT / "README.md"
+
+# Anything in this list is permitted to appear in README without resolving
+# on a public package registry, provided the same line / surrounding block
+# carries a "Coming … in v8.0" guard.
+KNOWN_UNPUBLISHED = {
+ "npm": {"@aisoc/mcp", "@aisoc/sdk", "aisoc-cli"},
+ "pypi": {"aisoc-cli", "aisoc-plugin-sdk", "aisoc-sdk", "aisoc-sandbox"},
+}
+
+# Maximum number of lines we promise to keep the README at.
+README_MAX_LINES = 250
+
+# Phrases that count as a "this is intentionally not yet published" guard.
+V8_GUARDS = (
+ "coming in v8.0",
+ "coming to npm in v8.0",
+ "lands in v8.0",
+ "lands with v8.0",
+ "lands with the v8.0",
+ "publish lands in v8.0",
+ "ships in v8.0",
+ "ships with v8.0",
+ "ships with the v8.0",
+ "v8.0 launch",
+ "with the next phase 2 visuals rollup",
+ # Treat explicit monorepo-source-install references as their own guard:
+ # if README directs the reader to `pip install -e packages/<pkg>` or
+ # links to the in-tree `packages/<pkg>` folder, we're not directing them
+ # to a registry path, so the registry-404 risk does not apply.
+ "pip install -e packages/aisoc-sandbox",
+ "pip install -e packages/aisoc-cli",
+ "pip install -e packages/aisoc-sdk",
+ "pip install -e packages/aisoc-plugin-sdk",
+ "packages/aisoc-sandbox/",
+ "packages/aisoc-cli/",
+ "packages/aisoc-sdk/",
+ "packages/aisoc-plugin-sdk/",
+ "pnpm --filter @aisoc/mcp",
+ "pnpm --filter @aisoc/sdk",
+ "monorepo source build",
+ "monorepo source-build",
+)
+
+
+@dataclass
+class GateFailure:
+ gate: str
+ detail: str
+
+ def render(self) -> str:
+ return f"FAIL [{self.gate}] {self.detail}"
+
+
+def _read(text_path: Path) -> str:
+ return text_path.read_text(encoding="utf-8")
+
+
+def _has_guard(window: str) -> bool:
+ lowered = window.lower()
+ return any(phrase in lowered for phrase in V8_GUARDS)
+
+
+# ── Gate 1: README line count ────────────────────────────────────────────────
+
+
+def gate_readme_line_count() -> list[GateFailure]:
+ """README must stay ≤ README_MAX_LINES lines."""
+ actual = sum(1 for _ in README.read_text(encoding="utf-8").splitlines())
+ if actual > README_MAX_LINES:
+ return [
+ GateFailure(
+ "readme-line-count",
+ f"README has {actual} lines; budget is {README_MAX_LINES}. "
+ f"Move detail to apps/docs/ or RELEASES.md.",
+ )
+ ]
+ return []
+
+
+# ── Gate 2: Package references resolve or are guarded ────────────────────────
+
+
+def _npm_exists(package: str) -> bool:
+ """Return True iff the npm registry returns a 200 for the package."""
+ url = f"https://registry.npmjs.org/{package}"
+ request = Request(url, method="HEAD")
+ try:
+ with urlopen(request, timeout=15) as response:
+ return 200 <= response.status < 300
+ except HTTPError as exc:
+ if exc.code == 404:
+ return False
+ return False
+ except URLError:
+ return False
+
+
+def _pypi_exists(package: str) -> bool:
+ """Return True iff the PyPI JSON endpoint returns a 200 for the package."""
+ url = f"https://pypi.org/pypi/{package}/json"
+ try:
+ with urlopen(url, timeout=15) as response:
+ return 200 <= response.status < 300
+ except HTTPError as exc:
+ if exc.code == 404:
+ return False
+ return False
+ except URLError:
+ return False
+
+
+_NPM_PATTERN = re.compile(r"@aisoc/[a-z0-9][a-z0-9-]*")
+_PIP_PATTERN = re.compile(r"\baisoc-(?:cli|plugin-sdk|sdk|sandbox)\b")
+
+
+def _surrounding_lines(text: str, line_idx: int, radius: int = 3) -> str:
+ lines = text.splitlines()
+ start = max(0, line_idx - radius)
+ end = min(len(lines), line_idx + radius + 1)
+ return "\n".join(lines[start:end])
+
+
+def gate_package_references(check_network: bool) -> list[GateFailure]:
+ """Every package referenced in README must resolve or be guarded."""
+ text = _read(README)
+ lines = text.splitlines()
+ failures: list[GateFailure] = []
+
+ npm_to_lines: dict[str, list[int]] = {}
+ pip_to_lines: dict[str, list[int]] = {}
+
+ for idx, line in enumerate(lines):
+ for match in _NPM_PATTERN.findall(line):
+ npm_to_lines.setdefault(match, []).append(idx)
+ for match in _PIP_PATTERN.findall(line):
+ pip_to_lines.setdefault(match, []).append(idx)
+
+ def _check_package(
+ name: str,
+ registry: str,
+ line_idxs: list[int],
+ exists: Callable[[str], bool],
+ known_unpublished: set[str],
+ ) -> None:
+ any_line_guarded = any(
+ _has_guard(_surrounding_lines(text, idx)) for idx in line_idxs
+ )
+ if any_line_guarded:
+ return
+ if name in known_unpublished:
+ failures.append(
+ GateFailure(
+ f"package-resolves[{registry}]",
+ f"{name} is on the known-unpublished list but no v8.0 "
+ f"guard was found within 3 lines of any reference in "
+ f"README. Add one of: " + ", ".join(sorted(V8_GUARDS)),
+ )
+ )
+ return
+ if not check_network:
+ return
+ if not exists(name):
+ failures.append(
+ GateFailure(
+ f"package-resolves[{registry}]",
+ f"{name} does not resolve on {registry} and has no "
+ f"v8.0 guard within 3 lines of any reference in README. "
+ f"Either publish it, drop the reference, or add a "
+ f"'Coming in v8.0' guard.",
+ )
+ )
+
+ for name, indices in sorted(npm_to_lines.items()):
+ _check_package(name, "npm", indices, _npm_exists, KNOWN_UNPUBLISHED["npm"])
+ for name, indices in sorted(pip_to_lines.items()):
+ _check_package(name, "PyPI", indices, _pypi_exists, KNOWN_UNPUBLISHED["pypi"])
+ return failures
+
+
+# ── Gate 3: Demo asset references are honest ────────────────────────────────
+
+
+_DEMO_ASSET_PATTERN = re.compile(
+ r"apps/web/public/demo/(?P<asset>[A-Za-z0-9._-]+\.(?:mp4|gif|webm|webp|png|jpg))"
+)
+
+
+def gate_demo_asset_references() -> list[GateFailure]:
+ """If README points at an `apps/web/public/demo/<asset>` file, the file
+ must either exist on disk or sit next to an explicit "rendered ... lands
+ with v8.0" guard."""
+ text = _read(README)
+ failures: list[GateFailure] = []
+ for match in _DEMO_ASSET_PATTERN.finditer(text):
+ asset = match.group("asset")
+ path = REPO_ROOT / "apps" / "web" / "public" / "demo" / asset
+ if path.exists():
+ continue
+ # Find the line containing this match.
+ line_idx = text.count("\n", 0, match.start())
+ window = _surrounding_lines(text, line_idx, radius=4)
+ if _has_guard(window):
+ continue
+ failures.append(
+ GateFailure(
+ "demo-asset",
+ f"README references apps/web/public/demo/{asset} but the "
+ f"file does not exist and no v8.0 guard was found within "
+ f"4 lines of the reference.",
+ )
+ )
+ return failures
+
+
+# ── Gate 4 placeholder ──────────────────────────────────────────────────────
+#
+# The aisoc-sandbox cross-platform offline smoke test does not run in this
+# script — it lives in the CI matrix at .github/workflows/readme-gates.yml.
+# This gate placeholder records that fact so a contributor running the
+# script locally on (say) macOS still sees an unambiguous "you must also
+# verify aisoc-sandbox" hint in the output.
+
+
+def gate_sandbox_offline_smoke() -> list[GateFailure]:
+ """Run `aisoc-sandbox demo --scenario <each>` against the local source."""
+ package_root = REPO_ROOT / "packages" / "aisoc-sandbox"
+ src = package_root / "src"
+ if not src.exists():
+ return [
+ GateFailure(
+ "sandbox-offline",
+ "packages/aisoc-sandbox/src is missing — the sandbox package "
+ "was deleted or moved. Check phase3-sandbox.",
+ )
+ ]
+ failures: list[GateFailure] = []
+ scenarios = [
+ "lateral-movement",
+ "aws-credential-exfil",
+ "phishing-payload",
+ "kubernetes-privesc",
+ "github-token-theft",
+ ]
+ env = {"PYTHONPATH": str(src), "PATH": __import__("os").environ.get("PATH", "")}
+ for scenario in scenarios:
+ result = subprocess.run(
+ [
+ sys.executable,
+ "-m",
+ "aisoc_sandbox.cli",
+ "demo",
+ "--scenario",
+ scenario,
+ "--json",
+ ],
+ capture_output=True,
+ env=env,
+ timeout=30,
+ )
+ if result.returncode != 0:
+ failures.append(
+ GateFailure(
+ "sandbox-offline",
+ f"`aisoc-sandbox demo --scenario {scenario}` exited "
+ f"with code {result.returncode}:\n"
+ + result.stderr.decode("utf-8", errors="replace")[:400],
+ )
+ )
+ continue
+ try:
+ payload = json.loads(result.stdout.decode("utf-8"))
+ except json.JSONDecodeError as exc:
+ failures.append(
+ GateFailure(
+ "sandbox-offline",
+ f"`aisoc-sandbox demo --scenario {scenario}` did not "
+ f"emit valid JSON: {exc}",
+ )
+ )
+ continue
+ steps = payload.get("ledger", [])
+ if len(steps) != 4:
+ failures.append(
+ GateFailure(
+ "sandbox-offline",
+ f"Scenario {scenario} produced {len(steps)} ledger "
+ f"steps; expected exactly 4 (Detect/Triage/Hunt/"
+ f"Respond).",
+ )
+ )
+ return failures
+
+
+# ── Driver ──────────────────────────────────────────────────────────────────
+
+
+def _run_all(check_network: bool, skip_sandbox: bool) -> list[GateFailure]:
+ failures: list[GateFailure] = []
+ failures.extend(gate_readme_line_count())
+ failures.extend(gate_package_references(check_network))
+ failures.extend(gate_demo_asset_references())
+ if not skip_sandbox:
+ failures.extend(gate_sandbox_offline_smoke())
+ return failures
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument(
+ "--no-network",
+ action="store_true",
+ help="Skip the npm / PyPI registry probe.",
+ )
+ parser.add_argument(
+ "--skip-sandbox",
+ action="store_true",
+ help="Skip the local aisoc-sandbox offline smoke test (the CI "
+ "matrix runs this independently).",
+ )
+ args = parser.parse_args(argv)
+ failures = _run_all(
+ check_network=not args.no_network,
+ skip_sandbox=args.skip_sandbox,
+ )
+ if not failures:
+ print("readme-gates: OK")
+ return 0
+ for failure in failures:
+ print(failure.render(), file=sys.stderr)
+ return 1
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/services/mcp/README.md b/services/mcp/README.md
index 34d71095d..50dfd512b 100644
--- a/services/mcp/README.md
+++ b/services/mcp/README.md
@@ -2,31 +2,55 @@
> The official [Model Context Protocol](https://modelcontextprotocol.io) server for **AiSOC** — connect Claude Desktop, Cursor, Cody, Continue, and any MCP-aware assistant to your alerts, cases, detections, and the agent decision ledger.
-[![npm](https://img.shields.io/npm/v/@aisoc/mcp.svg)](https://www.npmjs.com/package/@aisoc/mcp)
-[![license](https://img.shields.io/npm/l/@aisoc/mcp.svg)](https://github.com/beenuar/AiSOC/blob/main/LICENSE)
+[![license](https://img.shields.io/badge/license-MIT-22c55e.svg)](https://github.com/beenuar/AiSOC/blob/main/LICENSE)
+[![status](https://img.shields.io/badge/status-monorepo--source--build-blue)](#install-from-source-today)
+[![npm release](https://img.shields.io/badge/npm-coming%20in%20v8.0-f59e0b)](https://github.com/beenuar/AiSOC/blob/main/CHANGELOG.md)
[![tests](https://img.shields.io/badge/tests-50%20passing-brightgreen)](#development)
+> **Status — monorepo source build today; npm publish in v8.0.** Every command in this README that shows `npx -y @aisoc/mcp …` works once the package lands on npm. Until then, use the **source-build equivalents** shown right below each one — they call the same binary, take the same arguments, and write the same config files.
+
AiSOC is the open-source AI SOC where every agent decision is auditable. This package is the bridge that lets your assistant ask AiSOC questions like "show me the open P0 cases" or "replay the agent's reasoning on INC-0421" without leaving the chat.
---
-## Install
+## Install from source (today)
+
+```bash
+git clone https://github.com/beenuar/AiSOC.git
+cd AiSOC/services/mcp
+pnpm install
+pnpm build # writes dist/index.js (the executable bin)
+```
+
+`dist/index.js` is the binary. Every command below shows the **today** invocation (`node dist/index.js …`) and the **v8.0 npm** invocation (`npx -y @aisoc/mcp …`) side by side — they accept identical flags.
+
+## Configure your assistant
The recommended path is the one-liner installer. It writes the right snippet into the right config file for your host, and it's idempotent:
```bash
-# Claude Desktop
+# Claude Desktop — today:
+node dist/index.js install --host claude \
+ --aisoc-url https://aisoc.your-company.com \
+ --api-key aisoc_pat_xxxxxxxxxxxx
+# Claude Desktop — v8.0+:
npx -y @aisoc/mcp install --host claude \
--aisoc-url https://aisoc.your-company.com \
--api-key aisoc_pat_xxxxxxxxxxxx
-# Cursor
+# Cursor — today:
+node dist/index.js install --host cursor --aisoc-url ... --api-key ...
+# Cursor — v8.0+:
npx -y @aisoc/mcp install --host cursor --aisoc-url ... --api-key ...
-# Continue.dev
+# Continue.dev — today:
+node dist/index.js install --host continue --aisoc-url ... --api-key ...
+# Continue.dev — v8.0+:
npx -y @aisoc/mcp install --host continue --aisoc-url ... --api-key ...
-# Cody (prints a snippet to paste — the extension reads VS Code settings)
+# Cody — today (prints a snippet to paste; the extension reads VS Code settings):
+node dist/index.js install --host cody --aisoc-url ... --api-key ...
+# Cody — v8.0+:
npx -y @aisoc/mcp install --host cody --aisoc-url ... --api-key ...
```
@@ -39,13 +63,32 @@ Restart your assistant and the `aisoc` server will appear in its tool picker.
If you'd rather edit the JSON yourself, `install --dry-run` prints exactly what the installer would write:
```bash
+# Today:
+node dist/index.js install --host claude --dry-run \
+ --aisoc-url https://aisoc.your-company.com --api-key aisoc_xxx
+# v8.0+:
npx -y @aisoc/mcp install --host claude --dry-run \
--aisoc-url https://aisoc.your-company.com --api-key aisoc_xxx
```
-The snippet looks like this — paste it under `mcpServers` in your host's config:
+Paste the snippet the installer prints under `mcpServers` in your host's config. The today vs v8.0 shapes are:
```json
+// Today (monorepo source build — note the absolute path)
+{
+ "mcpServers": {
+ "aisoc": {
+ "command": "node",
+ "args": ["/absolute/path/to/AiSOC/services/mcp/dist/index.js", "serve"],
+ "env": {
+ "AISOC_URL": "https://aisoc.your-company.com",
+ "AISOC_API_KEY": "aisoc_pat_xxxxxxxxxxxx"
+ }
+ }
+ }
+}
+
+// v8.0+ (once @aisoc/mcp is on npm)
{
"mcpServers": {
"aisoc": {
@@ -116,6 +159,12 @@ All flags can be set via env vars. The CLI flag wins if both are present.
Before pointing your assistant at it, smoke-test the connection:
```bash
+# Today (monorepo source build):
+AISOC_URL=https://aisoc.your-company.com \
+AISOC_API_KEY=aisoc_pat_xxx \
+node dist/index.js doctor
+
+# v8.0+ (once @aisoc/mcp lands on npm):
AISOC_URL=https://aisoc.your-company.com \
AISOC_API_KEY=aisoc_pat_xxx \
npx -y @aisoc/mcp doctor
diff --git a/tools/detection_import/README.md b/tools/detection_import/README.md
index 6db62c724..ee7147d23 100644
--- a/tools/detection_import/README.md
+++ b/tools/detection_import/README.md
@@ -67,5 +67,5 @@ Detection rules drift. SigmaHQ moves a rule from `experimental/` into `stable/`,
1. Create `tools/detection_import/<name>_importer.py` with a `def import_rules(commit: str, *, output_root: Path | None = None) -> list[ImportedRule]` entrypoint.
2. Wire it into `tools/detection_import/import_orchestrator.py`.
-3. Document the upstream license in [`LICENSES.md`](../../LICENSES.md).
+3. Document the upstream license in [`.github/LICENSES.md`](../../.github/LICENSES.md).
4. Update [`detections/README.md`](../../detections/README.md) with the new tier.
diff --git a/uninstall.ps1 b/uninstall.ps1
index 4c234fa5f..9329ea883 100644
--- a/uninstall.ps1
+++ b/uninstall.ps1
@@ -103,7 +103,7 @@ function Confirm-Action {
}
# ─── Locate the AiSOC repo ──────────────────────────────────────────────────
-# We need the path to docker-compose.demo.yml so `docker compose down -v` can
+# We need the path to infra/compose/docker-compose.demo.yml so `docker compose down -v` can
# resolve project resources cleanly. Prefer the directory two levels above
# this script (script lives in <repo>/scripts/install/), then fall back to
# the canonical $env:USERPROFILE\aisoc.
@@ -112,7 +112,7 @@ function Find-RepoRoot {
# The uninstaller lives at the repo root, alongside install.ps1.
$selfDir = Split-Path -Parent $PSCommandPath
if ($selfDir -and
- (Test-Path (Join-Path $selfDir 'docker-compose.demo.yml')) -and
+ (Test-Path (Join-Path $selfDir 'infra/compose/docker-compose.demo.yml')) -and
(Test-Path (Join-Path $selfDir 'package.json'))) {
$pkg = Get-Content (Join-Path $selfDir 'package.json') -Raw -ErrorAction SilentlyContinue
if ($pkg -match '"name"\s*:\s*"aisoc"') {
@@ -121,11 +121,11 @@ function Find-RepoRoot {
}
# Fallback 1: $HOME/aisoc (where install.ps1 clones by default).
$homePath = Join-Path $env:USERPROFILE 'aisoc'
- if (Test-Path (Join-Path $homePath 'docker-compose.demo.yml')) {
+ if (Test-Path (Join-Path $homePath 'infra/compose/docker-compose.demo.yml')) {
return $homePath
}
# Fallback 2: cwd is an aisoc clone.
- if ((Test-Path (Join-Path (Get-Location) 'docker-compose.demo.yml')) -and
+ if ((Test-Path (Join-Path (Get-Location) 'infra/compose/docker-compose.demo.yml')) -and
(Test-Path (Join-Path (Get-Location) 'package.json'))) {
$pkg = Get-Content (Join-Path (Get-Location) 'package.json') -Raw -ErrorAction SilentlyContinue
if ($pkg -match '"name"\s*:\s*"aisoc"') {
@@ -171,7 +171,7 @@ function Stop-DemoStack {
Write-Info "Stopping AiSOC demo stack and removing its volumes..."
Push-Location $RepoRoot
try {
- docker compose -f docker-compose.demo.yml down -v --remove-orphans
+ docker compose -f infra/compose/docker-compose.demo.yml down -v --remove-orphans
if ($LASTEXITCODE -ne 0) {
Write-Warn "compose down exited with code $LASTEXITCODE; some resources may not have been cleaned up."
} else {
@@ -283,7 +283,7 @@ function Remove-RepoClone {
# Final sanity check: target must look like an AiSOC clone. Stops us
# from rm -rf'ing some unrelated dir the user happened to put in
# %USERPROFILE%\aisoc.
- $composeFile = Join-Path $target 'docker-compose.demo.yml'
+ $composeFile = Join-Path $target 'infra/compose/docker-compose.demo.yml'
$pkgFile = Join-Path $target 'package.json'
$looksLikeAiSOC = $false
if ((Test-Path $composeFile) -and (Test-Path $pkgFile)) {
diff --git a/uninstall.sh b/uninstall.sh
index c0bb76d14..07463a865 100755
--- a/uninstall.sh
+++ b/uninstall.sh
@@ -99,17 +99,17 @@ find_repo() {
# The uninstaller lives at the repo root, alongside install.sh.
local self_dir
self_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
- if [ -f "$self_dir/docker-compose.demo.yml" ] && grep -q '"name": "aisoc"' "$self_dir/package.json" 2>/dev/null; then
+ if [ -f "$self_dir/infra/compose/docker-compose.demo.yml" ] && grep -q '"name": "aisoc"' "$self_dir/package.json" 2>/dev/null; then
REPO_ROOT="$self_dir"
return 0
fi
# Fallback: maybe the user ran us from PATH or a copy. Try $HOME/aisoc.
- if [ -d "$HOME/aisoc" ] && [ -f "$HOME/aisoc/docker-compose.demo.yml" ]; then
+ if [ -d "$HOME/aisoc" ] && [ -f "$HOME/aisoc/infra/compose/docker-compose.demo.yml" ]; then
REPO_ROOT="$HOME/aisoc"
return 0
fi
# Fallback 2: maybe we're run from the cwd of an aisoc clone.
- if [ -f "$PWD/docker-compose.demo.yml" ] && grep -q '"name": "aisoc"' "$PWD/package.json" 2>/dev/null; then
+ if [ -f "$PWD/infra/compose/docker-compose.demo.yml" ] && grep -q '"name": "aisoc"' "$PWD/package.json" 2>/dev/null; then
REPO_ROOT="$PWD"
return 0
fi
@@ -154,7 +154,7 @@ stop_demo_stack() {
if [ -z "$REPO_ROOT" ]; then return 0; fi
info "Stopping AiSOC demo stack and removing its volumes..."
- ( cd "$REPO_ROOT" && docker compose -f docker-compose.demo.yml down -v --remove-orphans ) \
+ ( cd "$REPO_ROOT" && docker compose -f infra/compose/docker-compose.demo.yml down -v --remove-orphans ) \
|| warn "compose down exited non-zero; some resources may not have been cleaned up."
ok "Demo stack stopped, named volumes deleted."
}
@@ -247,7 +247,7 @@ remove_repo_clone() {
# compose file AND a package.json claiming the project name). This stops
# us from rm -rf'ing some unrelated directory the user happened to put
# in $HOME/aisoc.
- if [ ! -f "$target/docker-compose.demo.yml" ] || ! grep -q '"name": "aisoc"' "$target/package.json" 2>/dev/null; then
+ if [ ! -f "$target/infra/compose/docker-compose.demo.yml" ] || ! grep -q '"name": "aisoc"' "$target/package.json" 2>/dev/null; then
warn "$target doesn't look like an AiSOC clone (missing compose file or package.json marker)."
warn "Refusing to delete it — clean it up manually if you really want to."
SAFETY_REFUSED=1