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.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
Merge remote-tracking branch 'origin/main' into fix/playbook-editor-step-vocabulary
Beenu Arora15d36b4d397f
diff --cc CHANGELOG.mdindex baef29ac8,c3e3a3d0a..f2533cc2b--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -29,42 -29,17 +29,52 @@@ and this project adheres to [Semantic Vto published prose has no hand-copied link. A paragraph that dates ornegates the claim is exempt, so the retraction can quote the wording itretracts.+ - **The prerequisites that were required but undocumented.** Beyond Docker and+ its memory, a first run needs `python3` **on the host** (`make smoke` runs+ the golden-pipeline script there, so without it you can start AiSOC but+ cannot prove it works), `bash` (`make up` gates on `scripts/doctor.sh+ --ports-only` before it calls compose), and roughly 18 GB of free Docker+ disk — previously implied only by a troubleshooting row noting that Kafka+ corrupts its log directory and *still passes its healthcheck* when the+ daemon runs out of space. Node 22 and pnpm 8, which the installers require,+ were also unlisted. All are now in the quick-start prerequisites table with+ the command each one gates.+- **The playbook parity gate now reads every declaration of the step+ vocabulary, wherever it is.** `scripts/check_playbook_schema_parity.py`+ compared the engine against `packages/types/src/playbook.ts` and never+ opened `apps/web`; naming the editor's file here would have fixed that file+ and left the next one free. The TypeScript half is a scan: every `.ts` and+ `.tsx` file in the tree is parsed for literal collections of step-type+ names, and any collection overlapping the engine's vocabulary must either+ match it exactly or be a recorded subset with a reason, checked in both+ directions so an exemption that stops being needed fails the build. The+ editor's execution annotations are compared against the schema's+ `x-aisoc-execution` in both directions as well, so a surface cannot tell an+ author a step will run when the contract says it will not. `--list` prints+ what the scan credited, not only what it flagged, and the gate refuses to+ report agreement when it finds no declaration at all.++ Against `origin/main` it reports 56 disagreements across all five+ vocabularies; against this tree it credits five declarations, each complete.++ Two limits are stated rather than left implicit: a collection overlapping+ the vocabulary by fewer than two members is not treated as one, and a list+ derived at runtime is not a literal and is not seen — which is the shape the+ gate wants, because a derived list cannot drift. A file the reader cannot+ parse to the end is never silently skipped: it is checked for step-type+ names in its raw bytes first, and the gate refuses the tree if it finds any.++- **A WCAG AA sweep over all twenty-two inspector forms.** The labels in+ `SchemaForm` and `StepInspector` sat beside their controls with no+ association, requiredness was an `aria-hidden` asterisk, help text was+ unreferenced, and the error summary named fields it could not be reached+ from. Controls now carry ids, labels `htmlFor`, `aria-required`,+ `aria-invalid` and `aria-describedby`; errors are reported per field as well+ as in the summary; the condition and params groups are fieldsets. The sweep+ also caught `<ul role="alert">`, which is not an allowed role for a list and+ left its items without a list parent.+### Changed- **`readme_gates.py` covers the governance documents.** Its `FIGURE_DOCS`@@@ -119,51 -94,75 +129,119 @@@fabricated logos, but four of them assert a partner count nothing in therepository supports, and the window closed in June 2026 while still beingadvertised as upcoming.+ - **The Windows installer routed evaluators to a stack that cannot answer the+ question they came to ask.** `install.sh` was changed to bring up the real+ deployment, create an administrator and verify the pipeline; `install.ps1`+ was not, and nothing noticed. It handed off to `pnpm aisoc:demo` — a compose+ file that opens by saying it does not run the AiSOC pipeline, has no ingest+ service and no fusion service, sets `AISOC_DISABLE_KAFKA=true`, and whose+ console content comes entirely from a seed script writing rows straight into+ Postgres — and then printed `AiSOC is up and running.` A Windows user saw a+ populated console and concluded the platform worked, having never run the+ platform. `install.ps1` now performs the stages `make up` and `make smoke`+ perform: a port pre-check that names the process holding a port rather than+ letting compose fail with `Bind for 0.0.0.0:5432 failed`, `docker compose+ up -d`, a wait that reads `docker compose ps -a` so an exited or+ crash-looping container fails rather than passing, `docker compose run --rm+ -T api python -m app.scripts.bootstrap_admin`, and the golden-pipeline+ runner. Windows has no `make` and the Makefile's recipes are POSIX shell, so+ these are native re-implementations of the same commands rather than a+ `make` call; `tests/test_installer_parity_gate.py` fails the build if the+ two installers diverge again.+ - **No administrator was created on Windows, and the closing banner said+ nothing about credentials.** A Windows user either could not sign in at all+ or signed in to a seeded database and evaluated that as the product. The+ banner now surfaces the generated password the same way `install.sh` does:+ printed once, stored nowhere, with the reset command alongside it. It also+ no longer claims the pipeline was verified when the check was skipped for+ want of a Python interpreter.+ - **`install.ps1` pointed at an uninstaller that does not exist.** The closing+ banner named `.\scripts\install\uninstall.ps1`; the file is `uninstall.ps1`+ at the repository root and has never been anywhere else, so the last+ instruction the installer gave a Windows user could not work. The parity+ gate now asserts every `.ps1` path either script tells a user to run is a+ file in the repository.+ - **`uninstall.ps1` left the whole stack running while reporting success.** It+ tore down only `infra/compose/docker-compose.demo.yml`, so every CORE+ container — Postgres still holding 5432 — survived an uninstall that said it+ was complete. It now brings down the root `docker-compose.yml` project+ across every optional profile, then the demo project for anyone who ran the+ older installer.+ - **`install.ps1` installed dependencies nobody tested.** It used+ `pnpm install --no-frozen-lockfile` where `install.sh` uses+ `--frozen-lockfile` for the stated reason that a self-hoster's install must+ not quietly resolve a dependency set CI never saw. It also accepted Node 20+ where `install.sh` requires 22, the version every workflow tests on and both+ Node images ship. Both now match, and the gate compares them.+ - **The docs portal contradicted the README on whether the pipeline works.**+ `quickstart.md` was a pre-v8.2 page built around `pnpm aisoc:demo`; because+ the scripts it named still exist, nothing errored and it simply took readers+ to the wrong stack. Three statements were false. It claimed `.env.example`+ ships "a pre-generated dev `AISOC_CREDENTIAL_KEY`" — it ships a placeholder+ that is worse than an empty value, because an empty one makes the API+ generate an ephemeral key and warn while a malformed one makes the+ credential vault raise, so the first request touching a connector secret+ returns HTTP 500. It claimed events posted to `/v1/ingest/batch` "accept+ cleanly but never become `Alert` rows", which is the exact path `make smoke`+ asserts and the README publishes as its headline proof. And its cheat sheet+ offered `aisoc keygen` as the way to generate that vault key, when `aisoc+ keygen` writes an Ed25519 plugin-signing pair to `~/.aisoc/signing.key` and+ has nothing to do with Fernet. The page is now written around `make up`,+ `make bootstrap` and `make smoke`, and its compose-profile table was rebuilt+ from `docker-compose.yml` rather than corrected from the old text — six port+ numbers and profile memberships were wrong, and two whole profiles were+ missing.+ - **`installation.md` documented flags that do not exist.** `-SkipDemo`,+ `AISOC_SKIP_DEMO` and `-AisocDir` are not accepted by either installer; the+ real spellings are `--no-launch` / `-NoLaunch` and `--clone-dir` /+ `-CloneDir`. The page also still promised a browser opening on a seeded+ ransomware case with pre-filled credentials, which no longer happens and for+ which there are no default credentials.+- **The playbook editor could author nine of the engine's twenty-two step+ types, and the build was green.** `apps/web/src/components/playbooks/types.ts`+ declared its own nine-member `StepType` union under a header comment+ claiming it mirrored `services/agents/app/playbook/models.py`, which+ declares twenty-two. The registry behind every form is keyed+ `Record<StepType, StepSchema>`, so exhaustiveness was satisfied against the+ *local* union and thirteen missing forms compiled cleanly; had it imported+ the union from `packages/types`, `Record` would have failed with thirteen+ missing keys. None of the fourteen files in the directory imported the+ published package. It now re-exports `StepType` from `@aisoc/types`, and the+ compiler named the gap.++ The thirteen forms are built: `block_ioc`, `osquery_live_query`,+ `disable_user`, `reset_password`, `revoke_session`, `force_mfa`,+ `kill_process`, `quarantine_file`, `run_av_scan`, `run_script`,+ `search_siem`, `create_notable_event`, and `approval`. Each collects what+ its executor in `services/actions` reads, and each governed verb's target+ field is keyed on the name `engine._resolve_target` actually looks for, so a+ saved step carries its own target rather than depending on the alert context+ happening to hold one. Nothing collects a credential — those are resolved+ per tenant from the connector vault at dispatch — and nothing offers a+ `dry_run` control, because the bridge does not read one.++ `approval` is presented, never offered. The engine records it in+ `_UNBRIDGEABLE` with a full reason, so the palette and the type dropdown+ filter on `execution !== 'unimplemented'` rather than on its name, an+ existing `approval` step still renders so an imported playbook can be read+ and fixed, and the inspector states that the engine fails the step closed+ and the run stops there.++- **`osquery_live_query` reported SUCCESS while running nothing.** Its handler+ returned an error dict when the osquery backend clients could not be+ imported — which is always, in the shipped agents image, because those+ clients live in `services/actions` — and a returned dict leaves the step+ status at SUCCESS. Reachable from the console the moment the editor could+ author the type, so it now raises `PermanentStepFailure` and fails closed.++- **Three more partial vocabularies in the same directory.** `stepColors.ts`+ held a second nine-entry `Record<StepType, …>`; `StepInspector` and+ `PlaybookEditor` each hard-coded a nine-member array. All three are derived+ from the registry now. `packHelpers.ts` mapped step types to integration+ badges as a `Record<string, …>` covering eighteen of twenty-two, so a+ playbook built from the other four claimed to use no integrations at all.+## [10.0.0] — 2026-09-25**Two ways for a control to be absent: not written, or written and not