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 the statements recent work made false (#1229)

Beenu Arora3364706565f5
diff --git a/.github/LICENSES.md b/.github/LICENSES.md
index 4f5d55c3e..5b401941d 100644
--- a/.github/LICENSES.md
+++ b/.github/LICENSES.md
@@ -27,7 +27,7 @@ DRL-1.1 summary: you may use, modify, and redistribute Sigma rules provided you
| Field | Value |
|---|---|
| **Upstream repo** | [mitre-attack/car](https://github.com/mitre-attack/car) |
-| **License** | [Apache-2.0](https://github.com/mitre-attack/car/blob/master/LICENSE) |
+| **License** | [Apache-2.0](https://github.com/mitre-attack/car/blob/master/LICENSE.txt) |
| **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>` |
diff --git a/AGENTS.md b/AGENTS.md
index 959a6f4d8..821e7ec94 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,86 +1,185 @@
-## Learned User Preferences
-
-- Always track progress locally (e.g. in a TODO/PROGRESS file) so work can be resumed after IDE crashes or restarts.
-- Complete all planned tasks without stopping mid-way; work through the full list until done.
-- Do not name competitor products anywhere in code, comments, docs, plan files, or marketing copy. Where a competitor is the benchmark for a comparison, refer to it neutrally (e.g. "the reference AI-SOC platform") and keep the analytical content. Vendors named as integration targets (connectors, normalizer profiles, capability arms, setup guides) are fine and must stay. The canonical name list and the allow-listed integration paths live in `scripts/competitor_names.toml`, enforced by `scripts/check_competitor_names.py`.
-- Before pushing to GitHub, ensure no secrets, API keys, tokens, or sensitive data are present in any public repo files.
-- Host codebase on GitHub once fully built out; keep documentation in sync.
-- Never edit plan files directly — implement the plan as specified without modifying the plan document itself.
-- After every significant change, push code and update documentation on GitHub immediately — don't wait to be asked.
-- Benchmark data and documentation must be transparent about what is synthetic vs. real; never present fabricated metrics as actual measured performance.
-- When the task is clear, act autonomously — don't ask unnecessary clarifying questions.
-- Standing repo-maintenance loop is the default when no other task is queued: review open PRs at the canonical repo, resolve CI/conflicts, merge them, close issues those PRs resolved, and keep `main` green.
-- After any deploy to `tryaisoc.com`, do an end-to-end customer-journey review that covers the full **authenticated** app (registration → login → connector setup → live ingest/triage → billing), not just landing → dashboard: click through every interactive element and fix dead buttons, broken flows, and empty/errored views before declaring done. The user repeatedly reports broken authenticated features post-deploy and demands being "1000% sure" nothing is broken before any handover.
-- The authenticated product must run on **real, live** connector-ingested data and genuine LLM triage — never mock/demo/baseline-fallback or empty data presented as working. When a user connects a connector, the platform must automatically and continuously (near-real-time) pull and analyze that data for triage without the user having to ask; stubbed features, empty dashboards, and silent mock-data fallbacks are treated as bugs.
-- When asked "what else can we improve?" / "what are the missing pieces?" / "make this world-class", produce a concrete competitive gap analysis vs. leading commercial AI-SOC products and implement the gaps — don't just answer in prose.
-
-## Learned Workspace Facts
-
-- Project: AiSOC — open-source, AI-powered Security Operations Center maintained by the AiSOC community under the MIT license.
-- **Single source of truth (as of 2026-06-27):** `https://github.com/beenuar/AiSOC` is the only canonical repo. The previous private staging repo `beenuar/AISOC-Cyble` was archived (read-only, `archived: true`) and its full history was merged into this monorepo under `plans/cyble-aisoc/` via `git subtree add --prefix=plans/cyble-aisoc` ([PR #324](https://github.com/beenuar/AiSOC/pull/324)). The archive notice (`DEPRECATED.md`) was subsequently subtree-pulled into `plans/cyble-aisoc/DEPRECATED.md` ([PR #325](https://github.com/beenuar/AiSOC/pull/325)).
-- **Spec + historical prototype location:** the north-star design doc lives at `plans/cyble-aisoc/cyble-aisoc-plan.md`; the historical FastAPI/static prototype + early architecture notes + 12-month roadmap live under `plans/cyble-aisoc/{platform,architecture,roadmap}/`. Treat that subtree as historical reference only — the canonical deployable code is at the monorepo root (`services/`, `apps/`, `infra/`, `packages/`).
-- **CodeQL scoping:** `.github/workflows/codeql.yml` carries `paths-ignore: 'plans/cyble-aisoc/**'` so prototype findings don't appear as actionable security alerts. The same `paths-ignore` is documented inline in the workflow.
-- Monorepo managed with pnpm ([email protected]) and Turborepo; workspaces defined in `apps/*` and `packages/*`.
-- Apps: `apps/web` (Next.js frontend), `apps/docs` (documentation site).
-- Backend services in `services/`: `api` (FastAPI/Python 3.11), `agents`, `alert-fusion`, `connectors`, `demo-producer`, `enrichment`, `fusion`, `ingest`, `realtime`, `threatintel`, `ocsf`.
-- API service stack: FastAPI, Uvicorn, SQLAlchemy (async), asyncpg (PostgreSQL), Alembic (migrations), Redis, PyJWT (JWT), Pydantic v2.
-- Packages: `packages/types` (shared TypeScript types), `packages/ui`, `packages/sdk-go`, `packages/sdk-py`, `packages/sdk-ts`, `packages/plugin-sdk-go`, `packages/plugin-sdk-py`.
-- Docker Compose used for local dev: `infra/compose/` is the canonical home for all non-root compose files (`docker-compose.dev.yml`, `docker-compose.demo.yml`, `docker-compose.airgap.yml`); only the slim `docker-compose.yml` remains at repo root. Build contexts inside the moved files use `../../services/<name>` (two levels up). Terraform in `infra/terraform/` for infrastructure.
-- CI uses GitHub Actions (`.github/workflows/`); includes workflows for OpenAPI checks, CI, docs deployment, marketplace sync, and detection validation.
-- Detection rules stored in `detections/` (YAML format, categorized by cloud/endpoint/identity/network/application).
-- Marketplace plugin index at `marketplace/index.json`, synced to `apps/web/public/marketplace/` via `pnpm marketplace:sync`.
-- Connector platform conventions:
- - Connectors live under `services/connectors/app/connectors/<name>.py`. Each subclasses `BaseConnector` and declares a `schema()` classmethod returning a `ConnectorSchema(name, label, description, category, fields, oauth, default_poll_interval_seconds)`. Categories are `edr | siem | cloud | iam | saas | vcs | network`.
- - Discovery is registry-based — add the class to `_CONNECTOR_CLASSES` in `services/connectors/app/connectors/__init__.py` (no other wiring required).
- - Sensitive `auth_config` fields are marked `secret=True` in the schema and encrypted at the application layer using `CredentialVault` (Fernet AES-128-CBC + HMAC-SHA256). Key in `AISOC_CREDENTIAL_KEY`; rotation supported via `MultiFernet` + `AISOC_CREDENTIAL_KEY_ROTATION_FROM`. Vault token format is `vault:v1:<base64>`.
- - The API service (`services/api`) holds the encrypt/decrypt keypair authority; `services/connectors` ships a vendored read-path `decrypt_dict()` so the scheduler can decrypt at poll time without owning the write path.
- - Polling runs in-process inside `services/connectors` via APScheduler (`ConnectorScheduler`). One job per enabled instance, 5-min default cadence, overridable per-instance via `connector_config.poll_interval_seconds`. The scheduler reloads jobs every 30s. Disable in tests with `AISOC_CONNECTORS_DISABLE_SCHEDULER=1`.
- - Normalized events flow through `IngestClient` (`services/connectors/app/ingest_client.py`) to `services/ingest`'s `/v1/ingest/batch` endpoint with an `X-Tenant-ID` header.
- - Severity ladder is exactly five tiers: `info | low | medium | high | critical` (v1.5+). Vendor-native ladders that publish a distinct `critical` (Azure 5-tier, GCP SCC 5-tier, GitHub `critical`, ServiceNow priority 1, AWS GuardDuty ≥8.0, AuditD identity-destruction events, K8s `cluster-admin` bindings, Tailscale tailnet lockdown failures) MUST map to `critical` in their `normalize()` and NOT be collapsed into `high`. Confidence (`alert.confidence`, int 0–100 with band `low | medium | high`) is independent of severity and is emitted by `services/fusion` `ConfidenceScorer`.
- - Every connector ships a marketplace manifest at `plugins/<connector-id>/plugin.yaml` mirroring its `schema()`. Run `pnpm marketplace:sync` after adding one.
- - Per-connector setup walkthroughs live under `apps/docs/docs/connectors/<connector-id>.md` and are indexed by `apps/docs/sidebars.ts` under the `Connectors` category. The vault threat model + rotation procedure live in `apps/docs/docs/operations/credentials.md`.
-- **Alerts / Investigation Rail (v1.5):** `/alerts` is a two-pane workbench with `InvestigationRail.tsx` on the right. `GET /api/v1/alerts/{id}` returns an envelope (narrative, related entities with `pivotPath`, six-event mini-timeline, `recommended_actions`). Fusion writes deterministic correlation copy at fuse time (`services/fusion/app/services/narrative.py`); API uses `alert_rail.py`, `narrative_projection.py`, and vendored `app/_vendor/narrative.py` (keep in sync via `scripts/sync_vendored_narrative.py`). User doc: `apps/docs/docs/console/investigation-rail.md`.
-- v1.4 eval harness conventions:
- - Synthetic dataset is fixed at 200 incidents (`services/agents/tests/eval_data/synthetic_incidents.json`) plus an aligned synthetic telemetry corpus (`synthetic_telemetry.jsonl`). Three of the four metrics (`alert_reduction`, `investigation_completeness`, `response_quality`) are substrate self-consistency gates, not agent accuracy scores; only `mitre_accuracy` measures the live agent. The benchmark page (`apps/docs/docs/benchmark.md`) explains which is which.
- - PRs touching the agent, orchestrator graph, prompts, tools, RAG corpus, or detection content must re-grade against the harness and include before/after deltas in the PR body if any axis regresses.
-- Project website at `tryaisoc.com`; domain registered through Cloudflare. `tryaisoc.com/signup` is deprecated — the public entry point is `tryaisoc.com/dashboard` (interactive demo). Marketing-site signup CTAs should redirect there, not to a separate signup form.
-- Production hosting on Fly.io (region `iad`) with two apps: `aisoc-demo-web` (Next.js, serves `tryaisoc.com`) and `aisoc-demo-api` (FastAPI, also exposed at `api.tryaisoc.com`). The web app proxies `/api/v1/*` to `aisoc-demo-api.internal:8000`. Each service has its own `fly.toml`; deploys use the `fly` CLI with per-session tokens supplied by the user and rotated out-of-band. `services/api/app/scripts/run_migrations.py` retries `asyncpg.connect` with exponential backoff (6 attempts) to ride out Fly Postgres autostop / boot-race transients during the migration `release_command`.
-- v1.0 buyer-value plan (`aisoc_v1.0_—_buyer-value_plan_c8116970.plan.md`) is fully implemented (all WS-A through WS-H workstreams completed as of May 2026). Key additions:
- - WS-A: Demo seed script at `services/api/app/scripts/seed_demo.py` — 15 realistic incidents, one-click Render deploy (`render.yaml` + README badge).
- - WS-C: 25 named parameterised playbooks (WS-C1), playbook gallery with eval gate (WS-C2/C3).
- - WS-D: Auto-summary at investigation close with PDF export (WS-D2), replayable investigation timeline (WS-D3), rate-limit + real-test hardening (WS-D1).
- - WS-F: Light/dark theme persisted in user profile (WS-F1), WCAG AA axe-core CI gate (WS-F2), saved views on Alerts/Cases/Playbooks + drag-drop dashboard widgets (WS-F3), visual SOAR studio (undo/redo, edge validation, schema-driven forms — WS-F4), empty-state polish + v1.1 deferred badges (WS-F5).
- - WS-G: Slack Bolt service at `services/slack-bot/` with `/aisoc` ChatOps commands (WS-G1); executive digest with auto-generated PDF + weekly scheduler in `services/api/app/services/digest_pdf.py` and `services/api/app/api/v1/endpoints/reports.py` (WS-G2).
- - WS-H: LLM cost dashboard (`services/api/app/services/cost_dashboard.py` + `apps/web/src/app/(admin)/costs/page.tsx` — WS-H1); BYOK per-tenant LLM credentials vault-encrypted via `CredentialVault`, model `TenantLlmCredential`, settings UI in `apps/web/src/components/settings/SettingsView.tsx` (WS-H2); compliance audit export CSV + HTML bundles at `services/api/app/services/audit_export.py` (WS-H3); air-gapped / local-LLM mode via Ollama/LiteLLM overlay + zero-external-call demo seed (WS-H4).
- - Threat actor attribution engine v0 at `services/threatintel/` (rebased, hardened, open as PR #43).
-- **v8.0 wave-1 (tagged as `v7.5.0` on 2026-06-29):** Architectural foundation for the v8.0 line shipped as the `v7.5.0` release. `VERSION` is `7.5.0` (also reflected in `apps/web/package.json`); wave-2 work accumulates under `[Unreleased]` in `CHANGELOG.md` until the next tag. Tracking doc: `docs/roadmap/v8-progress.md`. Key shipped pieces:
- - **Graph at ingest (T1.1).** `services/ingest/internal/graph/` writes a Neo4j entity graph (`User`, `Asset`, `Process`, `IP`, `Domain`, `Alert`, 17 node labels / 14 edge types total) inline with Kafka consumption. Batched UNWIND upserts + fire-and-forget retry queue keep the ingest latency budget unchanged. Schema doc: `apps/docs/docs/architecture/graph-schema.md`. Anchor post: `apps/web/content/blog/graph-at-ingest.mdx`.
- - **Four-agent rebrand (T2.1).** `DetectAgent`, `TriageAgent`, `HuntAgent`, `RespondAgent` in `services/agents/app/agents/`. Back-compat aliases preserve existing imports. Each owns one funnel stage; funnel KPI doc at `apps/docs/docs/console/funnel-kpis.md`.
- - **`/hunt` natural-language surface (T2.2).** `apps/web/src/app/(app)/hunt/` + `services/api/app/api/v1/endpoints/saved_hunts.py`. NL prompt → ES|QL / SPL / KQL template (HuntAgent never writes raw queries). Saved hunts have `pivotPath` deep-links into the Investigation Rail.
- - **Sixteen first-party connectors.** Wave-1 fully tested: `tines`, `torq`, `falco`, `pagerduty`, `opsgenie`, `confluence_audit`. Wave-2 with full fixtures + tests: `cloudflare_zt`, `sysdig`, `vault`, `snowflake`. Six more `[wip]` in `docs/roadmap/v8-progress.md`. All five severity tiers preserved end-to-end.
- - **L0–L4 automation maturity model.** `apps/docs/docs/concepts/automation-maturity.md` + `apps/web/content/papers/l0-l4-automation-maturity.md` (PDF rendered via `pnpm docs:build`). Ladder: L0 manual → L4 fully autonomous closure with human sign-off.
- - **Public weekly benchmark scoreboard.** `apps/docs/docs/benchmark-scoreboard.mdx` reads `apps/docs/static/data/scoreboard.json`, refreshed by `.github/workflows/wet-eval.yml` (weekly). Existing eval-harness transparency rules apply (synthetic vs real labelled explicitly).
-- **Security wave shipped before v8.0 cut (PRs #116–#128, May 2026):** Twelve critical/high CVE-class fixes. Patterns to remember:
- - Rule engine no longer uses `eval()` / `compile()` on user input — conditions are parsed into a whitelisted AST in `services/api/app/services/rules_engine.py`.
- - Tenant isolation is enforced at the **query layer** (filter by `tenant_id` in `WHERE`), not via RLS alone, on `/hunts` and `/cases` endpoints. RLS remains as defence-in-depth.
- - CORS: shared `cors.py` is vendored byte-identical into every Python service. It refuses to start when `AISOC_CORS_ORIGINS` contains `*` while credentials are enabled and `AISOC_ENV=production`. TypeScript guard for `services/realtime` enforces the same rule.
- - Playbook outbound traffic: every `http_request` / `notify` step goes through `services/agents/app/playbook/ssrf_guard.py` — scheme allow-list, hostname resolution + IP allow-list, cloud-metadata block list that applies even when private IPs are explicitly allowed.
- - Plugin manager OCI installs verify signed manifests against an allow-list and pin image digests at install time, re-verifying on every load.
- - Dev-mode: one canonical `AISOC_DEV_MODE` env var replaces the per-service patchwork of `DEV_MODE` / `SKIP_AUTH` / `AISOC_DEMO_MODE` flags. `tests/test_security_defaults.py` is a CI gate that asserts no dev-mode shortcut is reachable when the flag is unset.
- - LLM input contract: untrusted enrichment (threat-intel feeds, user-submitted content) runs through `services/api/app/services/llm_safety.py` (boundary markers, control-character stripping, length cap) before any prompt concatenation.
-- **Static analysis hygiene (CodeQL):** the invariant is **zero open CodeQL alerts on `main` at every severity, `note` included**, enforced by `.github/workflows/codeql-alert-gate.yml` running `scripts/check_codeql_alerts.py`. That gate did not exist until 2026-09-24 even though the docs had claimed one since 2026-05-15 — `analyze` does not fail a build on findings, `main` has no branch protection, and nothing queried the code-scanning API — so two `note` alerts sat open under a documented count of zero. Dismissed alerts are excluded (audited escape hatch, ~20 accepted-risk `py/request-without-cert-validation`) but counted in the gate's output; Scorecard SARIF is out of scope. The gate also fails on an unanalysed ref, a missing language, an analysis >10 days old, or one from a different commit than the run's. Two patterns drove the original cleanup:
- - **`py/log-injection` — sanitise inline at the call site.** The taint tracker doesn't follow `_log_safe(value)` through function boundaries reliably, but it does recognise an inline `str(value).replace("\r", "").replace("\n", " ")[:N]` chain. Canonical example: `services/api/app/api/v1/endpoints/waitlist.py`. Even `uuid.UUID`-typed values are sanitised explicitly so the property is visible to both CodeQL and future readers.
- - **`py/import-and-import-from` — pick one import style per module.** Tests that monkey-patch module-level constants should use `pytest.MonkeyPatch.setattr(module, "_NAME", value)` (with the standard from-import form), not `import app.foo as foo_module` _and_ a from-import for the same names.
- - **`py/request-without-cert-validation` — accepted-risk for on-prem appliance clients.** The Splunk / FortiGate / PAN-OS / osctrl / FleetDM / MISP clients default to `verify=True` and only disable TLS verification on an explicit operator opt-in (required for self-signed / internal-CA appliances), so these ~20 alerts are dismissed `won't fix` with a comment recommending CA-bundle pinning as the future alternative. Related one-liners from the Jul-2026 pass: a count var named `secret*` trips the alert heuristic (rename to e.g. `vaulted`); `py/ineffectual-statement` on Protocol/abstract `...` bodies → use a docstring body; `py/empty-except` → add an explanatory comment. Zero open alerts re-confirmed on `main` (Jul 2026), now across Python + Go (`go vet` / `go build`).
- - Docs anchor: `apps/docs/docs/operations/security.md#static-analysis-codeql`.
-- **UEBA env-var convention (PR #135, first community contribution, closes Issue #134):** `services/ueba/app/core/config.py` uses Pydantic `BaseSettings` with `populate_by_name=True` and `Field(default=..., validation_alias=AliasChoices("UNPREFIXED", "UEBA_PREFIXED"))` per field. Both forms work; unprefixed wins when both are set. `services/ueba/alembic/env.py` follows the same rule: `os.environ.get("DATABASE_URL") or os.environ.get("UEBA_DATABASE_URL", default)`. Same pattern as `services/fusion/app/core/config.py`. Test coverage: `services/ueba/tests/test_config.py` asserts four cases (unprefixed-only / prefixed-only / both-with-unprefixed-winning / default-fallback). Doc anchor: `apps/docs/docs/deployment/env-vars.md#ueba-service-servicesueba`.
-- **Release flow is tag-driven (CHANGELOG-extraction).** `.github/workflows/release.yml` watches for `v*` tags, extracts the matching `[X.Y.Z]` section from `CHANGELOG.md` (Keep-a-Changelog format) via an awk script, then publishes via `softprops/action-gh-release` and pushes 12 service images to GHCR with the version tag. To cut a release: (1) promote `[Unreleased]` → `[X.Y.Z]` in `CHANGELOG.md` (leaving a fresh empty `[Unreleased]`), (2) bump `VERSION` and `apps/web/package.json`, (3) refresh the README version badge / headline / roadmap entry, (4) commit `chore(release): vX.Y.Z`, (5) `git tag vX.Y.Z && git push --tags`. Do NOT create the GitHub release manually — the workflow does it. v7.5.0 (2026-06-29) is the canonical reference example.
-- **Marketing shell is unified.** `apps/web/src/app/(marketing)/layout.tsx` renders the canonical `StickyNav` + `apps/web/src/components/landing/sections/Footer` ONCE for every marketing subpage; subpages must NOT re-import or re-render their own nav/footer. Standalone pages outside the route group (`not-found.tsx`, `why-open-source/page.tsx`, `benchmark/page.tsx`) import the shell directly. The deprecated `LandingNav` and `landing/Footer` were deleted. `StickyNav` anchor links use absolute paths (`/#solution`, `/#pillars`) so they work on subpages too. JSX whitespace pitfall (PR #337): when an interpolation like `{CONNECTOR_COUNT}` and adjacent text wrap to separate source lines, React injects `<!-- -->` comment markers and DROPS the leading whitespace — always use an explicit `{' '}` between expression and following text. The connector-count source of truth is `apps/web/src/lib/connector-count.ts` (`CONNECTOR_COUNT`); `scripts/generate_connector_count.py --check` is a CI gate that asserts the README contains the `**N click-and-connect data connectors**` phrase.
-- **`packages/aisoc-sandbox` — offline 30-second on-ramp.** Standalone simulator wrapping the agent graph with in-memory SQLite + deterministic LLM mode, designed so `pip install aisoc-sandbox && aisoc-sandbox demo` completes in <30 s with zero external deps. Ships five bundled scenarios (lateral-movement + four added in PR #368). Distinct from the full production LangGraph stack — keep it lightweight on purpose. Tested via `packages/aisoc-sandbox/tests/`.
-- **README + onramp CI gates.** `README.md` is capped at ≤250 lines (current target after PR #368 was 1,102 → 234). Heavy content lives in `RELEASES.md`, `ROADMAP.md`, `docs/architecture/overview.md`, and the docs portal. `.github/workflows/onramp-gates.yml` enforces four gates on every PR: (1) every CLI command shown in README either runs in CI or is explicitly marked "coming in v8.0", (2) `demo/hero.gif` + screencast assets exist on `main`, (3) README line count ≤250, (4) `aisoc-sandbox demo` cold-start. The matching local script lets contributors run the same checks. Advertised packages (`@aisoc/mcp`, `@aisoc/sdk`, `@aisoc/plugin-sdk`, `aisoc-cli`, `aisoc-sdk`, `aisoc-plugin-sdk`) are NOT yet published — README and docs use monorepo-local invocations and flag future commands as "coming in v8.0".
-- **Devcontainer prebuilt image.** `.devcontainer/devcontainer.json` prefers `ghcr.io/beenuar/aisoc-devcontainer:latest` (with local Dockerfile fallback). `.github/workflows/devcontainer-build.yml` publishes multi-arch (amd64+arm64) on changes to the Dockerfile; `.github/workflows/devcontainer-coldstart.yml` is `workflow_run`-triggered against the freshly-published `:latest` and probes the toolchain (image pull ≤60 s, `uv`/`ruff`/`docker compose`/etc. on PATH). Two durable gotchas the Dockerfile encodes: (a) `docker-compose-plugin` is NOT in Debian Bookworm's default apt repo — install Compose v2 by direct curl of the official binary into `/usr/local/lib/docker/cli-plugins/docker-compose` (pinned to v2.29.7); (b) `pipx`-installed tools land in `/root/.local/bin` which is invisible to the container's non-root `node` user — install `uv` and `ruff` system-wide into `/usr/local/bin` instead. Docs anchor: `apps/docs/docs/development/devcontainer.md`.
-- **World-class hardening program (12-phase, from Jul 2026) + claim-to-gate governance.** A staged program drives the repo toward production readiness; phase status is tracked in `ROADMAP.md` + a local `PROGRESS.md`, and the program forbids stub implementations, fake/circular gates, and simulated results presented as functional. Its backbone is `CLAIM_TO_GATE_MATRIX.md` — a permanent CI artifact mapping every product claim → the CI gate that proves it (each row is `GATED` / `PARTIAL` / `NO GATE`). A checker script enforces a **ratchet**: CI fails if the `NO GATE` count exceeds a committed baseline (`MAX_NO_GATE`, currently 3; `--max-no-gate` configurable). `.github/workflows/security.yml` runs the matrix ratchet as the **sole hard gate**, plus gitleaks / semgrep / trivy / checkov / tfsec in **observe mode** (`continue-on-error`, SARIF upload via `github/codeql-action`); `.gitleaksignore` is the curated secret allowlist and Trivy is installed as a pinned binary via a `run:` step (marketplace action versions were unreliable). Phase 1 also shipped a per-run nonce `PromptInjectionGuard` (ties detections to ledger flags + L0 demotion) and memory-poisoning-resistant override provenance (author / confidence / trust_weight; `apply_redisposition` gated by a confirmation token).
-- **Detection corpus honesty.** `detections/` carries ~6,975 rules on disk, but only ~939 are **executable** today (861 native + 77 Sigma-imported + 1 community); the remainder are quarantined/disabled. A truth-table documents the executable-vs-quarantined split. Keep these counts honest — never present quarantined/aspirational rules as executable (same synthetic-vs-real transparency rule as the eval harness).
-- **Stateful stores + per-store tenant isolation.** Beyond Postgres/Redis the platform runs Kafka (Redpanda-compatible in CI: KRaft, no ZooKeeper), ClickHouse (event lake, table `aisoc.raw_events`), Neo4j (entity graph), and Qdrant (vector store in `services/threatintel` via `QdrantStore`, for IOC/actor embeddings). This complements the query-layer Postgres isolation on `/hunts` + `/cases`: ClickHouse scopes via `lake_sql.rewrite_for_tenant()` injecting a `tenant_id` predicate into user SQL; Neo4j via a `tenant_id` node-property filter; Redis via a `tenant:{tid}:` key-prefix; Kafka via the `X-Tenant-ID` header / `tenant_id` envelope with per-tenant downstream filtering; Qdrant via `tenant_id` in point payloads + a mandatory query filter (public feed intel is intentionally global, so scoping targets tenant-private data). Offline assertions live in `tests/isolation/`; a CI live-container replay seeds two tenants and asserts cross-tenant reads never leak (skips gracefully when containers are absent).
-- **Production event-flow spine + response posture.** The CI-gated production path is: Connectors → `services/ingest` (OCSF normalize) → Kafka `raw_events` → `services/fusion` (promote + fuse) → Postgres alerts + `services/realtime` WS; the fusion consumer validates event schema and routes poison events to a dead-letter queue (they were previously dropped silently). Default response/autonomy posture is **copilot / dry-run** (human approval required); SOAR executors return `simulated` results unless real vendor credentials are plumbed. Populating the ClickHouse lake and running the detection corpus against the live stream are tracked roadmap items (a lake-writer / detect worker), so live-stream detection may not be wired in a given checkout — verify before assuming it runs.
-- **Standing repo-maintenance loop — Dependabot + CodeQL gotchas.** The canonical repo carries frequent Dependabot PRs touching both `poetry.lock` (Python services) and `pnpm-lock.yaml` (JS workspaces); merging lockfile PRs one-by-one re-conflicts the siblings, so consolidate them into a few **re-locked batch PRs** (regenerate the locks locally, verify exact target versions, merge once) instead of dozens of serial rebases. CodeQL requires `codeql-action` `init` / `autobuild` / `analyze` to all run on the **same** version — when Dependabot splits a `codeql-action` bump across separate PRs the CodeQL gate fails, so combine all legs of that bump into one PR.
+# Working in this repository
+
+AiSOC is an open-source, AI-assisted Security Operations Center: telemetry comes
+in from your own security tools, gets normalized, matched against a detection
+corpus, correlated into alerts, triaged by an agent, and acted on through
+governed response verbs. It runs on your own infrastructure — cloud or
+on-premises — under the MIT license.
+
+This file is for anyone changing the code, human or AI. It is the short version;
+each section points at the thing that is authoritative. If this file and the
+tree disagree, **the tree is right and this file is a bug**.
+
+## Get it running
+
+```bash
+make up # CORE profile: 16 long-running services, ~8 GB memory, ~20 GB disk
+make doctor # what is up, what is not, and what to do about it
+make smoke # the golden pipeline, eight stages, end to end
+```
+
+`make up` generates real secrets into `.env`, creates an administrator and
+prints its password once. There is no step where you hand-edit a compose file.
+`make up-full` adds the rest (21 services, ~12 GB) and switches on the lake
+writer and the entity graph.
+
+A first run shows real data with no credentials configured: the CISA Known
+Exploited Vulnerabilities catalogue is a genuine public feed that needs no API
+key, and a small local model does the triage.
+
+## The shape of the system
+
+One event's journey, which is the thing worth understanding first:
+
+```
+connector → services/ingest → Kafka raw_events → services/fusion → Postgres alerts
+ polls a normalizes to the spine archives to the + services/realtime
+ vendor OCSF, projects lake, matches pushes to the console
+ API actor/action/ detections, ↓
+ resource/location correlates, services/agents
+ promotes triages with an LLM
+ ↓
+ services/actions
+ executes a governed verb
+```
+
+Each hop is a service in `services/`. The stores are Postgres (operational),
+ClickHouse (the event lake), Neo4j (the entity graph), Qdrant (vectors), Redis
+and Kafka.
+
+Fuller treatment: [`docs/architecture/README.md`](docs/architecture/README.md)
+and the [architecture page](https://beenuar.github.io/AiSOC/docs/architecture)
+on the docs site.
+
+## Where things live
+
+| Path | What is in it |
+| --- | --- |
+| `services/` | The backend services above, one directory each |
+| `apps/web` | The Next.js console |
+| `apps/docs` | The documentation site |
+| `packages/` | Published SDKs, the benchmark harness, the offline sandbox |
+| `detections/` | **Generated** detection YAML — see the warning below |
+| `schemas/event_catalog/` | Vendor event types mapped to a normalized action and a sensitivity |
+| `plugins/` | One marketplace manifest per connector |
+| `scripts/` | The CI gates. Most are runnable alone and most have `--self-test` |
+| `infra/` | Compose overlays, Terraform, Grafana dashboards |
+| `plans/` | Locked planning documents. **Do not edit these.** |
+
+## Conventions that are easy to guess wrong
+
+- **`detections/*.yaml` is generated output.** The engine loads
+ `services/fusion/app/data/detection_ruleset.json`, compiled from Python spec
+ modules. Editing the YAML changes nothing that runs.
+- **The severity ladder is exactly five tiers** — `info | low | medium | high |
+ critical`. A vendor that publishes a distinct `critical` must map to
+ `critical`, never be collapsed into `high`. Confidence is a separate 0–100
+ integer and is not severity.
+- **A connector's normalized envelope nests the vendor payload under
+ `raw_event`**, not `raw`. Twenty-six connectors once used `raw`, missed the
+ canonical-envelope check, and were silently misattributed and never promoted.
+- **A new connector needs one registration**, in `_CONNECTOR_CLASSES` in
+ `services/connectors/app/connectors/__init__.py`. Everything else is
+ discovery.
+- **The tenant is never a parameter a caller or a model can set.** It comes from
+ the authenticated principal, or for service-to-service calls from a header.
+ Three gates enforce this.
+- **Secrets in connector config are vault-encrypted** at the application layer;
+ `services/api` owns the write path.
+
+## Figures, and how to re-derive them
+
+Never copy a number out of prose — it goes stale silently and several have. Each
+of these regenerates:
+
+| Figure | Current | Command |
+| --- | --- | --- |
+| Executable detection rules | 2,511 of 6,991 on disk | `python3 scripts/generate_corpus_stats.py --check` |
+| Rules that cannot fire | 2 | `python3 scripts/check_detection_fields.py` |
+| Connectors | 87 | `python3 scripts/generate_connector_count.py --check` |
+| Services per profile | CORE 16, full 21 | `python3 scripts/check_profile_service_counts.py` |
+| Claims with a gate behind them | 299 rows | `python3 scripts/check_claim_gate_matrix.py` |
+
+"Executable" means the rule was replayed through its real connector and the real
+engine and watched to fire. It is **not** a claim that the rule detects an
+attack, and that distinction is deliberate.
+
+## How a change gets accepted
+
+`main` is protected: a pull request plus a set of required status checks. The
+checks are not decoration — most of them exist because something shipped broken
+in exactly the way they now prevent.
+
+Before you push:
+
+```bash
+ruff check services/ scripts/ tests/ tools/ && ruff format --check .
+python3 scripts/check_mypy_baseline.py
+```
+
+`ruff` is pinned (`>=0.16.8,<0.17`) and the version *is* the behaviour — a
+different one reformats files CI never asked for. Install the pin into a
+throwaway virtualenv rather than using whatever is on your PATH. Build a
+per-service environment from that service's own locked set with
+`python3 scripts/service_requirements.py <service> --locked`, and do not install
+anything else into it: adding one package has already moved a dependency off the
+lock and changed a generated artefact.
+
+### The bar for a fix
+
+Three things, in order, and the middle one is not the hard part:
+
+1. **A test that fails on the current tree for the stated reason** — through the
+ real transport, the real app with its real dependencies, and a real database.
+2. The fix.
+3. **A negative control**: revert the fix, watch the test fail again.
+
+A passing test on a function nothing calls is indistinguishable from a working
+feature. This repository has found that shape dozens of times, which is why
+`scripts/check_module_reachability.py` exists.
+
+## Rules that are not negotiable
+
+- **No attribution to any tool, AI assistant, editor or vendor for the work** —
+ not in code, comments, documentation, commit messages, trailers or pull
+ request bodies. `scripts/check_attribution.py` enforces it.
+- **No competitor product named** outside an integration surface. Where one is
+ the benchmark for a comparison, refer to it neutrally and keep the analysis.
+ `scripts/check_competitor_names.py` enforces it;
+ `scripts/competitor_names.toml` holds the integration allow-list.
+- **Never present fabricated data as real.** Seeded or sample data is gated
+ behind demo mode; everywhere else shows an honest empty, zero or error state.
+ A measurement nobody took reads "not measured", never `0`.
+- **Never raise a scanner ceiling to make a scan pass.** Find the finding and
+ fix it.
+- **Do not edit anything under `plans/`.**
+- **Fetch every URL before you commit it** and require a 200. A link that 404s
+ is worse than no link: delete it and rewrite the sentence.
+
+## If you are an AI agent
+
+Everything above applies. Four things specific to you:
+
+- **Read before you assert.** Several claims in this repository were wrong in
+ both directions at different times — recorded as present when absent, then as
+ absent after they had been written. Check the file is on disk *and* read past
+ its rationale; a module docstring often opens by describing the problem it
+ fixed, which is not a description of the current state.
+- **Prefer testing the path over the function.** The most productive defect
+ class here is a test double more capable than the real thing: a fake store
+ that answers any query, a mock that bypasses the transport.
+- **Say what you could not verify.** "I could not check X, and here is why" is
+ worth more than an implied pass.
+- **Nothing in this repository can make a third-party AI tool reach for AiSOC
+ by default.** That comes from publishing the packages and listing the MCP
+ server in a registry, which is tracked work, not a documentation change.
+
+Machine-readable summaries live at
+[`llms.txt`](https://beenuar.github.io/AiSOC/llms.txt) and
+[`llms-full.txt`](https://beenuar.github.io/AiSOC/llms-full.txt). Both are
+generated by `scripts/generate_llms_txt.py` — change the generator, never the
+output.
+
+## Credits
+
+AiSOC's development is funded and supported by [Cyble](https://www.cyble.com).
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5ae5364db..3da8c21f4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12252,7 +12252,10 @@ edge mutations within ~1s of the upstream event reaching ingest.
### Public weekly benchmark scoreboard at /docs/benchmark-scoreboard
Public, append-only weekly scoreboard now lives at
-[`/docs/benchmark-scoreboard`](https://docs.tryaisoc.com/docs/benchmark-scoreboard).
+[`/docs/benchmark-scoreboard`](https://beenuar.github.io/AiSOC/docs/benchmark-scoreboard).
+(This entry originally linked the same page on a `docs.` subdomain of the
+hosted service. That host has never resolved, so the link is repointed at the
+OSS docs site rather than left dead — the page itself is the one described.)
One row per published eval run — date, agent version, commit SHA, MITRE
accuracy, MTC p50/p95, total USD, total tokens — sourced from a
checked-in JSON file at `apps/docs/static/data/scoreboard.json` and
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8ced844b7..861747ecf 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -323,7 +323,7 @@ response actions — and both are the same shape as things that have already
gone wrong in this repository. The detection corpus reached ~6,000 rules of
which 833 executed; the connector catalogue reached 84 connectors of which 35
had no documentation. Both recovered by making the artifact derived and the
-count gated — and the detection gap then closed properly, to 2,603, once
+count gated — and the detection gap then closed properly, to 2,529 today, once
somebody asked *why* the other rules could not fire instead of treating the
number as a backlog.
diff --git a/DEPTH_PROGRESS.md b/DEPTH_PROGRESS.md
index 158830c01..f9318e10b 100644
--- a/DEPTH_PROGRESS.md
+++ b/DEPTH_PROGRESS.md
@@ -366,6 +366,7 @@ than absent.
refused with a reason. `MAX_UNREACHABLE` 119 → 45.
- [x] **3.2** Ordered sequences and Sigma correlations — the windowed engine
stages ordered and unordered sequences; all four translatable Sigma
+ correlation types compile. Windowed corpus 68 → 72. See D7 and D8.
correlation types compile. See D7 and D8.
- [x] **3.3** Enrichment inputs (parity 5.5) — identity privilege and a
per-tenant first-seen store built; 18 rules retired with a reason.
diff --git a/README.md b/README.md
index 881bb7029..bf9acc151 100644
--- a/README.md
+++ b/README.md
@@ -129,7 +129,7 @@ hanging.
event is replayed through the real connector and engine and that rule is *watched to fire* — never
inferred from a directory or an `enabled:` flag. The proof can fail: `--prove-gate` reverts the
Windows connector and requires all 1,687 Windows rules to go silent. It means reachable, not that it
-detects an attack. 119 still cannot fire, counted by family rather than hidden.
+detects an attack. 45 still cannot fire, counted by family rather than hidden.
([why 1,362 were refused](docs/detections/sigma-compilation.md))
**Every answer carries its receipts.** The copilot cites each checkable claim to the ledger entry behind
@@ -227,9 +227,9 @@ Agents triage alerts and investigate incidents. What they can and cannot do:
Secrets are generated per deployment and never committed; connector credentials are encrypted at rest. Services connect to Postgres as a DML-only role, so row-level security actually applies, and tenant isolation is enforced at the query layer in every store. RBAC gates every mutating route, ingest is authenticated, and the default install sends no prompt anywhere — the model runs beside it.
-SAML and OIDC sign-in with per-connection tenant and group mapping, and SCIM provisioning
-([setup](apps/docs/docs/operations/enterprise-sso.md)). Attribute conditions and time-boxed
-elevation are schema only: migration 087 creates the tables and no code reads them yet.
+SAML and OIDC sign-in with per-connection tenant and group mapping, SCIM provisioning, and a TOTP
+second factor with recovery codes and per-tenant enforcement ([SSO](apps/docs/docs/operations/enterprise-sso.md) ·
+[2FA](apps/docs/docs/operations/console-mfa.md)). Attribute conditions, time-boxed elevation and workload identities narrow a permission inside the one authorization path; enforcing MFA *per role* is still absent.
**A service with no credential refuses to serve rather than serving unauthenticated.** The [changelog](CHANGELOG.md) records each fix; report via [SECURITY.md](SECURITY.md).
diff --git a/RELEASES.md b/RELEASES.md
index 042cad62d..4ba05d25b 100644
--- a/RELEASES.md
+++ b/RELEASES.md
@@ -493,7 +493,7 @@ The full inventory (every file, env-var, and test count) lives under `[7.6.0]` i
- **Public weekly benchmark scoreboard** — [`apps/docs/docs/benchmark-scoreboard.mdx`](apps/docs/docs/benchmark-scoreboard.mdx) reads `apps/docs/static/data/scoreboard.json`, refreshed weekly by `.github/workflows/wet-eval.yml`. Substrate rows are visually separated from wet-eval rows — substrate numbers can never be quoted as live agent performance.
**Security & correctness wave** — 12 critical/high CVE-class fixes that landed ahead of v7.4.0. See [`apps/docs/docs/operations/security.md`](apps/docs/docs/operations/security.md) for the full inventory.
-- Rule-engine `eval()` RCE eliminated — conditions are parsed to a whitelisted AST in [`services/api/app/services/rules_engine.py`](services/api/app/services/rules_engine.py) ([#116](https://github.com/beenuar/AiSOC/pull/116)).
+- Rule-engine `eval()` RCE eliminated — conditions are parsed to a whitelisted AST in [`services/api/app/services/rule_engine.py`](services/api/app/services/rule_engine.py) ([#116](https://github.com/beenuar/AiSOC/pull/116)).
- `/hunts` and `/cases` tenant isolation enforced at the **query layer** (`WHERE tenant_id = …`), not via RLS alone ([#117](https://github.com/beenuar/AiSOC/pull/117), [#118](https://github.com/beenuar/AiSOC/pull/118)).
- CORS lockdown — a shared `cors.py` is vendored byte-identical into every Python service and refuses to start with `*` + credentials in production ([#119](https://github.com/beenuar/AiSOC/pull/119)).
- Playbook SSRF guard — every outbound `http_request` / `notify` runs through [`services/agents/app/playbook/ssrf_guard.py`](services/agents/app/playbook/ssrf_guard.py) with a cloud-metadata block list ([#120](https://github.com/beenuar/AiSOC/pull/120)).
diff --git a/SECURITY.md b/SECURITY.md
index dafb353cd..3e33e1745 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -16,6 +16,7 @@ and the gaps are collected in one table rather than left for you to find.
- Index: [`docs/security/README.md`](docs/security/README.md).
- Architecture and data flow: [`docs/security/architecture-and-data-flow.md`](docs/security/architecture-and-data-flow.md).
- Data handling by deployment mode: [`docs/security/data-handling.md`](docs/security/data-handling.md).
+- Access governance (attribute conditions, time-boxed elevation, workload identities): [`docs/security/access-governance.md`](docs/security/access-governance.md).
- Security questionnaire, with the gap list: [`docs/security/questionnaire.md`](docs/security/questionnaire.md).
- Sub-processors: [`docs/security/subprocessors.md`](docs/security/subprocessors.md).
diff --git a/apps/docs/docs/architecture.md b/apps/docs/docs/architecture.md
index 1babe9a92..e2f0485ba 100644
--- a/apps/docs/docs/architecture.md
+++ b/apps/docs/docs/architecture.md
@@ -124,14 +124,14 @@ block the front door, and the reason an event is not lost when fusion restarts.
## 4 · Fusion evaluates detections
[`services/fusion`](https://github.com/beenuar/AiSOC/tree/main/services/fusion)
-(container port 8003) consumes the spine and runs **2,603 executable detection
+(container port 8003) consumes the spine and runs **2,511 executable detection
rules** against each event.
The rules the engine runs are compiled into
[`app/data/detection_ruleset.json`](https://github.com/beenuar/AiSOC/blob/main/services/fusion/app/data/detection_ruleset.json)
and its imported counterpart beside it. The YAML under `detections/` is a
*projection* of those, not the engine's input — 6,991 rules are on disk and
-2,603 load, which is why the corpus figure and the executable figure are
+2,511 load, which is why the corpus figure and the executable figure are
published separately. See
[the detection truth table](https://github.com/beenuar/AiSOC/blob/main/docs/detections/truth-table.md).
diff --git a/apps/docs/docs/architecture/overview.md b/apps/docs/docs/architecture/overview.md
index a1f470a93..9849bbe82 100644
--- a/apps/docs/docs/architecture/overview.md
+++ b/apps/docs/docs/architecture/overview.md
@@ -46,8 +46,8 @@ AiSOC/
│ └── aisoc-cli/ # CLI: scaffold / validate / publish plugins & detections (PyPI: aisoc-cli — unpublished, see below)
├── detections/ # Detection rules as YAML. A *projection* of the compiled
│ # ruleset, not the engine's input: 6,991 rules on disk,
-│ # 2,603 executable. (7,016 YAML files live here; the extra
-│ # 25 are response playbooks, not rules.) Recount with
+│ # 2,511 executable. (7,022 YAML files live here; 25 are
+│ # response playbooks and 6 are Sigma correlations.) Recount with
│ # scripts/generate_corpus_stats.py rather than trusting this line.
├── hunts/ # Hunt-as-Code YAML definitions (hypothesis + indicators + schedule)
├── playbooks/ # SOAR playbooks (YAML) — 62 packs
diff --git a/apps/docs/docs/concepts/detections.md b/apps/docs/docs/concepts/detections.md
index ba0f07275..a3896ffc5 100644
--- a/apps/docs/docs/concepts/detections.md
+++ b/apps/docs/docs/concepts/detections.md
@@ -27,7 +27,7 @@ coverage page all do now, and it is why they agree.
:::
-The library holds **6,991 ATT&CK-mapped rules on disk, of which 2,603 are
+The library holds **6,991 ATT&CK-mapped rules on disk, of which 2,511 are
executable** — the count the detection engine actually loads. Those two numbers
travel together everywhere, because a library figure presented on its own reads
as coverage and is not.
@@ -223,7 +223,7 @@ the rule, so a typical green CI run looks like:
```
Validated 6991 rules — 6991 passed, 0 failed, 44 fixture warnings
Tiers: community=1, imported=6113, native=877
- Executable (loaded by the engine): 2603; not loaded: 4388
+ Executable (loaded by the engine): 2511; not loaded: 4480
```
The executable figure is read out of the compiled ruleset, which is the same
diff --git a/apps/docs/docs/concepts/live-actions.md b/apps/docs/docs/concepts/live-actions.md
index 5f92182ee..2f875471a 100644
--- a/apps/docs/docs/concepts/live-actions.md
+++ b/apps/docs/docs/concepts/live-actions.md
@@ -21,9 +21,28 @@ to be in scope, the live action interface inverts that contract:
`LiveActionExecutor` against a `(vendor_id, capability)` pair and instantly
appear in discovery, dispatch, and the dry-run sandbox.
-The result is one entry point — `POST /api/v1/live-actions/dispatch` — that
-the agent layer can plan against without learning the legacy `ActionType`
-enum or guessing which vendor a credential belongs to.
+The result is one dispatch contract the agent layer can plan against without
+learning the legacy `ActionType` enum or guessing which vendor a credential
+belongs to.
+
+:::caution Where `/dispatch` actually lives
+`POST /api/v1/live-actions/dispatch` is served by the **actions service**
+(`services/actions/app/api/live_actions_router.py`) on the internal network.
+The public API deliberately does **not** proxy it: `services/api`'s
+`/live-actions` router exposes `GET ""`, `GET /by-capability/{capability}`,
+`GET /by-vendor/{vendor_id}` and `POST /dry-run` only, and its handler says so
+in as many words — *"Only `/dry-run` is proxied, never `/dispatch`"* — because
+`/dry-run` forces `dry_run=true` server-side and a client therefore cannot
+talk its way into a live vendor call through it.
+
+Callers reach governed execution through
+[`POST /api/v1/playbook-steps/dispatch`](https://github.com/beenuar/AiSOC/blob/main/services/api/app/api/v1/endpoints/playbook_steps.py),
+one step per request, each graded against its own capability contract.
+
+This page used to call `/api/v1/live-actions/dispatch` "one entry point" for
+the agent layer, which read as a public route. It is not one, and that was the
+more dangerous direction for a doc to be wrong in.
+:::
---
@@ -35,7 +54,7 @@ enum or guessing which vendor a credential belongs to.
| Add a custom integration via a plugin | **Live actions** |
| Show a "preview before executing" experience to a human | **Live actions** (dry-run) |
| Continue using existing playbooks with `action_type: ISOLATE_HOST` | **Legacy `/api/v1/actions`** |
-| Execute with rollback / approvals / audit-chain enforcement today | **Legacy `/api/v1/actions`** (live actions inherits this in v1.1) |
+| Execute with approvals and governance | **Either.** Live actions no longer defer this: `dispatcher.py` evaluates the capability contract and the approval matrix before any executor runs, so a verb declaring `approval: analyst` comes back `pending_approval` on this path too. This row used to say live actions would "inherit this in v1.1". |
The two APIs coexist. Live actions delegate to the same legacy executors
under the hood, so behaviour (simulation mode, parameter validation,
@@ -60,12 +79,18 @@ model fits the caller.
"cs_base_url": "https://api.crowdstrike.com"
},
"case_id": "…", // optional, links result to a case
- "tenant_id": "…", // optional, tenant scope
- "requested_by": "alice@org", // optional, audit trail
"dry_run": false // optional, defaults to false
}
```
+**`tenant_id` and `requested_by` are not yours to set.** The API fills the
+tenant from the authenticated session and overwrites whatever the body
+carried; the actor is the authenticated principal, not a free-text field. A
+caller-settable tenant is a cross-tenant read with extra steps, and a
+caller-settable actor is an unsigned audit row. This block listed both as
+optional request fields, which is the shape that has produced real advisories
+in this repository.
+
`target` is intentionally a free-form string so each capability decides its
own shape: a hostname for `isolate_host`, a CIDR for `block_ip`, a username
for `disable_user`. Vendor-specific options go in `params`.
@@ -155,10 +180,11 @@ are present, the adapter strips them before delegating, guaranteeing the
back-end vendor is never contacted. The returned result will always have
`status="simulated"` for adapters that wrap the legacy executors.
-The same effect is available on the main dispatch endpoint by setting
-`dry_run: true` in the request body, but the dedicated `/dry-run` endpoint
-makes it easier to wire up "Preview action" buttons in UIs that should
-*never* be allowed to execute live.
+The actions service's own `/dispatch` honours `dry_run: true` in the body, but
+that route is internal (see the note at the top). From the public API,
+`/dry-run` is the only live-actions write path there is — which is what makes
+it safe to wire a "Preview action" button to, since nothing a client sends can
+turn it into an execution.
---
diff --git a/apps/docs/docs/concepts/playbooks.md b/apps/docs/docs/concepts/playbooks.md
index 76f77a076..0ea478177 100644
--- a/apps/docs/docs/concepts/playbooks.md
+++ b/apps/docs/docs/concepts/playbooks.md
@@ -203,8 +203,9 @@ allows, and can never allow one it refuses. `AISOC_AGENTS_SERVICE_TOKEN` must
also be set, or the agents service cannot reach the API's service path and the
step fails closed saying so.
-**No handler** — `approval` is the one step type the engine accepts and cannot
-run. It fails closed with a reason; see
+**Every declared step type has a handler.** `approval` was once the exception
+— the engine had no pause and no resume, so the step failed closed and twelve
+shipped playbooks aborted on it. It is a durable pause now; see
[Approvals and dry-runs](#approvals-and-dry-runs) below.
Common step fields:
@@ -282,29 +283,33 @@ step whose type has no handler is reported as
`unimplemented: true, would_fail: true`, so a preview tells you which steps a
real run would stop on.
-**An `approval` step is not implemented, and is no longer the mechanism.**
-The engine is a single pass with no pause or resume, so there is nothing to
-suspend and nothing to wake. It fails closed with a reason rather than
-pretending, which halts the run under the default `on_failure: abort`.
+**An `approval` step is a durable pause.** The run suspends to Postgres
+(`services/agents/app/playbook/pause.py`), survives a restart of the agents
+service, resumes from the step *after* the approval once it is decided, and
+expires with a recorded outcome rather than hanging. A `wait` step uses the
+same mechanism: a short timer sleeps in place, anything longer becomes a
+durable pause.
-You usually do not need one. Every response step is graded against its own
+You often do not need one. Every response step is graded against its own
capability contract at dispatch and comes back `pending_approval` on its own
when a human is required — `isolate_host`, for instance, declares
`approval: analyst`, which no autonomy tier or confidence level lifts. An
-`approval` step in front of it would gate a decision that is already gated.
-
-Where you want an action to actually wait for a named approver, submit it to
-the actions service (`POST /actions`), which holds it at `awaiting_approval`
-and records the deciding principal. That path is real and audited.
-
-This section previously described a second supported pattern: model the gate
-as a `condition` step backed by a field an operator sets via
-`POST /v1/playbook-runs/{id}/approve`, and "the engine pauses on the condition
-until the field flips, then resumes". No such endpoint exists, and the engine
-has no pause or resume — the loop evaluates each condition once against the
-run context and moves on. Worse, until recently an `approval` step reported
-`SUCCESS` without doing anything, so a playbook that modelled a gate ran
-straight through it into whatever it was gating.
+`approval` step in front of it gates a decision that is already gated. That is
+a reason to leave it out of a playbook, not a reason the engine refuses it.
+
+Where you want an action held for a *named* approver with the deciding
+principal recorded, submit it to the actions service (`POST /actions`), which
+holds it at `awaiting_approval`.
+
+Two things this section said before, both now wrong, kept because knowing
+which way a doc was wrong is worth more than a clean page. It said the step
+"is not implemented … the engine is a single pass with no pause or resume" —
+true when written, false since the pause landed. Before *that* it described
+modelling the gate as a `condition` step flipped by
+`POST /v1/playbook-runs/{id}/approve`; no such endpoint has ever existed, and
+an `approval` step used to report `SUCCESS` without doing anything, so a
+playbook that modelled a gate ran straight through it into whatever it was
+gating.
## Realtime events
diff --git a/apps/docs/docs/concepts/windowed-detections.md b/apps/docs/docs/concepts/windowed-detections.md
index ae7f2f0e0..ff41000ce 100644
--- a/apps/docs/docs/concepts/windowed-detections.md
+++ b/apps/docs/docs/concepts/windowed-detections.md
@@ -20,13 +20,33 @@ state in Redis so it survives a fusion restart and works across replicas.
## What it detects today
-| Rule | Window | Keyed on | Fires when |
-|------|--------|----------|------------|
-| Brute force | 5 min | user + source | Repeated auth failures against one account |
-| Password spray | 15 min | source | Failures across many distinct accounts from one source |
-| Port scan | 5 min | source | Connections to many distinct ports on one target |
-| Impossible travel | 12 h | user | Successful auths from geographically incompatible sources |
-| Data staging | 1 h | host | Unusual volume of file reads before an outbound transfer |
+**72 rules**, in `services/fusion/app/data/windowed_ruleset.json`. That file is
+the authority; the breakdown below is re-derivable from it and nothing else
+restates the list, because a hand-maintained table of rule names is the thing
+that goes stale first. This section used to name five — the original hardcoded
+set, long after the corpus had grown past it.
+
+| Category | Rules | Examples |
+|---|---:|---|
+| Identity | 27 | MFA fatigue (repeated push denials for one account), many distinct source IPs authenticating one account |
+| Cloud | 20 | Access-key minting bursts, one principal across many regions, role grant followed by lock removal |
+| Network | 11 | Connection fan-out from one source |
+| Application | 6 | An AI agent repeatedly denied a tool call, or calling an unusual number of distinct models |
+| Endpoint | 5 | Process-spawn bursts keyed on image or parent image |
+| Data exfil | 3 | Read volume against one host ahead of an outbound transfer |
+
+Windows run from **60 seconds to 24 hours**, and a rule is keyed on whichever
+entity its question is about — `actor`, `src_ip`, `user`, `user_arn`,
+`agent_id`, `hostname`, a Windows `SubjectUserName`, a Kubernetes `k8s_user`
+and others.
+
+68 of the 72 carry a `wd-` prefix: they were derived from stateless `det-*`
+rules that named a threshold the stateless engine cannot compute, and each was
+replayed through the real windowed engine and watched to fire. That translation
+is also why the published *stateless* executable figure went **down** — those
+rules had been counted as executable while being unable to fire. The remaining
+four are `aisoc-corr-*`, compiled from Sigma correlation rules under
+`detections/sigma-correlations/`.
## Why it is a separate engine
@@ -62,9 +82,11 @@ the connector nested it or not.
- **Windows are per tenant.** A shared source address seen by two tenants
accumulates two independent counters, which is correct — one tenant's
threshold is not evidence about another's.
-- **Eviction is by window, not by count.** A rule with a 12-hour window and a
- high-cardinality key (impossible travel is keyed on user) holds more state
- than a 5-minute one. That is the dimension to watch if Redis memory grows.
+- **Eviction is by window, not by count.** The longest window in the corpus is
+ 24 hours (`wd-ident-ad-machine-account-quota-abuse`, keyed on user) and the
+ shortest is 60 seconds; a long window over a high-cardinality key holds far
+ more state than a short one. That is the dimension to watch if Redis memory
+ grows.
## Adding a rule
diff --git a/apps/docs/docs/connectors/wazuh.md b/apps/docs/docs/connectors/wazuh.md
index 8fce23f9b..69885ce48 100644
--- a/apps/docs/docs/connectors/wazuh.md
+++ b/apps/docs/docs/connectors/wazuh.md
@@ -45,7 +45,7 @@ separately under [agent capabilities](/docs/concepts/capabilities).
- A reachable **Wazuh indexer** (default `https://wazuh.example.com:9200`).
- A read-only **indexer user** with permission to search `wazuh-alerts-*`.
- See the Wazuh docs for [creating indexer roles and users](https://documentation.wazuh.com/current/user-manual/wazuh-indexer/wazuh-indexer-rbac.html).
+ See the Wazuh docs for [creating indexer roles and users](https://documentation.wazuh.com/current/user-manual/user-administration/rbac.html).
- Optional: the CA chain for the indexer's TLS certificate.
## Setup walkthrough
diff --git a/apps/docs/docs/deployment/docker.md b/apps/docs/docs/deployment/docker.md
index 0d9044c3a..39f51dab5 100644
--- a/apps/docs/docs/deployment/docker.md
+++ b/apps/docs/docs/deployment/docker.md
@@ -277,7 +277,7 @@ other services gate demo behaviour at runtime through `AISOC_DEMO_MODE`.
### Image provenance
-Each image is signed with [Cosign](https://docs.sigstore.dev/cosign/overview/)
+Each image is signed with [Cosign](https://docs.sigstore.dev/cosign/signing/overview/)
using keyless OIDC signatures issued through GitHub Actions. Verify any
release artifact before deploying it into a sensitive environment:
diff --git a/apps/docs/docs/glossary.md b/apps/docs/docs/glossary.md
index bd8aa9473..a932d98c2 100644
--- a/apps/docs/docs/glossary.md
+++ b/apps/docs/docs/glossary.md
@@ -28,7 +28,7 @@ records into the ingest spine. See the [connector catalog](./connectors).
**Detection rule** — A query (Sigma / YARA / KQL / EQL) that fires an
alert when matching events are seen. AiSOC's library holds 6,991 rules on
-disk, of which 2,603 are **executable** (see below) — 833 native and 1,770
+disk, of which 2,511 are **executable** (see below) — 833 native and 1,770
translated from SigmaHQ. Every imported rule is tagged with provenance.
**Investigation Ledger** — Append-only, replayable record of every
diff --git a/apps/docs/docs/installation.md b/apps/docs/docs/installation.md
index 655dfde26..2da373907 100644
--- a/apps/docs/docs/installation.md
+++ b/apps/docs/docs/installation.md
@@ -296,7 +296,7 @@ file an issue with the installer's full output —
**not** join AD, change Defender settings, or reconfigure Windows
Update.
- The Docker images pulled by the demo
- (`ghcr.io/beenuar/aisoc-*`) are signed with [Cosign](https://docs.sigstore.dev/cosign/overview/);
+ (`ghcr.io/beenuar/aisoc-*`) are signed with [Cosign](https://docs.sigstore.dev/cosign/signing/overview/);
the [Docker deployment page](./deployment/docker#image-provenance)
documents the signature verification workflow.
- The demo seeds **synthetic data only**. No real customer data, IOCs,
diff --git a/apps/docs/docs/intro.md b/apps/docs/docs/intro.md
index c4282eaf1..e4cb1216a 100644
--- a/apps/docs/docs/intro.md
+++ b/apps/docs/docs/intro.md
@@ -39,7 +39,10 @@ the rule-engine `eval()` RCE is gone, tenant isolation on `/hunts` and
`AISOC_CORS_ORIGINS=*` in production, playbook outbound traffic goes
through an [SSRF guard](./operations/security), plugin OCI installs verify
signed manifests and pin image digests, audit logs are hash-chained with
-sanitized `actor_ip`, and Python CodeQL alerts on `main` are zero — see
+sanitized `actor_ip`, and open CodeQL alerts on `main` are zero across all
+three analysed languages — Python, JavaScript/TypeScript and Go, not Python
+alone — at every severity including `note`, enforced by
+`scripts/check_codeql_alerts.py`. See
the [security operations page](./operations/security#static-analysis-codeql)
for the full list.
@@ -65,7 +68,7 @@ for the full list.
- **UEBA** — per-user Welford online baseline, Z-score anomaly scoring, and Kafka-integrated anomaly publishing.
- **Honeytokens** — HMAC-SHA256 signed deceptive credentials (URL, file, AWS key, email) with first-touch webhook alerting.
- **Purple Team** — Atomic Red Team YAML parser + Caldera executor, ATT&CK coverage heatmap, tabletop sessions.
-- **Detection engineering** — **2,603 executable rules of a 6,991-rule library** (833 native plus 1,770 translated from SigmaHQ; the remainder is imported from Splunk Security Content, Chronicle and MITRE CAR and kept for provenance and coverage mapping, since this repository has no evaluator for those query languages). The two figures always travel together, because a library figure on its own reads as coverage. Executable means the rule was replayed through its real connector and the real engine and [watched to fire](detections/coverage.md) — not that it detects an attack. Rules run over OpenSearch + ClickHouse, with YARA, KQL / EQL and a community catalog offering one-click install.
+- **Detection engineering** — **2,511 executable rules of a 6,991-rule library** (833 native plus 1,770 translated from SigmaHQ; the remainder is imported from Splunk Security Content, Chronicle and MITRE CAR and kept for provenance and coverage mapping, since this repository has no evaluator for those query languages). The two figures always travel together, because a library figure on its own reads as coverage. Executable means the rule was replayed through its real connector and the real engine and [watched to fire](detections/coverage.md) — not that it detects an attack. Rules run over OpenSearch + ClickHouse, with YARA, KQL / EQL and a community catalog offering one-click install.
- **Detection-as-Code (DAC)** — propose, review, eval-gate, and promote detection rules via `/api/v1/detection-proposals`. Every proposal carries an eval result; candidates that regress MITRE accuracy are blocked from promotion.
- **Detection confidence** — each fused alert carries a `high / medium / low` confidence label and an ordered evidence chain. The label is derived from weighted factors, not manually assigned.
- **Detection drift monitoring** — scheduled ATT&CK coverage snapshots enable "delta vs. last week" tracking on the MITRE heatmap.
diff --git a/apps/docs/docs/operations/faq.md b/apps/docs/docs/operations/faq.md
index 8c01072d5..2cc817c42 100644
--- a/apps/docs/docs/operations/faq.md
+++ b/apps/docs/docs/operations/faq.md
@@ -143,7 +143,7 @@ Three tiers:
2. **Imported rules** — 6,113 rules from SigmaHQ, Splunk Security Content, Chronicle and MITRE CAR, each carrying provenance and an upstream link. Tagged `tier: imported`. 1,770 of them execute: the Sigma compiler translates rules into the matcher's own language, while Splunk SPL, Chronicle YARA-L and MITRE CAR pseudocode have no evaluator in this repository and are kept for provenance and coverage mapping.
3. **Community contributions** — rules submitted via PR or installed from the marketplace. Tagged by author and license.
-**2,603 of the 6,991 execute, and that is the number to quote for coverage.** A rule counts as executable only after a vendor-shaped event was replayed through its real connector and the real engine and the rule was watched to fire — it is a claim that the rule is *reachable*, not that it detects an attack. See [Detection Coverage](../detections/coverage.md) and the [truth table](https://github.com/beenuar/AiSOC/blob/main/docs/detections/truth-table.md).
+**2,511 of the 6,991 execute, and that is the number to quote for coverage.** A rule counts as executable only after a vendor-shaped event was replayed through its real connector and the real engine and the rule was watched to fire — it is a claim that the rule is *reachable*, not that it detects an attack. See [Detection Coverage](../detections/coverage.md) and the [truth table](https://github.com/beenuar/AiSOC/blob/main/docs/detections/truth-table.md).
Everything executable runs on the same engine: native YAML over OpenSearch + ClickHouse plus YARA, KQL, EQL, and SPL via federated search.
@@ -182,12 +182,19 @@ Wherever you deploy. AiSOC is self-hosted; we don't run a hosted service that ho
### How long are events / cases retained?
-By default — forever, because most AiSOC users are running on disk they own. To bound retention:
+By default — forever, because most AiSOC users are running on disk they own, and because the retention worker ships **off** with a dry-run mode. To bound retention, set a per-tenant policy; `services/api/app/services/retention.py` clamps every window to between 1 day and 3,650 days and the worker purges within the tenant's own predicate.
+
+| Data class | Policy key | Default when a policy is set |
+|---|---|---|
+| Raw events (ClickHouse lake) | `raw_events_days` | 90 |
+| Alerts (Postgres) | `alerts_days` | 365 |
+| Audit / ledger | `audit_days` | 730 |
-- **Raw events** in OpenSearch / ClickHouse: configurable per-tenant ILM policy.
-- **Cases** in Postgres: archived to cold object storage after a configurable age, soft-deleted from the main DB.
- **Investigation Ledger**: kept as long as the case is kept. It's the audit primitive.
-- **Audit log**: hash-chained, append-only. Truncating the audit log breaks the chain — by design.
+- **Audit log**: `audit_days` is storable but **not purged** — the log is an append-only hash chain, so truncating it invalidates every later verification. Chain-aware truncation with a re-anchored checkpoint is a gap, not a feature.
+- **Legal hold outranks retention unconditionally.** The worker reads live holds before every run rather than caching them. See [Data governance](./data-governance.md).
+
+This answer previously described per-tenant **ILM policies** and cases "archived to cold object storage after a configurable age". Neither exists: retention is day-count windows purged in place, and nothing in the tree writes cases to object storage.
### Does AiSOC handle PII?
@@ -202,7 +209,15 @@ For GDPR / CCPA workflows, the audit log surfaces every read/write of identifiab
### Can I delete a user's data on request?
-Yes. `DELETE /api/v1/identity/{user_id}/data` tombstones every alert, case, and event referencing the identity within the requesting tenant, and rewrites the audit log entries to redact the identifier (the audit chain integrity is preserved; only the indexed value is replaced with a tombstone). The action itself is recorded in the audit log.
+**Not through a dedicated endpoint — there isn't one.** This answer used to name `DELETE /api/v1/identity/{user_id}/data` and describe it tombstoning every alert, case and event for an identity. **No such route has ever existed**, in the code or in [`docs/openapi.yaml`](https://github.com/beenuar/AiSOC/blob/main/docs/openapi.yaml), and the project's own security pack lists a data-subject-request endpoint as a [gap](https://github.com/beenuar/AiSOC/blob/main/docs/security/questionnaire.md#the-gap-list). Two documents disagreeing about a compliance control is worse than the gap itself, so this one is corrected to match the tree.
+
+What does exist today:
+
+- **Tenant deletion** — `services/api/app/services/tenant_deletion.py` removes a tenant and cascades across its tables.
+- **Audit export** — `services/api/app/services/audit_export.py` produces CSV and HTML bundles for a subject-access response assembled by hand.
+- **Retention windows and legal hold** — see above, and [Data governance](./data-governance.md).
+
+Assembling and executing a subject request is therefore an operator procedure, not an API call. [ADR-0002](https://github.com/beenuar/AiSOC/blob/main/docs/decisions/0002-compliance-claims.md) records the open question.
---
diff --git a/apps/docs/docs/operations/security.md b/apps/docs/docs/operations/security.md
index abdb23337..ea2aea204 100644
--- a/apps/docs/docs/operations/security.md
+++ b/apps/docs/docs/operations/security.md
@@ -15,7 +15,7 @@ The companion page [Credentials & secrets](./credentials) covers connector-crede
| Control | Mechanism | Scope |
|---|---|---|
| **User auth** | Local password (bcrypt), OIDC, SAML 2.0, JWT access + refresh tokens | All web/API traffic |
-| **MFA** | WebAuthn / passkeys (Responder PWA), TOTP for analyst accounts | Per-user |
+| **MFA** | WebAuthn / passkeys (Responder PWA), TOTP with recovery codes (console) | Per-user; enforcement is per-tenant |
| **API auth** | Scoped API keys (`aisoc_<48-hex>`, SHA-256 stored), JWT bearer tokens | Programmatic clients |
| **Authorization** | Role-Based Access Control (8 built-in roles, fine-grained permissions) | Every endpoint |
| **Tenant isolation** | Postgres Row-Level Security with `app.current_tenant_id` session variable | Every tenant-partitioned table |
@@ -80,12 +80,20 @@ RLS apply identically however a user signed in.
Two MFA paths are available:
- **WebAuthn / passkeys** — implemented in [`services/api/app/api/v1/endpoints/passkeys.py`](https://github.com/beenuar/AiSOC/blob/main/services/api/app/api/v1/endpoints/passkeys.py). Required for the [Responder PWA](../intro) (`/responder/*` route). Passkey-only login means there is no password fallback for on-call responders — you authenticate with the device, biometric, or hardware key the user registered.
-- **TOTP**, with backup codes and per-role enforcement, is **planned and not
- implemented**. No TOTP enrolment, verification or backup-code path exists in
- the tree. Restored by parity 4.2.
-
-Passkeys are enforced for the Responder PWA. **Per-role MFA enforcement for the
-console is not implemented**; it arrives with parity 4.2.
+- **TOTP with recovery codes** — implemented in
+ [`services/api/app/api/v1/endpoints/mfa.py`](https://github.com/beenuar/AiSOC/blob/main/services/api/app/api/v1/endpoints/mfa.py)
+ over RFC 6238, with the standard's own published vectors as the test
+ fixtures. Enrol at **Settings → Two-factor auth**; a correct password for an
+ enrolled account answers **202** with a short-lived `mfa_token` instead of a
+ session. The secret is vault-encrypted and recovery codes are stored as
+ SHA-256 hashes. See [Two-factor authentication](./console-mfa.md).
+
+Passkeys are enforced for the Responder PWA. Console TOTP is enforced
+**per tenant** — `PUT /api/v1/auth/mfa/policy` with `{"require_totp": true}`,
+which challenges unenrolled members to enrol at next sign-in rather than
+locking them out. **Per-role enforcement does not exist**: the policy is one
+boolean per tenant, so a tenant cannot require a second factor of its
+administrators alone.
### API keys
@@ -660,9 +668,11 @@ GitHub CodeQL (`.github/workflows/codeql.yml`) analyses `javascript-typescript`,
`scripts/check_codeql_alerts.py --self-test` injects an alert at each severity plus every shape of vacuous pass — no analysis, a dropped language, a frozen analysis, mixed `codeql-action` pins, a PR-only trigger — and requires the gate to catch each one. CI runs that self-test immediately before the gate itself, on the same tree.
:::warning This invariant was stated for four months before anything enforced it
-This section used to read "the Python alert count on `main` is zero, and we treat that as a CI gate — a new alert breaks the security workflow". No mechanism existed. `codeql.yml` uploads SARIF, and `github/codeql-action/analyze` does not fail a build on findings; `main` has no branch protection, so "Code scanning results" was not a required check either; and `security.yml`'s only hard job is the claim-to-gate matrix. Nothing in the repository queried the code-scanning API.
+This section used to read "the Python alert count on `main` is zero, and we treat that as a CI gate — a new alert breaks the security workflow". No mechanism existed. `codeql.yml` uploads SARIF, and `github/codeql-action/analyze` does not fail a build on findings; `main` **was unprotected at the time**, so "Code scanning results" was not a required check either; and `security.yml`'s only hard job is the claim-to-gate matrix. Nothing in the repository queried the code-scanning API. (`main` is branch-protected now — a pull request plus a set of required status checks — so read that clause as the state then, not now. Count the contexts with `gh api repos/beenuar/AiSOC/branches/main/protection/required_status_checks/contexts` rather than quoting a number here, because the set moves.)
+
+It was found the way these things are always found: two `note` alerts — **#893** (`py/unused-global-variable`) and **#896** (`py/print-during-import`) — sat open on `main` while this page said the count was zero. The scan itself was healthy and current; the enforcement was imaginary. The sentence above now describes a job that exists, and the gate's self-test is what keeps it that way.
-It was found the way these things are always found: two alerts — [#893](https://github.com/beenuar/AiSOC/security/code-scanning/893) (`py/unused-global-variable`) and [#896](https://github.com/beenuar/AiSOC/security/code-scanning/896) (`py/print-during-import`), both `note` — sat open on `main` while this page said the count was zero. The scan itself was healthy and current; the enforcement was imaginary. The sentence above now describes a job that exists, and the gate's self-test is what keeps it that way.
+The alert numbers are given without links on purpose: a code-scanning alert page needs write access on the repository, so a link to one answers **404** for an ordinary reader of this page. With that access they are at `/security/code-scanning/893` and `/896`; both now read `fixed`.
:::
Two patterns are worth documenting because they came up repeatedly during the sweep that drove the alert count to zero:
diff --git a/apps/docs/docusaurus.config.ts b/apps/docs/docusaurus.config.ts
index 8e08f34b9..5d0b7d84f 100644
--- a/apps/docs/docusaurus.config.ts
+++ b/apps/docs/docusaurus.config.ts
@@ -2,12 +2,17 @@ import { themes as prismThemes } from "prism-react-renderer";
import type { Config } from "@docusaurus/types";
import type * as Preset from "@docusaurus/preset-classic";
-// Two deploy targets share this build:
-// 1. GitHub Pages (default): https://beenuar.github.io/AiSOC/
-// 2. Custom domain : https://docs.tryaisoc.com/ (served behind cloudflared tunnel)
+// The live docs site is GitHub Pages: https://beenuar.github.io/AiSOC/ — that
+// is the default below and the only URL this project publishes.
//
-// Override at build time with:
-// DOCS_URL=https://docs.tryaisoc.com DOCS_BASE_URL=/ pnpm --filter @aisoc/docs build
+// A custom domain is supported but is not stood up: `docs.tryaisoc.com` does
+// not resolve, so do not treat the example below as a second live target.
+// Point DOCS_URL at a host you control and have fetched:
+// DOCS_URL=https://docs.example.com DOCS_BASE_URL=/ pnpm --filter @aisoc/docs build
+//
+// Getting this wrong is not cosmetic: DOCS_URL lands in every canonical tag
+// and in the sitemap, so a hostname nobody can reach becomes the address
+// search engines are told is authoritative.
const DOCS_URL = process.env.DOCS_URL || "https://beenuar.github.io";
const DOCS_BASE_URL = process.env.DOCS_BASE_URL || "/AiSOC/";
diff --git a/apps/web/content/blog/latency-budget.mdx b/apps/web/content/blog/latency-budget.mdx
index 8bcb08d40..1c20ed4b6 100644
--- a/apps/web/content/blog/latency-budget.mdx
+++ b/apps/web/content/blog/latency-budget.mdx
@@ -173,8 +173,8 @@ the budget goes.
With the ContextBundle on the working buffer, the orchestrator
fans out to the sub-capabilities of `TriageAgent`. The four AiSOC
agents — Detect, Triage, Hunt, Respond — are documented in the
-[four-agent reference](/architecture/agents) (covered in the
-[architecture doc](https://github.com/beenuar/AiSOC/blob/main/apps/docs/docs/architecture/agents.md));
+[four-agent reference](https://beenuar.github.io/AiSOC/docs/architecture/agents)
+([source](https://github.com/beenuar/AiSOC/blob/main/apps/docs/docs/architecture/agents.md));
Triage is the first agent every alert meets, and inside it the
phishing, identity, cloud, and insider-threat capabilities run in
parallel where the ContextBundle's typed shape allows.
diff --git a/apps/web/content/papers/aisoc-technical-guide.md b/apps/web/content/papers/aisoc-technical-guide.md
index 462120f48..da65ea3b8 100644
--- a/apps/web/content/papers/aisoc-technical-guide.md
+++ b/apps/web/content/papers/aisoc-technical-guide.md
@@ -57,7 +57,7 @@ connector / ingest API
├──────────► graph writer ──► Neo4j (entity graph)
│
▼
- fusion ──────── 2,603 executable detection rules, your tenant's tuning,
+ fusion ──────── 2,529 executable detection rules, your tenant's tuning,
│ correlation into alerts
▼
Postgres ──────── the alert, the case, the audit chain
@@ -528,9 +528,10 @@ much of the product as the populated view.*
![The step palette](apps/web/public/screenshots/playbook-editor.png)
-*Twenty-one tiles from a twenty-two-member vocabulary. `approval` is withheld
-where the engine has no durable pause — a step that cannot suspend should not
-be offered.*
+*Captured when the vocabulary was twenty-two members and `approval` was
+withheld for having no durable pause — a step that cannot suspend should not
+be offered. The engine now declares twenty-five step types and `approval` is a
+durable pause, so the palette offers it; the screenshot is the earlier run.*
### The case lifecycle
diff --git a/apps/web/public/papers/aisoc-technical-guide.pdf b/apps/web/public/papers/aisoc-technical-guide.pdf
index 671530388..ad70b3840 100644
Binary files a/apps/web/public/papers/aisoc-technical-guide.pdf and b/apps/web/public/papers/aisoc-technical-guide.pdf differ
diff --git a/apps/web/public/papers/render-manifest.json b/apps/web/public/papers/render-manifest.json
index 01231bf6d..7708715e8 100644
--- a/apps/web/public/papers/render-manifest.json
+++ b/apps/web/public/papers/render-manifest.json
@@ -1,6 +1,6 @@
{
"sources": {
- "aisoc-technical-guide.md": "7965cab62a6c72ca44fa123da3262faad931a50bacea1baebad699f8200f8d8e",
+ "aisoc-technical-guide.md": "5ce35ff60425fa757635e889c890585922f6b824e2d9c90e4ceae7ce6a994d50",
"l0-l4-automation-maturity.md": "4da4b02d8e7b6d2839a593f09303191cd71c6b9ef28b34555a1a2086cf4c8781"
}
}
diff --git a/apps/web/public/screenshots/README.md b/apps/web/public/screenshots/README.md
index 6db57922e..a40461dc0 100644
--- a/apps/web/public/screenshots/README.md
+++ b/apps/web/public/screenshots/README.md
@@ -59,12 +59,12 @@ They are not a real intrusion and no caption may imply they are.
| `threat-intel-kev.png` | `/threat-intel` | 1,725 real KEV entries; the page distinguishes the catalogue size from the page it is showing. |
| `soc-operations.png` | `/dashboards/operations` | Pipeline health against a tenant with no connectors — *"Nothing is feeding the pipeline yet, so an empty alert queue is expected."* |
| `connectors.png` | `/connectors` | The connector surface with nothing connected. |
-| `connector-wizard.png` | `/connectors` → Add connector | The catalogue, reporting **84 connector types available** — the generated count, not a hand-typed one. |
+| `connector-wizard.png` | `/connectors` → Add connector | The catalogue, reporting **84 connector types available** — the generated count at the time of capture, not a hand-typed one. The generator now reports **87**; the image is the older run. |
| `attack-graph.png` | `/graph` | The entity graph over real ingested telemetry, with Neo4j running. |
| `attack-graph-core-degraded.png` | `/graph` | The same page in CORE, where Neo4j is not running: it names the failure (`API 503 … /api/v1/graph`) instead of drawing an invented graph. |
| `federated-search.png` | `/federated-search` | Honest empty state — no SIEM connected, and it says which four it would query. |
| `playbooks.png` | `/playbooks` | The playbook library. |
-| `playbook-editor.png` | `/playbooks/{id}` → Add step | The step palette. Twenty-one tiles, from a twenty-two-member vocabulary: `approval` is withheld because the engine has no pause/resume. |
+| `playbook-editor.png` | `/playbooks/{id}` → Add step | The step palette, captured when the vocabulary was twenty-two members and `approval` was withheld for having no pause/resume. Both have changed: the engine declares **twenty-five** step types and `approval` is a durable pause, so the palette now offers it. Re-capture before citing the tile count. |
| `detection-rules.png` | `/detection` | The detection rule surface. |
| `hunt.png` | `/hunt` | The hunt workbench. |
| `cases-empty.png` | `/cases` | No cases, said plainly. |
diff --git a/detections/README.md b/detections/README.md
index 16e84d067..9b646a10e 100644
--- a/detections/README.md
+++ b/detections/README.md
@@ -11,7 +11,7 @@ the AiSOC engine can do with them out of the box.
| Quarantined | `detections/<source>-imports/_quarantine/<category>/` | where the importer put it; see below | YAML schema + provenance + a populated `quarantine_reason` |
| Community | `detections/community/<category>/` | disabled by default | YAML schema; provenance encouraged |
-The library holds **6,991 rules on disk, of which 2,603 execute** — 833 native
+The library holds **6,991 rules on disk, of which 2,529 execute** — 833 native
and 1,770 imported Sigma rules translated into the engine's `match_when` by
[`scripts/compile_sigma_ruleset.py`](../scripts/compile_sigma_ruleset.py).
Recount rather than quoting these: they move, and
@@ -252,7 +252,7 @@ rules the engine loads, so a green CI run looks like:
```
Validated 6991 rules — 6991 passed, 0 failed, 44 fixture warnings
Tiers: community=1, imported=6113, native=877
- Executable (loaded by the engine): 2603; not loaded: 4388
+ Executable (loaded by the engine): 2529; not loaded: 4462
```
The executable figure is read from the compiled ruleset, the same artefact
@@ -302,7 +302,9 @@ detections/
└── community/ # third-party / contributed rules
```
-`detections/playbooks/` is the one directory here that holds no rules. Its 25
-files are response playbooks — `trigger:` and `steps:`, no `detection:` block.
-They are the entire difference between the 7,016 YAML files under this tree and
-the 6,991 rules every count in this repository publishes.
+Two directories here hold no rules. `detections/playbooks/` has 25 response
+playbooks — `trigger:` and `steps:`, no `detection:` block — and
+`detections/sigma-correlations/` has 6 multi-document Sigma correlation files
+that compile into the windowed ruleset rather than the stateless one. They are
+the entire difference between the 7,022 YAML files under this tree and the
+6,991 rules every count in this repository publishes.
diff --git a/docs/api/API_REFERENCE.md b/docs/api/API_REFERENCE.md
index 5ed5a873e..6d5c0cb48 100644
--- a/docs/api/API_REFERENCE.md
+++ b/docs/api/API_REFERENCE.md
@@ -414,7 +414,7 @@ tenant) with ZSET-backed top-N sorted queues for O(log N) reads.
Admin only (`roles:write`); every mutation requires a `reason`, writes an
audit row, and revokes the target's active sessions. See
-[Roles & Permissions](roles-and-permissions.md) for the full model.
+[Roles & Permissions](../roles-and-permissions.md) for the full model.
| Method | Path | Purpose |
|--------|------|---------|
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
index 2f8a39431..e7edd6afc 100644
--- a/docs/architecture/README.md
+++ b/docs/architecture/README.md
@@ -43,7 +43,7 @@ fails CI if any name in either direction stops resolving.
independent: anything can consume the spine without ingest knowing about it.
**4. Fusion consumes it and evaluates detections.**
-[`services/fusion`](../../services/fusion) runs the 2,603 executable rules
+[`services/fusion`](../../services/fusion) runs the 2,511 executable rules
against the event — 833 native and 1,770 imported Sigma rules, each of which
was replayed through its real connector and this engine and watched to fire
before it was allowed into the compiled ruleset. Separately it decides whether the event is *promotable* —
@@ -59,7 +59,7 @@ alerts while the console showed it disabled — the worst shape a defect can
have, because it tells the operator the problem is solved.
It is an overlay rather than a per-tenant ruleset: the *difference* applied
-over one shared corpus, not N copies of 2,603 rules rebuilt whenever anyone
+over one shared corpus, not N copies of 2,511 rules rebuilt whenever anyone
edits anything. Suppression is applied **after** the match so the dropped hit
is logged with the tuning, its author and its reason — "no alert" with no
explanation is indistinguishable from a rule that simply did not match. A
@@ -281,7 +281,7 @@ flowchart TD
C --> E["OCSF-shaped envelope"]
D --> E
E --> F[("Kafka aisoc.raw_events")]
- F --> G["Detection engine<br/>2,603 executable rules"]
+ F --> G["Detection engine<br/>2,511 executable rules"]
F --> H{"Promotable?<br/>category 2, or severity >= high"}
G -->|rule fires| I["Alert"]
H -->|yes| I
diff --git a/docs/architecture/SYSTEM_DESIGN.md b/docs/architecture/SYSTEM_DESIGN.md
index d88382cc1..a0eef4af3 100644
--- a/docs/architecture/SYSTEM_DESIGN.md
+++ b/docs/architecture/SYSTEM_DESIGN.md
@@ -304,7 +304,8 @@ Each agent emits chain-of-thought traces persisted in PostgreSQL for explainabil
* [API Reference](../api/API_REFERENCE.md)
* [Local Development](../runbooks/LOCAL_DEVELOPMENT.md)
-* [PROGRESS.md](../../PROGRESS.md)
+* [The lettered deferrals](../audit/DEFERRED_SUBPHASES.md) — this entry used to
+ link `PROGRESS.md`, which is gitignored and was never committed.
---
diff --git a/docs/audit/CLAIM_TO_GATE_MATRIX.md b/docs/audit/CLAIM_TO_GATE_MATRIX.md
index e1196c6cd..1f006832f 100644
--- a/docs/audit/CLAIM_TO_GATE_MATRIX.md
+++ b/docs/audit/CLAIM_TO_GATE_MATRIX.md
@@ -20,7 +20,7 @@ Statuses: `GATED` (a CI job fails when the claim stops being true) · `PARTIAL`
| Runs entirely on your infrastructure, and evidence sent to a hosted model is pseudonymized first | README L63 | `ci.yml :: python-test` (agents) runs `test_privacy_redactor.py` (zero raw PII survives) | full | GATED (redaction gated; the CLI now has no default telemetry endpoint and `telemetry.test.ts` pins that an enabled-but-unconfigured run makes zero network calls; **v9.0 adds the Helm egress default-deny** — `infra/helm/aisoc/templates/networkpolicy.yaml`, gated by `helm.yml` which asserts it denies by default, excludes `169.254.169.254/32` from every allowed CIDR, and stays opt-in because a CNI that does not enforce NetworkPolicy ignores it silently; **the platform-wide half landed with `check_default_egress.py`** — every service's declared settings defaults are read and a public host that no air-gap guard covers fails, with each exemption naming the guard that justifies it so deleting the guard withdraws the exemption — plus `tests/test_no_default_egress.py`, which patches the socket layer and drives each service's import and startup with a blank environment, covering 7 of 13 services in CI and naming the missing package for each of the other 6 rather than skipping silently. `services/purple-team` declared an ATT&CK CDN URL nothing in the service read, and it was deleted rather than exempted. **the container half landed with `check_container_egress.py`** — images built from the commit under test start on a docker network created with `--internal`, with a DNS sinkhole as their only resolver, and every name they ask for is classified with the same predicate the services enforce air-gap policy with. Observation, not only prevention, because a block alone cannot tell "made no call" from "made a call that failed". Two controls, because zero observations is what a correct run and a blind probe both look like and the API's unconfigured startup legitimately records zero — it dials Postgres on loopback, which needs no DNS: a canary wired with the identical network and `--dns` flags must be seen by the sinkhole, and a container that emitted no log line and asked for no name is a finding rather than a pass. `container-egress.yml` also builds an image that deliberately resolves a public name and requires the gate to fail on it. One limit stated rather than implied: a dial straight to a public IP literal asks no DNS, so it is prevented by the `--internal` network and statically checked by `check_default_egress.py`, but not observed. **Narrowed 2026-10-01**: the claim used to read "no data exfiltration", which a reader takes to cover a *configured* hosted model as well. It does not. When an operator configures a hosted provider, evidence reaches it unredacted: `services/agents/app/privacy/redactor.py` exists and is unit-tested, and **no LLM call site invokes it**, so `test_privacy_redactor.py` gates a function rather than a path. **Restored 2026-10-01 by parity 2.4.** Hosted calls now go through the pseudonymizer at the contract layer, which is the one place all sixteen agent call sites already pass through, and the row rests on `test_egress_pseudonymization.py`, which drives `safe_ainvoke` and inspects what a fake provider actually received rather than calling the redactor directly. Testing the path rather than the function immediately found a real gap the unit test could not: a bare username in prose (`running as priya.raghavan`) was sent in the clear, because usernames were only redacted in the `DOMAIN\user` form or under a user-ish key. The file also pins the documented trade-off in the other direction, that public IOCs are deliberately **not** redacted, and carries a test that disables the control and requires the leak assertion to fail, so it cannot pass vacuously) | — |
| Detection-as-Code rejects candidates that regress MITRE accuracy | README L170 | `ci.yml :: python-test` (`test_detection_eval.py` — candidate `rule_body` run through the real engine vs its own positive/negative fixtures; approval requires it) + `p1-eval` w2-dac baseline | core | GATED | - |
| 800+ native detection rules | README L78, L170 | `validate-detections.yml` (strict fixture replay) | core | GATED | - |
-| 6000+ imported detection rules | README L78 | `validate-detections.yml` (parse/provenance + `detection_truth_table.py --check`); README cites the executable figure (2603) not the on-disk figure (6991) for coverage | core | GATED | - |
+| 6000+ imported detection rules | README L78 | `validate-detections.yml` (parse/provenance + `detection_truth_table.py --check`); README cites the executable figure (2511) not the on-disk figure (6991) for coverage | core | GATED | - |
| L0-L4 automation maturity gates every action | README L171 | `ci.yml` autonomy-policy drift test + `test_autonomy_safety.py` (dry-run-default, rollback-capability contract, verification-mandate, scorecard) + `test_governed_dispatch.py` (Phase B2 — `decide()` wired into the live-actions `/dispatch` path: above-tier→dry-run, dry-run-off→queued, L0→blocked, executor never invoked when queued/blocked) | core | GATED | - |
| Hunt-as-Code + `/hunt` | README L172 | `ci.yml :: p1-eval` (`hunt_corpus`) | core | GATED | - |
| Weekly benchmark scoreboard runs live against `main` | README L173 | `ci.yml` agents job (Phase E1 — `scripts/check_scoreboard.py` runs the deterministic live-agent MITRE-accuracy eval over the 200-incident corpus and fails if the published `scoreboard.json` substrate row drifts > 0.02, the schema is invalid, or a substrate row is mislabelled) + `wet-eval.yml` (weekly funded LLM rows) | core | GATED | - |
@@ -279,7 +279,7 @@ Statuses: `GATED` (a CI job fails when the claim stops being true) · `PARTIAL`
| A playbook can start from an alert, and previews before it acts | `apps/docs/docs/console/playbooks.md` | `ci.yml :: Python — Tests` (agents, `test_alert_triggered_playbooks.py`) | core | GATED | `find_matching()` had **no production caller**, so no playbook ever ran from an alert. Three switches must agree before one acts (deployment, tenant, playbook) and the default of every one is off; anything short of all three runs in **preview**, with its plan and simulated steps attached to the alert. Preview is the default state rather than a mode somebody has to remember, so a deployment that enables the feature and forgets the per-playbook list gets previews rather than containment. The live list is read per call, so turning one off takes effect on the next alert rather than the next restart. It runs **after** triage, because a playbook's conditions read the verdict |
| An approval step is a durable pause that survives a restart | `apps/docs/docs/console/playbooks.md` | `ci.yml :: Python — Tests` (agents, `test_playbook_pause_resume.py`) | core | GATED | The engine is a single-threaded index walk with no pause and no resume, so `approval` failed closed and **12 shipped playbooks aborted on it**. Failing closed was right (it previously returned `{"skipped": true}` while reporting SUCCESS, letting a run continue into the action a human was meant to authorise) but it is not an approval mechanism. Migration `081` stores the position **and the context**, because the resumed half would otherwise see an empty context and every templated parameter would resolve to nothing. The stored index is the approval step itself and resume advances past it, so a replayed decision continues rather than pausing again. The pause is resolved **before** the run continues, so a double-tap in the responder app resumes once. Expiry is mandatory with a recorded outcome: `expired` is a decision, not the absence of one |
| A tenant's detection tuning reaches the streaming engine, and only that tenant's | `apps/docs/docs/console/detection-tuning.md` | `ci.yml :: Python — Service unit tests` (`services/fusion/tests/test_tenant_tuning_overlay.py`) | core | GATED | `DetectionEngine` evaluated the shared corpus and nothing else. The console writes a tenant's disables, thresholds and suppressions to `detection_rules`, where the streaming engine never looked, so a tenant who turned a noisy rule off **kept receiving its alerts while the console showed it disabled**, which is the worst shape because it tells the operator the problem is solved. An overlay rather than a per-tenant ruleset: the difference applied over one shared corpus, not N copies of 833 rules. Suppression is applied **after** the match so the hit can be logged with the tuning, its author and its reason, because "no alert" with no explanation is indistinguishable from a rule that did not match. A failed reload **keeps the previous overlay**: falling back to no-tuning would turn the tenant's queue back on and read as a flood rather than a fault |
-| Rules that cannot fire are counted, and the count only goes down | `docs/detections/truth-table.md` | `ci.yml :: Python — Lint & Type-check` (`check_detection_fields.py`, ratchet at 119) | core | GATED | **133 to 119.** The per-tenant-allowlist family (15 rules reading an `<x>_in_allowlist` boolean nothing computed) is closed: the overlay derives it from the allowlists the console already writes, which was the cheapest of the five families because an allowlist is the same decision a tenant expresses as a suppression. Derived per tenant rather than in the shared pass, because a global allowlist would make one tenant's exceptions apply to everybody. An unconfigured allowlist contributes **no key**, not `False`: a `not_in_allowlist` clause against a missing key is true for every event, which is the negation-flips-on-absence failure already recorded for the Sigma import. A test asserts every allowlist boolean the corpus reads is mapped, so a rule cannot stay unreachable while the ratchet says otherwise. The four remaining families (74 windowed, 24 identity, 8 comparison, 8 first-seen, 6 other, 2 baseline) need engine or enrichment work and are named rather than hidden |
+| Rules that cannot fire are counted, and the count only goes down | `docs/detections/truth-table.md` | `ci.yml :: Python — Lint & Type-check` (`check_detection_fields.py`, ratchet at 45) | core | GATED | **133 to 119 to 45.** The per-tenant-allowlist family (15 rules reading an `<x>_in_allowlist` boolean nothing computed) is closed: the overlay derives it from the allowlists the console already writes, which was the cheapest of the five families because an allowlist is the same decision a tenant expresses as a suppression. Derived per tenant rather than in the shared pass, because a global allowlist would make one tenant's exceptions apply to everybody. An unconfigured allowlist contributes **no key**, not `False`: a `not_in_allowlist` clause against a missing key is true for every event, which is the negation-flips-on-absence failure already recorded for the Sigma import. A test asserts every allowlist boolean the corpus reads is mapped, so a rule cannot stay unreachable while the ratchet says otherwise. The 74-rule windowed family is closed too: 50 were translated into windowed rules replayed through the real engine and 24 were refused with a recorded reason, which is also why the published executable figure fell 2,603 to 2,511 — a rule that could not fire had been counted as one that could. The remaining families (22 identity, 8 first-seen/age, 7 comparison, 6 other, 2 baseline) need enrichment work and are named rather than hidden |
| Raw SQL names only columns a migration creates, on reads as well as writes | `docs/audit/REPOSITORY_REALITY.md` | `ci.yml :: Python — Lint & Type-check` (`check_raw_sql_columns.py`, self-tested) | core | GATED | The gate parsed `INSERT` and `UPDATE` only, which is one-directional in the way that matters: an absent column fails a `SELECT` just as hard, and a handler that wraps the read in `except` turns the crash into a warning and an empty result. **Live QA found exactly that**: `tenant_overlay._fetch` selected `rule_id` and `updated_by` from `detection_rules`, which has neither, so the per-tenant tuning overlay would have loaded nothing on every deployment — while every unit test passed, because the fake answered whatever it was asked. A `SELECT` fails only where the gate genuinely knows (table migrated, projection fully read, column absent); osquery virtual tables and the ClickHouse lake are declined rather than failed, because the gate knows which tables are migrated and not which engine a statement targets. Statement coverage 130 to 335, and the self-test is proven against the real pre-fix defect |
| An expired session sends you to sign in, rather than locking you out | `apps/docs/docs/console/getting-started.md` | `ci.yml :: Web — Unit tests` (`apps/web/src/lib/authExpiry.test.ts`) | core | GATED | Found by a live browser walkthrough and reproduced deterministically: with an expired token in `localStorage`, `/login` redirected to `/dashboard`, every call there answered 401, and **nothing ever sent the user back** — the only way out was clearing browser storage by hand. Two independent causes, so two fixes: `isAuthenticated()` answered "is a token stored", which is a different question from "can this session make a request"; and nothing handled a 401, so a session that died mid-shift left every panel failing with no explanation. Either fix alone leaves a hole — the first still strands a user whose token expires *while* they work, the second still bounces a returning user off `/login` before any request is made. An unreadable token counts as not authenticated, because the pessimistic answer costs a sign-in and the optimistic one costs the lockout |
| Two different CloudTrail events become two different alerts | `apps/docs/docs/connectors/aws-cloudtrail.md` | `ci.yml :: Go — Tests` (`services/ingest/internal/normalizer/cloudtrail_profile_test.go`) | core | GATED | `aws_cloudtrail` had **no entry in `connectorProfiles`**, so it hit the generic fallback, which titles every event "Security Finding from aws_cloudtrail" and carries no vendor id. The alert id is a v5 UUID derived from that content, so a console login and a `DeleteTrail` **deduplicated onto the same row**: a customer connecting CloudTrail saw exactly one alert no matter what happened in their account, which reads as a quiet estate rather than as a bug. Mapped from the connector's own lowercase keys, not raw CloudTrail names, because the connector has already flattened them — a test asserts that in both directions. `2001` rather than `3005`, matching the Splunk-notable reasoning: the connector ships a curated ~80-event allow-list, so it has already judged these security-relevant and category 2 is always promoted. Proven live: three distinct events produced three alerts with correct titles, vendor ids and severities including `critical` |
diff --git a/docs/audit/REPOSITORY_REALITY.md b/docs/audit/REPOSITORY_REALITY.md
index 170d96d54..937c18d14 100644
--- a/docs/audit/REPOSITORY_REALITY.md
+++ b/docs/audit/REPOSITORY_REALITY.md
@@ -123,9 +123,9 @@ SSRF allow-list entry, and is commented as such.
| Item | Count | Status |
|---|---|---|
-| Rules the engine loads | **2603** | **WORKING** — each was replayed through its real connector and the real engine and watched to fire |
+| Rules the engine loads | **2511** | **WORKING** — each was replayed through its real connector and the real engine and watched to fire |
| Detection rules on disk | **6991** | the rest are imports in languages with **no evaluator** here (Splunk SPL, Chronicle YARA-L, CAR pseudocode); the engine never reads them |
-| YAML files under `detections/` | **7016** | the extra 25 are response playbooks, not rules — see `detections/playbooks/` |
+| YAML files under `detections/` | **7022** | 25 are response playbooks (`detections/playbooks/`) and 6 are Sigma correlation files (`detections/sigma-correlations/`); neither is a stateless rule |
| Hunts under `hunts/` | **68** | **WORKING** — each replayed against a synthetic scenario and observed to fire, and each graded in the other direction too. Not a claim a hunt fires on a given deployment's telemetry, which depends on whether its connectors emit the fields the hunt names. The negative half of that grading was satisfiable without testing anything until Phase 8.4: a negative drawn from a different log source never fires on any hunt, so `check_hunt_scenarios.py` now requires it to differ from its positive in exactly one indicator field. It found 8 violations on first run, 3 in the 5 hunts that predate the phase |
The gap matters and has been published both ways in the past. `make stats`
diff --git a/docs/community-feedback/2026-05-12/AiSOC_ROADMAP.md b/docs/community-feedback/2026-05-12/AiSOC_ROADMAP.md
index 67bb9ae24..bcede0cf2 100644
--- a/docs/community-feedback/2026-05-12/AiSOC_ROADMAP.md
+++ b/docs/community-feedback/2026-05-12/AiSOC_ROADMAP.md
@@ -224,5 +224,7 @@ re-prioritization.
- **Stable feedback IDs:** [`AiSOC_Community_Feedback_Synthesis.md`](./AiSOC_Community_Feedback_Synthesis.md)
- **Implementation tickets:** [`AiSOC_Proposed_Issues.md`](./AiSOC_Proposed_Issues.md)
- **Historical roadmap:** [`/ROADMAP.md`](../../../ROADMAP.md)
-- **Active progress tracker:** [`/PROGRESS.md`](../../../PROGRESS.md)
+- **Active progress tracker:** [`/DEPTH_PROGRESS.md`](../../../DEPTH_PROGRESS.md).
+ This entry named `/PROGRESS.md`, which is gitignored and has never been in
+ the repository.
- **Contributor invariants & eval gates:** [`/AGENTS.md`](../../../AGENTS.md)
diff --git a/docs/contributing/detection-translation-drive.md b/docs/contributing/detection-translation-drive.md
index 1d411357d..8f6b180aa 100644
--- a/docs/contributing/detection-translation-drive.md
+++ b/docs/contributing/detection-translation-drive.md
@@ -18,7 +18,7 @@ which is generated by `scripts/detection_truth_table.py` and gated by
| car (imported) | 99 | 0 |
| community | 1 | 0 |
-**2,603 of 6,991 rules fire today.** The other 4,388 are on disk for
+**2,511 of 6,991 rules fire today.** The other 4,462 are on disk for
provenance and ATT&CK coverage mapping — 4,213 of them under `_quarantine/`
because their body is an upstream query language the engine does not execute,
and 175 carrying `enabled: false` with a reason.
@@ -97,4 +97,4 @@ fine for that to be your whole contribution.
- Add a negative fixture to an existing native rule that has only a positive one.
- Fix a false positive someone has already reported against a firing rule.
-- Pick up an issue labelled [good first issue](../../issues?q=is%3Aopen+label%3A%22good+first+issue%22).
+- Pick up an issue labelled [good first issue](https://github.com/beenuar/AiSOC/issues?q=is%3Aopen+label%3A%22good+first+issue%22).
diff --git a/docs/contributing/strategies-and-actions.md b/docs/contributing/strategies-and-actions.md
index d216e07b0..b3f7bf83e 100644
--- a/docs/contributing/strategies-and-actions.md
+++ b/docs/contributing/strategies-and-actions.md
@@ -14,7 +14,7 @@ defend had been published for months. The connector catalogue went the same
way — 35 of 84 had no documentation, and the sidebar listed 34 pages against
96 files, so most of what existed could not be found.
-The detection figure is 2,603 now, and how it moved is the part worth keeping.
+The detection figure is 2,511 now, and how it moved is the part worth keeping.
It was not closed by writing rules. Someone asked why the existing ones could
not fire and found a single cause — Windows events nest their payload one
level below the namespace the matcher reads, so the two most-used fields in
@@ -24,6 +24,13 @@ the fix and requires those rules to go silent. A count that is gated on
evidence can be raised honestly; a count that is gated on a flag can only be
edited.
+It has since gone **down**, from 2,603, and that direction matters more than
+the rise. 74 rules that depended on a windowed evaluator were counted as
+executable while being unable to fire; 50 were translated into windowed rules
+and 24 were refused with a reason, and the published figure fell by the
+difference. A count derived from evidence moves both ways — recount it with
+`scripts/generate_corpus_stats.py` rather than quoting this paragraph.
+
Both recovered by making the artifact derived and the count gated. A
strategy library aiming at a hundred entries, and an action registry aiming
at dozens per vendor, will reach the same state within a year without the
diff --git a/docs/decisions/0001-cyble-cti-moat.md b/docs/decisions/0001-cyble-cti-moat.md
index 5deea24ab..37a29eebd 100644
--- a/docs/decisions/0001-cyble-cti-moat.md
+++ b/docs/decisions/0001-cyble-cti-moat.md
@@ -3,7 +3,8 @@
- **Status:** accepted
- **Date:** 2026-06-28
- **Decision-makers:** Beenu Arora (founder), AiSOC core team
-- **Plan reference:** [cyble-aisoc-plan.md](../../plans/cyble-aisoc/cyble-aisoc-plan.md) §3a / §3d / §5, [AiSOC missing pieces plan](../../plans/aisoc-missing-pieces/aisoc_missing_pieces_plan.md) §5.1
+- **Plan reference:** [cyble-aisoc-plan.md](../../plans/cyble-aisoc/cyble-aisoc-plan.md) §3a / §3d / §5
+- **Not followable:** this ADR was written against a missing-pieces plan that is not in this repository — `plans/aisoc-missing-pieces/` has never been committed — so the section numbers it cited cannot be looked up. The decision stands on its own text.
## Context
diff --git a/docs/decisions/0002-compliance-claims.md b/docs/decisions/0002-compliance-claims.md
index fab69f9c3..88f8e80a6 100644
--- a/docs/decisions/0002-compliance-claims.md
+++ b/docs/decisions/0002-compliance-claims.md
@@ -3,7 +3,8 @@
- **Status:** accepted
- **Date:** 2026-06-28
- **Decision-makers:** Beenu Arora (founder), AiSOC core team
-- **Plan reference:** [AiSOC missing pieces plan](../../plans/aisoc-missing-pieces/aisoc_missing_pieces_plan.md) §5.2; the Phase 1.3 fix already landed in v8.x.
+- **Context:** the Phase 1.3 fix already landed in v8.x.
+- **Not followable:** this ADR was written against a missing-pieces plan that is not in this repository — `plans/aisoc-missing-pieces/` has never been committed — so the section numbers it cited cannot be looked up. The decision stands on its own text.
## Context
diff --git a/docs/decisions/0003-mssp-pricing-shape.md b/docs/decisions/0003-mssp-pricing-shape.md
index b9fff4164..9fb3e683e 100644
--- a/docs/decisions/0003-mssp-pricing-shape.md
+++ b/docs/decisions/0003-mssp-pricing-shape.md
@@ -3,7 +3,7 @@
- **Status:** accepted
- **Date:** 2026-06-28
- **Decision-makers:** Beenu Arora (founder), AiSOC core team
-- **Plan reference:** [AiSOC missing pieces plan](../../plans/aisoc-missing-pieces/aisoc_missing_pieces_plan.md) §5.3
+- **Not followable:** this ADR was written against a missing-pieces plan that is not in this repository — `plans/aisoc-missing-pieces/` has never been committed — so the section numbers it cited cannot be looked up. The decision stands on its own text.
## Context
diff --git a/docs/decisions/0004-live-demo-strategy.md b/docs/decisions/0004-live-demo-strategy.md
index 66683f8ca..4f416c6cc 100644
--- a/docs/decisions/0004-live-demo-strategy.md
+++ b/docs/decisions/0004-live-demo-strategy.md
@@ -3,7 +3,9 @@
- **Status:** accepted
- **Date:** 2026-06-28
- **Decision-makers:** Beenu Arora (founder), AiSOC core team
-- **Plan reference:** [AiSOC missing pieces plan](../../plans/aisoc-missing-pieces/aisoc_missing_pieces_plan.md) §5.4; [README.md](../../README.md) "Try it live" section.
+- **See also:** [README.md](../../README.md). The ADR cited a "Try it live"
+ section there; the README has never carried one under that heading.
+- **Not followable:** this ADR was written against a missing-pieces plan that is not in this repository — `plans/aisoc-missing-pieces/` has never been committed — so the section numbers it cited cannot be looked up. The decision stands on its own text.
## Context
@@ -36,6 +38,20 @@ Concretely:
### Code / infra changes that land alongside this ADR
+:::caution What this list is
+A plan of intended changes, not a record of shipped ones. Four of the seven
+entries below are **not in the repository** and never were:
+`infra/fly/managed/tenants/demo.yaml`, `.github/workflows/demo-reseed.yml`,
+`services/api/app/demo/seed.py` and `docs/runbooks/demo-tenant-down.md`. The
+README callout named here was also never written under that heading — the
+README has no "Try it live" section. Read this as the decision's intent; check
+the tree before citing any path from it.
+
+The deterministic seeder that *does* exist is
+[`services/api/app/scripts/seed_demo.py`](../../services/api/app/scripts/seed_demo.py),
+reached with `make demo`.
+:::
+
- `infra/fly/managed/tenants/demo.yaml` (new) — tenant manifest for the always-on demo.
- `.github/workflows/demo-reseed.yml` (new) — nightly reseed.
- `services/api/app/demo/seed.py` (new) — deterministic fixture seeder (alerts, cases, playbook runs, hunt history).
diff --git a/docs/design/landing-page-brief.md b/docs/design/landing-page-brief.md
index 63375443e..9547261d8 100644
--- a/docs/design/landing-page-brief.md
+++ b/docs/design/landing-page-brief.md
@@ -35,7 +35,7 @@ AiSOC is an MIT-licensed agentic Security Operations Center that fuses raw
events into incidents, runs four named agents — Detect, Triage, Hunt, and
Respond — against them, and records every prompt, tool call, and rationale
to a replayable Investigation Ledger. It ships with 84 click-and-connect
-data sources, 2,603 executable detection rules, 62 playbook packs, and a public
+data sources, 2,511 executable detection rules, 62 playbook packs, and a public
benchmark harness that gates every PR. You can self-host the whole stack
in five minutes, take it air-gapped on a flag, or join the managed
waitlist at `tryaisoc.com` — same code in every direction.
@@ -195,13 +195,13 @@ Ranked. Five total. Each one cites the shipped feature behind it.
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
- marketplace ships 7,155 items (6,991 detections on disk, 87 playbooks
+ marketplace ships 7,158 items (6,991 detections on disk, 87 playbooks
across 62 packs, 77 plugins) per `marketplace/index.json`.
- **Repo evidence.** `services/connectors/app/connectors/`,
`apps/docs/docs/operations/credentials.md`,
`packages/plugin-sdk-py/`, `packages/plugin-sdk-go/`,
`packages/plugin-sdk-ts/`, `marketplace/index.json`.
-- **Metric to display.** 84 connectors live, 9 categories, 7,155
+- **Metric to display.** 87 connectors live, 9 categories, 7,158
marketplace items. Render these from the generated constants rather than
retyping them: `CONNECTOR_COUNT` in `apps/web/src/data/connectorCount.ts`,
and `MARKETPLACE_ITEM_COUNT` / `EXECUTABLE_DETECTION_COUNT` in
@@ -237,7 +237,7 @@ number is MIT-licensed and reproducible from a fresh clone.
**Defence.** The agent orchestrator is ~600 lines of LangGraph in
`services/agents/app/orchestrator/`. The detection corpus is YAML under
`detections/` (6,991 rules on disk across cloud, endpoint, identity,
-network, application, and data-exfil, of which 2,603 are executable). The benchmark dataset and harness are in
+network, application, and data-exfil, of which 2,511 are executable). The benchmark dataset and harness are in
`services/agents/tests/eval_data/` and `scripts/run_evals.py`. Anyone can
run `python3 scripts/run_evals.py` and reproduce every number on the
benchmark page in roughly 35 ms. There is no private fork, no
@@ -423,7 +423,7 @@ section tracking.
- **Persona:** Manager primary.
- **Conversion behaviour:** Click through to the marketplace; encourage
SDK contribution.
-- **Content blocks:** H2 ("84 connectors, 2,603 executable detections, 62
+- **Content blocks:** H2 ("87 connectors, 2,511 executable detections, 62
playbook packs") · category chips (EDR, SIEM, Cloud, IAM, SaaS, VCS,
Network, NDR, AI) ·
marquee or grid of connector logos · "Build your own in 50 lines" code
@@ -890,7 +890,7 @@ Condensed teardown lives at `docs/design/landing-page-references.md`.
| LLM input contract (fail-closed) | `services/agents/.../llm_input_contract.py` (T2.3) | CISO | V1, P3 | pillars (P3) | Shipped (T2.3 wip) |
| Pre-fetched ContextBundle | `services/agents/.../context_bundle.py` (T2.1) | Manager | V1 | features-hunt | Shipped (T2.1 wip) |
| 84 click-and-connect connectors | `services/connectors/app/connectors/__init__.py` | Analyst, manager | V4 | connectors, features-operate | Shipped |
-| Marketplace (7,155 items) | `marketplace/index.json` · `scripts/build_marketplace.py` | Detection engineer | V4 | connectors | Shipped |
+| Marketplace (7,158 items) | `marketplace/index.json` · `scripts/build_marketplace.py` | Detection engineer | V4 | connectors | Shipped |
| Credential vault (Fernet + HMAC) | `services/api/app/services/vault.py` · `apps/docs/docs/operations/credentials.md` | CISO | V4, P3 | deploy, pillars (P3) | Shipped |
| Plugin SDKs (Python, TypeScript, Go) | `packages/plugin-sdk-py/` · `packages/plugin-sdk-ts/` · `packages/plugin-sdk-go/` | Detection engineer | V4 | features-operate | Shipped |
| MCP server (19 tools) | `services/mcp/` | Detection engineer | V4 | features-operate | Shipped |
diff --git a/docs/design/landing-page-component-recipes.md b/docs/design/landing-page-component-recipes.md
index 8c47130d4..8a2aeb65c 100644
--- a/docs/design/landing-page-component-recipes.md
+++ b/docs/design/landing-page-component-recipes.md
@@ -38,7 +38,7 @@
- **Custom:** Right-column visual is a hand-built SVG of the four-agent topology rendered with framer-motion `<motion.path>` (motion spec `agent-beam`). Eyebrow uses `<Eyebrow />` chip with `bg-brand-900/40 text-brand-300 border-brand-500/20`.
- **Anatomy:** `Hero` → `HeroCopy` (eyebrow, H1, sub-head, CTAs, social-proof), `HeroVisual` (SVG topology + Border Beam), `HeroBackground` (Spotlight + AnimatedGridPattern).
- **States:** Visual right at `lg+`, stacked at `<lg`; auto-pauses motion at `<md`. Hover primary CTA shimmer slow-loops; secondary CTA border `surface-border → brand-500`. Reduced-motion: H1 instant; mesh static; Border Beam → 1 px static `brand-500/30`.
-- **Failure:** Spotlight fails → inline `radial-gradient`. Mesh fails → flat `bg-surface-base`. SVG fails → `<img src="/og.png" />` poster.
+- **Failure:** Spotlight fails → inline `radial-gradient`. Mesh fails → flat `bg-surface-base`. SVG fails → `<img src="/og-image.png" />` poster.
---
@@ -97,7 +97,7 @@
- **Primitives:**
- Aceternity **Glowing Effect** (`/components/glowing-effect`) — wraps each card border. `glow={true}`, `proximity={64}`, `inactiveZone={0.4}`.
- Aceternity **Bento Grid** — used loosely (flat 2 × 2, equal heights, no skew).
- - MagicUI **Number Ticker** — stat lines. P1 `value={EXECUTABLE_DETECTION_COUNT}` (from `apps/web/src/data/corpusStats.ts`, currently 2603 — do not hard-code it; the literal `6998` sat here while the corpus moved), P2 `value={17}`, P3 `value={4}`, P4 `value={6}`.
+ - MagicUI **Number Ticker** — stat lines. P1 `value={EXECUTABLE_DETECTION_COUNT}` (from `apps/web/src/data/corpusStats.ts`, currently 2511 — do not hard-code it; the literal `6998` sat here while the corpus moved, and `2603` sat here after that), P2 `value={17}`, P3 `value={4}`, P4 `value={6}`.
- **Custom:** 24 × 24 brand glyphs (`open-source`, `graph`, `agentic`, `deploy-anywhere`). Active borders: P2 → `landing.gradient.pillars`, P3 → `landing.accent.ember`, P1 / P4 → `brand-500/30`.
- **Anatomy:** `Pillars` → `PillarsHeading`, `PillarsGrid` (4 × `PillarCard`), each → `PillarIcon`, `PillarTitle`, `PillarBody`, `PillarStat`, `PillarLink`.
- **States:** Default `landing.shadow.1`, `surface-border`. Hover → Glowing Effect on; lift `-2 px`. Focus → existing `:focus-visible` 2 px `brand-500` ring. <768 stacks. Reduced-motion → Glowing `disabled={true}`; lift instant.
diff --git a/docs/design/landing-page-content.md b/docs/design/landing-page-content.md
index 7bf7bdeed..615e8cc93 100644
--- a/docs/design/landing-page-content.md
+++ b/docs/design/landing-page-content.md
@@ -30,7 +30,7 @@
- **Tertiary link (under CTAs):** `Watch a 90-second investigation →`
- **Social-proof bar (three chips):**
- `84 connectors · EDR · SIEM · cloud · IAM · SaaS · VCS · network · NDR · AI`
- - `2,603 executable detections · 62 playbook packs · 77 plugins`
+ - `2,511 executable detections · 62 playbook packs · 80 plugins`
- `Self-host · Render · Fly.io · Helm · Terraform · air-gap`
---
@@ -124,7 +124,7 @@
- **Card P1 — Open source and transparent**
- **Body:** `MIT-licensed agent, public detection corpus, reproducible
benchmark — every claim on this page maps to a file in the repo.`
- - **Stat:** `2,603 executable detection rules`
+ - **Stat:** `2,511 executable detection rules`
- **Link:** `Read the LICENSE →`
- **Card P2 — Graph-native at ingest**
- **Body:** `The entity graph is written while events are normalised,
@@ -151,7 +151,7 @@
1. **Fusion engine.** `Real-time dedup, ML scoring, per-alert confidence.`
2. **Entity-risk rollup (RBA).** `Time-decayed risk per user, host, IP,
domain — 50:1 alert-to-incident.`
-3. **Native detections.** `2,603 executable rules across cloud, endpoint,
+3. **Native detections.** `2,511 executable rules across cloud, endpoint,
identity, network, application, and data-exfil, of 6,991 on disk.`
4. **Investigation Ledger.** `Replayable, step-by-step record of every
agent decision per case.`
@@ -178,7 +178,7 @@
1. **84 click-and-connect connectors.** `EDR · SIEM · cloud · IAM ·
SaaS · VCS · network · NDR · AI.`
-2. **Marketplace.** `7,155 community items — detections, playbooks,
+2. **Marketplace.** `7,158 community items — detections, playbooks,
plugins.`
3. **Plugin SDKs.** `Python, TypeScript, Go — build a connector in 50
lines.`
@@ -194,7 +194,7 @@
## `connectors` — Connectors + Marketplace
- **Eyebrow:** `Plug in everything`
-- **H2:** `84 connectors. 2,603 executable detections. 62 playbook packs.`
+- **H2:** `87 connectors. 2,511 executable detections. 62 playbook packs.`
- **Sub-head:**
`Every connector renders a schema-driven form, encrypts its secrets at
the application layer, and starts polling on a per-instance schedule.
@@ -384,7 +384,7 @@
6. **Q.** `How do connectors work?`
**A.** `Each connector is a Python class that declares a schema,
tests its credentials, polls on a schedule, and normalises events
- into OCSF. 69 ship in the box. The plugin SDKs (Python, TypeScript,
+ into OCSF. 87 ship in the box. The plugin SDKs (Python, TypeScript,
Go) let you author your own in roughly 50 lines.`
7. **Q.** `What runs in production today?`
**A.** `Beta deployments through reference partners and an internal
diff --git a/docs/operations/observability.md b/docs/operations/observability.md
index 79920a1cd..902374c7b 100644
--- a/docs/operations/observability.md
+++ b/docs/operations/observability.md
@@ -30,11 +30,12 @@ a page. Slow burn (10% in six hours) is a ticket — not an outage, but the
shape that exhausts a month's budget without any single incident to point
at.
-**Coverage is five of seventeen services**, because only five expose
-`/metrics`. Generating rules for the other twelve would produce alerts
+**Coverage is five of nineteen services**, because only five expose
+`/metrics`. Generating rules for the other fourteen would produce alerts
that can never fire, and an alert that can never fire reads as coverage
while providing none. The generator names the uncovered services on every
-run rather than quietly skipping them.
+run rather than quietly skipping them, and
+`scripts/audit_prometheus_targets.py` prints the current split.
## The four golden signals
@@ -61,20 +62,30 @@ A collector now ships: `docker compose --profile monitoring up` starts an OpenTe
Tempo's retention in the dev stack is 24 hours. It is there so a developer can follow a trace, not to retain them.
-- Trace context does **not** yet propagate across the Kafka spine, because the producing
- and consuming ends are the two uninstrumented services. HTTP hops between the
- instrumented services (api ↔ agents) do propagate.
-- The Investigation Ledger records per-step model/tool attribution (see the
- [model router](../concepts/model-router.md) and
- [LLMOps](../concepts/llmops.md) docs), so the reasoning path inside the
- `agents` span is itself replayable.
+- Trace context does **not** yet propagate across the Kafka spine. The reason
+ changed and is worth stating precisely, because this bullet used to give the
+ old one: both ends *are* instrumented now (see above). What is missing is
+ that `services/ingest`'s publisher writes no `traceparent` into the Kafka
+ message headers, and `services/fusion` — the service that consumes
+ `raw_events` — emits no spans at all, so there is nothing on either side of
+ the queue to join. HTTP hops between the instrumented services (api ↔ agents)
+ do propagate.
+- The Investigation Ledger records per-step model and tool attribution, so the
+ reasoning path inside the `agents` span is itself replayable. (This bullet
+ used to link a model-router and an LLMOps page; neither exists — `docs/concepts/`
+ is not a directory in this repository.)
## Metrics endpoints
-Each service exposes Prometheus metrics at `/metrics`; the scrape config lives
-in `infra/docker/prometheus.yml` and is gated (every `job_name` must point at a
-real, instrumented `hostname:port` — a CI check enforces this so a scrape job
-can't silently break).
+**Five of nineteen services expose `/metrics`** — `api`, `ingest`, `fusion`,
+`threatintel` and `agents`. The other fourteen emit nothing for Prometheus to
+scrape; `scripts/audit_prometheus_targets.py` names them on every run rather
+than letting the gap read as coverage.
+
+The scrape config lives in `infra/docker/prometheus.yml` and is gated: every
+`job_name` must point at a real, instrumented `hostname:port`, so a scrape job
+cannot silently break. The gate checks the config against the tree — it does
+not make an unscraped service scraped.
## Governance
diff --git a/docs/security/README.md b/docs/security/README.md
index e2d0b57d2..69fa54943 100644
--- a/docs/security/README.md
+++ b/docs/security/README.md
@@ -1,7 +1,7 @@
# Security pack
-For a reviewer doing diligence on AiSOC. Six documents, in the order a
-security questionnaire usually walks them.
+For a reviewer doing diligence on AiSOC, in the order a security
+questionnaire usually walks them.
| Document | Answers |
|---|---|
@@ -9,10 +9,15 @@ security questionnaire usually walks them.
| [Data handling by deployment mode](data-handling.md) | What leaves your perimeter under each of the four ways AiSOC can be run, and what is retained where. |
| [Platform threat model](platform-threat-model.md) | STRIDE over the platform, with the credential vault as the top asset. |
| [Agent and tool threat model](agent-threat-model.md) | STRIDE over the prompt and tool boundaries, both of which take attacker-influenced input. |
+| [Access governance](access-governance.md) | Attribute conditions, time-boxed elevation and per-service workload identities, and where each is narrower than its heading sounds. |
| [Connector least privilege](connector-least-privilege.md) | The minimum vendor scope each connector needs. |
| [Security questionnaire](questionnaire.md) | Standard control questions, answered, with the gap list stated rather than omitted. |
| [Sub-processors](subprocessors.md) | What this repository can and cannot establish about the hosted service. |
+Leaving `access-governance.md` out of this table is how the questionnaire
+came to answer "no reader" about three controls that had one: a reviewer
+walking the pack never reached the page that documents them.
+
## The one rule these documents follow
**Every statement names the file or the CI job that makes it true, and where a
diff --git a/docs/security/questionnaire.md b/docs/security/questionnaire.md
index 4b66fea1f..7485b3c8f 100644
--- a/docs/security/questionnaire.md
+++ b/docs/security/questionnaire.md
@@ -64,10 +64,16 @@ or WebAuthn passkeys
tokens expire in 30 minutes and refresh tokens in 7 days by default.
**Is multi-factor authentication enforced?**
-**Not today.** WebAuthn passkeys exist and work, which is a passwordless
-*sign-in* factor rather than an enforced second factor, and there is no
-policy that requires MFA per role or per tenant. This is a gap, listed
-[below](#the-gap-list).
+**Per tenant, yes; per role, no.** The console carries a TOTP second factor
+with recovery codes
+([`mfa.py`](../../services/api/app/api/v1/endpoints/mfa.py)), and
+`PUT /api/v1/auth/mfa/policy` with `{"require_totp": true}` requires it of
+every member of the tenant — unenrolled members are challenged to enrol at
+their next sign-in rather than locked out. WebAuthn passkeys remain the
+factor for the responder PWA. What does **not** exist is a policy that
+requires a second factor of *some* roles and not others: the policy row is
+`aisoc_tenant_mfa_policy`, one boolean per tenant. That narrower gap is
+listed [below](#the-gap-list).
**How is authorization decided?**
One path. `CurrentUser.require_permission` in
@@ -101,12 +107,28 @@ Most, and the rest are counted rather than hidden.
only fall. Its own docstring calls the number "not a target, a debt balance".
**Is there just-in-time privileged access?**
-**No.** A role is held permanently or not at all, so an analyst who needs a
-permission once either holds it every day or waits for somebody who does.
-Migration `087_enterprise_iam.sql` created a `privilege_grants` table for
-exactly this and **nothing reads it**, which is worse than the table not
-existing: a row written into it confers nothing while reading as though it
-does. Listed as a gap [below](#the-gap-list).
+**Yes.** A time-boxed grant in `privilege_grants` adds a permission to a
+principal for a stated window and expires on its own.
+[`abac.py`](../../services/api/app/security/abac.py) resolves grants into
+the effective permission set and
+[`deps.py`](../../services/api/app/api/v1/deps.py) reads them on the one
+permission path, so a grant is a real authorization change rather than a
+row nothing consults.
+
+The same module evaluates **attribute conditions** that narrow a
+permission — by source address, by time of day, by a value on the request.
+Conditions can only turn an allow into a deny: a condition that could
+*grant* would be a second authorization system reaching its own answer,
+and the two would disagree on the day it mattered. The operator set is
+closed and total rather than an expression language, for the reason this
+repository already removed an evaluator from the rule engine once.
+
+[Access governance](access-governance.md) states the limits of both,
+including the one condition operator the write surface refuses and why.
+
+This answer previously read "**No** … nothing reads it", which was true of
+migration `087_enterprise_iam.sql` when the table was created and stopped
+being true when the readers landed.
**How do services authenticate to each other?**
With a shared service token, and **the tenant is a mandatory header verified
@@ -118,8 +140,13 @@ read that treated absent as "no filter".
The weakness of one shared token is real and worth stating: it cannot be
attributed to a particular service, cannot be scoped so the ingest pipeline
carries less authority than the agents worker, and cannot be rotated without
-restarting everything at once. A `workload_identities` table exists for that
-and, like `privilege_grants`, has no reader. Both are in the gap list.
+restarting everything at once. **A per-service credential now exists** —
+`workload_identities` is issued and verified by
+[`workload_identity.py`](../../services/api/app/services/workload_identity.py)
+behind `/api/v1/workload-identities`, so a service can hold its own scoped,
+individually rotatable credential. The shared token remains the default a
+stock deployment boots with, and moving a deployment off it is a migration
+you perform rather than something that has happened to you.
This area had a worse defect that is fixed: the API once posted to the
connectors service with **no `Authorization` header at all** from two modules,
@@ -342,10 +369,7 @@ Each is a real absence, not a caveat.
| Gap | State today | Where it is recorded |
|---|---|---|
-| **Enforced MFA** | Passkeys exist as a sign-in factor; no per-role or per-tenant enforcement policy | This page |
-| **Just-in-time elevation** | `privilege_grants` exists as schema with no reader; a row in it confers nothing | This page |
-| **Attribute conditions on a permission** | `permission_conditions` exists as schema with no reader; a row in it denies nothing | This page |
-| **Per-service internal credentials** | `workload_identities` exists as schema with no reader; the one shared token is unattributable, unscopable and effectively unrotatable | This page |
+| **Per-role MFA enforcement** | TOTP with recovery codes and *per-tenant* enforcement ship; the policy is one boolean per tenant, so a tenant cannot require a second factor of its admins alone | This page |
| **SOC 2 / ISO 27001** | Not commissioned; "controls aligned to" framing held by convention | [ADR-0002](../decisions/0002-compliance-claims.md) |
| **The gate ADR-0002 claims guards that framing** | `scripts/audit_compliance_claims.py` does not exist and no workflow references it | [`REALITY_REPORT.md`](../audit/REALITY_REPORT.md) |
| **Penetration test** | Not commissioned; 16 published advisories instead | [`SECURITY.md`](../../SECURITY.md) |
diff --git a/docs/upgrade/MIGRATION.md b/docs/upgrade/MIGRATION.md
index a91994e7c..7707a04d9 100644
--- a/docs/upgrade/MIGRATION.md
+++ b/docs/upgrade/MIGRATION.md
@@ -260,7 +260,7 @@ ALL GATES PASSED (alert reduction + 3 substrate self-consistency gates)
The eval harness runs deterministic substrate code (extractors, fusion,
templates, judges) against synthetic incidents. It does not call the live LLM
-agent. See [`apps/docs/docs/benchmark.md`](apps/docs/docs/benchmark.md) for
+agent. See [`apps/docs/docs/benchmark.md`](../../apps/docs/docs/benchmark.md) for
what each suite measures.
---
diff --git a/examples/lateral-movement.md b/examples/lateral-movement.md
index efe548583..9d5f8d0cf 100644
--- a/examples/lateral-movement.md
+++ b/examples/lateral-movement.md
@@ -25,7 +25,7 @@ aisoc submit examples/alerts/lateral-movement.json
### Step 0 · DetectAgent · detect
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`
+detection corpus (2,529 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
@@ -87,7 +87,8 @@ require password reset, create the case, page the SOC on-call. The
1. Approve `user.session.revoke_all` (the only single-user-blast-radius
action) immediately via the responder PWA.
-2. Pivot on the second IP (203.0.113.50) in the [Threat Intel](https://docs.tryaisoc.com/console/threat-intel) tab to see if it has appeared in
+2. Pivot on the second IP (203.0.113.50) in the console's **Threat
+ Intelligence** tab (`/threat-intel`) to see if it has appeared in
other tenants' OTX feeds.
3. Page Alice's manager from the case to confirm whether she travelled.
4. If credential reuse is suspected: rotate every API key in Alice's
diff --git a/examples/phishing-payload.md b/examples/phishing-payload.md
index 1d2669c95..60e0302ba 100644
--- a/examples/phishing-payload.md
+++ b/examples/phishing-payload.md
@@ -72,6 +72,6 @@ Proposes the canonical phishing containment:
IT lead first.
3. Add `acme-paychecks.com` to the perimeter blocklist permanently,
not just at the proxy.
-4. Open a brief learning case in [Threat Intel](https://docs.tryaisoc.com/console/threat-intel)
- so the org's analysts know to look for similar typosquat patterns
- over the next 30 days.
+4. Open a brief learning case from the console's **Threat Intelligence**
+ tab (`/threat-intel`) so the org's analysts know to look for similar
+ typosquat patterns over the next 30 days.
diff --git a/playbooks/README.md b/playbooks/README.md
index f5fba6011..2c99b7453 100644
--- a/playbooks/README.md
+++ b/playbooks/README.md
@@ -9,21 +9,21 @@ rollback paths.
```
playbooks/
-└── packs/
- └── v1/ # Canonical, versioned production pack (62 playbooks
- │ # across 21 directories; the figure
- │ # marketplace/index.json publishes)
- ├── account-takeover/ # 5 — ATO, MFA fatigue, session theft, OAuth abuse
- ├── ransomware/ # 5 — host isolate, shadow-copy, fileserver, C2, exposure
- ├── bec/ # 5 — inbox rules, payment redirect, impersonation, token theft
- ├── insider-risk/ # 5 — mass download, exit-risk, privilege misuse, src-exfil
- ├── cloud-misconfig/ # 10 — S3, IAM, key-leak, root MFA, CloudTrail, SG, RDS, GKE, Azure, x-account
- ├── data-exfil/ # 5 — large upload, archive, DNS tunnel, personal cloud, USB
- ├── lateral-movement/ # 5 — PsExec, RDP, kerberoast, PTH, cross-domain
- ├── supply-chain/ # 5 — npm, PyPI, GH Action, vendor breach, IaC drift
- └── ddos/ # 5 — L3/L4, L7, DNS amp, SYN flood, auth-endpoint
+└── packs/ # Canonical, versioned production pack: 62 playbooks
+ └── v1/ # across 21 directories — the figure
+ # marketplace/index.json publishes
+ ├── account-takeover/ # ATO, MFA fatigue, session theft, OAuth abuse
+ ├── ransomware/ # host isolate, shadow-copy, fileserver, C2, exposure
+ ├── bec/ # inbox rules, payment redirect, impersonation, token theft
+ ├── cloud-misconfig/ # S3, IAM, key-leak, root MFA, CloudTrail, SG, RDS, GKE, Azure
+ ├── … # 17 more: phishing, malware, privilege-escalation,
+ └── ddos/ # container-escape, brute-force, web-compromise, …
```
+`ls playbooks/packs/v1` is the list; the four above are a sample, not the
+whole tree. Counts per directory are not published here because they move
+with the generator and nothing would hold them true.
+
The runtime (`services/agents/app/playbook/store.py`) loads `packs/v1/**`
on startup and merges with user-defined playbooks in
`services/agents/data/playbooks/index.json`. User playbooks win over pack
@@ -66,43 +66,68 @@ Each file is a `*.playbook.json` document validated against the Pydantic
### Supported step types
-| Type | Purpose |
-| --------------- | ------------------------------------------------------ |
-| `enrich` | Call enrichment service for an indicator |
-| `investigate` | Hand off to the AI investigator agent |
-| `notify` | Slack / email / PagerDuty / webhook |
-| `block_ip` | Edge or firewall IP block |
-| `isolate_host` | EDR host isolation |
-| `create_ticket` | Open a ticket in the SOC / HR / procurement queue |
-| `close_case` | Auto-close (typically gated on `verdict`) |
-| `http` | Generic outbound HTTP for any custom integration |
-| `condition` | Branching gate; reads `field op value` from run context |
+All twenty-five members of `StepType` in
+[`models.py`](../services/agents/app/playbook/models.py), which is the only
+place this vocabulary is defined. This table listed nine of them for a long
+time, which is how the approval pattern below came to be documented wrongly.
+
+| Type | Purpose |
+| --- | --- |
+| `enrich` | Call the enrichment service for an indicator |
+| `investigate` | Hand off to the AI investigator agent |
+| `notify` | Slack / Teams / email / PagerDuty / signed webhook. A governed verb |
+| `http` | Outbound HTTP to a **named** tenant integration, through the SSRF guard |
+| `condition` | Branching gate; reads `field op value` from run context |
+| `wait` | Hold for a timer or a callback. Short timers sleep in place; longer ones become a durable pause |
+| `parallel` | Run child steps concurrently, then join |
+| `loop` | Run child steps once per item, bounded |
+| `approval` | Suspend the run until an analyst decides. Durable — see below |
+| `block_ip` | Edge or firewall IP block |
+| `block_ioc` | Block an IOC (hash, domain, IP) |
+| `isolate_host` | EDR host isolation |
+| `kill_process` | Terminate a process on an endpoint |
+| `quarantine_file` | Quarantine a file on an endpoint |
+| `run_av_scan` | Trigger an on-demand AV scan |
+| `run_script` | Run a vendor-side response script |
+| `osquery_live_query` | Distributed osquery via osctrl / FleetDM / `aisoc-direct`. A governed verb |
+| `disable_user` | Disable an identity |
+| `reset_password` | Force a password reset |
+| `revoke_session` | Revoke active sessions |
+| `force_mfa` | Force re-authentication with a second factor |
+| `search_siem` | Run a query against a connected SIEM |
+| `create_notable_event` | Write a notable / incident back to the SIEM |
+| `create_ticket` | Open a ticket in the SOC / HR / procurement queue |
+| `close_case` | Auto-close (typically gated on `verdict`) |
+
+Every verb that touches somebody's estate is graded against its own
+capability contract at dispatch, and previews rather than acts unless
+`AISOC_PLAYBOOK_ACTIONS_EXECUTE` is set. See
+[Playbooks](../apps/docs/docs/concepts/playbooks.md) for the full
+`status` / `executed` table.
### Human-approval gates
-Approval gates are modelled as `condition` steps that read a flag from
-run context (e.g. `context.approved_by_oncall`). The flag is expected to
-be set by an out-of-band approval system — Slack interactive button,
-email link, or the AiSOC web console — before the gated step runs.
+Use an `approval` step. The run suspends to Postgres, survives a restart of
+the agents service, resumes at the step after the approval once it is
+decided, and expires with a recorded outcome rather than hanging.
```json
{
"id": "approve",
- "name": "Wait for human approval",
- "type": "condition",
- "params": {},
- "condition": {
- "field": "context.approved_by_oncall",
- "operator": "eq",
- "value": true
- },
- "next_true": "reset",
- "on_failure": "abort",
- "retry_max": 0,
- "timeout_seconds": 5
+ "name": "Approve credential reset",
+ "type": "approval",
+ "params": { "prompt": "Reset this account's password?" },
+ "on_failure": "abort"
}
```
+**Do not model a gate as a `condition` step reading a flag somebody sets out
+of band.** This file used to document exactly that, and it never worked: the
+engine evaluates each condition once against the run context and moves on, so
+the "wait" was a single false evaluation, and no endpoint ever existed to flip
+the flag. A playbook written that way ran straight through its gate into
+whatever it was gating.
+
### Rollback
Rollback is modelled by pairing every containment action with a
diff --git a/scripts/check_hosted_hostname.py b/scripts/check_hosted_hostname.py
index 224130b25..f2148d1a6 100644
--- a/scripts/check_hosted_hostname.py
+++ b/scripts/check_hosted_hostname.py
@@ -189,9 +189,16 @@ ALLOWED: dict[str, tuple[int, str]] = {
"marketing/launch/blog-outlines.md": (2, _MARKETING),
"marketing/launch/product-hunt.md": (1, _MARKETING),
# --- history: changelog, releases, decision records, incident notes ----
- "CHANGELOG.md": (24, _HISTORY),
+ # 24 before the v7.2.0 benchmark-scoreboard entry's dead `docs.` link was
+ # repointed at the OSS docs site; the sentence is annotated rather than
+ # rewritten, so the history still says what it said.
+ "CHANGELOG.md": (23, _HISTORY),
"RELEASES.md": (4, _HISTORY),
- "AGENTS.md": (6, _HISTORY),
+ # AGENTS.md held six: it was a session log that published the
+ # commercial hostname, and it is now contributor guidance that
+ # mentions no deployment but this project's own. The entry goes
+ # with them, because a stale exemption claims a reader checked
+ # something that is no longer there.
"docs/decisions/0004-live-demo-strategy.md": (5, _HISTORY),
"docs/decisions/0003-mssp-pricing-shape.md": (2, _HISTORY),
"services/api/app/db/database.py": (1, _HISTORY),
@@ -220,7 +227,11 @@ ALLOWED: dict[str, tuple[int, str]] = {
"services/agents/app/workers/fused_alert_consumer.py": (1, _UUID_SEED),
# --- documentation about the managed instance --------------------------
"apps/docs/docs/operations/managed-instance.md": (14, _DOCS),
- "apps/docs/docusaurus.config.ts": (2, _DOCS),
+ # 2 before the header stopped advertising `docs.tryaisoc.com` as a second
+ # live deploy target. It does not resolve; the one remaining mention says
+ # so. DOCS_URL lands in canonical tags and the sitemap, so a non-resolving
+ # host here is published as the authoritative address for every page.
+ "apps/docs/docusaurus.config.ts": (1, _DOCS),
"docs/operations/live-demo-runbook.md": (7, _DOCS),
"docs/design/landing-page-brief.md": (3, _DOCS),
"docs/design/landing-page-content.md": (3, _DOCS),
@@ -228,8 +239,13 @@ ALLOWED: dict[str, tuple[int, str]] = {
"docs/design/README.md": (1, _DOCS),
"docs/managed-mode.md": (1, _DOCS),
"docs/press/README.md": (1, _DOCS),
- "examples/lateral-movement.md": (1, _DOCS),
- "examples/phishing-payload.md": (1, _DOCS),
+ # examples/lateral-movement.md and examples/phishing-payload.md were
+ # exempted here under "accurate as written". They were not: both linked
+ # `docs.tryaisoc.com`, which does not resolve at all (DNS failure, not a
+ # 404). The sentences now name the console surface instead of linking a
+ # host that was never stood up, so the exemptions are gone rather than
+ # re-counted. A hostname exemption is only honest once the URL has been
+ # fetched.
"services/slack-bot/README.md": (1, _DOCS),
".env.example": (2, _DOCS),
# --- plan files: never edited, reported instead ------------------------
diff --git a/scripts/check_profile_service_counts.py b/scripts/check_profile_service_counts.py
index 272a6f19f..953e66190 100644
--- a/scripts/check_profile_service_counts.py
+++ b/scripts/check_profile_service_counts.py
@@ -72,6 +72,11 @@ CLAIM_SITES: tuple[tuple[str, str, str], ...] = (
# compose file supporting neither. Registered rather than merely
# corrected: an unregistered figure is one nobody notices going stale,
# which is how all three got there.
+ # The contributor guide at the repository root. Both figures are in its
+ # opening "get it running" block, which is the first thing a reader runs,
+ # so a stale one there is wrong before anything else can be.
+ ("AGENTS.md", "core", r"CORE profile: (\d+) long-running services"),
+ ("AGENTS.md", "prod:full", r"adds the rest \((\d+) services"),
("install.sh", "core", r"Starting the (\d+)-service CORE stack"),
("apps/docs/docs/deployment/walkthrough.mdx", "core", r"starts the (\d+) CORE services"),
("Makefile", "core", r"`missing` on all (\d+) first-party services"),