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: correct Markdown that describes a tree that no longer exists (#1058)

Beenu Aroracb89a205fdd0
diff --git a/.github/CREDITS.md b/.github/CREDITS.md
index 19b331c08..ce86886d8 100644
--- a/.github/CREDITS.md
+++ b/.github/CREDITS.md
@@ -16,7 +16,7 @@ We deeply appreciate everyone who takes the time to report a security issue resp
| [**@mangod12**](https://github.com/mangod12) | Reported [#159](https://github.com/beenuar/AiSOC/issues/159) — proposed cross-tenant isolation tests + nightly CI for RBAC regression. Directly informed the tenant-isolation hardening work that landed in [PR #221](https://github.com/beenuar/AiSOC/pull/221). |
| [**@jay-cyble**](https://github.com/jay-cyble) (Jay Vasant) | Reported [#130](https://github.com/beenuar/AiSOC/issues/130) — a structured review of 13 security & UI issues found via code review + live-site inspection. Multiple findings were used to drive follow-up hardening tickets. |
-If you want to report a vulnerability, please use [GitHub's private vulnerability reporting](https://github.com/beenuar/AiSOC/security/advisories/new) and read [SECURITY.md](SECURITY.md) first.
+If you want to report a vulnerability, please use [GitHub's private vulnerability reporting](https://github.com/beenuar/AiSOC/security/advisories/new) and read [SECURITY.md](../SECURITY.md) first.
---
diff --git a/.github/LICENSES.md b/.github/LICENSES.md
index 7f6e3eec6..4f5d55c3e 100644
--- a/.github/LICENSES.md
+++ b/.github/LICENSES.md
@@ -1,8 +1,8 @@
# Third-Party Content Licenses
-AiSOC ships under the [MIT License](LICENSE). Some content under [`detections/`](detections/) is **imported** from upstream open-source detection corpora and is redistributed under each upstream project's own license. Every imported rule carries a `provenance` block documenting its source, upstream id, commit SHA, and license, so you can always trace a rule back to its origin.
+AiSOC ships under the [MIT License](../LICENSE). Some content under [`detections/`](../detections/) is **imported** from upstream open-source detection corpora and is redistributed under each upstream project's own license. Every imported rule carries a `provenance` block documenting its source, upstream id, commit SHA, and license, so you can always trace a rule back to its origin.
-This file is the canonical attribution registry. It is updated automatically when [`tools/detection-import/import.py`](tools/detection-import/import.py) runs.
+This file is the canonical attribution registry. It is maintained by hand: nothing in the tree writes it, so an importer added to [`tools/detection_import/`](../tools/detection_import/) must be accompanied by an entry here in the same change.
> ⚠️ **If you redistribute AiSOC's detection corpus** (e.g. ship it as part of a managed-service offering), you are responsible for honoring every upstream license below in your own attribution notices.
@@ -17,7 +17,7 @@ This file is the canonical attribution registry. It is updated automatically whe
| **Upstream repo** | [SigmaHQ/sigma](https://github.com/SigmaHQ/sigma) |
| **License** | [Detection Rule License (DRL) 1.1](https://github.com/SigmaHQ/Detection-Rule-License) |
| **License classification** | Permissive, redistribution-allowed with attribution |
-| **Imported via** | [`tools/detection-import/sigma_importer.py`](tools/detection-import/sigma_importer.py) |
+| **Imported via** | [`tools/detection_import/sigma_importer.py`](../tools/detection_import/sigma_importer.py) |
| **Provenance file** | every rule carries `provenance.source: SigmaHQ/sigma`, `provenance.source_id: <upstream uuid>`, `provenance.source_commit: <sha>` |
DRL-1.1 summary: you may use, modify, and redistribute Sigma rules provided you keep attribution intact. Each imported rule retains its upstream `id` (UUID) inside the `provenance` block.
@@ -28,7 +28,7 @@ DRL-1.1 summary: you may use, modify, and redistribute Sigma rules provided you
|---|---|
| **Upstream repo** | [mitre-attack/car](https://github.com/mitre-attack/car) |
| **License** | [Apache-2.0](https://github.com/mitre-attack/car/blob/master/LICENSE) |
-| **Imported via** | [`tools/detection-import/car_importer.py`](tools/detection-import/car_importer.py) |
+| **Imported via** | [`tools/detection_import/car_importer.py`](../tools/detection_import/car_importer.py) |
| **Provenance file** | every rule carries `provenance.source: mitre-attack/car`, `provenance.source_id: CAR-YYYY-MM-NNN`, `provenance.source_commit: <sha>` |
### Splunk Security Content — `detections/splunk-imports/`
@@ -37,8 +37,8 @@ DRL-1.1 summary: you may use, modify, and redistribute Sigma rules provided you
|---|---|
| **Upstream repo** | [splunk/security_content](https://github.com/splunk/security_content) |
| **License** | [Apache-2.0](https://github.com/splunk/security_content/blob/develop/LICENSE) |
-| **Imported via** | [`tools/detection-import/splunk_importer.py`](tools/detection-import/splunk_importer.py) |
-| **Note** | SPL → Sigma transpile is best-effort. Rules that don't round-trip cleanly are emitted with `enabled: false` and surfaced in [`detections/REVIEW.md`](detections/REVIEW.md). |
+| **Imported via** | [`tools/detection_import/splunk_importer.py`](../tools/detection_import/splunk_importer.py) |
+| **Note** | SPL → Sigma transpile is best-effort. Rules that don't round-trip cleanly are emitted with `enabled: false`. [`detections/splunk-imports/_quarantine/README.md`](../detections/splunk-imports/_quarantine/README.md) is the generated index of what was held back and why. |
### Chronicle Detection Rules — `detections/chronicle-imports/`
@@ -46,8 +46,8 @@ DRL-1.1 summary: you may use, modify, and redistribute Sigma rules provided you
|---|---|
| **Upstream repo** | [chronicle/detection-rules](https://github.com/chronicle/detection-rules) |
| **License** | [Apache-2.0](https://github.com/chronicle/detection-rules/blob/main/LICENSE) |
-| **Imported via** | [`tools/detection-import/chronicle_importer.py`](tools/detection-import/chronicle_importer.py) |
-| **Note** | YARA-L 2.0 → Sigma conversion covers ~60% of upstream rules cleanly. The hard cases (statistical aggregations, `match` clauses with windowed joins) are deferred and tracked in [`detections/REVIEW.md`](detections/REVIEW.md). |
+| **Imported via** | [`tools/detection_import/chronicle_importer.py`](../tools/detection_import/chronicle_importer.py) |
+| **Note** | YARA-L 2.0 → Sigma conversion covers ~60% of upstream rules cleanly. The hard cases (statistical aggregations, `match` clauses with windowed joins) are deferred; [`docs/detections/truth-table.md`](../docs/detections/truth-table.md) is the generated record of which rules the engine actually loads. |
### Atomic Red Team mappings — `detections/atomic-imports/` (planned)
@@ -61,7 +61,7 @@ DRL-1.1 summary: you may use, modify, and redistribute Sigma rules provided you
## Native AiSOC content
-Everything under `detections/cloud/`, `detections/identity/`, `detections/endpoint/`, `detections/network/`, `detections/application/`, and `detections/data-exfil/` is **native AiSOC content** authored against AiSOC's own normalized event schema. Native rules are licensed under the [MIT License](LICENSE) and carry a `provenance.source: native` marker.
+Everything under `detections/cloud/`, `detections/identity/`, `detections/endpoint/`, `detections/network/`, `detections/application/`, and `detections/data-exfil/` is **native AiSOC content** authored against AiSOC's own normalized event schema. Native rules are licensed under the [MIT License](../LICENSE) and carry a `provenance.source: native` marker.
`detections/community/` carries community contributions, also under MIT with the contributor named in the provenance block.
@@ -69,16 +69,16 @@ Everything under `detections/cloud/`, `detections/identity/`, `detections/endpoi
## Plugins
-Each plugin under [`plugins/`](plugins/) declares its own license in `plugin.yaml`. Plugins shipped with AiSOC core are MIT or Apache-2.0; community plugins under `plugins/community/` may declare any OSI-approved license.
+Each plugin under [`plugins/`](../plugins/) declares its own license in `plugin.yaml`. Plugins shipped with AiSOC core are MIT or Apache-2.0; community plugins under `plugins/community/` may declare any OSI-approved license.
---
## How to add a new imported source
-1. Add an importer to [`tools/detection-import/`](tools/detection-import/) that emits the AiSOC YAML schema with a populated `provenance` block.
+1. Add an importer to [`tools/detection_import/`](../tools/detection_import/) that emits the AiSOC YAML schema with a populated `provenance` block.
2. Add a section to this file describing the upstream license and any redistribution caveats.
3. Run `python3 scripts/validate_detections.py` and `pnpm marketplace:build` to confirm the new rules parse and surface.
---
-_Last updated by `tools/detection-import/import.py` on first run; subsequent runs only append new sources, never rewrite the file._
+_Last updated by `tools/detection_import/import.py` on first run; subsequent runs only append new sources, never rewrite the file._
diff --git a/apps/docs/docs/deployment/azure.md b/apps/docs/docs/deployment/azure.md
index 826021f81..6b0c98b98 100644
--- a/apps/docs/docs/deployment/azure.md
+++ b/apps/docs/docs/deployment/azure.md
@@ -138,7 +138,7 @@ For the cheapest sandbox set `postgres_sku = "B_Standard_B1ms"` and
This is a **skeleton**, not the full Azure migration:
- **No long-running services.** `services/agents`, `services/realtime`,
- `services/connectors`, `services/alert-fusion`, `services/threatintel`, and
+ `services/connectors`, `services/fusion`, `services/threatintel`, and
`services/fusion` need always-on compute. Run them as dedicated Container
Apps with `min_replicas > 0` (KEDA can still scale on queue depth) or move
them to AKS sharing this VNet, Postgres, and Redis.
diff --git a/apps/docs/docs/deployment/gcp.md b/apps/docs/docs/deployment/gcp.md
index 835905082..be1618a13 100644
--- a/apps/docs/docs/deployment/gcp.md
+++ b/apps/docs/docs/deployment/gcp.md
@@ -134,7 +134,7 @@ plus a `STANDARD_HA` Redis.
This is a **skeleton**, not the full GCP migration:
- **No long-running services.** `services/agents`, `services/realtime`,
- `services/connectors`, `services/alert-fusion`, `services/threatintel`, and
+ `services/connectors`, `services/fusion`, `services/threatintel`, and
`services/fusion` need persistent compute. The websocket fan-out and the
APScheduler-driven connector polling don't fit Cloud Run's request lifecycle
cleanly. The recommended follow-up is GKE Autopilot for those workloads,
diff --git a/apps/web/public/demo/README.md b/apps/web/public/demo/README.md
index fe5cec687..0815c671c 100644
--- a/apps/web/public/demo/README.md
+++ b/apps/web/public/demo/README.md
@@ -54,7 +54,7 @@ records a different, older product tour of a *deployed* instance
(`apps/web/e2e/demo/screencast.spec.ts`) and uploads it as a workflow artefact;
it does not write into this directory. Re-recording the deployment walkthrough
means driving a real deployment again — the written form of every step is in
-[`apps/docs/docs/deployment/walkthrough.md`](../../../docs/docs/deployment/walkthrough.md),
+[`apps/docs/docs/deployment/walkthrough.mdx`](../../../docs/docs/deployment/walkthrough.mdx),
including the recording method, so it can be reproduced rather than guessed at.
Keep the budget in mind if you replace them: these files are committed, so
diff --git a/docs/QUICK_INSTALL.md b/docs/QUICK_INSTALL.md
index 94b1e059d..8403a4299 100644
--- a/docs/QUICK_INSTALL.md
+++ b/docs/QUICK_INSTALL.md
@@ -5,9 +5,8 @@ machine to a running AiSOC dashboard in your browser, with **zero assumed
prerequisites**, in a single command.
If you already have Docker, Node 22, pnpm 8+, and git installed, you don't need
-these scripts — just run `pnpm aisoc:demo` from a clone. These installers exist
-for the case where you don't (or you're handing the repo to someone who
-doesn't).
+these scripts — just run `make up` from a clone. These installers exist for the
+case where you don't (or you're handing the repo to someone who doesn't).
## TL;DR
@@ -25,9 +24,25 @@ Open PowerShell **as Administrator** and run:
iwr -useb https://raw.githubusercontent.com/beenuar/AiSOC/main/install.ps1 | iex
```
-When the script finishes, your default browser opens at
-`http://localhost:3000/cases/INC-RT-001?tab=ledger` with `[email protected]`
-already auto-logged-in and a real LockBit 3.0 investigation mid-flight.
+When the script finishes it starts the CORE stack with `make up`, creates the
+first administrator, prints that password **once**, and then runs the golden
+pipeline end to end — one real event through Kafka, fusion and detection, read
+back as an alert from the API. If that check fails the installer exits
+non-zero and says so; "the containers started" is not "it works".
+
+The console is at `http://localhost:3000` and Swagger at
+`http://localhost:8000/api/docs`. Sign in as `[email protected]` with the
+generated password. The console starts **empty** — that is correct, because
+nothing has been connected yet. `make demo` loads clearly-labelled synthetic
+data if you want something to look at.
+
+> Earlier revisions of this page said the browser opened on a seeded LockBit
+> investigation at `/cases/INC-RT-001?tab=ledger` under a `[email protected]`
+> auto-login. That was the old `pnpm aisoc:demo` handoff, which started a
+> different nine-service compose file with no ingest and no fusion, populated
+> by a seed script writing rows straight into Postgres. It was removed
+> precisely because a reader saw a full console and concluded the platform
+> worked without ever having run it.
## What gets installed
@@ -38,12 +53,12 @@ needs, and only if they are missing or too old:
| ---------------------- | --------------------------------- | ---------------------- | -------------------------------- |
| `git` | distro package manager | `winget Git.Git` | clone the repo |
| Docker Engine + Compose v2 | distro package manager (Linux), `brew install --cask docker` (macOS) | `winget Docker.DockerDesktop` (+ WSL2) | run the AiSOC stack |
-| Node.js 22 LTS | NodeSource (Linux), `brew` (macOS) | `winget OpenJS.NodeJS.LTS` | drive `pnpm aisoc:demo` |
+| Node.js 22 LTS | NodeSource (Linux), `brew` (macOS) | `winget OpenJS.NodeJS.LTS` | build the console and run the repo's tooling |
| pnpm 8+ | `corepack enable` + `corepack prepare pnpm@latest` | same | install Node deps |
**It does not install:** Python, Go, Rust, Postgres, Redis, Kafka,
ClickHouse, OpenSearch, Neo4j, Qdrant, or anything else. Those run inside
-Docker containers via `pnpm aisoc:demo`, never on your host.
+Docker containers, started by `make up`, never on your host.
**It does not modify:** your dotfiles, your shell init, your existing Docker
installation, your existing Node installation, or any system packages outside
@@ -92,9 +107,13 @@ the `docker` group to take effect.
```text
--no-install Skip the dependency-install phase (use what's on PATH).
---no-launch Set everything up but don't run pnpm aisoc:demo at the end.
---no-pull Forwarded to aisoc:demo to skip image pull.
---rebuild Forwarded to aisoc:demo to build images from source.
+--no-launch Set everything up but don't start the stack at the end.
+--no-pull Accepted for backward compatibility. It no longer does
+ anything: the handoff is `make up`, which runs
+ `docker compose up -d` and honours AISOC_PULL_POLICY.
+--rebuild Accepted for backward compatibility; same note as above.
+ To build from source, run `docker compose build` in the
+ clone before `make up`.
--clone-dir DIR Where to clone the repo when running as a one-liner.
Default: $HOME/aisoc
--branch BR Git branch to clone. Default: main.
@@ -114,9 +133,9 @@ the `docker` group to take effect.
```text
-NoInstall Skip the dependency-install phase.
--NoLaunch Set everything up but don't run pnpm aisoc:demo.
--NoPull Forwarded to aisoc:demo.
--Rebuild Forwarded to aisoc:demo.
+-NoLaunch Set everything up but don't start the stack.
+-NoPull No longer applies; the script warns and continues.
+-Rebuild Adds --build to the compose up it runs.
-CloneDir PATH Where to clone. Default: $env:USERPROFILE\aisoc
-Branch NAME Git branch. Default: main.
-SkipPreflight Skip the up-front environment checks.
@@ -188,10 +207,10 @@ clone that branch instead of `main`.
**I want to put the clone somewhere specific.** `./install.sh --clone-dir
~/code/aisoc` (default is `$HOME/aisoc`).
-**I want to build images from source instead of pulling from GHCR.**
-`./install.sh --rebuild` forwards `--rebuild` to `pnpm aisoc:demo`. This is
-slower (~10-15 min cold) but lets you run an unreleased branch without waiting
-for image publishing.
+**I want to build images from source instead of pulling from GHCR.** Clone the
+branch, then run `docker compose build` followed by `make up`. This is slower
+(~10-15 min cold) but lets you run an unreleased branch without waiting for
+image publishing. On Windows, `install.ps1 -Rebuild` does this for you.
## Uninstalling
@@ -285,7 +304,7 @@ If preflight flags one of these as in use:
- Linux/macOS: `lsof -nP -iTCP:3000 -sTCP:LISTEN`
- Windows: `Get-NetTCPConnection -LocalPort 3000 | Select OwningProcess; Get-Process -Id <pid>`
2. Either stop that process, or set the matching `AISOC_*_PORT` env var
- in `.env` (or in your shell) and re-run `pnpm aisoc:demo`.
+ in `.env` (or in your shell) and re-run `make up`.
Preflight only **warns** if a port is taken by a process that looks like
an existing AiSOC container — re-running the installer on a machine that
@@ -295,7 +314,7 @@ already has the demo running won't fail preflight.
The installer adds you to the `docker` group, but the new membership only
takes effect for new shells. The installer works around this for the same
-session by piping `pnpm aisoc:demo` through `sg docker -c`. If you open a
+session by piping `make up` through `sg docker -c`. If you open a
fresh terminal afterwards and still see the error, log out and back in (or
reboot) to pick up the new group.
@@ -371,26 +390,26 @@ then re-run the installer.
The installer launches your browser via `xdg-open` (Linux), `open` (macOS),
or `Start-Process` (Windows). If your environment doesn't have a browser
-configured (e.g. SSH session, headless CI), open
-`http://localhost:3000/cases/INC-RT-001?tab=ledger` in any browser on the
-host yourself.
+configured (e.g. SSH session, headless CI), open `http://localhost:3000` in
+any browser on the host yourself.
-### `pnpm aisoc:demo` fails after a successful install
+### The stack fails after a successful install
-Run `pnpm aisoc:doctor` from inside the clone — it pinpoints which container
-or port is unhealthy. Common causes:
+Run `make doctor` from inside the clone (or `pnpm aisoc:doctor`) — it
+pinpoints which container or port is unhealthy, and `make smoke` re-runs the
+end-to-end pipeline check. Common causes:
- One of the bound ports is already in use → see
[Port conflicts](#port-conflicts) above for the table of ports and
the env vars to change them.
- Docker daemon out of disk → `docker system prune -a` and retry.
- Corporate proxy blocking `ghcr.io` → either configure Docker's
- HTTP proxy or run `./install.sh --rebuild` to build from source.
+ HTTP proxy or run `docker compose build` to build from source.
-If `aisoc:demo` finishes "successfully" but no browser opens, that's
-usually an `AISOC_NO_BROWSER=1` env var leaking from a previous CI run, or
-a headless environment (SSH session, no `$DISPLAY`). The URL is printed in
-the final banner — open it manually.
+If the install finishes successfully but no browser opens, that is usually an
+`AISOC_NO_BROWSER=1` env var leaking from a previous CI run, or a headless
+environment (SSH session, no `$DISPLAY`). The URL is printed in the final
+banner — open it manually.
## Security notes
diff --git a/docs/api/API_REFERENCE.md b/docs/api/API_REFERENCE.md
index 4cb77efab..9719cf825 100644
--- a/docs/api/API_REFERENCE.md
+++ b/docs/api/API_REFERENCE.md
@@ -1,6 +1,13 @@
# AiSOC API Reference
-This document describes the REST endpoints exposed by AiSOC services. For the auto-generated, exhaustive schema visit `/docs` (Swagger) on each running service.
+This document describes the REST endpoints exposed by AiSOC services. For the
+auto-generated, exhaustive schema visit `/api/docs` (Swagger) on a running API
+service — the app mounts it there, not at `/docs`.
+
+> The maintained, published API reference is
+> [`apps/docs/docs/api/rest.md`](../../apps/docs/docs/api/rest.md) on the docs
+> portal. This page is the longer-form companion; where the two disagree, the
+> generated OpenAPI schema at `/api/openapi.json` wins.
| Service | Base URL (local) |
|---------|-------------------|
@@ -10,14 +17,14 @@ This document describes the REST endpoints exposed by AiSOC services. For the au
| Fusion | `http://localhost:8003` |
| Threat Intel | `http://localhost:8005` |
| Purple Team | `http://localhost:8006` |
-| Connectors | (internal scheduler — no external port) |
+| Connectors | `http://localhost:8088` |
All examples assume:
```bash
# AISOC_ADMIN_PASSWORD is the password `make bootstrap` printed. There is no
# default credential — each deployment generates its own at first run.
-export AISOC_TOKEN="$(curl -sX POST http://localhost:8000/v1/auth/login \
+export AISOC_TOKEN="$(curl -sX POST http://localhost:8000/api/v1/auth/login \
-H 'content-type: application/json' \
-d "{\"email\":\"[email protected]\",\"password\":\"$AISOC_ADMIN_PASSWORD\"}" \
| jq -r .access_token)"
@@ -26,17 +33,17 @@ export AISOC_TENANT="00000000-0000-0000-0000-000000000001"
---
-## 1. Graph (Neo4j) — `/v1/graph`
+## 1. Graph (Neo4j) — `/api/v1/graph`
Service: `services/api`.
-### 1.1 `GET /v1/graph/attack-path/{case_id}`
+### 1.1 `GET /api/v1/graph/attack-path/{case_id}`
Reconstructs the kill-chain for a case by traversing `(:Case)-[:CONTAINS]->(:Alert)-[:USES]->(:Technique)-[:PART_OF]->(:Tactic)`.
```bash
curl -H "authorization: Bearer $AISOC_TOKEN" \
- http://localhost:8000/v1/graph/attack-path/$CASE_ID
+ http://localhost:8000/api/v1/graph/attack-path/$CASE_ID
```
**Response**
@@ -55,19 +62,21 @@ curl -H "authorization: Bearer $AISOC_TOKEN" \
}
```
-### 1.2 `GET /v1/graph/blast-radius`
+### 1.2 `GET /api/v1/graph/blast-radius/{entity_type}/{entity_id}`
Returns 1-3 hop neighborhood of a node, used to gate high-impact actions.
+`entity_type` and `entity_id` are **path** segments; only `max_hops` is a
+query parameter.
-| Query param | Required | Description |
-|-------------|----------|-------------|
-| `entity_type` | yes | One of `host`, `user`, `ioc` |
-| `entity_id` | yes | Node identifier |
-| `max_hops` | no (default `2`) | 1-3 |
+| Parameter | Where | Description |
+|-----------|-------|-------------|
+| `entity_type` | path | One of `host`, `user`, `ioc` |
+| `entity_id` | path | Node identifier |
+| `max_hops` | query (default `2`) | 1-3 |
```bash
curl -H "authorization: Bearer $AISOC_TOKEN" \
- "http://localhost:8000/v1/graph/blast-radius?entity_type=host&entity_id=HOST-42&max_hops=2"
+ "http://localhost:8000/api/v1/graph/blast-radius/host/HOST-42?max_hops=2"
```
**Response**
@@ -84,11 +93,12 @@ curl -H "authorization: Bearer $AISOC_TOKEN" \
}
```
-### 1.3 `GET /v1/graph/neighbors`
+### 1.3 `GET /api/v1/graph/neighbors/{entity_type}/{entity_id}`
-1-hop neighborhood for the SOC console "context" panel.
+1-hop neighborhood for the SOC console "context" panel. Same path-parameter
+shape as blast radius.
-### 1.4 `GET /v1/graph/mitre-coverage`
+### 1.4 `GET /api/v1/graph/mitre-coverage`
Aggregated counts of distinct techniques observed per tenant.
@@ -98,11 +108,11 @@ Aggregated counts of distinct techniques observed per tenant.
---
-## 2. Detection Rules — `/v1/rules`
+## 2. Detection Rules — `/api/v1/rules`
Service: `services/api`.
-### 2.1 `GET /v1/rules`
+### 2.1 `GET /api/v1/rules`
| Query param | Description |
|-------------|-------------|
@@ -110,7 +120,7 @@ Service: `services/api`.
| `enabled` | `true`/`false` |
| `severity` | `low`-`critical` |
-### 2.2 `POST /v1/rules`
+### 2.2 `POST /api/v1/rules`
```json
{
@@ -123,7 +133,7 @@ Service: `services/api`.
}
```
-### 2.3 `POST /v1/rules/{id}/execute`
+### 2.3 `POST /api/v1/rules/{id}/execute`
Run a single rule on demand against the last `lookback` of telemetry.
@@ -148,7 +158,7 @@ Run a single rule on demand against the last `lookback` of telemetry.
}
```
-### 2.4 `POST /v1/rules/hunt`
+### 2.4 `POST /api/v1/rules/hunt`
Multi-rule, time-bounded threat hunt.
@@ -161,25 +171,25 @@ Multi-rule, time-bounded threat hunt.
}
```
-### 2.5 `PATCH /v1/rules/{id}` / `DELETE /v1/rules/{id}`
+### 2.5 `PATCH /api/v1/rules/{id}` / `DELETE /api/v1/rules/{id}`
Standard CRUD with optimistic concurrency via `If-Match` ETag.
---
-## 3. Detection Proposals (Detection-as-Code) — `/v1/detection-proposals`
+## 3. Detection Proposals (Detection-as-Code) — `/api/v1/detection-proposals`
Service: `services/api`.
The DAC lifecycle manages detection rule proposals from creation through eval-gated promotion into the live rule set. Every proposal carries an eval result from `scripts/run_evals.py`; candidates that regress MITRE accuracy by ≥ 1 pp cannot be promoted.
-### 3.1 `GET /v1/detection-proposals`
+### 3.1 `GET /api/v1/detection-proposals`
| Query param | Description |
|-------------|-------------|
| `status` | `draft` · `in_review` · `approved` · `rejected` · `promoted` |
-### 3.2 `POST /v1/detection-proposals`
+### 3.2 `POST /api/v1/detection-proposals`
```json
{
@@ -190,17 +200,17 @@ The DAC lifecycle manages detection rule proposals from creation through eval-ga
}
```
-### 3.3 `GET /v1/detection-proposals/{id}`
+### 3.3 `GET /api/v1/detection-proposals/{id}`
Returns proposal detail including comments and attached eval results.
-### 3.4 `POST /v1/detection-proposals/{id}/comment`
+### 3.4 `POST /api/v1/detection-proposals/{id}/comment`
```json
{ "body": "Looks good — verified against last 30 days of telemetry." }
```
-### 3.5 `POST /v1/detection-proposals/{id}/eval`
+### 3.5 `POST /api/v1/detection-proposals/{id}/eval`
Attach eval result (metric deltas from `scripts/run_evals.py`).
@@ -213,7 +223,7 @@ Attach eval result (metric deltas from `scripts/run_evals.py`).
}
```
-### 3.6 `POST /v1/detection-proposals/{id}/decide`
+### 3.6 `POST /api/v1/detection-proposals/{id}/decide`
```json
{ "decision": "approve" }
@@ -221,27 +231,27 @@ Attach eval result (metric deltas from `scripts/run_evals.py`).
Valid decisions: `approve`, `reject`.
-### 3.7 `POST /v1/detection-proposals/{id}/promote`
+### 3.7 `POST /api/v1/detection-proposals/{id}/promote`
Promotes an approved proposal into `detection_rules`. Returns the new rule ID.
-### 3.8 `GET /v1/detection-proposals/baseline`
+### 3.8 `GET /api/v1/detection-proposals/baselines`
Current eval baseline metrics used as the promotion gate reference.
-### 3.9 `POST /v1/detection-proposals/baseline`
+### 3.9 `POST /api/v1/detection-proposals/baselines`
Reset eval baseline to the latest harness run (admin-only).
---
-## 4. Federated Search — `/v1/federated`
+## 4. Federated Search — `/api/v1/federated`
Service: `services/api` → `services/connectors`.
Fan out a single query to connected SIEMs. The API translates the query into each target's native dialect (SPL for Splunk, KQL for Sentinel, ES|QL for Elastic).
-### 4.1 `POST /v1/federated/query`
+### 4.1 `POST /api/v1/federated/search`
```json
{
@@ -264,11 +274,13 @@ Fan out a single query to connected SIEMs. The API translates the query into eac
---
-## 5. Threat Intel IOC Search — `/v1/iocs`
+## 5. Threat Intel IOC Search — `/api/v1/iocs`
-Service: `services/threatintel`.
+Service: `services/threatintel` (port 8005). Note the full prefix: the route
+is declared on the app, so it is `/api/v1/iocs/search` on the threat-intel
+service, not on the core API.
-### 5.1 `GET /v1/iocs/search`
+### 5.1 `GET /api/v1/iocs/search`
| Query param | Description |
|-------------|-------------|
@@ -277,44 +289,18 @@ Service: `services/threatintel`.
| `actor` | Filter by named actor |
| `since` | ISO timestamp |
-### 5.2 `POST /v1/iocs/semantic`
-
-Vector similarity search against Qdrant.
-
-```json
-{
- "text": "powershell encoded base64 mshta DownloadString",
- "k": 10,
- "min_score": 0.6
-}
-```
-
-### 5.3 `GET /v1/iocs/{value}`
-
-Resolve a single indicator with all enrichment + actor links.
-
-### 5.4 `GET /v1/feeds/status`
-
-```json
-{
- "feeds": [
- { "name": "mitre-taxii", "last_run": "…", "ioc_count": 12345 },
- { "name": "cisa-kev", "last_run": "…", "ioc_count": 1023 }
- ]
-}
-```
-
-### 5.5 `POST /v1/feeds/{name}/poll`
-
-Trigger an immediate poll (admin-only).
+This is the only IOC route the service exposes. Earlier revisions of this page
+also listed `POST /iocs/semantic`, `GET /iocs/{value}`, `GET /feeds/status` and
+`POST /feeds/{name}/poll`; none of them was ever implemented. IOC records the
+core API stores are at `GET`/`POST /api/v1/threat-intel/iocs`.
---
-## 6. ML Fusion — `/ml`
+## 6. ML Fusion — `/api/v1/fusion`
-Service: `services/fusion`.
+Service: `services/fusion` (port 8003), proxied by the core API.
-### 6.1 `GET /ml/status`
+### 6.1 `GET /api/v1/fusion/ml/status`
```json
{
@@ -331,56 +317,33 @@ Service: `services/fusion`.
}
```
-### 6.2 `POST /ml/feedback`
-
-Submitted by analysts when triaging an alert.
-
-```json
-{
- "alert_id": "…",
- "tenant_id": "…",
- "analyst_id": "alice@corp",
- "is_true_positive": true,
- "assigned_priority": 2,
- "notes": "Confirmed lateral movement"
-}
-```
-
-### 6.3 `POST /ml/retrain`
-
-Force a retrain. Returns the new model metadata.
-
-```json
-{ "status": "scheduled", "job_id": "…" }
-```
+`POST /ml/feedback` and `POST /ml/retrain` exist on the fusion service itself
+(`services/fusion/app/api/router.py`) but are **not** proxied by the core API,
+so they are reachable only from inside the compose network at
+`http://fusion:8003/ml/feedback` and `http://fusion:8003/ml/retrain`.
---
## 7. Vulnerability Match Stream
-Vulnerability matches are surfaced both via Kafka (`vulnerability.matches` topic) and the API:
-
-### 7.1 `GET /v1/vulnerabilities`
-
-Lists recent KEV-correlated matches with host context joined from Neo4j.
-
-| Query param | Description |
-|-------------|-------------|
-| `cve` | Filter by CVE ID |
-| `host_id` | Filter by host |
-| `kev_only` | `true`/`false` (default `true`) |
+Vulnerability matches are surfaced on the Kafka `vulnerability.matches` topic.
+There is no `GET /api/v1/vulnerabilities` route; this page previously claimed
+one. KEV exposure is read through the posture surface
+(`services/api/app/api/v1/endpoints/posture.py`).
---
-## 8. Cases — `/v1/cases`
+## 8. Cases — `/api/v1/cases`
-Unchanged from v1, but now joined with Neo4j attack paths via `GET /v1/cases/{id}/attack-path`.
+Standard CRUD. The attack path for a case is read from the graph surface —
+`GET /api/v1/graph/attack-path/{case_id}` (§1.1) — not from a route under
+`/cases`.
---
## 9. Hunt-as-Code — `/api/v1/hunts`
-Service: `services/agents`.
+Service: `services/api` (`app/api/v1/endpoints/hunts.py`).
YAML hunt definitions live in `hunts/`. Each file declares a hypothesis,
MITRE ATT&CK tags, log sources, indicators, expected outcomes, and an
@@ -399,17 +362,17 @@ Single hunt definition (hypothesis, MITRE tags, indicators, schedule).
Run a hunt on demand. Returns run output including findings.
-### 9.4 `GET /api/v1/hunts/runs`
-
-Recent hunt runs (DB-backed). Query param: `limit` (default 50, max 500).
+### 9.4 `GET /api/v1/hunts/{hunt_id}/runs`
-### 9.5 `GET /api/v1/hunts/findings`
+Recent runs for one hunt (DB-backed). Query param: `limit`.
-Recent findings across all hunts. Query params: `hunt_id`, `status`, `limit`.
+### 9.5 `GET /api/v1/hunts/{hunt_id}/findings`
-### 9.6 `POST /api/v1/hunts/reload`
+Recent findings for one hunt. Query params: `status`, `limit`.
-Reload the corpus from disk and re-sync the catalog table.
+Both are scoped to a single hunt; there are no corpus-wide `/hunts/runs` or
+`/hunts/findings` routes, and no `POST /hunts/reload`. The corpus is loaded at
+startup.
---
@@ -429,15 +392,16 @@ ratios of ≥ 50:1.
Entity risk data is stored in Redis hashes (per entity, namespaced by
tenant) with ZSET-backed top-N sorted queues for O(log N) reads.
-> Entity risk is accessed internally by the fusion engine. The web
-> console reads the queue via the `/entity-risk` endpoints on the
-> API service (see the Docusaurus REST reference for the public surface).
+> Entity risk is accessed internally by the fusion engine. The web console
+> reads the queue through the API's fusion proxy:
+> `GET /api/v1/fusion/entity-risk/queue`, `/entity-risk/stats` and
+> `/entity-risk/{entity_type}/{entity_value}`.
---
## 11. Authentication
-* JWT issued by `POST /v1/auth/login`.
+* JWT issued by `POST /api/v1/auth/login`.
* API keys via `Authorization: ApiKey <key>` header.
* All requests must specify a tenant context — either implicit (from JWT) or explicit (`X-Tenant-Id` header for service-to-service calls).
@@ -453,7 +417,7 @@ All endpoints return RFC 7807 Problem Details:
"title": "Sigma rule failed validation",
"status": 422,
"detail": "Unknown field 'EventID' in selection 'sel_powershell'",
- "instance": "/v1/rules"
+ "instance": "/api/v1/rules"
}
```
@@ -464,8 +428,7 @@ All endpoints return RFC 7807 Problem Details:
| Tier | Requests/min |
|------|--------------|
| Default | 600 |
-| `/v1/rules/hunt` | 30 |
-| `/ml/retrain` | 6 |
+| `/api/v1/rules/hunt` | 30 |
Limits are tenant-scoped and enforced by Redis.
@@ -473,4 +436,5 @@ Limits are tenant-scoped and enforced by Redis.
## 14. Versioning
-The API follows semver via the URL prefix `/v1`. Breaking changes will move to `/v2` and the previous version remains supported for at least 6 months.
+The API follows semver via the URL prefix `/api/v1`. Breaking changes will move
+to `/api/v2` and the previous version remains supported for at least 6 months.
diff --git a/docs/audit/REALITY_REPORT.md b/docs/audit/REALITY_REPORT.md
index 21f25b0ad..53ca35041 100644
--- a/docs/audit/REALITY_REPORT.md
+++ b/docs/audit/REALITY_REPORT.md
@@ -3,6 +3,12 @@
Phase 0 of the world-class program (`AISOC_CURSOR_PROMPT_V2.md`). This document classifies every headline claim in `README.md` against the code that is supposed to back it. It changes no code.
- Repo state audited: `main` @ `982ef2ca`, `VERSION` 7.5.0.
+- **This is a dated Phase 0 snapshot, not a current-state document.** The
+ maintained inventory of what actually works is
+ [`REPOSITORY_REALITY.md`](REPOSITORY_REALITY.md); read that first. Findings
+ below that have since been closed carry an inline note saying so, in the
+ release that closed them. Anything without such a note was still open when
+ last re-read and should be re-verified against the tree before it is quoted.
- Method: source-level reconciliation (read the code, not the docs) across the agent, eval harness, data spine, connectors, SOAR, storage, supply chain, and governance surfaces.
## Status legend
@@ -54,6 +60,10 @@ Phase 0 of the world-class program (`AISOC_CURSOR_PROMPT_V2.md`). This document
## Overclaims (ranked)
1. **"No data exfiltration / runs entirely on your infrastructure."** The default investigation path uses a cloud LLM (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`) and reasons over raw evidence. There is no PII pseudonymization (`services/agents/app/privacy/` does not exist), so usernames, hostnames, internal IPs, file paths, and command lines are sent verbatim to a third-party provider. The claim is only true in the local-model / air-gapped configuration, which is not the default and has no egress-blocked CI proof. Fix in Phase 1.4 + Phase 2.
+ **Partly closed.** `services/agents/app/privacy/` now exists (`redactor.py`,
+ with `services/agents/tests/test_privacy_redactor.py`), and
+ [`docs/trust/data-flows.md`](../trust/data-flows.md) describes the redactor as
+ the shipped default. The egress-blocked CI proof is still outstanding.
2. **"6000+ imported detection rules."** ~5921 of 6113 imported rules live under `_quarantine/` (`enabled: false`) because their upstream query language (SPL / YARA-L / CAR pseudocode) does not execute on the engine. The coverage heatmap (`scripts/build_marketplace.py::coverage_block`) counts MITRE tags on rule metadata, not rules that fire. Fix in Phase 4 Tier 3 + Phase 10.
**Closed in v11.2.0.** Published counts now lead with the executable figure beside the library one (2,603 of 6,991), and 1,770 Sigma rules were translated into the matcher's own language after each was replayed through its real connector and the real engine and watched to fire. The blocker was never the quarantine flag: Windows events nest their payload under `System`/`EventData`, one level below the namespace the matcher reads, so no Windows rule could fire whatever its `enabled:` said.
3. **"Detection-as-Code ... CI rejects any candidate that regresses MITRE accuracy."** True in letter, misleading in spirit: the gate never evaluates the proposed rule (see Circular Gates). Fix in Phase 4.
@@ -64,7 +74,10 @@ Phase 0 of the world-class program (`AISOC_CURSOR_PROMPT_V2.md`). This document
1. **The Kafka spine end-to-end.** No CI proves raw event -> OCSF normalize -> enrich -> fuse -> alert row -> WS frame -> agent -> ledger. `compose-smoke.yml` boots the stack but only probes `/health` + web 200. Everything else in `ci.yml` is offline/mocked. Fix in Phase 3.1.
2. **Prompt-injection defenses.** `services/agents/app/investigator/prompt_sanitizer.py` (envelope wrap + injection redaction) and `services/agents/app/llm/contract.py` (fail-closed input contract) are real and wired in, but `services/agents/tests/test_prompt_sanitizer.py` is not in the agents job's hardcoded file list in `.github/workflows/ci.yml`, so the defense is effectively ungated. Fix in Phase 1.1.
-3. **Cross-tenant isolation outside Postgres.** `services/threatintel/app/storage/qdrant.py` has zero tenant scoping (global collections, no `tenant_id` filter). Neo4j/Redis/ClickHouse/Kafka have no isolation tests. `cross-tenant-rbac.yml` is nightly, Postgres-only, 3 endpoints, and asserts against compiled SQL (no live DB). Fix in Phase 1.3.
+3. **Cross-tenant isolation outside Postgres.** **Closed for Qdrant.**
+ `services/threatintel/app/storage/qdrant.py` now carries
+ `tenant_scope_filter()` and a mandatory-filter contract; public feed intel
+ is global on purpose. When this was written it had no tenant scoping at all. Neo4j/Redis/ClickHouse/Kafka have no isolation tests. `cross-tenant-rbac.yml` is nightly, Postgres-only, 3 endpoints, and asserts against compiled SQL (no live DB). Fix in Phase 1.3.
4. **SOAR rollback + post-action verification.** `rollback()` is real only for the `aws_sg` path in `services/actions/app/executors/network.py`; other vendors return `True` without a reverse call, and the live-actions layer omits rollback entirely. There is no post-action verification that a containment actually took effect. Fix in Phase 9.
5. **Backup/restore.** `backup.sh` / `restore.sh` exist; nothing tests them and no RTO/RPO is published. Fix in Phase 3.3.
6. **Approval SLA timers.** `services/slack-bot/app/services/approval_timeout.py` is in-memory; a restart wipes pending approvals (fail-safe default is reject, but the timer state is lost). Fix in Phase 9.
@@ -78,9 +91,14 @@ Phase 0 of the world-class program (`AISOC_CURSOR_PROMPT_V2.md`). This document
## Internal inconsistencies found (fix in Phase 2 / Phase 12)
-- **License disagreement.** `README.md` L229 and `LICENSE` say MIT; `.github/LICENSES.md` L3 says "AiSOC ships under Apache-2.0" and marks native detections Apache-2.0.
+- ~~**License disagreement.** `README.md` L229 and `LICENSE` say MIT; `.github/LICENSES.md` L3 says "AiSOC ships under Apache-2.0" and marks native detections Apache-2.0.~~
+ **Closed.** `.github/LICENSES.md` now says MIT throughout, matching `LICENSE`
+ and the README.
- **Referenced-but-missing CI guard.** `docs/decisions/0002-compliance-claims.md` asserts a CI check at `scripts/audit_compliance_claims.py` exists and fails the build on unqualified framework names. That script does not exist and no workflow references it.
-- **Stale internal reference.** `AGENTS.md` and `packages/aisoc-sandbox/src/aisoc_sandbox/investigation.py` reference `services/.../llm_safety.py`; the real file is `services/agents/app/investigator/prompt_sanitizer.py`.
+- ~~**Stale internal reference.** `AGENTS.md` and `packages/aisoc-sandbox/src/aisoc_sandbox/investigation.py` reference `services/.../llm_safety.py`; the real file is `services/agents/app/investigator/prompt_sanitizer.py`.~~
+ **Closed.** `services/api/app/services/llm_safety.py` was subsequently written
+ and is on disk, imported by seven endpoint modules. The reference is no longer
+ stale.
- **AGENTS.md eval claim is wrong.** It states only `mitre_accuracy` measures the live agent; per the code, `mitre_accuracy` is an offline keyword extractor and no PR-gated suite runs the live agent.
## Prompt premises that are already satisfied (build the delta, do not rebuild)
diff --git a/docs/community-feedback/2026-05-12/README.md b/docs/community-feedback/2026-05-12/README.md
index d49e048fb..4ddc65f11 100644
--- a/docs/community-feedback/2026-05-12/README.md
+++ b/docs/community-feedback/2026-05-12/README.md
@@ -1,10 +1,17 @@
# AiSOC — Community-Feedback-Driven Roadmap (2026-05-12)
-This directory captures the **active** planning artifacts for AiSOC, derived
-from a community-feedback synthesis pass on 2026-05-12. It supersedes the
-"deferred beyond v7" sections of [`/ROADMAP.md`](../../../ROADMAP.md) for
-day-to-day prioritization while leaving the major-version history intact for
-traceability.
+> **Status: a dated snapshot, not the current plan.** These artefacts were
+> produced by a community-feedback synthesis pass on **2026-05-12**, against
+> the v7.1 line. The tree has since moved several majors past that. They are
+> kept as received — `scripts/check_deferral_tracker.py` excludes this
+> directory for exactly that reason — so the `F`-ID trail from feedback to
+> shipped work survives. For what is planned now, read
+> [`/ROADMAP.md`](../../../ROADMAP.md); for what actually works, read
+> [`/docs/audit/REPOSITORY_REALITY.md`](../../audit/REPOSITORY_REALITY.md).
+
+This directory captures the planning artifacts derived from that synthesis
+pass. No second pass has been run, so there is no later dated directory
+beside it.
## Contents
@@ -19,17 +26,19 @@ traceability.
- **`F-IDs` are stable.** Every issue, PR, and commit that addresses a feedback
theme should reference the matching `F` ID in its body so the trail back to
the originating feedback survives refactors.
-- **The "Now" bucket is the work-in-flight queue.** Items here are expected to
- ship within 30 days of the doc's date and are tracked in
- [`/PROGRESS.md`](../../../PROGRESS.md) under the active version line
- (currently v7.1.x).
+- **The "Now" bucket was the work-in-flight queue as of 2026-05-12**, scoped
+ to the 30 days after that date on the v7.1 line. It is history now. This
+ README previously pointed at a root `PROGRESS.md` for its status; that file
+ is gitignored and has never been committed, so the pointer resolved to
+ nothing. Release-by-release status lives in
+ [`/CHANGELOG.md`](../../../CHANGELOG.md).
- **"Next" and "Later" are intent, not commitment.** They get re-prioritized
on the next synthesis pass.
-- **Path & module references in the issue drafts are authoritative.** Where
- the draft conflicts with reality on `main`, the draft wins (file the
- reconciliation as a Stage-0 task before starting the work). The drafts in
- this directory have already been path-corrected against the v7.1.0
- baseline.
+- **Path & module references in the issue drafts are *not* authoritative.**
+ They were path-corrected against the v7.1.0 baseline and nothing since.
+ Where a draft conflicts with `main`, **`main` wins** — this README used to
+ say the opposite, which on a v12 tree would send a contributor to rename
+ working code to match a snapshot from eight majors ago.
## Reconciliation notes (carried forward)
@@ -47,13 +56,14 @@ therefore built fresh on `main`, not on top of those primitives.
2. Open a GitHub issue using the draft body (or reference the file if the
draft is faithful enough to skip re-typing). Apply the `area:subarea`
labels listed in the draft.
-3. Branch off `main`, implement against the acceptance criteria, satisfy the
+3. Re-verify every path the draft names against `main` before you start.
+4. Branch off `main`, implement against the acceptance criteria, satisfy the
eval gates listed in [`/AGENTS.md`](../../../AGENTS.md) when relevant.
-4. PR title format: `[F<id>] <area>: <change>` so the feedback trail is
+5. PR title format: `[F<id>] <area>: <change>` so the feedback trail is
visible in `git log`.
-5. Update `PROGRESS.md` checkboxes as items land.
## Next synthesis pass
-Plan: re-run the synthesis on a 30-day cadence. The next dated directory will
-live alongside this one (e.g. `docs/community-feedback/2026-06-12/`).
+The 2026-05-12 pass planned a 30-day cadence. It was not repeated, and
+`2026-05-12/` remains the only dated directory here. A future pass would land
+beside it under its own date.
diff --git a/docs/design/landing-page-brief.md b/docs/design/landing-page-brief.md
index 009d10858..fb1a80419 100644
--- a/docs/design/landing-page-brief.md
+++ b/docs/design/landing-page-brief.md
@@ -189,9 +189,9 @@ Ranked. Five total. Each one cites the shipped feature behind it.
`.github/workflows/wet-eval.yml` once it runs (T5.5).
- **Persona.** Detection engineer primary, CISO secondary.
-### V4 — Connect 69 sources in three clicks, MIT-licensed plugin SDK in three languages
+### V4 — Connect 84 sources in three clicks, MIT-licensed plugin SDK in three languages
-- **Proof.** `services/connectors/app/connectors/__init__.py` registers 69
+- **Proof.** `services/connectors/app/connectors/__init__.py` registers 84
connector classes spanning EDR / SIEM / cloud / IAM / SaaS / VCS /
network. Each one renders a schema-driven form, encrypts secrets via
`CredentialVault`, and starts polling on a per-instance schedule. The
@@ -769,8 +769,8 @@ that need extra care:
- The four-agent diagram in §6.e must remain legible at 360 px. Step
labels collapse to two-letter glyphs (D · T · H · R) below 640 px.
-- The connector grid in §6.i must not flash a single-column list of 69
- logos on phone; show 18 logos plus a "See all 69" link.
+- The connector grid in §6.i must not flash a single-column list of 84
+ logos on phone; show 18 logos plus a "See all 84" link.
---
diff --git a/docs/design/landing-page-component-recipes.md b/docs/design/landing-page-component-recipes.md
index 6e7e3d1c1..8c47130d4 100644
--- a/docs/design/landing-page-component-recipes.md
+++ b/docs/design/landing-page-component-recipes.md
@@ -3,7 +3,7 @@
> Companion to `landing-page-brief.md` §6 and
> `landing-page-design-tokens.md`. One recipe per IA section, in the
> same order with the same ID. The frontend engineer (Subagent F) reads
-> this while implementing `apps/web/src/app/(marketing)/page.tsx`.
+> this while implementing the landing page at `apps/web/src/app/page.tsx`.
>
> **Library catalog:**
> - Aceternity UI — `https://ui.aceternity.com/components`
@@ -85,7 +85,7 @@
- MagicUI **Border Beam** — frame. `duration={10}`, `colorFrom="#3b82f6"`, `colorTo="#8b5cf6"`, `borderWidth={1.5}`.
- Aceternity **Container Scroll Animation** (`/components/container-scroll-animation`) — *optional*, tilts demo on scroll. `titleComponent={null}`. Skip first ship if it bloats bundle.
- Aceternity **Spotlight** — soft glow. Reuse hero with `fill="var(--color-brand-700)"`.
-- **Custom:** 90-second muted video at `apps/web/public/demo/inc-rt-001.mp4` + Vimeo fallback. Caption overlay (`INC-RT-001 · LockBit 3.0 · step 14 of 32`) is an absolutely-positioned `<div>`. Lazy-load via `IntersectionObserver` once 30% in viewport. Poster at `apps/web/public/demo/inc-rt-001-poster.avif`.
+- **Custom:** muted walkthrough video at `apps/web/public/demo/demo.mp4` + fallback. Caption overlay is an absolutely-positioned `<div>`. Lazy-load via `IntersectionObserver` once 30% in viewport. Poster at `apps/web/public/demo/demo-poster.png`. (This bullet previously named `inc-rt-001.mp4`/`.avif`, which were never committed.)
- **Anatomy:** `Demo` → `DemoHeading`, `DemoFrame` (Border Beam wraps `<video>`), `DemoCaptionOverlay`, `DemoCta`.
- **States:** Autoplay muted, loop, inline. Hover → caption + scrub controls. <768 controls always visible. Reduced-motion → freezes on poster, "Play replay" button centred.
- **Failure:** `<video>` fails → poster + "Watch on Vimeo" link. Border Beam fails → static `brand-500/30` border. Vimeo blocked → CTA changes to "Run this yourself."
@@ -201,7 +201,7 @@ Three sub-section bands with anchor IDs `features-detect`,
## §15 — `faq`
- **Primitives:**
- - **Radix Accordion** (existing at `apps/web/src/components/ui/accordion.tsx`) — `type="multiple"`, `defaultValue={['faq-q1','faq-q2']}`.
+ - **Radix Accordion** (to add — there is no `Accordion` component in `apps/web/src` today) — `type="multiple"`, `defaultValue={['faq-q1','faq-q2']}`.
- Aceternity **Tracing Beam** (`/components/tracing-beam`) — *optional* left-edge beam. Skip first ship.
- **Custom:** Each question carries `id={faq-q{n}}` for analytics. Answers may include `<code>`; respect mono token.
- **Anatomy:** `Faq` → `FaqHeading`, `FaqAccordion` (Radix), each → `FaqQuestion`, `FaqAnswer`.
diff --git a/docs/design/landing-page-design-tokens.md b/docs/design/landing-page-design-tokens.md
index 383d9bf30..983780e36 100644
--- a/docs/design/landing-page-design-tokens.md
+++ b/docs/design/landing-page-design-tokens.md
@@ -303,7 +303,8 @@ Not allowed inside any landing component:
3. Inline `rgba()` shadows — use `landing.shadow.*` (§6).
4. Inline `cubic-bezier()` — use `landing.ease.*` (§7).
5. Tailwind arbitrary values (`text-[14.5px]`, `bg-[#123456]`) outside
- the OG image generator at `apps/web/src/app/og/route.tsx` (Satori
+ the OG image generator (to add — the only Satori route in the tree today
+ is `apps/web/src/app/r/[slug]/opengraph-image.tsx`) (Satori
demands literal hex).
6. `font-bold` on body copy — body is `400`, headings `600`/`700`.
7. The word `severity` outside product screenshots.
diff --git a/docs/operations/live-demo-runbook.md b/docs/operations/live-demo-runbook.md
index cc04ea9e4..b6fca4f66 100644
--- a/docs/operations/live-demo-runbook.md
+++ b/docs/operations/live-demo-runbook.md
@@ -8,7 +8,7 @@ AiSOC instance running on Fly.io, fronted by a Cloudflare Tunnel. It is
**Always-on fallback:** open the repo in
[GitHub Codespaces](https://codespaces.new/beenuar/AiSOC?quickstart=1).
-The devcontainer at [`.devcontainer/devcontainer.json`](.devcontainer/devcontainer.json)
+The devcontainer at [`.devcontainer/devcontainer.json`](../../.devcontainer/devcontainer.json)
will bring up Node 22, Python 3.11, Go 1.26, Docker-in-Docker, and the
GitHub CLI for you. Then:
@@ -76,7 +76,7 @@ cloudflared tunnel info tryaisoc
cloudflared tunnel route dns tryaisoc tryaisoc.com
```
-The deploy script ([`infra/fly/fly-demo-deploy.sh`](infra/fly/fly-demo-deploy.sh))
+The deploy script ([`infra/fly/fly-demo-deploy.sh`](../../infra/fly/fly-demo-deploy.sh))
is idempotent — re-running is safe. It runs migrations and the demo
seed (`python -m app.scripts.seed_demo`) as the release_command, so
the `INC-RT-001` LockBit case is always present after a successful
@@ -84,7 +84,7 @@ deploy.
## After the deploy: customer-journey checklist
-The user has repeatedly flagged broken items post-deploy, so after every
+Broken items are repeatedly found only after a deploy, so after every
deploy to `tryaisoc.com`, walk the journey:
- [ ] Landing page (`/`) renders without console errors.
@@ -108,5 +108,5 @@ and should be fixed before declaring the deploy done.
If demand for an always-on hosted demo gets significant enough to
warrant funding it, the funding model lives in
-[`.github/FUNDING.yml`](.github/FUNDING.yml). Until then, this file is
+[`.github/FUNDING.yml`](../../.github/FUNDING.yml). Until then, this file is
the operations runbook.
diff --git a/docs/operations/multi-region.md b/docs/operations/multi-region.md
index 9bdf98f66..40d35ae1a 100644
--- a/docs/operations/multi-region.md
+++ b/docs/operations/multi-region.md
@@ -1,7 +1,8 @@
# AiSOC Multi-Region Operations
> **Audience**: Platform / SRE teams running AiSOC in production across multiple cloud regions.
-> **Last updated**: auto-generated (see `scripts/generate_runbook.py`)
+> **Last updated**: maintained by hand. `scripts/generate_runbook.py` exists but
+> needs a live OTel endpoint, so nothing in CI regenerates this page.
---
@@ -190,7 +191,7 @@ AiSOC emits **OpenTelemetry** traces, metrics, and structured logs to a configur
| `api` | `http_request_duration_p99` | < 500 ms |
| `api` | `http_error_rate` | < 0.5 % |
| `ingest` | `event_ingestion_lag_p99` | < 2 s |
-| `alert-fusion` | `alert_fusion_latency_p99` | < 5 s |
+| `alert-fusion` (the Helm service key for `services/fusion`) | `alert_fusion_latency_p99` | < 5 s |
| `agents` | `agent_run_duration_p95` | < 30 s |
| All | Pod ready ratio | > 99 % |
@@ -240,21 +241,31 @@ RB-NNN-<slug>.md
### Available runbooks
-| ID | Slug | Trigger |
-|---|---|---|
-| RB-001 | `api-high-latency` | `http_request_duration_p99 > 500ms` |
-| RB-002 | `postgres-replica-lag` | Replication lag > 30 s |
-| RB-003 | `region-failover` | Region health check failure |
-| RB-004 | `ingest-pipeline-stall` | Ingest lag > 30 s |
-| RB-005 | `agent-runner-oom` | OOMKilled in `agents` pods |
-| RB-006 | `cert-expiry` | TLS cert expires in < 14 days |
+The committed runbooks live in [`docs/runbooks/`](../runbooks/) and are indexed
+by [`docs/runbooks/README.md`](../runbooks/README.md), which maps each one to
+the Prometheus alert that fires it in `infra/docker/alerts/aisoc.rules.yml`:
+
+| File | Trigger |
+|---|---|
+| [`http-latency-high.md`](../runbooks/http-latency-high.md) | p99 request latency above the SLO |
+| [`http-5xx-high.md`](../runbooks/http-5xx-high.md) | 5xx rate above the SLO |
+| [`database-incident.md`](../runbooks/database-incident.md) | Postgres unavailable or replicating badly |
+| [`kafka-consumer-lag.md`](../runbooks/kafka-consumer-lag.md) | Consumer lag above threshold |
+| [`detection-pipeline-stalled.md`](../runbooks/detection-pipeline-stalled.md) | Events stop becoming alerts |
+| [`service-down.md`](../runbooks/service-down.md) | A service fails its health check |
+| [`action-executor-failures.md`](../runbooks/action-executor-failures.md) | Response actions failing |
+
+An earlier revision of this page listed six `RB-00N` runbooks under
+`docs/operations/runbooks/`. That directory has never existed and no `RB-*`
+file is tracked anywhere; the table above is the real set.
-To regenerate all runbooks:
+`scripts/generate_runbook.py` can draft a runbook from live traces, but it
+needs a reachable OTel endpoint and is not wired into CI:
```bash
OTEL_ENDPOINT=http://tempo:4317 \
python scripts/generate_runbook.py \
- --output docs/operations/runbooks/ \
+ --output docs/runbooks/ \
--lookback-hours 168 # 1 week of traces
```
diff --git a/docs/press/README.md b/docs/press/README.md
index eb632c42d..c8766dd05 100644
--- a/docs/press/README.md
+++ b/docs/press/README.md
@@ -19,14 +19,17 @@ accurately. Please keep quotes and stats consistent with the
> Unlike closed-source AI SOC products, the agent and the substrate are open:
> every prompt, tool call, piece of evidence, and rationale is stored in an
> Investigation Ledger and replayable, and a public eval harness gates every
-> change. You can try it in 60 seconds with `npx aisoc triage --demo` — no
+> change. The wedge CLI is `npx aisoc triage --demo` — but `aisoc` is ready and
+> unpublished, so that command does not resolve yet; run it from a clone with
+> `pnpm --filter aisoc build && node packages/aisoc-lite/dist/cli.js triage --demo`. No
> account, no Docker, no API key — or self-host the full stack so no data leaves
> your perimeter.
## Fast facts
- **License:** MIT
-- **Try it:** `npx aisoc triage --demo` (deterministic, offline, <1s)
+- **Try it:** `npx aisoc triage --demo` (deterministic, offline, <1s) — **not
+ yet on npm**; from a clone, `pnpm --filter aisoc build && node packages/aisoc-lite/dist/cli.js triage --demo`
- **Live demo:** https://tryaisoc.com
- **Source:** https://github.com/beenuar/AiSOC
- **Orchestrator:** ~600-line LangGraph in `services/agents/`
diff --git a/docs/roadmap/v8-progress.md b/docs/roadmap/v8-progress.md
index 99de03295..546dbfb94 100644
--- a/docs/roadmap/v8-progress.md
+++ b/docs/roadmap/v8-progress.md
@@ -1,7 +1,7 @@
# AiSOC v8 — progress tracker
-**Last updated:** 2026-09-28
-**Current release:** `v12.2.0` (2026-09-28) · **Next:** unscheduled.
+**Last updated:** 2026-09-29
+**Current release:** `v12.3.2` (2026-09-29) · **Next:** unscheduled.
Packaging is no longer named against a version: it slipped v8.0 to v8.1 to
v8.2 for the same reason each time, and the blocker is registry credentials
rather than code. Each major since v10.0 has been a major for the same kind of
@@ -143,8 +143,8 @@ script.
| README rewritten for adoption | done |
| Consolidated `Makefile` | done |
| The three packages that could not be built at the v8.1.0 tag | done |
-| CrowdStrike has no normalizer profile and uses the generic one | open — recorded in the reality audit |
-| OpenSearch is started by `full` and read by nothing | open — recorded, not drawn into a diagram |
+| CrowdStrike has no normalizer profile and uses the generic one | withdrawn — the wrong diagnosis. The connector does take the canonical path; the real faults were an unread `behaviors[].user_name` and a canonical field map that recognised only `actor`. Both fixed in v9.0 — see `docs/audit/REPOSITORY_REALITY.md` |
+| OpenSearch is started by `full` and read by nothing | withdrawn — checked against `services/api`, which holds no OpenSearch client, and never against `services/threatintel`, which uses one unconditionally. Retracted in `docs/audit/REPOSITORY_REALITY.md` under "Correction (v9.0)" |
---
diff --git a/docs/runbooks/HARDENING.md b/docs/runbooks/HARDENING.md
index 4465e7189..e43fc611a 100644
--- a/docs/runbooks/HARDENING.md
+++ b/docs/runbooks/HARDENING.md
@@ -2,7 +2,7 @@
This runbook is the operator's checklist for taking an AiSOC deployment from "it boots" to "I would put real customer telemetry through it." It assumes you are running the platform from official images on Kubernetes via the Helm chart in [`infra/helm/aisoc/`](../../infra/helm/aisoc/), or via the production Compose profile.
-If you only need a quick local demo, use [`pnpm aisoc:demo`](../../README.md#quickstart) instead — that flow intentionally skips most of the controls below.
+If you only need a quick local demo, use [`make up && make demo`](../../README.md#quick-start) instead — that flow intentionally skips most of the controls below.
---
@@ -27,7 +27,7 @@ If you only need a quick local demo, use [`pnpm aisoc:demo`](../../README.md#qui
- the public API on `/api/*`,
- the realtime websocket on `/ws/*`,
- the MCP endpoint on `/mcp/*` (only if you actually expose it).
- Everything else (Postgres, NATS, OpenSearch, Redis, the eval harness) must stay on the cluster network.
+ Everything else (Postgres, Kafka, OpenSearch, Redis, ClickHouse, Neo4j, Qdrant, the eval harness) must stay on the cluster network.
- [ ] Apply Kubernetes `NetworkPolicy` resources from the chart so each service only reaches its required dependencies.
- [ ] Set sane CORS defaults: explicit allow-list of origins, no wildcard `*` once you have a real frontend hostname.
- [ ] Enable rate limiting middleware (see [`services/api/app/middleware/`](../../services/api/app/middleware/)) and tune the per-token / per-API-key limits to your load profile.
@@ -54,12 +54,18 @@ If you only need a quick local demo, use [`pnpm aisoc:demo`](../../README.md#qui
## 5. Observability and audit
- [ ] Forward audit logs to an immutable sink (S3 Object Lock, GCS Bucket Lock, or a SIEM with WORM storage).
-- [ ] Verify the Investigation Ledger periodically:
+- [ ] Read back the Investigation Ledger for a recent run and confirm the
+ decision record is intact. There is **no** `/ledger/verify` route — an
+ earlier revision of this runbook published one and it never existed. The
+ ledger surface is `GET /api/v1/ledger/{run_id}/published` and the replay
+ routes beside it (`services/api/app/api/v1/endpoints/replay.py`):
```bash
- curl -fsSL "$AISOC_API/api/v1/ledger/verify?case_id=$CASE_ID" \
+ curl -fsSL "$AISOC_API/api/v1/ledger/$RUN_ID/published" \
-H "Authorization: Bearer $TOKEN"
```
- Add this to a synthetic check that pages on a non-200 response.
+ Add this to a synthetic check that pages on a non-200 response. The
+ ledger/replay contract itself is gated in CI by
+ `scripts/check_ledger_replay_contract.py`.
- [ ] Wire OpenTelemetry traces from all services to your collector and keep at least 7 days of trace data for incident response.
- [ ] Send platform metrics (`/metrics`) to Prometheus or a managed equivalent. Alert on saturation, p99 latency, and 5xx rates per service.
diff --git a/docs/runbooks/LOCAL_DEVELOPMENT.md b/docs/runbooks/LOCAL_DEVELOPMENT.md
index ad121ec20..7515db02c 100644
--- a/docs/runbooks/LOCAL_DEVELOPMENT.md
+++ b/docs/runbooks/LOCAL_DEVELOPMENT.md
@@ -12,12 +12,18 @@ This runbook walks you from a freshly cloned repository to a running AiSOC stack
| Docker Compose | v2.20 | Multi-service orchestration |
| Node.js | 20.x | Frontend (`apps/web`) and `services/realtime` |
| pnpm | 8.x | Workspace package manager |
-| Go | 1.21 | `services/ingest`, `services/enrichment` |
+| Go | 1.26 | `services/ingest`, `services/enrichment` (both `go.mod` files declare `go 1.26`) |
| Python | 3.11 | All FastAPI services and the agent runner |
| Poetry | 1.8 | Python service dependency management |
| `gh` CLI | 2.40+ | Optional, used by some helper scripts |
-Memory budget: the full stack uses **~6 GB RAM** with all services running. If you only need a subset, use the targeted commands in §4.
+Memory budget: the CORE profile (`make up`) needs **8 GB memory and 20 GB free
+disk in the Docker VM**; the `full` profile (`make up-full`) needs roughly
+12 GB. The per-profile service counts and memory figures are published in the
+deployment-profile table in [`README.md`](../../README.md), which
+`scripts/check_profile_service_counts.py` gates against the compose files —
+read them there rather than restating them here. If you only need a subset,
+use the targeted commands in §4.
---
@@ -359,4 +365,5 @@ docker system prune -f # reclaim build cache
* [System Design](../architecture/SYSTEM_DESIGN.md)
* [API Reference](../api/API_REFERENCE.md)
-* [PROGRESS.md](../../PROGRESS.md)
+* [What actually works](../audit/REPOSITORY_REALITY.md)
+* [CHANGELOG.md](../../CHANGELOG.md)
diff --git a/examples/README.md b/examples/README.md
index a7b6b648e..04b950ecc 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -3,10 +3,13 @@
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).
+1. **Real ingest** — `aisoc submit examples/alerts/<name>.json`
+ posts the events to the running stack (started by `make up`). The CLI is
+ `packages/aisoc-cli`; install it with `pip install -e packages/aisoc-cli`
+ from the repo root. It POSTs to `/api/v1/alerts/submit`, which writes the
+ alert row directly, so the result lands in the
+ [Investigation Rail](../apps/docs/docs/console/investigation-rail.md)
+ within a second without waiting on the Kafka pipeline.
2. **Offline simulator** — `aisoc-sandbox demo --scenario <name>` runs
the same scenario through a zero-dependency in-memory simulator.
diff --git a/examples/aws-credential-exfil.md b/examples/aws-credential-exfil.md
index 7566410e1..76ee766ed 100644
--- a/examples/aws-credential-exfil.md
+++ b/examples/aws-credential-exfil.md
@@ -17,8 +17,8 @@
# Offline simulator:
aisoc-sandbox demo --scenario aws-credential-exfil
-# Real stack:
-pnpm aisoc:submit examples/alerts/aws-credential-exfil.json
+# Real stack (after `make up`, with `pip install -e packages/aisoc-cli`):
+aisoc submit examples/alerts/aws-credential-exfil.json
```
## What the agent does, step by step
diff --git a/examples/github-token-theft.md b/examples/github-token-theft.md
index df77193e6..4f21a5c20 100644
--- a/examples/github-token-theft.md
+++ b/examples/github-token-theft.md
@@ -17,8 +17,8 @@
# Offline simulator:
aisoc-sandbox demo --scenario github-token-theft
-# Real stack:
-pnpm aisoc:submit examples/alerts/github-token-theft.json
+# Real stack (after `make up`, with `pip install -e packages/aisoc-cli`):
+aisoc submit examples/alerts/github-token-theft.json
```
## What the agent does, step by step
diff --git a/examples/kubernetes-privesc.md b/examples/kubernetes-privesc.md
index ecee6f5ba..94b7a47c8 100644
--- a/examples/kubernetes-privesc.md
+++ b/examples/kubernetes-privesc.md
@@ -17,8 +17,8 @@
# Offline simulator:
aisoc-sandbox demo --scenario kubernetes-privesc
-# Real stack:
-pnpm aisoc:submit examples/alerts/kubernetes-privesc.json
+# Real stack (after `make up`, with `pip install -e packages/aisoc-cli`):
+aisoc submit examples/alerts/kubernetes-privesc.json
```
## What the agent does, step by step
diff --git a/examples/lateral-movement.md b/examples/lateral-movement.md
index 234c43ccb..efe548583 100644
--- a/examples/lateral-movement.md
+++ b/examples/lateral-movement.md
@@ -16,21 +16,22 @@
# 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
+# Real stack (after `make up`, with `pip install -e packages/aisoc-cli`):
+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
+Matches the two Okta `user.session.start` events against the executable
+detection corpus (2,603 rules as of this writing — `docs/detections/truth-table.md`
+carries the generated count). 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 `rules.match({"technique_set": ["T1078", "T1078.004"]})`
>
> would-call `fusion.score({"window_minutes": 15})`
diff --git a/examples/phishing-payload.md b/examples/phishing-payload.md
index 0122e4929..1d2669c95 100644
--- a/examples/phishing-payload.md
+++ b/examples/phishing-payload.md
@@ -18,8 +18,8 @@
# Offline simulator:
aisoc-sandbox demo --scenario phishing-payload
-# Real stack:
-pnpm aisoc:submit examples/alerts/phishing-payload.json
+# Real stack (after `make up`, with `pip install -e packages/aisoc-cli`):
+aisoc submit examples/alerts/phishing-payload.json
```
## What the agent does, step by step
diff --git a/infra/fly/managed/README.md b/infra/fly/managed/README.md
index 8d795eba7..089ff28e1 100644
--- a/infra/fly/managed/README.md
+++ b/infra/fly/managed/README.md
@@ -1,15 +1,24 @@
# AiSOC Managed-Mode Deployment (Fly.io)
+> ## Status: nothing here is deployed
+>
+> No managed tenant is running on Fly.io. The Fly organisation has overdue
+> invoices and every app was reclaimed for non-payment —
+> [`../README.md`](../README.md) carries the measured `dig`/`curl` output.
+> `tenants/` holds only `_example.yaml`. Read this directory as the
+> provisioning *design* and the scripts that implement it, not as a
+> description of a live estate.
+
> **Phase 4.2 / T6.1 completion** — the paved-path provisioning surface for
> single-tenant AiSOC stacks on Fly.io. Each customer gets a dedicated set of
> Fly apps + a managed Postgres cluster; isolation lives at the infra layer,
> not just at the application's row-level-security boundary.
-This directory is parallel to `infra/fly/` (which hosts the public demo at
-`tryaisoc.com`). The managed-mode pattern uses the **same images and the same
-fly.toml shape** as the demo — the difference is that every Fly app name and
-hostname is parameterised on a per-customer slug, so we can run N customers
-in the same Fly org without colliding.
+This directory is parallel to `infra/fly/`, which held the public demo at
+`tryaisoc.com` before the apps were reclaimed. The managed-mode pattern uses
+the **same images and the same fly.toml shape** as that demo — the difference
+is that every Fly app name and hostname is parameterised on a per-customer
+slug, so N customers can run in the same Fly org without colliding.
## Why a separate `infra/fly/managed/` directory
diff --git a/infra/helm/README.md b/infra/helm/README.md
index ddaa1519d..9b728c997 100644
--- a/infra/helm/README.md
+++ b/infra/helm/README.md
@@ -10,8 +10,8 @@ infra/helm/
│ ├── Chart.yaml # appVersion tracks the AiSOC release
│ ├── values.yaml # All knobs live here
│ ├── templates/ # Service deployments, HPA, PDB, ingress, etc.
-│ └── charts/ # Reserved for vendored sub-charts (currently empty)
-└── charts/ # Reserved for additional umbrella charts (currently empty)
+│ └── charts/ # Vendored sub-charts (postgresql, redis)
+
```
## What it deploys
@@ -26,6 +26,8 @@ shared `Ingress`. The default `services` map covers:
- `agents` — Python AI agents (`ghcr.io/beenuar/aisoc-agents`)
- `web` — Next.js UI (`ghcr.io/beenuar/aisoc-web`)
- `realtime` — WebSocket service (`ghcr.io/beenuar/aisoc-realtime`)
+- `alert-fusion` — correlation and alert promotion (`ghcr.io/beenuar/aisoc-fusion`;
+ the chart's service key is `alert-fusion`, the source tree is `services/fusion`)
Three feature services have their own templates rather than the generic
deployment because their pod specs differ:
diff --git a/infra/render/README.md b/infra/render/README.md
index 322fc98d2..722b54056 100644
--- a/infra/render/README.md
+++ b/infra/render/README.md
@@ -99,9 +99,9 @@ machine. Render doesn't have native cron, so the options are:
1. **Render Cron Job service** (~$1/mo) — add a 7th service of type `cron`
to `render.yaml` that runs the seed script on a schedule. Skipped from
the Blueprint by default to keep the cost story simple.
-2. **GitHub Actions workflow** — `.github/workflows/render-demo-reset.yml`
- that hits the deployed api on a schedule. Free, but tied to your GH Actions
- minutes budget.
+2. **GitHub Actions workflow** — add a scheduled workflow of your own that
+ hits the deployed api. Free, but tied to your GH Actions minutes budget.
+ There is no such workflow in this repository today.
3. **Skip it** — for a personal evaluation deploy, the demo data will drift
over time but won't break.
diff --git a/infra/terraform/README.md b/infra/terraform/README.md
index 6197d2eb9..a53e2b36d 100644
--- a/infra/terraform/README.md
+++ b/infra/terraform/README.md
@@ -14,17 +14,13 @@ infra/terraform/
├── rds/ # PostgreSQL RDS
├── elasticache/ # Redis (sharded)
├── kafka/ # MSK
- ├── opensearch/ # OpenSearch (optional)
- ├── clickhouse/ # Self-managed ClickHouse on EC2 (optional)
- ├── databases/ # Helper module that wires DSNs into k8s secrets
- ├── kubernetes/ # In-cluster bootstrap (CRDs, namespaces, addons)
- ├── network/ # Extra security groups + private endpoints
- └── vault/ # HashiCorp Vault (optional)
+ └── osquery-tls/ # osquery TLS enrollment endpoint
```
-`main.tf` deploys the **core** stack: `vpc`, `eks`, `rds`, `elasticache`,
-`kafka`. The other modules under `modules/` are optional add-ons — wire them
-in by extending `main.tf` if you need OpenSearch, ClickHouse, or Vault.
+`main.tf` instantiates all six: `vpc`, `eks`, `rds`, `elasticache`, `kafka`
+and `osquery_tls`. There are no other modules — ClickHouse, Neo4j, Qdrant
+and OpenSearch are not provisioned by this stack and would need modules
+written for them.
## What you get
diff --git a/infra/terraform/azure/README.md b/infra/terraform/azure/README.md
index 2450bb09f..7d4337e19 100644
--- a/infra/terraform/azure/README.md
+++ b/infra/terraform/azure/README.md
@@ -156,7 +156,7 @@ For the cheapest sandbox set `postgres_sku = "B_Standard_B1ms"` and
This is the **skeleton**, not the full migration. Known gaps:
- **No long-running services.** `services/agents`, `services/realtime`,
- `services/connectors`, `services/alert-fusion`, `services/threatintel`, and
+ `services/connectors`, `services/fusion`, `services/threatintel`, and
`services/fusion` need always-on compute. Run them as dedicated Container
Apps with `min_replicas > 0` (KEDA can still scale on queue depth) or move
them to AKS sharing this VNet, Postgres, and Redis.
diff --git a/infra/terraform/gcp/README.md b/infra/terraform/gcp/README.md
index d328f9df3..2f0d1be7f 100644
--- a/infra/terraform/gcp/README.md
+++ b/infra/terraform/gcp/README.md
@@ -150,7 +150,7 @@ cheaper sandbox; the smallest sensible production is `db-custom-2-7680` +
This is the **skeleton**, not the full migration. Known gaps:
- **No long-running services.** `services/agents`, `services/realtime`,
- `services/connectors`, `services/alert-fusion`, `services/threatintel`, and
+ `services/connectors`, `services/fusion`, `services/threatintel`, and
`services/fusion` need persistent compute. Cloud Run v2 *does* support sidecar
workloads up to 60 minutes per request, but the websocket fan-out and the
APScheduler-driven connector polling don't fit cleanly. The recommended
diff --git a/marketing/launch/blog-outlines.md b/marketing/launch/blog-outlines.md
index f7535f92e..8097c59a6 100644
--- a/marketing/launch/blog-outlines.md
+++ b/marketing/launch/blog-outlines.md
@@ -22,7 +22,10 @@ run. Keep them engineering-first; the CTA is "run this", not "book a demo".
(public IOCs, ATT&CK techniques) and why.
- The immutability guarantee (DB trigger) and the non-RLS public read.
- The OG image pipeline for unfurls.
-- **Run it:** publish a demo run, open `tryaisoc.com/r/demo-lockbit`.
+- **Run it:** publish a demo run and open `/r/demo-lockbit` **on your own
+ deployment** — replays are served by the instance that produced them, so on a
+ local stack that is `http://localhost:3000/r/demo-lockbit`. There is no hosted
+ public instance, so a `tryaisoc.com/r/demo-lockbit` link in the copy would 404.
## 3. "Grading your ATT&CK coverage in the browser" (W2 — the free tools)
@@ -30,7 +33,9 @@ run. Keep them engineering-first; the CTA is "run this", not "book a demo".
- Parsing Sigma tags client-side; the prevalence-ranked catalog.
- The A–F grade and the "top uncovered" list as a shareable artifact.
- SEO as distribution: 30 programmatic format-pair pages.
-- **Run it:** paste your rules at `tryaisoc.com/tools/coverage`.
+- **Run it:** paste your rules into the coverage tool on your own deployment.
+ Verify any `tryaisoc.com/tools/coverage` link returns 200 before it goes in
+ the published copy.
## 4. "A GitHub Action that triages your own security alerts" (W4)
diff --git a/marketing/launch/demo-video-shotlist.md b/marketing/launch/demo-video-shotlist.md
index 070108446..dfeae70dc 100644
--- a/marketing/launch/demo-video-shotlist.md
+++ b/marketing/launch/demo-video-shotlist.md
@@ -8,7 +8,7 @@ required. Captions on. Each shot is a real command against `main`.
| 1 | 0:00–0:12 | Cold terminal | `npx aisoc triage --demo` typed and run | "No install. No key. No Docker." |
| 2 | 0:12–0:22 | Verdict table + headline fills in | The table + "triaged 200 alerts: 12 TP, 171 FP suppressed (85.5% noise), 17 need review — in 0.1s" | "A verdict on every alert, in under a second." |
| 3 | 0:22–0:30 | `npx aisoc triage --demo --share` → open the SVG card | The report card | "Share the result — aggregate only, nothing leaks." |
-| 4 | 0:30–0:45 | Browser: open a public replay permalink `/r/demo-lockbit` | Animated playback: timeline scrubber, evidence cards, attack graph growing, verdict stamp | "Every agent decision is logged — and replayable." |
+| 4 | 0:30–0:45 | Browser: open a public replay permalink on the local stack, `http://localhost:3000/r/demo-lockbit` (replays are served by the deployment that produced them; there is no hosted public instance) | Animated playback: timeline scrubber, evidence cards, attack graph growing, verdict stamp | "Every agent decision is logged — and replayable." |
| 5 | 0:45–0:58 | Scrub the replay timeline; hover a step to show the rationale | Step rationale + confidence | "Prompt, tool call, evidence, rationale — per step." |
| 6 | 0:58–1:12 | Terminal: `pnpm aisoc:selfplay` (self-play campaign) — sped up | 5-stage attack chain running; detections firing; DAC proposals auto-filed | "It attacks itself nightly and files detections for every miss." |
| 7 | 1:12–1:24 | Browser: the mesh/network stats page | Instances connected, signatures shared, community FP-suppression lift | "Every install makes every other install smarter." |
@@ -18,8 +18,9 @@ required. Captions on. Each shot is a real command against `main`.
- Record shot 1–3 with `asciinema` or a clean terminal at 16–18pt; the demo is
deterministic so re-takes are identical.
-- Shots 6–7 depend on P2 (self-play) and P1 (mesh) being merged; until then,
- swap in the docker-compose demo landing on `/cases/INC-RT-001?tab=ledger`.
+- Shots 6–7 are recordable: self-play (`pnpm aisoc:selfplay`) and the mesh
+ service (`services/mesh/`) have both merged. This note used to say they were
+ pending.
- Keep total assets under `apps/web/public/demo/`; the README hero references
`demo/hero.gif` + the `.mp4`.
- No fabricated dashboards — every screen must be a real run.
diff --git a/marketing/launch/product-hunt.md b/marketing/launch/product-hunt.md
index 780ca0e62..8e8ff425a 100644
--- a/marketing/launch/product-hunt.md
+++ b/marketing/launch/product-hunt.md
@@ -1,5 +1,12 @@
# Product Hunt assets
+> **Before posting:** `aisoc` is built and packed on every tag but has never
+> been uploaded — `npx aisoc` does not resolve today, and the blocker is an
+> npm credential rather than code. Either publish first, or replace the
+> command in the copy below with the from-clone form
+> (`pnpm --filter aisoc build && node packages/aisoc-lite/dist/cli.js triage --demo`).
+> `packages/aisoc-lite/README.md` carries the same caveat.
+
## Name
AiSOC
diff --git a/marketing/launch/show-hn.md b/marketing/launch/show-hn.md
index 6861ca411..4b0e94bad 100644
--- a/marketing/launch/show-hn.md
+++ b/marketing/launch/show-hn.md
@@ -3,6 +3,13 @@
> Review against the benchmark page before posting. Keep it plain — no
> superlatives, no unbacked numbers.
+> **Before posting:** `aisoc` is built and packed on every tag but has never
+> been uploaded — `npx aisoc` does not resolve today, and the blocker is an
+> npm credential rather than code. Either publish first, or replace the
+> command in the copy below with the from-clone form
+> (`pnpm --filter aisoc build && node packages/aisoc-lite/dist/cli.js triage --demo`).
+> `packages/aisoc-lite/README.md` carries the same caveat.
+
## Title
```
diff --git a/packages/aisoc-ai-sdk/README.md b/packages/aisoc-ai-sdk/README.md
index 7d8bc06b6..17b497840 100644
--- a/packages/aisoc-ai-sdk/README.md
+++ b/packages/aisoc-ai-sdk/README.md
@@ -20,7 +20,7 @@ the detection engine, promoted, triaged.
## Install
```bash
-pip install -e packages/aisoc-ai-sdk # PyPI publish lands in v8.1
+pip install -e packages/aisoc-ai-sdk # not yet on PyPI; install from source
```
## Use
diff --git a/packages/aisoc-benchmark/README.md b/packages/aisoc-benchmark/README.md
index a37ea4667..76595e37f 100644
--- a/packages/aisoc-benchmark/README.md
+++ b/packages/aisoc-benchmark/README.md
@@ -7,7 +7,7 @@ This package is the boundary that makes it a standard instead: implement one
method, get graded on the same incidents by the same code.
```bash
-pip install -e packages/aisoc-benchmark # published to PyPI in v8.1
+pip install -e packages/aisoc-benchmark # not yet on PyPI; install from source
aisoc-benchmark corpus # what is in the corpus
aisoc-benchmark run --agent-url https://your-agent/investigate \
diff --git a/packages/aisoc-cli/README.md b/packages/aisoc-cli/README.md
index 910299122..6ff861d62 100644
--- a/packages/aisoc-cli/README.md
+++ b/packages/aisoc-cli/README.md
@@ -2,7 +2,7 @@
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.
+> **Status — monorepo today, not yet on PyPI.** The CLI ships from this monorepo and is fully functional today. `pip install aisoc-cli` does not resolve: the upload is blocked on registry credentials, which is an account action rather than a code change. The CLI name (`aisoc`) and command surface stay identical once it ships.
## Installation
diff --git a/packages/aisoc-sandbox/README.md b/packages/aisoc-sandbox/README.md
index 4682ed9ff..cf3669b74 100644
--- a/packages/aisoc-sandbox/README.md
+++ b/packages/aisoc-sandbox/README.md
@@ -3,7 +3,7 @@
> 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.1-f59e0b)](https://github.com/beenuar/AiSOC/blob/main/CHANGELOG.md)
+[![PyPI release](https://img.shields.io/badge/pypi-not%20yet%20published-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.
diff --git a/packages/plugin-sdk-py/README.md b/packages/plugin-sdk-py/README.md
index 6322a89dd..9e13e00dc 100644
--- a/packages/plugin-sdk-py/README.md
+++ b/packages/plugin-sdk-py/README.md
@@ -3,7 +3,7 @@
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.
+> **Status — monorepo today, not yet on PyPI.** `pip install aisoc-plugin-sdk` does not resolve; install from the monorepo source path below. The import path (`aisoc_plugin_sdk`) and API surface stay identical once it ships.
## Installation
diff --git a/packages/sdk-py/README.md b/packages/sdk-py/README.md
index 91e650e0c..ef4cb4b44 100644
--- a/packages/sdk-py/README.md
+++ b/packages/sdk-py/README.md
@@ -1,11 +1,11 @@
# 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)
+[![PyPI release](https://img.shields.io/badge/pypi-not%20yet%20published-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.
+> **Status — monorepo today, not yet on PyPI.** `pip install aisoc-sdk` does not resolve; install from the monorepo source path below. The import path (`aisoc_sdk`) and API surface stay identical once it ships.
## Installation
diff --git a/packages/sdk-ts/README.md b/packages/sdk-ts/README.md
index c39312551..9d0c7aea6 100644
--- a/packages/sdk-ts/README.md
+++ b/packages/sdk-ts/README.md
@@ -1,18 +1,18 @@
# @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)
+[![npm release](https://img.shields.io/badge/npm-not%20yet%20published-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.
+> **Status — monorepo today, not yet on npm.** `npm install @aisoc/sdk` does not resolve; 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
+cd AiSOC && pnpm --filter @aisoc/sdk install
# Not yet on npm — the upload is blocked on registry credentials,
# which is an account action rather than a code change. Until then, install
diff --git a/packs/README.md b/packs/README.md
index 8be7c736d..133128c1e 100644
--- a/packs/README.md
+++ b/packs/README.md
@@ -19,7 +19,7 @@ queries:
<query_name>:
sql: SELECT ... # SQL query string
interval: 60 # Poll interval in seconds
- severity: high # info | low | medium | high
+ severity: high # info | low | medium | high | critical
description: ...
mitre: [T1098] # Optional MITRE ATT&CK technique IDs
references:
@@ -32,7 +32,7 @@ file_paths: # Optional FIM paths section
## Compiling to Canonical Osquery JSON
-The `pack_loader` (in `services/api/app/services/pack_loader.py`) reads all YAML files and exposes them as validated `OsqueryPack` Pydantic models.
+The `pack_loader` (in `services/osquery-tls/app/services/pack_loader.py`) reads all YAML files and exposes them as validated `OsqueryPack` Pydantic models.
The `pack_resolver` (in `services/osquery-tls/app/services/pack_resolver.py`) takes an enrolled node's tenant ID, looks up assigned packs, and compiles them into the osquery TLS config JSON shape:
@@ -46,7 +46,7 @@ The `pack_resolver` (in `services/osquery-tls/app/services/pack_resolver.py`) ta
## Rendering for osctrl / FleetDM
-Use `GET /v1/packs/{id}/render?format=osctrl|fleetdm|osquery-json` to download a pack in the native format for manual import into your fleet manager. See [docs/packs/distribution.md](../apps/docs/docs/packs/distribution.md) for import walkthroughs.
+Use `GET /api/v1/osquery/packs/{pack_id}/render?format=osctrl|fleetdm|osquery-json` to download a pack in the native format for manual import into your fleet manager. The handler is `render_pack` in [`services/osquery-tls/app/api/v1/endpoints/packs.py`](../services/osquery-tls/app/api/v1/endpoints/packs.py).
## Curated Packs
@@ -61,6 +61,10 @@ Use `GET /v1/packs/{id}/render?format=osctrl|fleetdm|osquery-json` to download a
## Contributing
1. Copy an existing pack as a template.
-2. Validate with `python scripts/validate_packs.py packs/<your-pack>.yaml`.
+2. Validate by loading it: from `services/osquery-tls/`, run
+ `python -c "from app.services.pack_loader import get_all_packs; print(len(get_all_packs()))"`.
+ `get_all_packs()` parses every YAML in this directory into an `OsqueryPack`
+ model and raises on a malformed pack. There is no standalone validation
+ script.
3. Add a fixture under `detections/fixtures/` if the pack drives detections.
4. Update the table above and open a PR.
diff --git a/profiles/auditd/README.md b/profiles/auditd/README.md
index d4d70c307..cf844f51a 100644
--- a/profiles/auditd/README.md
+++ b/profiles/auditd/README.md
@@ -9,14 +9,20 @@ The connector tails `/var/log/audit/audit.log` directly and matches on
the `key=` field every rule attaches via `-k aisoc_*`. The connector's
severity heuristic is a pure function of the key prefix:
-| Key prefix | Severity |
-| ------------------- | -------- |
-| `aisoc_critical_*` | `high` |
-| `aisoc_priv_esc_*` | `medium` |
-| `aisoc_persistence_*` | `medium` |
-| `aisoc_exec` | `medium` |
-| `aisoc_watch_*` | `low` |
-| `aisoc_audit_*` | `low` |
+| Key prefix | Severity |
+| --------------------- | ---------- |
+| `aisoc_critical_*` | `critical` |
+| `aisoc_priv_esc_*` | `high` |
+| `aisoc_persistence_*` | `medium` |
+| `aisoc_exec` | `medium` |
+| `aisoc_watch_*` | `low` |
+| `aisoc_audit_*` | `low` |
+
+Highest-priority match wins, so an explicit `aisoc_critical_*` key beats the
+generic `aisoc_exec` bucket. The table above is `_KEY_SEVERITY_PREFIXES` in
+[`auditd.py`](../../services/connectors/app/connectors/auditd.py); a
+modification of a path in `_HIGH_RISK_PATHS` (`/etc/passwd` and friends) is
+lifted to `high` regardless of the key.
This means the SOC analyst sees the same severity in the AiSOC console
as the rule author intended at policy-write time — no second-guessing.
@@ -42,7 +48,7 @@ sudo augenrules --load
sudo auditctl -l | grep aisoc_
```
-You should see ~30 rules with `key=aisoc_*` attached. If you see zero,
+You should see 47 rules with `key=aisoc_*` attached. If you see zero,
re-check that `audit.rules.d` isn't being clobbered by a CIS / STIG
benchmark profile and that `auditd` itself is running
(`systemctl status auditd`).
@@ -69,22 +75,31 @@ sudo usermod -aG adm aisoc
## What gets detected, end-to-end
-Every rule in `aisoc.rules` is wired into at least one detection rule
-that already ships with AiSOC. The full mapping:
-
-| `audit.rules` key | Detection rule(s) |
-| -------------------------------- | --------------------------------------------------------------------------------- |
-| `aisoc_critical_exec_tmp` | `detections/endpoint/linux-exec-from-tmp.yaml` |
-| `aisoc_critical_memfd` | `detections/endpoint/linux-memfd-create.yaml` |
-| `aisoc_critical_identity_write` | `detections/endpoint/linux-passwd-shadow-write.yaml` |
-| `aisoc_critical_sudoers_write` | `detections/endpoint/linux-sudoers-modification.yaml` |
-| `aisoc_critical_pam_write` | `detections/endpoint/linux-pam-modification.yaml` |
-| `aisoc_critical_ssh_config` | `detections/endpoint/linux-sshd-config-modification.yaml` |
-| `aisoc_critical_authorized_keys` | `detections/endpoint/linux-authorized-keys-write.yaml` |
-| `aisoc_persistence_cron` | `detections/endpoint/linux-cron-persistence.yaml` |
-| `aisoc_persistence_systemd` | `detections/endpoint/linux-systemd-persistence.yaml` |
-| `aisoc_priv_esc_module_load` | `detections/endpoint/linux-kernel-module-load.yaml` |
-| `aisoc_audit_self_tamper` | `detections/endpoint/linux-auditctl-disable.yaml` |
+The profile emits 47 rules across 22 distinct `aisoc_*` keys. The Linux
+endpoint detections that consume this telemetry live under
+`detections/endpoint/`; the ones most directly tied to the keys in this
+profile are:
+
+| `audit.rules` key prefix | Related detections in `detections/endpoint/` |
+| --------------------------- | ------------------------------------------------------------------------------------- |
+| `aisoc_critical_memfd` | `linux-memfd-create-then-execve.yaml`, `linux-fileless-via-procfd.yaml` |
+| `aisoc_critical_exec_tmp` | `linux-chmod-plus-x-tmp.yaml`, `linux-large-stage-tmp.yaml`, `linux-ld-preload-set-tmp.yaml` |
+| `aisoc_critical_identity_write` | `linux-passwd-modified.yaml`, `linux-shadow-read.yaml` |
+| `aisoc_critical_sudoers_write` | `linux-auditd-sudoers-tampering.yaml`, `linux-sudoers-d-add.yaml`, `linux-nopasswd-sudo-line.yaml` |
+| `aisoc_critical_pam_write` | `linux-pam-d-modified.yaml` |
+| `aisoc_critical_ssh_config` | `linux-auditd-ssh-config-tampering.yaml`, `linux-ssh-config-permitrootlogin-yes.yaml` |
+| `aisoc_critical_authorized_keys` | `linux-authorized-keys-bulk-append.yaml`, `fim-ssh-authorized-keys-changed.yaml` |
+| `aisoc_persistence_cron` | `linux-cron-d-write.yaml`, `linux-anacron-job-add.yaml`, `linux-at-job-create.yaml` |
+| `aisoc_persistence_systemd` | `linux-auditd-systemd-persistence.yaml`, `linux-systemd-timer-create.yaml` |
+| `aisoc_persistence_initd` | `linux-initd-script-add.yaml` |
+| `aisoc_priv_esc_module_load`| `linux-auditd-kernel-module-load.yaml`, `linux-kernel-module-load-insmod.yaml` |
+| `aisoc_audit_self_tamper` | `linux-auditctl-disable.yaml`, `linux-auditd-stopped.yaml` |
+| `aisoc_watch_nss` | `linux-nss-module-installed.yaml` |
+
+This is a topical index, not a wiring contract: a detection fires on the
+normalised event, not on the audit key, so enabling a key does not guarantee
+a specific rule matches on your hosts. `docs/detections/truth-table.md` is
+the generated record of which rules the engine actually loads.
If you author a new rule against this profile, follow the same
convention — pick a key with a documented prefix, and the rest of the
diff --git a/services/connectors/README.md b/services/connectors/README.md
index 579241cb8..6eac346c7 100644
--- a/services/connectors/README.md
+++ b/services/connectors/README.md
@@ -16,31 +16,25 @@ normalises raw events into OCSF, and forwards them to the ingest pipeline.
instance, 5-min default cadence, configurable per-instance.
- **Federated search** — translate a single query into SPL, KQL, and ES|QL
and fan out to connected SIEMs.
-- **Four-tier severity** — vendor-native ladders collapse into
- `info | low | medium | high` in every connector's `normalize()` method.
+- **Five-tier severity** — every connector's `normalize()` emits one of
+ `info | low | medium | high | critical`. A vendor ladder that publishes a
+ distinct `critical` must map to `critical` and must **not** be collapsed
+ into `high`; 50 of the connector modules rely on that tier today.
---
## Supported connectors
-| Connector | Category | Source |
-|------------------------|----------|------------------------------|
-| AWS Security Hub | cloud | SecurityHub findings |
-| Azure Activity | cloud | Azure Resource Graph API |
-| Azure Defender | cloud | Microsoft Defender for Cloud |
-| Azure Entra | iam | Microsoft Entra ID (AAD) |
-| Cloudflare | cloud | Cloudflare security events |
-| CrowdStrike | edr | CrowdStrike Falcon |
-| Elastic | siem | Elasticsearch / Elastic SIEM |
-| GCP Cloud Audit | cloud | Google Cloud Logging API |
-| GCP SCC | cloud | Security Command Center |
-| GitHub | vcs | GitHub Audit Log API |
-| Google Workspace | saas | Google Reports API |
-| M365 Audit | saas | Office 365 Management API |
-| Microsoft Sentinel | siem | Azure Log Analytics |
-| Okta | iam | Okta System Log API |
-| Splunk | siem | Splunk REST API |
-| Tailscale | network | Tailscale audit log API |
+84 connectors are registered in `_CONNECTOR_CLASSES`
+(`app/connectors/__init__.py`), which is the only source of truth. The count
+and its per-category breakdown are generated into
+[`apps/web/src/data/connector-count.json`](../../apps/web/src/data/connector-count.json)
+by `scripts/generate_connector_count.py`, and `--check` gates it in CI, so a
+hand-written table here would go stale the day the next connector lands.
+
+Per-connector setup walkthroughs live under
+[`apps/docs/docs/connectors/`](../../apps/docs/docs/connectors/) and are
+indexed in the docs sidebar.
---
diff --git a/services/demo-producer/README.md b/services/demo-producer/README.md
index c4e360f56..ea253d178 100644
--- a/services/demo-producer/README.md
+++ b/services/demo-producer/README.md
@@ -14,11 +14,19 @@ pnpm docker:dev
# 2. Seed the database with the demo tenant + baseline alerts/cases
pnpm seed:demo
-# 3. Stream live events into the ingest service
-pnpm demo:produce # ~24 events/sec across 6 connectors
-pnpm demo:produce:fast # 480 events/sec — for stress demos
+# 3. Mint the ingest credential — /v1/ingest refuses requests without one
+make ingest-token
+
+# 4. Stream live events into the ingest service
+AISOC_INGEST_TOKEN=<the token> pnpm demo:produce # 120 events/sec across 6 connectors
+AISOC_INGEST_TOKEN=<the token> pnpm demo:produce:fast # 480 events/sec — for stress demos
```
+The throughput is `rate x batch x len(profiles)`: the default `--rate 4`
+(batches per second, **per connector**) times `--batch 5` times the six
+connector profiles is 120 events/sec. `demo:produce:fast` passes
+`--rate 8 --batch 10`, which is 480.
+
## Flags
| Flag | Default | Notes |
@@ -28,8 +36,10 @@ pnpm demo:produce:fast # 480 events/sec — for stress demos
| `--rate` | `4` | Batches per second per connector |
| `--batch` | `5` | Events per batch |
| `--duration` | `0` | How long to run (0 = forever) |
+| `--token` | `$AISOC_INGEST_TOKEN` (empty) | **Required.** `/v1/ingest` refuses requests without one; mint it with `make ingest-token` |
-Environment variables `INGEST_URL` and `TENANT_ID` are honored as defaults.
+Environment variables `INGEST_URL`, `TENANT_ID` and `AISOC_INGEST_TOKEN` are
+honored as defaults.
## Design notes
diff --git a/services/enrichment/README.md b/services/enrichment/README.md
index 044463c40..451f2a50d 100644
--- a/services/enrichment/README.md
+++ b/services/enrichment/README.md
@@ -36,9 +36,11 @@ pipeline, the AI Copilot, the case workspace, and the hunt UI.
| VirusTotal | IP, domain, URL, hash | API key | `VIRUSTOTAL_API_KEY` |
| AbuseIPDB | IP | API key | `ABUSEIPDB_API_KEY` |
| GreyNoise | IP | API key | `GREYNOISE_API_KEY` |
-| Shodan | IP | API key | `SHODAN_API_KEY` |
-| URLScan | URL, domain | API key | `URLSCAN_API_KEY` |
-| IPinfo | IP | API key | `IPINFO_API_KEY` |
+
+Shodan (`SHODAN_API_KEY`), URLScan (`URLSCAN_API_KEY`) and IPinfo
+(`IPINFO_API_KEY`) are read from the environment but have **no client
+implementation yet** — there is no constructor for them and they are not in
+the fan-out, so setting those keys changes nothing today.
### Commercial
@@ -131,7 +133,7 @@ For each enrich request the service:
### Enrich an IOC
```
-POST /v1/enrich
+POST /enrich
Content-Type: application/json
{
@@ -143,10 +145,18 @@ Content-Type: application/json
Response: a JSON-encoded `EnrichmentResult`.
+### Enrich a batch of IOCs
+
+```
+POST /enrich/bulk
+```
+
+Takes a list of the same objects and returns a list of results.
+
### Health
```
-GET /healthz
+GET /health
```
Returns `200 OK` once the cache and at least one provider are reachable.
@@ -160,7 +170,8 @@ cd services/enrichment
# minimal config: VirusTotal only
export VIRUSTOTAL_API_KEY=...
-export REDIS_ADDR=localhost:6379
+export REDIS_URL=redis://localhost:6379/1
+export HTTP_PORT=8082 # the default
go run .
```
diff --git a/services/slack-bot/README.md b/services/slack-bot/README.md
index e374cf494..3cf5487e9 100644
--- a/services/slack-bot/README.md
+++ b/services/slack-bot/README.md
@@ -88,9 +88,10 @@ container). Point Slack's request URL at
## Slack app review checklist
-Before submitting to the Slack app directory (target: end of week 12 in the
-buyer-value plan), confirm every box below. The manifest under
-`marketplace/slack-app/manifest.json` should match this configuration
+Before submitting to the Slack app directory, confirm every box below. There
+is no committed Slack app manifest — `marketplace/` holds only `index.json`
+and `curated.json` — so the manifest you upload to Slack must match this
+configuration
verbatim.
### App configuration
diff --git a/services/teams-bot/README.md b/services/teams-bot/README.md
index f4093d160..63fa6e3e9 100644
--- a/services/teams-bot/README.md
+++ b/services/teams-bot/README.md
@@ -47,10 +47,11 @@ malformed, or older than `AISOC_TEAMS_CALLBACK_MAX_AGE_SECONDS` (default
| Variable | Required | Description |
| --------------------------------------- | -------- | -------------------------------------------------------- |
-| `AISOC_TEAMS_APP_ID` | yes | Microsoft App ID for the bot registration. |
-| `AISOC_TEAMS_APP_PASSWORD` | yes | Bot framework secret. |
-| `AISOC_TEAMS_CALLBACK_SECRET` | yes | Shared HMAC secret used to sign + verify card payloads. |
-| `AISOC_TEAMS_CALLBACK_MAX_AGE_SECONDS` | no | Replay window for signed payloads. Default `600`. |
+| `AISOC_TEAMS_APP_ID` | not read | Declared for the Bot Framework registration, but no code in this service reads it today. |
+| `AISOC_TEAMS_APP_PASSWORD` | not read | Same — the outbound Bot Framework client is not wired yet. |
+| `AISOC_TEAMS_CALLBACK_SECRET` | yes | Shared HMAC secret used to sign + verify card payloads (`app/main.py`). |
+| `AISOC_TEAMS_CALLBACK_MAX_AGE_SECONDS` | no | Replay window for signed payloads. Default `600` (`app/callbacks.py`). |
+| `AISOC_TEAMS_HMAC_MODULE_PATH` | no | Test hook: redirects the HMAC signer module lookup (`app/services/hmac_signer.py`). |
| `AISOC_API_BASE_URL` | yes | `services/api` base URL — same env var as the Slack bot. |
| `AISOC_ACTIONS_BASE_URL` | yes | `services/actions` base URL. |
| `AISOC_API_SERVICE_TOKEN` | yes | API key with `cases:read,cases:write`. |
@@ -66,5 +67,5 @@ poetry run pytest tests/
Coverage:
* `tests/test_cards.py` — Adaptive Card factory output shape.
-* `tests/test_callbacks.py` — HMAC verify, replay rejection, audit row,
- upstream-failure path.
+* `tests/test_callbacks_approver.py` — HMAC verify, replay rejection, audit
+ row, upstream-failure path.
diff --git a/tools/detection_import/README.md b/tools/detection_import/README.md
index ee7147d23..03ab46aa9 100644
--- a/tools/detection_import/README.md
+++ b/tools/detection_import/README.md
@@ -10,7 +10,7 @@ Tools for pulling detection content from upstream open-source projects and conve
| [`car_importer.py`](car_importer.py) | [mitre-attack/car](https://github.com/mitre-attack/car) | `detections/car-imports/` | working |
| [`chronicle_importer.py`](chronicle_importer.py) | [chronicle/detection-rules](https://github.com/chronicle/detection-rules) | `detections/chronicle-imports/` | scaffolded |
| [`splunk_importer.py`](splunk_importer.py) | [splunk/security_content](https://github.com/splunk/security_content) | `detections/splunk-imports/` | scaffolded |
-| [`import.py`](import.py) | (orchestrator) | runs every importer in turn | working |
+| [`import_orchestrator.py`](import_orchestrator.py) | (orchestrator) | runs every importer in turn | working |
## Provenance schema