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.

Merge remote-tracking branch 'origin/main' into fix/playbook-editor-step-vocabulary

Beenu Arora15d36b4d397f
diff --cc CHANGELOG.md
index baef29ac8,c3e3a3d0a..f2533cc2b
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -29,42 -29,17 +29,52 @@@ and this project adheres to [Semantic V
to published prose has no hand-copied link. A paragraph that dates or
negates the claim is exempt, so the retraction can quote the wording it
retracts.
+ - **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 the
repository supports, and the window closed in June 2026 while still being
advertised 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