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
Three wave-2 gaps where the control existed and authorized nothing (#723)
Beenu Arora4595d504ef9f
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfileindex 8d5209fc4..5d8b83ee0 100644--- a/.devcontainer/Dockerfile+++ b/.devcontainer/Dockerfile@@ -114,6 +114,20 @@ RUN corepack enable \RUN su node -c "pnpm config set store-dir /home/node/.local/share/pnpm/store \&& pnpm store status >/dev/null 2>&1 || true"+# ─── Docker socket access for the non-root user (issue #716) ────────────────+#+# `apt install docker.io` creates the `docker` group but puts nobody in it, so+# `node` could not reach /var/run/docker.sock and every `docker` command+# failed with a permission error that reads like a missing daemon. The+# docker-in-docker feature does this too; baking the binaries without it left+# the user locked out of the socket its own daemon creates.+#+# `|| true` on groupadd: the base image may already define the group, and a+# duplicate is not a build failure.+RUN groupadd --system docker 2>/dev/null || true; \+ usermod -aG docker node; \+ getent group docker+USER nodeWORKDIR /workspaces/AiSOCdiff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.jsonindex 81421208a..f128e67ba 100644--- a/.devcontainer/devcontainer.json+++ b/.devcontainer/devcontainer.json@@ -7,7 +7,17 @@"dockerfile": "Dockerfile","context": "."},- "//features": "We intentionally do NOT enable docker-in-docker / python / go / github-cli features here — they are baked into the image at build time. Re-enabling them would cancel the cold-start win.",+ "//features": "We intentionally do NOT enable docker-in-docker / python / go / github-cli features here — the *binaries* are baked into the image at build time and re-enabling the features would cancel the cold-start win. But see runArgs/mounts/postStartCommand below: the docker-in-docker feature also supplies container runtime options and a dockerd entrypoint, and that half has no Dockerfile equivalent. Omitting it is what broke the Codespaces quickstart (#716).",+ "//runArgs": "The half an image cannot provide. Capabilities are granted at container creation, so a Dockerfile cannot self-grant them: without --privileged the container ran with CapEff: 0 and CAP_SYS_ADMIN outside the bounding set, so not even sudo could start dockerd. --init reaps the zombies a background dockerd leaves behind.",+ "runArgs": ["--privileged", "--init"],+ "//mounts": "dockerd's overlay2 graph driver cannot run on the container's own overlay filesystem. A named volume gives it a real one, and keeps pulled images across a Codespace stop/resume so the demo does not re-pull on every boot.",+ "mounts": [+ {+ "source": "aisoc-dind-var-lib-docker",+ "target": "/var/lib/docker",+ "type": "volume"+ }+ ],"hostRequirements": {"cpus": 4,"memory": "16gb",@@ -34,6 +44,8 @@},"//onCreateCommand": "Runs once at image-spawn time. The pnpm store is already warm in the prebuilt image, so `--frozen-lockfile=false` here is fast (≤ 30 s on a green Codespace).","onCreateCommand": "pnpm install --frozen-lockfile=false",+ "//postStartCommand": "Starts dockerd. Runs on every container start rather than only at create, so a Codespace stop/resume comes back with a working daemon — `onCreateCommand` would leave the second boot without one.",+ "postStartCommand": "bash .devcontainer/start-docker.sh","postAttachCommand": "echo '\\n>>> AiSOC dev container is ready.\\n>>> To run the demo, open a terminal and run:\\n>>> pnpm aisoc:demo --no-open\\n>>> Then click the forwarded port 3000 in the Ports panel.\\n>>> Or, no-Docker: pip install -e packages/aisoc-sandbox && aisoc-sandbox demo\\n'","remoteUser": "node","containerEnv": {diff --git a/.devcontainer/start-docker.sh b/.devcontainer/start-docker.shnew file mode 100755index 000000000..67b3b6897--- /dev/null+++ b/.devcontainer/start-docker.sh@@ -0,0 +1,68 @@+#!/usr/bin/env bash+#+# Start dockerd inside the devcontainer (issue #716).+#+# `ghcr.io/devcontainers/features/docker-in-docker` does two things, and only+# the first has a Dockerfile equivalent:+#+# 1. installs the Docker binaries — replicated by `apt install docker.io`+# plus the Compose v2 plugin in ../Dockerfile+# 2. supplies container *runtime* options (`--privileged`, `--init`, a+# volume at /var/lib/docker) and an entrypoint that launches dockerd+#+# Capabilities are granted at container creation and cannot be self-granted+# from an image, so (2) is impossible to bake in. The devcontainer.json now+# passes the runtime options, and this script is the missing entrypoint. Both+# halves are needed: with the options and no daemon, `docker ps` fails; with+# the daemon and no options, dockerd cannot create its network bridge.+#+# Idempotent — `postStartCommand` runs on every container start, including+# after a Codespace stop/resume, and a second dockerd must not be launched.+set -euo pipefail++readonly SOCKET=/var/run/docker.sock+readonly LOG=/tmp/dockerd.log+# Long enough for a cold overlay2 graph driver on a slow Codespaces disk,+# short enough that a genuinely broken daemon is reported rather than waited+# on forever.+readonly TIMEOUT_SECONDS="${AISOC_DOCKERD_TIMEOUT:-60}"++log() { printf '[start-docker] %s\n' "$1"; }++if docker info >/dev/null 2>&1; then+ log "daemon already reachable"+ exit 0+fi++# A missing socket is the normal first-boot state. A socket that exists but+# does not answer means a previous dockerd died, and leaving the stale file+# in place makes the new one refuse to bind.+if [ -S "$SOCKET" ]; then+ log "removing a stale socket left by a dead daemon"+ sudo rm -f "$SOCKET"+fi++if ! sudo -n true 2>/dev/null; then+ # Worth naming precisely, because the symptom ("docker: command not found"+ # is *not* what happens — the CLI is present and the daemon is not) sends+ # people looking in the wrong place.+ log "ERROR: passwordless sudo is unavailable, so dockerd cannot be started."+ log " The container also needs --privileged; see .devcontainer/devcontainer.json."+ exit 1+fi++log "starting dockerd (log: $LOG)"+sudo sh -c "nohup dockerd >'$LOG' 2>&1 &"++deadline=$(( $(date +%s) + TIMEOUT_SECONDS ))+until docker info >/dev/null 2>&1; do+ if [ "$(date +%s)" -ge "$deadline" ]; then+ log "ERROR: dockerd did not become ready within ${TIMEOUT_SECONDS}s."+ log " Last 40 lines of $LOG:"+ sudo tail -n 40 "$LOG" 2>/dev/null || log " (no log written — dockerd never started)"+ exit 1+ fi+ sleep 1+done++log "daemon ready after $(( TIMEOUT_SECONDS - (deadline - $(date +%s)) ))s"diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 2d39f544d..0ec859092 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -191,6 +191,14 @@ jobs:# `python scripts/sync_vendored_nl_query.py` locally to fix.- name: Verify vendored nl_query is in syncrun: python scripts/sync_vendored_nl_query.py --check+ # Same reasoning as nl_query above. The LLM input contract's rules are+ # authored in services/agents and vendored into the API, which is the+ # only way both services can run the *same* classifier — two heuristics+ # disagreeing about what counts as a raw log is worse than one. The API+ # had no contract at all until this was wired, so a drifted or+ # non-importable copy is how the gap silently returns.+ - name: Verify vendored llm_contract_rules is in sync+ run: python scripts/sync_vendored_llm_contract.py --check# Fabricated security data must never render as a tenant's real state.# Around three dozen console components served a `MOCK_*` / `DEMO_*`# array of plausible alerts, connectors and coverage numbers whenever thediff --git a/.github/workflows/devcontainer-coldstart.yml b/.github/workflows/devcontainer-coldstart.ymlindex f9ed2e99b..6165841a3 100644--- a/.github/workflows/devcontainer-coldstart.yml+++ b/.github/workflows/devcontainer-coldstart.yml@@ -9,9 +9,12 @@ name: Devcontainer · cold-start KPI# ~5-min cold boot and the README's "Try AiSOC in 60 seconds" promise no# longer holds for Codespaces users — release-blocking.#-# Strategy: pull the published `ghcr.io/beenuar/aisoc-devcontainer:latest`-# (the same image Codespaces resolves) and verify it is immediately useful-# as a dev environment. We measure two budgets independently:+# Strategy: probe the image Codespaces would resolve and verify it is+# immediately useful as a dev environment. On `main` that is the published+# `ghcr.io/beenuar/aisoc-devcontainer:latest`; on a pull request touching+# `.devcontainer/**` it is built from the PR's own source, because probing+# `:latest` from a PR can only ever validate the *previous* image. We measure+# two budgets independently:## 1. image pull — the "before any keystroke is possible" phase.# Budget: 60 s.@@ -38,13 +41,19 @@ on:paths:- '.devcontainer/**'- '.github/workflows/devcontainer-coldstart.yml'- # PRs that touch this workflow run the toolchain probe against the- # currently-published `:latest` image. That validates the workflow's- # logic without needing a fresh image (the build & publish workflow's- # PR job verifies the Dockerfile separately).+ # A PR that changes `.devcontainer/**` builds the image from *its own*+ # source and probes that, rather than the published `:latest`.+ #+ # It used to probe `:latest` on the grounds that this "validates the+ # workflow's logic without needing a fresh image". The consequence is that+ # a PR could only ever validate the *previous* image, so a Dockerfile+ # change was unverifiable until after it shipped — which is how a+ # devcontainer whose non-root user was not in the `docker` group reached+ # `main` (#716).pull_request:branches: [main]paths:+ - '.devcontainer/**'- '.github/workflows/devcontainer-coldstart.yml'workflow_dispatch:@@ -67,6 +76,12 @@ jobs:env:PHASE_PULL_BUDGET: '60'PHASE_TOOLCHAIN_BUDGET: '30'+ # Built from source on a PR, pulled from GHCR otherwise. Referenced by+ # every phase so the thing measured and the thing probed cannot drift.+ PROBE_IMAGE: >-+ ${{ github.event_name == 'pull_request'+ && 'aisoc-devcontainer:pr'+ || 'ghcr.io/beenuar/aisoc-devcontainer:latest' }}steps:- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7@@ -78,11 +93,22 @@ jobs:username: ${{ github.actor }}password: ${{ secrets.GITHUB_TOKEN }}+ # On a pull request the image under test is the one this PR would+ # publish, so it is built here. The pull budget is a property of the+ # published image and is measured on the `main` paths only.+ - name: Build the image from this PR's source+ if: github.event_name == 'pull_request'+ run: |+ set -euo pipefail+ docker build -t "$PROBE_IMAGE" .devcontainer+ echo "::notice title=devcontainer-probe::built from this PR"+- name: Phase 1 — pull prebuilt image (KPI budget ${{ env.PHASE_PULL_BUDGET }}s)+ if: github.event_name != 'pull_request'run: |set -euo pipefailstart=$(date +%s)- docker pull ghcr.io/beenuar/aisoc-devcontainer:latest+ docker pull "$PROBE_IMAGE"elapsed=$(( $(date +%s) - start ))echo "::notice title=devcontainer-pull-seconds::${elapsed}"if [ "$elapsed" -gt "${PHASE_PULL_BUDGET}" ]; then@@ -101,7 +127,7 @@ jobs:# streamed directly to the job log — no inside-container# redirection that would swallow errors on container exit.docker run --rm \- ghcr.io/beenuar/aisoc-devcontainer:latest \+ "$PROBE_IMAGE" \bash -lc 'set -euo pipefailecho "── node ──"; node --version@@ -115,6 +141,18 @@ jobs:echo "── docker compose ──"; docker compose versionecho "── ripgrep ──"; rg --version | head -1echo "── jq ──"; jq --version+ # Issue #716: the probe above asserted the docker *CLI* exists,+ # which it does without any daemon — so a container that could+ # never run `pnpm aisoc:demo` passed this check for months.+ # A daemon needs runtime options the image cannot grant itself,+ # so it is verified in Phase 3 against a container started the+ # way devcontainer.json starts one, not here.+ echo "── docker socket access ──"+ getent group docker+ id node | grep -q "(docker)" || {+ echo "node is not in the docker group — it cannot reach the socket" >&2+ exit 1+ }'elapsed=$(( $(date +%s) - start ))echo "::notice title=devcontainer-toolchain-seconds::${elapsed}"@@ -122,3 +160,38 @@ jobs:echo "::error::Devcontainer toolchain check took ${elapsed}s, over budget of ${PHASE_TOOLCHAIN_BUDGET}s." >&2exit 1fi++ - name: Phase 3 — a Docker daemon actually starts (issue #716)+ # The gap that let the Codespaces quickstart stay broken: Phase 2+ # proves the CLI is installed, which says nothing about whether+ # `pnpm aisoc:demo` can run. The binaries were baked in without the+ # runtime options the docker-in-docker feature also supplies, so the+ # container had CapEff: 0 and dockerd could never start.+ #+ # This runs the real script under the same flags devcontainer.json+ # passes. Drop either `--privileged` or the /var/lib/docker volume and+ # it fails, which is the point — a passing Phase 2 with a failing+ # Phase 3 is exactly the state #716 described.+ run: |+ set -euo pipefail+ start=$(date +%s)+ docker run --rm --privileged --init \+ -v aisoc-coldstart-dind:/var/lib/docker \+ -v "$PWD/.devcontainer:/probe/.devcontainer:ro" \+ -w /probe \+ "$PROBE_IMAGE" \+ bash -lc '+ set -euo pipefail+ bash .devcontainer/start-docker.sh+ echo "── daemon reachable as the non-root user ──"+ docker info --format "server: {{.ServerVersion}} | driver: {{.Driver}}"+ echo "── compose can talk to it ──"+ docker compose version+ echo "── and it can actually run something ──"+ docker run --rm hello-world >/dev/null && echo "container ran"+ '+ echo "::notice title=devcontainer-dockerd-seconds::$(( $(date +%s) - start ))"++ - name: Clean up the probe volume+ if: always()+ run: docker volume rm -f aisoc-coldstart-dind || truediff --git a/.github/workflows/publish-images.yml b/.github/workflows/publish-images.ymlindex 660627d92..ee11c8d21 100644--- a/.github/workflows/publish-images.yml+++ b/.github/workflows/publish-images.yml@@ -94,6 +94,14 @@ jobs:steps:- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7+ # arm64 is cross-built on an amd64 runner, which needs the binfmt+ # handlers QEMU registers. Without this the arm64 leg of the manifest+ # fails with "exec format error" rather than anything that names the+ # missing piece. Same SHA-pinned action devcontainer-build.yml already+ # uses for its multi-arch build.+ - name: Set up QEMU+ uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4+- uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4- uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4@@ -143,7 +151,19 @@ jobs:build-args: ${{ steps.web-build-args.outputs.build_args }}cache-from: type=gha,scope=${{ matrix.service }}cache-to: type=gha,mode=max,scope=${{ matrix.service }}- platforms: linux/amd64+ # Apple Silicon is the majority of contributor laptops, and+ # amd64-only manifests meant `pnpm aisoc:demo` - the README's+ # headline "Docker + pnpm" path - could not pull a single service+ # image there. Compose reported+ # `no matching manifest for linux/arm64/v8` for every one, fell back+ # to building four services from source, and the quickstart became a+ # long silent build instead of a demo. The devcontainer image has+ # been multi-arch all along, so the pattern already existed; it was+ # simply never applied to the service images.+ #+ # This roughly doubles image-build time. That is the correct trade:+ # a first run that cannot start is worse than a slower release.+ platforms: linux/amd64,linux/arm64# SLSA provenance + SPDX SBOM attached to the image by BuildKit.provenance: mode=maxsbom: truediff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 6c39e5405..69104311a 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -155,6 +155,14 @@ jobs:image: ghcr.io/beenuar/aisoc-slack-botsteps:- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7+ # arm64 is cross-built on an amd64 runner, which needs the binfmt+ # handlers QEMU registers. Without this the arm64 leg of the manifest+ # fails with "exec format error" rather than anything that names the+ # missing piece. Same SHA-pinned action devcontainer-build.yml already+ # uses for its multi-arch build.+ - name: Set up QEMU+ uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4+- uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4- uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4with:@@ -192,7 +200,19 @@ jobs:build-args: ${{ steps.web-build-args.outputs.build_args }}cache-from: type=gha,scope=${{ matrix.service }}cache-to: type=gha,mode=max,scope=${{ matrix.service }}- platforms: linux/amd64+ # Apple Silicon is the majority of contributor laptops, and+ # amd64-only manifests meant `pnpm aisoc:demo` - the README's+ # headline "Docker + pnpm" path - could not pull a single service+ # image there. Compose reported+ # `no matching manifest for linux/arm64/v8` for every one, fell back+ # to building four services from source, and the quickstart became a+ # long silent build instead of a demo. The devcontainer image has+ # been multi-arch all along, so the pattern already existed; it was+ # simply never applied to the service images.+ #+ # This roughly doubles image-build time. That is the correct trade:+ # a first run that cannot start is worse than a slower release.+ platforms: linux/amd64,linux/arm64# SLSA provenance + SPDX SBOM attached to the image by BuildKit.provenance: mode=maxsbom: truediff --git a/.github/workflows/screencast.yml b/.github/workflows/screencast.ymlindex c90c25254..bb2849f74 100644--- a/.github/workflows/screencast.yml+++ b/.github/workflows/screencast.yml@@ -14,10 +14,15 @@ on:workflow_dispatch:inputs:target_url:- description: "URL to record against (defaults to the latest preview)"+ description: "URL to record against. Defaults to a local demo stack (pnpm aisoc:demo)."required: falsetype: string- default: "https://tryaisoc.com"+ # Deliberately a local address rather than a hosted one. A default+ # pointing at a specific deployment means a self-hoster who runs this+ # workflow records somebody else's instance — and that hostname then+ # travels into the README caption and the docs. Bring the stack up+ # with `pnpm aisoc:demo --no-open` and record against it.+ default: "http://localhost:3000"release_tag:description: "Optional release tag; if set, the recording is uploaded as a release asset"required: false@@ -67,7 +72,7 @@ jobs:- name: Run the screencast specworking-directory: apps/webenv:- AISOC_SCREENCAST_URL: ${{ inputs.target_url || 'https://tryaisoc.com' }}+ AISOC_SCREENCAST_URL: ${{ inputs.target_url || 'http://localhost:3000' }}# Disable any analytics injection so the recorder browser# doesn't render a cookie banner in the final cut.AISOC_DISABLE_ANALYTICS: "1"diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 5aef4e794..169dc99bf 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -151,6 +151,172 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Fixed+- **The Codespaces quickstart could never start Docker+ ([#716](https://github.com/beenuar/AiSOC/issues/716)).** The README+ advertises Codespaces as "the zero-install way to drive the real stack in a+ browser"; it failed at step 1 of `pnpm aisoc:demo` and was not recoverable+ from inside the codespace. The `docker-in-docker` feature does two things,+ and only the first has a Dockerfile equivalent: it installs the binaries+ (replicated), and it supplies container *runtime* options (`--privileged`,+ `--init`, a volume at `/var/lib/docker`) plus an entrypoint that launches+ `dockerd`. Capabilities are granted at container creation and cannot be+ self-granted from an image, so baking the binaries and stopping there+ produced a container with `CapEff: 0` and `CAP_SYS_ADMIN` outside the+ bounding set — `sudo` could not help, because the capability was not in the+ set to grant. `devcontainer.json` passes the runtime half now and+ `.devcontainer/start-docker.sh` is the missing entrypoint, running from+ `postStartCommand` so a stop-and-resume comes back with a working daemon.+ `apt install docker.io` also creates the `docker` group and puts nobody in+ it, so `node` could not reach the socket its own daemon creates and every+ command failed with a permission error that reads like a missing daemon.+ The cold-start gate is why this survived: it asserted the docker *CLI* was+ installed, which it is with no daemon anywhere. A third phase now starts a+ real daemon under the same flags and runs a container as the non-root user.+- **Service images were published amd64-only.** Apple Silicon is the majority+ of contributor laptops, and `pnpm aisoc:demo` — the README's headline+ "Docker + pnpm" path — could not pull a single service image there.+ Compose reported `no matching manifest for linux/arm64/v8` for every one,+ fell back to building four services from source, and the quickstart became+ a long silent build instead of a demo. The devcontainer image has been+ multi-arch all along, so the pattern existed and was simply never applied+ to the service images. This roughly doubles image-build time, which is the+ correct trade: a first run that cannot start is worse than a slower+ release.+- **The OSS screencast recorder defaulted to a commercial host.**+ `screencast.yml` recorded `https://tryaisoc.com` unless told otherwise and+ the shot list named that host in three shots, so a self-hoster running the+ workflow would record somebody else's deployment — and that hostname would+ then travel into the README caption. Both default to the local demo stack+ now, and the outro carries no URL at all, because a hostname there dates+ the cut and points viewers at an instance rather than at the project.+- **`beenuar/aisoc-action` does not exist as a repository.** Every+ `uses: beenuar/aisoc-action@v1` example in the README and the integration+ doc 404s. The reference that resolves is the monorepo subdirectory form,+ `beenuar/AiSOC/packages/[email protected]`, which is what both show now;+ `docs/operations/publishing.md` records what the short alias would actually+ require, since a Marketplace listing resolves to a repository root.+- **Config snapshots could never run, and reported themselves enabled.** The+ Go config-snapshotter called `GET {base}/v1/connectors/{id}/resource-config`;+ the connectors service serves `POST /api/v1/connectors/{id}/resource_config`.+ Four mismatches at once — method, prefix, separator, payload — and the last+ is not a typo: that endpoint requires decrypted `auth_config` in the body and+ the ingest service has no vault, so it could never have called that route at+ all. Renaming the URL would have turned a silent 404 into a silent 422.+ Silent either way, because a 404 maps to `ErrNotImplemented`, which the+ snapshotter treats as a soft skip — so an operator saw "T1.2 config snapshots+ enabled" on boot and zero `Configuration` nodes in the graph, with nothing+ connecting the two. Fixed with an instance-scoped route on the connectors+ service that resolves the saved instance and decrypts credentials the way+ `ConnectorScheduler` does at poll time, so the ingest service needs no+ secrets. Query values are escaped: an ARN containing `&` or `#` would+ otherwise truncate the URL or inject a parameter.+- **The documented "latest configuration" graph query matched zero edges.**+ `is_current`, `valid_from` and `valid_to` are declared in+ `schemas/graph-schema.yaml` and the published schema doc advertised an O(1)+ lookup via `:CONFIGURED_AS {is_current: true}`. Nothing wrote any of the+ three. The drift gate could not catch it, because it validates properties+ only on edges declared `event_edge: true` and this one is structural. All+ three are written now, with the limitation stated rather than implied:+ closing the previous interval needs a read-modify-write the ingest hot path+ deliberately does not do, so `valid_to` is **absent** while the interval is+ open — an open interval is not one that closed at the epoch — and the doc+ now shows the `ORDER BY valid_from DESC` query that actually works.+- **Four effective-permissions resolvers were documented as scaffolds long+ after they were implemented.** The endpoint docstring described Azure, GCP,+ Okta and GWS as returning HTTP 501, and the `NotImplementedError` branch had+ been unreachable for as long. All five resolvers report `coverage: "full"`.+ What is still limited is the *snapshot*, not the resolver: only Okta's is+ assembled from a live connector, because the other four expect a connector+ to answer the `__posture_snapshot__` sentinel and **no connector implements+ it**, so with live mode on they return 412 rather than a fabricated+ snapshot. That was honest but unrecorded, so `coverage: full` was the only+ figure a reader saw. A new gate pins the real shape of the gap in both+ directions — a resolver registered without a snapshot source fails, and so+ does a stale entry on the allow-list once its connector starts answering the+ sentinel. The gap is allowed to exist; it is not allowed to be invisible.+- **A fabricated investigation rendered whenever no run was selected.**+ `InvestigationTimeline.tsx` called `makeDemoTimeline()` — a named analyst, a+ routable source IP, "Session suspended; email dispatched" — with no demo+ gate. `check_mock_data_gated.py` missed it because it matches `MOCK_*` /+ `DEMO_*` constant *names* and this is a function call, which is the other of+ the two ways to render invented state. Gated, and the gate now also catches+ a `set*(makeDemo*())` factory. Verified by reverting the component: the+ widened gate names the exact line.+- **A ChatOps approval authorized nobody.** The Slack and Teams bots verified+ who clicked — Slack signs every interaction payload, Teams payloads carry an+ HMAC — recorded that person in an audit event, and then called+ `approve_action(action_id)` with no body. The actions service ran+ `authorize_approver` against `None`, so the permission-tier check *and*+ separation of duties were both skipped; the clicking user appeared in the+ audit trail and was never bound to the authorization decision. An approval+ path that does not authorize is worse than none, because it reads as a+ control.+ A bot cannot supply permissions — it knows a Slack user id and has no idea+ what that person may do in AiSOC, and a bot permitted to assert its own+ permissions could grant itself anything. It now asserts identity only, and+ the actions service maps it through `AISOC_CHATOPS_APPROVERS`: operator+ configuration rather than a directory lookup, because the actions service+ owns no user table and an approval should not depend on a second service+ being reachable. Fails closed — `AISOC_ACTIONS_REQUIRE_APPROVER` defaults+ true, an unmapped user is refused rather than admitted with an empty+ permission set, and a malformed map raises rather than resolving to "no+ approvers", which looks identical to correctly having none. **Operators+ using Slack or Teams approvals must populate the map or approvals will be+ refused**; that is the intended failure.+ Approve and reject are deliberately asymmetric: a rejection causes no vendor+ effect and a timeout-driven one has no human by definition, so requiring an+ identity there would strand expired requests in `awaiting_approval` forever.+ An identity supplied on a rejection is still authorized, and the decider is+ now recorded — it never was.+ Separately, the signed email-approval link pointed at+ `/v1/actions/email-decide`, a path served by no router, so every approve and+ deny button in a rendered approval email linked to a **404** — the documented+ fallback for "Slack is unreachable" failed at the moment it was needed. The+ route exists, and the recipient is signed into the token, because a bare+ signed link is a bearer credential that approves as nobody. Docs:+ `apps/docs/docs/operations/action-approvals.md`, which states the three+ remaining limitations rather than implying they are closed.+- **One `not` rule silently discarded a tenant's entire business-context rule+ set.** Rules are parsed twice by two implementations. The console requires+ `not` to be a mapping; the triage worker iterated every aggregator as a+ list, and iterating a mapping yields its string keys — so+ `_parse_condition("field")` called `.get()` on a `str`, raised+ `AttributeError`, and the caller's catch turned that into `rules = []`. A+ single console-accepted rule therefore stopped every *other* rule that+ tenant had written, suppressions included: a rule written to suppress+ known-benign noise quietly stopped suppressing, with nothing on the console+ to say so and one `warning` in the worker log. Fixed in two places, because+ the parser bug and its blast radius are separate problems — `not` takes a+ mapping now, and a rule that fails to parse is skipped while the rest+ survive. Also closed two smaller divergences: the worker accepted any+ `route_to` string while the console validated against a fixed set, and the+ two copies of that set had nothing pinning them together.+- **The API service had no LLM input contract at all.** `services/agents` has+ had a fail-closed one since T2.3 landed there; the module this repo's own+ notes described as living at `services/api/app/services/llm_safety.py` was+ absent from the tree. Seven endpoints POSTed untrusted input straight to a+ chat-completions provider — `phishing` (a submitted email body,+ attacker-authored by definition), `translation`, `knowledge_base`, `hunts`,+ `nl_detection`, `detection_loop`, and `alert_explain` (a JSON dump of the+ alert). All validate before the request now, because a check that runs after+ it is a log line rather than a control.+ The rules are shared rather than reimplemented: they sat in `contract.py`+ next to LangChain, the cost-telemetry recorder and the response cache, none+ of which ship in the API image — which is precisely why the API could not+ run them. They now live in `contract_rules.py` with stdlib imports only,+ vendored byte-identically and gated by+ `scripts/sync_vendored_llm_contract.py --check`. Two heuristics disagreeing+ about what counts as a raw log would be worse than one.+ Two more holes closed alongside: `services/agents/app/api/explain.py`+ reached a model with raw `httpx` and never touched the contract, invisible+ to a gate that walked the AST for `.ainvoke`/`.astream` only — it proved the+ LangChain path clean and said nothing about the other way to reach a model,+ so a second gate now flags any file that both names a completions endpoint+ and issues its own POST. And the NL-query translator, one file vendored into+ both services, imported `app.llm.contract` and `app.llm.factory` — neither of+ which exists in the API process. The `ImportError` was swallowed, so+ `/nl-query` always returned the deterministic translation and **never+ reached a model**: safe by accident, and invisible.- **The detection truth table was a gate that could certify a no-op.** Itclassified rules by file path and by the key names inside `detection:`, neverconsulting the engine — so it published **947 executable** while the engine@@ -364,6 +530,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0deliberately so**: what remains is a funded provider key for the live-agenteval, not code. Marking it done would be the exact failure the program existsto prevent.+- The wave-2 work adds six more rows, closing at **108 rows: 99 GATED, 9+ PARTIAL, 0 NO GATE** — one per capability whose gate this release built:+ authorized approvals, the signed email link, the LLM input contract across+ both services, rule-id agreement between engine and catalogue, which identity+ providers can resolve permissions live, and config snapshots reaching the+ graph. Four carry a named caveat rather than a clean claim, because the+ limitation is real: approvals are still an in-process dict, the contract is+ a leak control rather than an injection sanitizer, four of five posture+ snapshots cannot be collected, and `is_current` is set on write and never+ cleared.+- **The wave-2 backlog in [#362](https://github.com/beenuar/AiSOC/issues/362)+ was wrong in both directions.** Two items (business-context rules,+ effective-permissions resolvers) were already built, and four had the+ capability present with the path that feeds it broken — which is the same+ shape v8.0 found a dozen times. Auditing each item against the tree before+ writing code is now the first step of any wave, not an optional one.- **A rule id named one rule in the engine and a different one in thecatalogue.** #697 made ids position-independent by pinningdiff --git a/README.md b/README.mdindex 8e1c236e7..eb8d2d9eb 100644--- a/README.md+++ b/README.md@@ -23,7 +23,7 @@ An open-source, self-hostable AI SOC. The agent's prompts, tool calls, and ratio<a href="apps/web/public/demo/"><img src="apps/web/public/demo-thumbnail.svg" alt="90-second AiSOC product walkthrough — agent investigating the seeded LockBit 3.0 case" width="720" /></a>-<sub><em>90-second walkthrough — agent investigates the seeded LockBit 3.0 case end-to-end. The rendered <code>.mp4</code> + <code>hero.gif</code> land with the v8.1 packaging release; the brief is in <a href="docs/demo/SCREENCAST_SHOTLIST.md">docs/demo/SCREENCAST_SHOTLIST.md</a>.</em></sub>+<sub><em>90-second walkthrough — agent investigates the seeded LockBit 3.0 case end-to-end. <strong>This is a placeholder diagram, not a recording.</strong> The shot list is in <a href="docs/demo/SCREENCAST_SHOTLIST.md">docs/demo/SCREENCAST_SHOTLIST.md</a> and the recorder is <a href=".github/workflows/screencast.yml">screencast.yml</a>; the cut ships in v8.2, because recording needs a running stack to point a browser at and the hosted OSS demo is down pending a billing action on the account. Run it yourself with <code>pnpm aisoc:demo</code> and you are looking at the same thing.</em></sub></div>@@ -42,7 +42,7 @@ One alert through the four-stage agent funnel — Detect → Triage → Hunt →| If you have… | Run this | What you get ||---------------------------------------|----------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|-| **npm, and v8.1 has shipped** | `npx aisoc triage --demo` | Batch-scores 200 alerts to escalate / review / suppress with the deterministic triage engine. **Not yet published** — `aisoc` is not on npm today, so this 404s. Builds from [`packages/aisoc-lite/`](packages/aisoc-lite/) meanwhile. |+| **npm, and v8.2 has shipped** | `npx aisoc triage --demo` | Batch-scores 200 alerts to escalate / review / suppress with the deterministic triage engine. **Not yet published** — `aisoc` is not on npm today, so this 404s. Builds from [`packages/aisoc-lite/`](packages/aisoc-lite/) meanwhile. || **A browser** (zero install) | [Open in Codespaces](https://codespaces.new/beenuar/AiSOC?quickstart=1) | Browser IDE → `pnpm aisoc:demo --no-open` → click forwarded port `3000`. ~5 min cold. || **Docker + pnpm** | `git clone https://github.com/beenuar/AiSOC && cd AiSOC && pnpm aisoc:demo` | Local stack on Postgres + Redis + Kafka + api + agents + web. Browser opens at `INC-RT-001`. || **Nothing** (clean Linux/macOS/Win) | `curl -fsSL https://raw.githubusercontent.com/beenuar/AiSOC/main/install.sh \| bash` | Bootstraps Docker, Node, pnpm, git for you; then runs `pnpm aisoc:demo`. |@@ -172,7 +172,7 @@ Full architecture (every service, every storage role, the v1.5 console workbenchA handful of headline capabilities — the rest are catalogued in [`apps/docs/docs/features/`](apps/docs/docs/features/) and indexed at the top of [`apps/docs/docs/intro.md`](apps/docs/docs/intro.md):-> **Maturity (v8.0.0 — Close the loop).** The end-to-end spine is wired and CI-gated: ingest → ClickHouse lake → live detection → fused alert → auto-triage → governed response. v8.0 connected capabilities the codebase already contained but never called. Response actions are now **verified against the vendor** rather than assumed from a 200 — an action that reports success while the effect is absent is reported as failed, because that gap is how a SOC comes to believe a host is contained when it is not. Autonomy is governed by **each tenant's own** L0–L4 policy instead of one deployment-wide environment variable. Repeat-alert suppression, shipped in v7.7, **could never fire** — the evidence fingerprint included the alert id, so no repeat ever matched; it now does. Analysts can **hunt the events AiSOC itself ingested** instead of needing an external SIEM. A verdict citing indicators the evidence never contained is demoted to human review rather than auto-closed. Autonomous *response* still defaults to copilot/dry-run: an autonomy policy governs every real execution. The live-agent LLM benchmark is preview (the deterministic-tier scoreboard is CI-gated per PR); substrate eval suites are GA. Every product claim is backed by a failing test — [claim-to-gate matrix](docs/audit/CLAIM_TO_GATE_MATRIX.md): 93 GATED / 9 PARTIAL / 0 NO GATE. Full per-claim status: [`docs/audit/REALITY_REPORT.md`](docs/audit/REALITY_REPORT.md).+> **Maturity (v8.0.0 — Close the loop).** The end-to-end spine is wired and CI-gated: ingest → ClickHouse lake → live detection → fused alert → auto-triage → governed response. v8.0 connected capabilities the codebase already contained but never called. Response actions are now **verified against the vendor** rather than assumed from a 200 — an action that reports success while the effect is absent is reported as failed, because that gap is how a SOC comes to believe a host is contained when it is not. Autonomy is governed by **each tenant's own** L0–L4 policy instead of one deployment-wide environment variable. Repeat-alert suppression, shipped in v7.7, **could never fire** — the evidence fingerprint included the alert id, so no repeat ever matched; it now does. Analysts can **hunt the events AiSOC itself ingested** instead of needing an external SIEM. A verdict citing indicators the evidence never contained is demoted to human review rather than auto-closed. Autonomous *response* still defaults to copilot/dry-run: an autonomy policy governs every real execution. The live-agent LLM benchmark is preview (the deterministic-tier scoreboard is CI-gated per PR); substrate eval suites are GA. Every product claim is backed by a failing test — [claim-to-gate matrix](docs/audit/CLAIM_TO_GATE_MATRIX.md): 99 GATED / 9 PARTIAL / 0 NO GATE. Full per-claim status: [`docs/audit/REALITY_REPORT.md`](docs/audit/REALITY_REPORT.md).- **84 click-and-connect data connectors** (EDR/XDR, SIEM, NDR, cloud, CNAPP, identity, SaaS, VCS, K8s audit, network) with schema-driven config, live `Test connection`, and vault-encrypted secrets — recently adding Qualys, GreyNoise, JumpCloud, Darktrace, and Imperva alongside IBM QRadar, Netskope, Zeek/Suricata NDR, and more. One query runs SIEM-agnostic **federated search** across Splunk SPL / Sentinel KQL / Elastic ES|QL / **QRadar AQL**. Walkthrough: [`apps/docs/docs/connectors/index.md`](apps/docs/docs/connectors/index.md).- **End-to-end SIEM spine** — a cold `docker compose up` ingests connector data → lands it in the ClickHouse event lake → the executable detection corpus (833 rules) fires on the live stream → a fused alert is created, all asserted by an extended integration gate. Fuse-time threat-intel + CISA-KEV enrichment now feeds the confidence score and exploit-in-wild boost, and **stateful/windowed detections** (brute-force, password-spray, port-scan) run alongside the corpus. [`apps/docs/docs/architecture.md`](apps/docs/docs/architecture.md).@@ -191,7 +191,7 @@ A handful of headline capabilities — the rest are catalogued in [`apps/docs/doAiSOC ships an [MCP server](https://modelcontextprotocol.io) (`services/mcp/`) so analysts can query alerts, run agent investigations, and replay every step the agent took without leaving the IDE or chat. The server exposes 13 tools — discovery, deep-dive, governed lake query, and the action / replay set that walks the agent decision ledger step-by-step.-> **Status — monorepo source build today; npm publish lands in v8.1.** Full setup is in [`apps/docs/docs/integrations/mcp.md`](apps/docs/docs/integrations/mcp.md), which shows the today-vs-published invocations side by side.+> **Status — monorepo source build today; npm publish lands in v8.2.** Full setup is in [`apps/docs/docs/integrations/mcp.md`](apps/docs/docs/integrations/mcp.md), which shows the today-vs-published invocations side by side.---@@ -203,9 +203,9 @@ Three contribution surfaces; each is one file plus optional fixtures, and CI val- **Connector.** Subclass `BaseConnector` in [`services/connectors/app/connectors/`](services/connectors/app/connectors/), register it in `_CONNECTOR_CLASSES`, and add a `plugins/<id>/plugin.yaml` manifest. The marketplace picks it up automatically. Walkthrough: [`apps/docs/docs/connectors/`](apps/docs/docs/connectors/).- **Playbook.** Drop a YAML under [`playbooks/`](playbooks/); [`validate-playbooks`](https://github.com/beenuar/AiSOC/actions/workflows/validate-playbooks.yml) gates the PR. Schema: [`playbook.schema.json`](playbook.schema.json).-Plugin and detection SDK (Python · TypeScript · Go) — see [`apps/docs/docs/plugins/overview.md`](apps/docs/docs/plugins/overview.md). The CLI (`aisoc-cli`) is in [`packages/aisoc-cli/`](packages/aisoc-cli/); PyPI publish lands in v8.1.+Plugin and detection SDK (Python · TypeScript · Go) — see [`apps/docs/docs/plugins/overview.md`](apps/docs/docs/plugins/overview.md). The CLI (`aisoc-cli`) is in [`packages/aisoc-cli/`](packages/aisoc-cli/); PyPI publish lands in v8.2.-**In your CI:** add `- uses: beenuar/aisoc-action@v1` to triage your repo's Dependabot / CodeQL / secret-scanning alerts on every PR (deterministic, nothing leaves your runner; dogfooded on this repo, Marketplace publish lands with v8.1). [Docs](apps/docs/docs/integrations/github-action.md).+**In your CI:** add `- uses: beenuar/AiSOC/packages/[email protected]` to triage your repo's Dependabot / CodeQL / secret-scanning alerts on every PR (deterministic, nothing leaves your runner). The short `beenuar/aisoc-action@v1` form needs a Marketplace listing, which lands with v8.2 — until then the subdirectory form above is the one that resolves. [Docs](apps/docs/docs/integrations/github-action.md).---@@ -214,7 +214,7 @@ Plugin and detection SDK (Python · TypeScript · Go) — see [`apps/docs/docs/p- **Latest GitHub release with downloads:** <https://github.com/beenuar/AiSOC/releases/latest>- **Per-release narrative:** [`RELEASES.md`](RELEASES.md) (mirrors what used to live in this README)- **Machine-readable inventory with file paths, env-var diffs, test counts:** [`CHANGELOG.md`](CHANGELOG.md)-- **v8.1 packaging work in flight (`[~]` items):** [`docs/roadmap/v8-progress.md`](docs/roadmap/v8-progress.md)+- **v8.1 scope, and why packaging is named against v8.2:** [`docs/roadmap/v8-progress.md`](docs/roadmap/v8-progress.md)- **Bigger-picture roadmap (BYOC multi-cloud, MSSP rollups, federated search):** [`ROADMAP.md`](ROADMAP.md)---diff --git a/RELEASES.md b/RELEASES.mdindex 83419745c..b309fef17 100644--- a/RELEASES.md+++ b/RELEASES.md@@ -2,7 +2,7 @@This file mirrors what used to live in the "What's new" section of [`README.md`](README.md). The complete, machine-readable inventory (with file paths, env-var diffs, and per-release test counts) lives in [`CHANGELOG.md`](CHANGELOG.md).-> **TL;DR for first-time visitors:** AiSOC is on `v8.0.0`, released 2026-09-22 — the **Close the loop** release. It connected capabilities the codebase already contained but never called: response actions are verified against the vendor rather than assumed from a 200, autonomy is governed by each tenant's own L0–L4 policy instead of one deployment-wide environment variable, repeat-alert suppression can fire at all, and analysts can hunt the events AiSOC itself ingested. Every product claim is backed by a failing CI test (claim-to-gate matrix: 93 GATED / 9 PARTIAL / 0 NO GATE). The latest GitHub release with notes and downloads: <https://github.com/beenuar/AiSOC/releases/latest>.+> **TL;DR for first-time visitors:** AiSOC is on `v8.0.0`, released 2026-09-22 — the **Close the loop** release. It connected capabilities the codebase already contained but never called: response actions are verified against the vendor rather than assumed from a 200, autonomy is governed by each tenant's own L0–L4 policy instead of one deployment-wide environment variable, repeat-alert suppression can fire at all, and analysts can hunt the events AiSOC itself ingested. Every product claim is backed by a failing CI test (claim-to-gate matrix: 99 GATED / 9 PARTIAL / 0 NO GATE). The latest GitHub release with notes and downloads: <https://github.com/beenuar/AiSOC/releases/latest>.---@@ -37,7 +37,7 @@ The full inventory (every file, env-var, and test count) lives under `[8.0.0]` i- **Phase D — breadth.** Eight new connectors — IBM QRadar, Exabeam, Securonix, Devo, Netskope, Windows/Sysmon (WEF), Zeek/Suricata NDR, and a generic syslog/CEF listener (D1); an AI/LLM-usage audit connector + eight `llm-*` detections + hot/cold ClickHouse lake tiering (D2); and a live-vendor mock-server smoke suite that exercises each connector's real HTTP client (D3).- **Phase E — prove it.** The public benchmark scoreboard is now CI-gated against a deterministic live-agent MITRE-accuracy run, closing the last `NO GATE` and ratcheting `MAX_NO_GATE` to 0 (E1).-The full inventory (every file, env-var, and test count) lives under `[7.6.0]` in [`CHANGELOG.md`](CHANGELOG.md). Note that the claim-to-gate figure quoted in the v7.6.0 announcement (33 GATED / 7 PARTIAL) was the count at that time; the matrix has grown to 102 rows since.+The full inventory (every file, env-var, and test count) lives under `[7.6.0]` in [`CHANGELOG.md`](CHANGELOG.md). Note that the claim-to-gate figure quoted in the v7.6.0 announcement (33 GATED / 7 PARTIAL) was the count at that time; the matrix has grown to 108 rows since.---diff --git a/ROADMAP.md b/ROADMAP.mdindex 2abd6b884..ffe397056 100644--- a/ROADMAP.md+++ b/ROADMAP.md@@ -44,7 +44,7 @@ A proof-first, security-first program to make every README claim gate-backed, cl- **Phase D (breadth):** D1 eight connectors (QRadar/Exabeam/Securonix/Devo/Netskope/Windows-Sysmon/Zeek-Suricata/syslog-CEF) · D2 AI/LLM-usage audit connector + `llm-*` detections + hot/cold lake tiering · D3 live-vendor mock-server smoke.- **Phase E (prove it):** E1 CI-gated benchmark scoreboard tied to a deterministic live-agent MITRE-accuracy run.-The claim-to-gate matrix stands at **102 rows — 93 GATED / 9 PARTIAL / 0 NO GATE** — **every product claim is backed by a failing test** and the ratchet (`MAX_NO_GATE=0`) forbids any regression. The 9 remaining PARTIAL rows are honest, named deferrals; none was relabelled without building the gate it names. Count the table rows with `python3 scripts/check_claim_gate_matrix.py` rather than trusting a figure quoted in prose — this line has gone stale before. Per-session working detail is tracked locally in `docs/audit/PROGRESS.md`.+The claim-to-gate matrix stands at **108 rows — 99 GATED / 9 PARTIAL / 0 NO GATE** — **every product claim is backed by a failing test** and the ratchet (`MAX_NO_GATE=0`) forbids any regression. The 9 remaining PARTIAL rows are honest, named deferrals; none was relabelled without building the gate it names. Count the table rows with `python3 scripts/check_claim_gate_matrix.py` rather than trusting a figure quoted in prose — this line has gone stale before. Per-session working detail is tracked locally in `docs/audit/PROGRESS.md`.## v4.0 — Shippeddiff --git a/apps/docs/docs/architecture/graph-schema.md b/apps/docs/docs/architecture/graph-schema.mdindex 81d893a33..78e6d9ea8 100644--- a/apps/docs/docs/architecture/graph-schema.md+++ b/apps/docs/docs/architecture/graph-schema.md@@ -245,11 +245,39 @@ Every event edge in the schema below carries the three required event-edge prope### `:CONFIGURED_AS` — `Resource` → `Configuration`-**Structural edge.** The Resource is described by this Configuration snapshot. Multiple Configuration nodes per resource form a time-series; the most-recent one is reachable in O(1) via the `:CONFIGURED_AS {is_current: true}` shortcut.+**Structural edge.** The Resource is described by this Configuration snapshot. Multiple Configuration nodes per resource form a time-series.- **Required edge properties**: `snapshot_id`.- **Additional properties**: `is_current`, `valid_from`, `valid_to`.+:::caution `is_current` is set on write and never cleared+This page previously stated that the most recent configuration was reachable+in O(1) via a `:CONFIGURED_AS {is_current: true}` shortcut. None of+`is_current`, `valid_from` or `valid_to` was written by anything, so that query+matched **zero** edges; the drift gate missed it because it only validates+properties on edges declared `event_edge: true` and this one is structural.++All three are written now, but with a limitation worth stating rather than+implying: closing the previous interval would need a read-modify-write against+the graph, which the ingest hot path deliberately does not do. So every edge+carries `is_current: true` and `valid_to` is **absent** while the interval is+open — an open interval is not one that closed at the epoch, and a reader+filtering `valid_to < now` would otherwise exclude the current configuration.++To get the latest configuration, order by `valid_from` descending and take the+first:++```cypher+MATCH (r:Resource {tenant_id: $tenant, natural_key: $key})-[c:CONFIGURED_AS]->(cfg:Configuration)+RETURN cfg ORDER BY c.valid_from DESC LIMIT 1+```++Note also that `configurationKey` truncates the timestamp into a TTL bucket+(10 minutes by default), so several events touching one resource inside a+window MERGE onto a single Configuration node. Drift is queryable per bucket,+not per event.+:::+### `:DEPLOYED_FROM` — `Container` → `Image`**Structural edge.** A Container instance was launched from a specific Image digest. Lets the graph answer "every running container of this CVE-affected image" in one hop, which is the lookup the agent uses to scope containment.diff --git a/apps/docs/docs/compliance/evidence-pack.md b/apps/docs/docs/compliance/evidence-pack.mdindex bed6aaecc..c0ec1aeaa 100644--- a/apps/docs/docs/compliance/evidence-pack.md+++ b/apps/docs/docs/compliance/evidence-pack.md@@ -33,7 +33,7 @@ and says so.| Prompt-injection resistance | 32-payload adversarial corpus with a recall floor and a false-positive ceiling | `services/agents/tests/adversarial/` || Claim-to-gate traceability | Every product claim mapped to the CI job that fails when it stops being true | `docs/audit/CLAIM_TO_GATE_MATRIX.md` |-The last row is the one worth reading first. It is the honest index: 93 rows+The last row is the one worth reading first. It is the honest index: 99 rows`GATED`, 9 `PARTIAL` with the specific gap named, and a ratchet that refusesto let a row sit at `NO GATE`.diff --git a/apps/docs/docs/integrations/github-action.md b/apps/docs/docs/integrations/github-action.mdindex 0900a0f15..dceb67cec 100644--- a/apps/docs/docs/integrations/github-action.md+++ b/apps/docs/docs/integrations/github-action.md@@ -10,9 +10,22 @@ repository's own security alerts — Dependabot, CodeQL (code scanning), andsecret scanning — and posts verdicts, suppression rationale, and prioritizationas a PR comment or job summary. No LLM, no data leaves your CI runner.-> **Status:** the Action is dogfooded on the AiSOC repo today via the in-repo-> path (`uses: ./packages/aisoc-action`). Publishing to the GitHub Marketplace-> as `beenuar/aisoc-action@v1` lands with the v8.0 launch.+:::warning Use the subdirectory form+`beenuar/aisoc-action` **does not exist as a repository** — that reference+404s, and every example on this page used to carry it. The form that resolves+today points at the action's directory inside the monorepo:++```yaml+- uses: beenuar/AiSOC/packages/[email protected]+```++Pin a tag rather than a branch, so a workflow cannot change underneath you.++The short `beenuar/aisoc-action@v1` alias needs a GitHub Marketplace listing,+which is an account action rather than an engineering one, and is named+against v8.2 alongside the npm and PyPI publishes. The Action itself is+complete and dogfooded on this repo via `uses: ./packages/aisoc-action`.+:::## PR triage (comment on every pull request)@@ -28,7 +41,7 @@ jobs:triage:runs-on: ubuntu-lateststeps:- - uses: beenuar/aisoc-action@v1+ - uses: beenuar/AiSOC/packages/[email protected]with:mode: pr-commentmin-severity: low@@ -57,7 +70,7 @@ jobs:digest:runs-on: ubuntu-lateststeps:- - uses: beenuar/aisoc-action@v1+ - uses: beenuar/AiSOC/packages/[email protected]with:mode: digest```diff --git a/apps/docs/docs/operations/action-approvals.md b/apps/docs/docs/operations/action-approvals.mdnew file mode 100644index 000000000..157848120--- /dev/null+++ b/apps/docs/docs/operations/action-approvals.md@@ -0,0 +1,182 @@+---+title: Action approvals+description: How AiSOC authorizes a human approval of a response action — the permission tier, separation of duties, and how Slack, Teams and email approvers are mapped to principals.+---++# Action approvals++A response action above the auto-execute threshold waits for a human. This page+covers who is allowed to be that human, and how AiSOC knows.++:::info What changed in v8.1+Slack and Teams approvals used to authorize **nobody**. The bots verified who+clicked — Slack signs every interaction payload, Teams payloads carry an HMAC —+recorded that person in an audit event, and then called the actions service with+no approver. The permission-tier check and separation of duties were both+skipped, so the clicking user appeared in the audit trail but was never bound to+the authorization decision.++Approvals now require a resolvable identity by default. **If you use Slack or+Teams approvals, you must populate `AISOC_CHATOPS_APPROVERS` or approvals will+be refused with a 403.** That is the intended failure: an approval path that+does not authorize reads as a control while providing none.+:::++## The two checks++Every approval runs through `authorize_approver` in+`services/actions/app/security/authz.py`:++1. **Permission tier.** The approver must hold the permission the action's blast+ radius demands — `actions:execute:low`, `:medium` or `:high`, where a higher+ tier grants the lower ones and `actions:*` grants all. Isolating a host is a+ high-blast action; someone with `actions:execute:low` cannot approve it.+2. **Separation of duties.** The approver must not be the principal who+ requested the action. This check needs only an identity, which is why a+ principal-less approval could never satisfy it.++## Why the bot does not send permissions++A bot knows a Slack user id. It has no idea what that person may do in AiSOC,+and a bot permitted to assert its own permissions would be a bot that could+grant itself anything. So the bot asserts **identity only**, and the actions+service maps that identity onto a principal.++The mapping is operator configuration rather than a directory lookup. The+actions service owns no user table — the API does — and a network call on the+approval path would mean an approval whose authorization depends on a second+service being reachable.++```mermaid+flowchart LR+ click["Analyst clicks Approve"] --> bot["Slack or Teams bot"]+ bot -->|"signature verified"| assert["identity only, no permissions"]+ assert --> svc["services/actions"]+ svc --> map["AISOC_CHATOPS_APPROVERS"]+ map --> principal["principal with permissions"]+ principal --> checks["permission tier + separation of duties"]+ checks --> exec["execute, or refuse"]+```++## Configuring approvers++`AISOC_CHATOPS_APPROVERS` on the **actions** service holds JSON, either inline+or as a `file:` path so it can be mounted as a secret:++```json+{+ "slack": {+ "U04ABCDEF": {+ "user_id": "[email protected]",+ "permissions": ["actions:execute:high"],+ "roles": ["soc-lead"],+ "tenant_id": "3f1c0b8e-0000-0000-0000-000000000001"+ },+ "U04GHIJKL": {+ "user_id": "[email protected]",+ "permissions": ["actions:execute:low"]+ }+ },+ "teams": {+ "29:1abcDEF...": { "user_id": "[email protected]", "permissions": ["actions:execute:medium"] }+ },+ "email": {+ "[email protected]": { "user_id": "[email protected]", "permissions": ["actions:execute:high"] }+ }+}+```++Notes that matter in practice:++- **Platform keys are lower-cased; user ids are matched exactly.** Slack ids are+ case-sensitive opaque handles, so `u04abcdef` will not match `U04ABCDEF`.+- **Only `slack`, `teams` and `email` are accepted.** An unknown platform is+ refused rather than trusted, so a new integration cannot quietly inherit+ approval rights.+- **An unmapped user resolves to nothing, not to an empty principal.** A+ permission-less principal would pass the identity check and then fail the tier+ check for a reason you could not tell apart from a misconfigured tier.+- **A malformed map is loud.** Invalid JSON raises rather than resolving to "no+ approvers", because silently having no approvers looks identical to correctly+ having none.+- **Leaving it unset means nobody can approve over ChatOps.** That is the right+ default for a control that was previously absent.++Finding a Slack user id: the `/aisoc` bot logs it on every interaction, or use+Slack's **Copy member ID** in the profile menu.++## Settings++| Variable | Service | Default | Purpose |+|---|---|---|---|+| `AISOC_ACTIONS_REQUIRE_APPROVER` | actions | `true` | Refuse approvals with no resolvable identity. |+| `AISOC_CHATOPS_APPROVERS` | actions | *(unset)* | Platform identity to principal map. |+| `AISOC_ACTIONS_REQUIRE_PRINCIPAL` | actions | `false` | Governs the **request** path, not approvals. |+| `AISOC_EMAIL_APPROVAL_SECRET` | api | *(unset)* | HMAC key for signed email links. Unset fails closed. |+| `AISOC_EMAIL_APPROVAL_TTL_SECONDS` | api | `3600` | Link lifetime. |+| `AISOC_ACTIONS_BASE_URL` | api | `http://aisoc-actions:8085` | Where the email route forwards a decision. |++`AISOC_ACTIONS_REQUIRE_APPROVER` and `AISOC_ACTIONS_REQUIRE_PRINCIPAL` default+in opposite directions on purpose. A system-initiated *request* legitimately has+no human. An *approval* with no identity cannot be evaluated against separation+of duties at all, so it is not a legacy convenience — it is the control being+absent.++## Approve and reject are deliberately asymmetric++Approving requires an identity. Rejecting does not.++A rejection causes no vendor effect, and a timeout-driven rejection has no human+by definition — `services/slack-bot/app/services/approval_timeout.py` fires a+safe default of `rejected` when nobody answers. Requiring an identity there+would leave expired requests stuck in `awaiting_approval` forever.++An identity supplied on a rejection is still authorized, so "who declined to+contain this host, and were they entitled to" has a checked answer rather than+an unverified one.++## Email approvals++When Slack and Teams are unconfigured or unreachable, the API can mail a signed+link. Two properties are worth understanding:++**The recipient is signed into the token.** A bare signed link is a bearer+credential — whoever holds it approves, and the approval arrives with no+principal. The recipient address travels inside the HMAC, and the endpoint+forwards it as the approver, so an email approver must be mapped under `email`+exactly like a Slack one. Re-pointing a forwarded link at yourself breaks the+signature.++**A link works once.** Single-use falls out of the action's own state machine+rather than a nonce table: the actions service only accepts an approval while+the action is `awaiting_approval`, so a replayed link gets a "this action was+already decided" page.++The consuming route is `GET /api/v1/actions/email-decide`. It is unauthenticated+by necessity — the recipient is in a mail client, not a session — so the token+*is* the credential and every check that would normally come from a session+comes from the signature instead.++:::warning This route did not exist before v8.1+`approval_url()` defaulted to `/v1/actions/email-decide`, a path served by no+router, so every approve and deny button in a rendered approval email linked to+a 404 — the documented fallback for "Slack is down" failed at the moment it was+needed.+:::++## Known limitations++Stated rather than implied, because each one changes how you should operate the+feature:++- **Pending approvals are in-memory.** `services/actions` keeps them in a+ process dict, so they are lost on restart and not shared across replicas. Run+ a single actions replica if you depend on approvals surviving, and expect a+ restart to strand anything mid-flight.+- **Nothing pushes an approval card proactively.** The Slack card appears as a+ reply to an analyst's own `/aisoc isolate` or `/aisoc block` command. An+ action that enters `awaiting_approval` from auto-triage, the console or a+ playbook produces no Slack or Teams prompt — you will find it in the console.+- **The Teams approval card has no sender.** Inbound verification and the card+ factory are both real and tested, so Teams can verify and respond to a card+ that nothing in the repo currently sends.diff --git a/apps/docs/docs/operations/codespaces.md b/apps/docs/docs/operations/codespaces.mdindex 6863bd8bf..f7ccb2e5d 100644--- a/apps/docs/docs/operations/codespaces.md+++ b/apps/docs/docs/operations/codespaces.md@@ -31,6 +31,44 @@ The source lives atthe publisher at[`.github/workflows/devcontainer-build.yml`](https://github.com/beenuar/AiSOC/blob/main/.github/workflows/devcontainer-build.yml).+## Why the Docker daemon needs runtime options++Baking the toolchain into the image instead of resolving it through+`features:` is what buys the cold start, but it does not work for Docker, and+that distinction broke the quickstart for several releases+([#716](https://github.com/beenuar/AiSOC/issues/716)).++`ghcr.io/devcontainers/features/docker-in-docker` does two things:++1. **Installs the Docker binaries.** Reproducible in a Dockerfile — that is+ the `docker.io` package plus the pinned Compose v2 plugin above.+2. **Supplies container runtime options** (`--privileged`, `--init`, a volume+ at `/var/lib/docker`) and an entrypoint that launches `dockerd`.++Only the first has a Dockerfile equivalent. **Capabilities are granted at+container creation and cannot be self-granted from an image**, so an image+that bakes the binaries and stops there produces a container with `CapEff: 0`+and `CAP_SYS_ADMIN` outside the bounding set. `sudo` cannot help, because the+capability is not in the set to grant. `dockerd` dies on its first `iptables`+call:++```text+failed to start daemon: Error initializing network controller: ...+iptables -t nat -N DOCKER: Permission denied (you must be root)+```++The symptom is confusing because the CLI works perfectly — `docker --version`+answers, `docker ps` does not — which sends people looking for a missing+install rather than a missing capability.++`devcontainer.json` therefore passes the runtime half explicitly+(`runArgs`, a named volume for `/var/lib/docker` because overlay2 cannot run+on the container's own overlay filesystem), and+[`.devcontainer/start-docker.sh`](https://github.com/beenuar/AiSOC/blob/main/.devcontainer/start-docker.sh)+is the missing entrypoint. It runs from `postStartCommand` rather than+`onCreateCommand` so a Codespace stop and resume comes back with a working+daemon, and it is idempotent because that hook fires on every start.+## Cold-start budgetThe KPI we hold ourselves to is _time-to-first-keystroke in a Codespace_,@@ -43,6 +81,14 @@ acceptance gate.|---|---|---|| `docker pull` of the devcontainer image | 60 s | `PHASE_PULL_BUDGET` || Toolchain ready (every `--version` on PATH) | 30 s | `PHASE_TOOLCHAIN_BUDGET` |+| A Docker daemon actually starts | reported, not budgeted | Phase 3, `#716` |++Phase 3 exists because Phase 2 asserted the docker *CLI* was installed, which+it is with no daemon anywhere — so a container that could never run+`pnpm aisoc:demo` passed the gate for months. Phase 3 runs the real+`start-docker.sh` under the same flags `devcontainer.json` passes, then pulls+and runs a container as the non-root user. Remove `--privileged` or the+`/var/lib/docker` volume and it fails, which is the point.Both budgets are gated by[`.github/workflows/devcontainer-coldstart.yml`](https://github.com/beenuar/AiSOC/blob/main/.github/workflows/devcontainer-coldstart.yml),diff --git a/apps/docs/docs/operations/security.md b/apps/docs/docs/operations/security.mdindex 8c96029bc..55d9a63b8 100644--- a/apps/docs/docs/operations/security.md+++ b/apps/docs/docs/operations/security.md@@ -311,6 +311,48 @@ When you move from `pnpm aisoc:demo` to a production deployment, walk through th- [ ] Enable mTLS between services if you're running on Kubernetes with a mesh.- [ ] Subscribe to the AiSOC GitHub Security Advisories for vulnerability notifications.+## The LLM input contract++Every prompt that leaves AiSOC for a third-party model passes a fail-closed+validator first. It is a **minimum-leak** control: it aborts a call that is+about to ship raw OCSF, vendor log lines, Sysmon XML or secret-shaped values+outside the deployment. It is *not* an injection sanitizer — that is+`PromptInjectionGuard`, which detects and demotes rather than refusing.++The rules live once, in `services/agents/app/llm/contract_rules.py`, and are+vendored byte-identically to `services/api/app/_vendor/llm_contract_rules.py`+(gated by `scripts/sync_vendored_llm_contract.py --check`). One classifier+rather than two: a prompt refused by one service and accepted by the other+reads as a bug in the refusal.++Enforcement is governed by `AISOC_AGENTS_LLM_CONTRACT_ENFORCED` (default on)+for both services, so it cannot be left enabled on one path and disabled on the+other.++Routing an LLM call:++| How you call the model | Use |+|---|---|+| LangChain chat model in `services/agents` | `safe_ainvoke` / `safe_astream` / `make_safe_chat_model` |+| Raw HTTP in `services/agents` | `app.llm.contract.safe_chat_completions_request` |+| Raw HTTP in `services/api` | `app.services.llm_safety.safe_chat_completions_request` |++Two CI gates in `services/agents/tests/test_llm_contract_no_bypass.py` enforce+this. The first walks the AST for `.ainvoke` / `.astream`; the second flags a+file that both names a completions endpoint and issues its own POST.++:::warning Why the second gate exists+The first gate proved the LangChain path was clean and said nothing about the+other way to reach a model. `services/agents/app/api/explain.py` POSTed to a+completions URL with raw `httpx` and was invisible to it for several releases,+under a test named "no bypass" — and **every** LLM call in `services/api` did+the same, because that service had no contract at all. The module this+documentation used to describe as living there did not exist in the tree.++Both are fixed, and the gate now asks the question that catches the shape+rather than the one that catches the library.+:::+## Static analysis (CodeQL)GitHub CodeQL runs on every pull request and on a nightly schedule against `main`. As of the v8.0 wave-1 push the Python alert count on `main` is zero, and we treat that as a CI gate — a new alert breaks the security workflow and blocks the next release.diff --git a/apps/docs/sidebars.ts b/apps/docs/sidebars.tsindex 24bcc7643..17e4af554 100644--- a/apps/docs/sidebars.ts+++ b/apps/docs/sidebars.ts@@ -190,6 +190,7 @@ const sidebars: SidebarsConfig = {"operations/theming","operations/upgrades","operations/notifications",+ "operations/action-approvals","operations/case-reports","operations/troubleshooting","operations/faq",diff --git a/apps/web/src/components/copilot/InvestigationTimeline.tsx b/apps/web/src/components/copilot/InvestigationTimeline.tsxindex 0309f7302..bbce0c6d6 100644--- a/apps/web/src/components/copilot/InvestigationTimeline.tsx+++ b/apps/web/src/components/copilot/InvestigationTimeline.tsx@@ -15,6 +15,8 @@import { useCallback, useEffect, useRef, useState } from "react";+import { canUseDemoData } from "@/lib/demoFallback";+// ---------------------------------------------------------------------------// Types (mirror backend TimelineResponse / TimelineNode)// ---------------------------------------------------------------------------@@ -562,7 +564,20 @@ export default function InvestigationTimeline({useEffect(() => {if (!runId) {- setTimeline(makeDemoTimeline());+ // `makeDemoTimeline()` returns a fully invented investigation — a named+ // analyst, a routable source IP, "Session suspended; email dispatched".+ // It rendered unconditionally whenever `runId` was absent, so an+ // operator with no run selected read fabricated activity as their own+ // tenant's. Gated now; without demo mode the panel says it has nothing+ // rather than inventing something.+ //+ // `check_mock_data_gated.py` did not catch this: it matches `MOCK_*` /+ // `DEMO_*` constant *names*, and this is a function call.+ if (canUseDemoData()) {+ setTimeline(makeDemoTimeline());+ } else {+ setTimeline(null);+ }return;}setLoading(true);diff --git a/apps/web/src/lib/demoMode.ts b/apps/web/src/lib/demoMode.tsindex df87fb139..6dded1764 100644--- a/apps/web/src/lib/demoMode.ts+++ b/apps/web/src/lib/demoMode.ts@@ -1,5 +1,9 @@/**- * Demo-mode helpers for the hosted demo at tryaisoc.com.+ * Demo-mode helpers for a hosted demo deployment.+ *+ * Deliberately not naming a hostname: this module ships to every+ * self-hoster, and a specific deployment's domain in a shared component is+ * how one install's branding ends up inside another's product.** Reads `NEXT_PUBLIC_DEMO_MODE` (set by `infra/fly/web/fly.toml`) to flag-gate* write actions in the UI:diff --git a/docs/audit/CLAIM_TO_GATE_MATRIX.md b/docs/audit/CLAIM_TO_GATE_MATRIX.mdindex 290d1fdec..6afb0e317 100644--- a/docs/audit/CLAIM_TO_GATE_MATRIX.md+++ b/docs/audit/CLAIM_TO_GATE_MATRIX.md@@ -110,6 +110,12 @@ Statuses: `GATED` (a CI job fails when the claim stops being true) · `PARTIAL`| Benchmark figures declare the provenance of the corpus they came from | README (benchmark transparency) | `ci.yml` agents job - the runner refuses a corpus whose incidents do not declare provenance, the counts travel with the result so a consumer cannot drop them, `--limit` recounts over the slice rather than reporting the whole corpus, and the report prints provenance before any figure | GATED | the shipped corpus is 200 synthetic incidents; public-dataset and real-anonymised entries are supported by the schema but not yet contributed || Analyst disagreement becomes durable organisation memory | README (learning from analysts) | `ci.yml` api job (`test_analyst_feedback.py`) - the reason vocabulary is closed, corroboration counts distinct analysts rather than rows (one person clicking the same button ten times is one opinion), an approved-pentest statement expires within 14 days because one that outlives the pentest is an attacker's best friend, rule defects route to detection engineering rather than becoming a suppression that hides them, and a compiled statement names the process, principal, host and window rather than degrading to 'PowerShell is expected' | GATED | the triage prompt does not yet read `active_statements`; the memory is written and queryable but not yet consumed || Backup artifacts are encrypted at rest and integrity-checked | architecture.md (backup & restore) | `integration.yml` backup-restore job: asserts the uploaded object carries the AiSOC AEAD header, has no gzip magic, leaks no schema names, and is listed in a SHA-256 manifest; then flips a bit and asserts restore refuses it | GATED | - |+| A human approval of a response action is authorized, not just logged | operations/action-approvals.md | `ci.yml` actions job (`test_approval_identity.py`) — an approval with no resolvable identity is refused, an unmapped ChatOps user cannot approve, a user below the action's blast-radius tier cannot approve, and separation of duties applies to a ChatOps approval; plus `test_interactions.py` and `test_callbacks_approver.py` assert the verified platform identity reaches the client rather than only the audit row | GATED | pending approvals are still an in-process dict, so they are lost on restart and not shared across replicas; nothing pushes a card proactively |+| A signed email approval link resolves and carries an identity | operations/action-approvals.md | `ci.yml` api job (`test_email_approval_endpoint.py`) — the path the issuer mints is requested rather than inspected in the route table, the recipient is signed into the token, swapping it breaks the signature, a token without one is refused rather than forwarded, and an already-decided action answers 409 | GATED | - |+| Every LLM call passes a fail-closed input contract before the request | operations/security.md (LLM input contract) | `ci.yml` agents job (`test_llm_contract_no_bypass.py`) — one gate AST-walks `.ainvoke`/`.astream`, a second flags any file in either service that names a completions endpoint and issues its own POST, each with a synthetic-bypass self-test; `ci.yml` api job (`test_llm_safety.py`) asserts per endpoint that it routes through the wrapper **and** no longer POSTs to a provider itself; `sync_vendored_llm_contract.py --check` keeps both services on one classifier | GATED | the contract is a minimum-leak control, not an injection sanitizer — that is `PromptInjectionGuard`, which demotes rather than refuses |+| A rule id names the same detection in the engine and in the catalogue | detections/truth-table.md | `validate-detections.yml` (`generate_detections.py --check` plus `test_detection_id_stability.py`) — the committed pack must reproduce byte-for-byte, YAML and engine ids are each compared against the lock, an id must name the same rule in both, and reordering the spec list must not renumber the engine | GATED | - |+| Which identity providers can resolve permissions live is stated, not implied | effective-permissions endpoint docstring | `ci.yml` api job (`test_posture_snapshot_coverage.py`) — a resolver registered without a declared snapshot source fails, the live-capable set is pinned, and a stale allow-list entry fails once its connector starts answering the posture sentinel | GATED | four of five providers cannot collect a live snapshot: no connector implements `__posture_snapshot__`, so they answer 412 rather than fabricating one |+| Config snapshots reach the graph when the feature reports enabled | architecture/graph-schema.md (`:CONFIGURED_AS`) | `ci.yml` ingest job (`http_provider_test.go`) — the provider's request shape is pinned against the served route, vendor-supplied ids are escaped so an ARN cannot inject a query parameter, a 501 is distinguished from an error, and the bi-temporal edge properties the schema declares are asserted present | GATED | `is_current` is set on write and never cleared, because closing the previous interval needs a read-modify-write the ingest hot path does not do |## Summarydiff --git a/docs/demo/SCREENCAST_SHOTLIST.md b/docs/demo/SCREENCAST_SHOTLIST.mdindex cf4517667..001834dde 100644--- a/docs/demo/SCREENCAST_SHOTLIST.md+++ b/docs/demo/SCREENCAST_SHOTLIST.md@@ -18,7 +18,7 @@## Shot 1 · Alert hits (0:02 — 0:14)-* **Visual:** browser at `tryaisoc.com/dashboard/alerts`. A new alert+* **Visual:** browser at `localhost:3000/dashboard/alerts`. A new alertcard animates in from the top (the seed dataset includes a CrowdstrikeEDR detection for `wmic.exe` spawn from `winword.exe`).* **Voice (12 words):** "An EDR detection comes in. AiSOC opens an@@ -73,10 +73,11 @@## Outro (1:20 — 1:30)-* **Visual:** fade to the AiSOC wordmark on dark with the URL- `tryaisoc.com` and "MIT licensed · github.com/beenuar/AiSOC" under- it.-* **Voice (8 words):** "Try the live demo at tryaisoc.com."+* **Visual:** fade to the AiSOC wordmark on dark with+ "MIT licensed · github.com/beenuar/AiSOC" under it. No deployment+ hostname — a URL in the outro dates the cut and points viewers at one+ particular instance rather than at the project.+* **Voice (9 words):** "Run it yourself: one command, no account required."---diff --git a/docs/openapi.yaml b/docs/openapi.yamlindex 082749e48..5aa2f6820 100644--- a/docs/openapi.yaml+++ b/docs/openapi.yaml@@ -7383,6 +7383,42 @@ paths:application/json:schema:$ref: '#/components/schemas/HTTPValidationError'+ /api/v1/actions/email-decide:+ get:+ tags:+ - actions+ summary: Email Decide+ description: 'Verify a signed approval link and forward the decision.+++ Unauthenticated by necessity — the recipient is reading email, not holding++ a session — so the token *is* the credential and every check that would++ otherwise come from a session has to come from the signature.'+ operationId: email_decide_api_v1_actions_email_decide_get+ parameters:+ - name: token+ in: query+ required: true+ schema:+ type: string+ description: Signed approval token+ title: Token+ description: Signed approval token+ responses:+ '200':+ description: Successful Response+ content:+ text/html:+ schema:+ type: string+ '422':+ description: Validation Error+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/HTTPValidationError'/api/v1/costs/dashboard:get:tags:diff --git a/docs/operations/publishing.md b/docs/operations/publishing.mdindex 6f2a174c9..dfceceaa6 100644--- a/docs/operations/publishing.md+++ b/docs/operations/publishing.md@@ -84,6 +84,31 @@ Then set the repository **variable** (not secret)There is no API token to store or rotate in this path.+## One-time setup: GitHub Marketplace (the Action)++`beenuar/aisoc-action` **does not exist as a repository**, so+`uses: beenuar/aisoc-action@v1` 404s. Until a Marketplace listing exists, the+reference that resolves is the action's directory inside this monorepo:++```yaml+- uses: beenuar/AiSOC/packages/[email protected]+```++That form needs no setup and is what the README and+`apps/docs/docs/integrations/github-action.md` show. Publishing the short+alias is a repository-settings action, not an engineering one:++1. On the repo's **Releases** page, edit the release for the tag you want to+ list and tick **Publish this Action to the GitHub Marketplace**. GitHub+ validates `packages/aisoc-action/action.yml` at that point — it needs+ `name`, `description` and `branding`.+2. Accept the Marketplace developer agreement if prompted.+3. Marketplace listings are per-repository and resolve to the repository+ root, so the short `beenuar/aisoc-action@v1` alias additionally requires a+ dedicated repository with the action at its root. Mirroring+ `packages/aisoc-action/` there on each tag is the remaining work; the+ subdirectory form above stays valid either way.+## Cutting a releaseThe existing tag-driven flow is unchanged — see the release section ofdiff --git a/docs/roadmap/v8-progress.md b/docs/roadmap/v8-progress.mdindex e5c846736..d3429f9f4 100644--- a/docs/roadmap/v8-progress.md+++ b/docs/roadmap/v8-progress.md@@ -44,7 +44,7 @@ migration runners for all three non-Postgres stores), recursive investigationcontract, and a SOC-agent benchmark a third party can run against their ownagent.-Claim-to-gate matrix: **102 rows — 93 GATED / 9 PARTIAL / 0 NO GATE**. Recount+Claim-to-gate matrix: **108 rows — 99 GATED / 9 PARTIAL / 0 NO GATE**. Recountwith `python3 scripts/check_claim_gate_matrix.py`; do not quote a rememberedfigure.@@ -62,14 +62,21 @@ Each item is audited against the tree before any code is written, because thev8.0 lesson is that a capability is often already present and merely unwired.Status is filled in from that audit rather than from the original ticket.-| T-ID | Item | Status |-|------|------|--------|-| T1.2 | Versioned config-snapshot writers (AWS / GitHub / Lacework / Okta) — Neo4j `:CONFIGURED_AS {ts}` edges so posture drift is queryable across time | see audit |-| T2.3 | `LLMInputContract` fail-closed validation across every sub-agent | see audit |-| T3.2 | Effective-permissions resolvers for Azure / GCP / Okta / Google Workspace | see audit |-| T3.3 | Attack-chain ranking + timeline UI hardening | see audit |-| T3.5 | Business-context rule engine | see audit |-| T3.6 | ChatOps coverage — Slack Block Kit approvals, Teams Adaptive Cards, signed email approval URLs | see audit |+The audit found the backlog **wrong in both directions**: two items were+already built, and four had the capability present with the path that feeds it+broken. That is the same shape v8.0 found a dozen times — the mechanism exists,+is tested, and has no caller on the path that needs it — so auditing against+the tree before writing code is now the first step of a wave rather than an+optional one.++| T-ID | Item | What the audit found | Done |+|------|------|----------------------|------|+| T1.2 | Versioned config-snapshot writers, Neo4j `:CONFIGURED_AS {ts}` | The Neo4j writer is fully built. The Go provider called a route nobody serves, and could not have called the real one (it has no vault), so snapshots silently never ran while reporting themselves enabled. `is_current` / `valid_from` / `valid_to` were declared and never written, so the documented O(1) lookup matched zero edges. | yes |+| T2.3 | `LLMInputContract` across every sub-agent | Real and fail-closed in `services/agents`, covering 15 of 16 call sites. `services/api` had **no contract at all** across seven endpoints, and the module described as living there did not exist. The no-bypass gate could not see a raw-HTTP LLM call. | yes |+| T3.2 | Effective-permissions resolvers (Azure / GCP / Okta / GWS) | **Already shipped** — all five exist, are registered and report `coverage: "full"`. The gap is the snapshot, not the resolver: no connector answers `__posture_snapshot__`, so four of five return 412. Docstrings still called them scaffolds. | audited; gap gated |+| T3.3 | Attack-chain ranking + timeline UI | Grouping (fusion, Redis) and weighted ranking (API, Postgres) both exist as independent implementations that never exchange data. `AttackChainPanel` and `AttackStory.tsx` are honest about empty states; `InvestigationTimeline.tsx` rendered a fabricated investigation with no demo gate. | partial — fabrication gated, the two implementations remain separate |+| T3.5 | Business-context rule engine | **Already shipped**, and the v8.0 Postgres fix is real. But the two evaluators disagreed on `not`, so one console-accepted rule silently discarded that tenant's entire rule set at triage, suppressions included. | yes |+| T3.6 | ChatOps coverage | Every piece existed; three had no caller. Slack Block Kit approvals worked only as a reply to the analyst's own slash command, the Teams card factory had zero senders, and the signed email link pointed at a route that did not exist. Worse: approvals **authorized nobody**. | partial — authorization and the email route fixed; proactive card push and a durable approval store remain |### Release integrity@@ -79,8 +86,9 @@ Status is filled in from that audit rather than from the original ticket.| `RELEASES.md` brought up to v8.0.0 (it still announced v7.6.0) | done || `ROADMAP.md` — "v8.0 — Planned" section, stale matrix count | done || This tracker | done |-| Codespaces quickstart ([#716](https://github.com/beenuar/AiSOC/issues/716)) | open |-| Screencast + `hero.gif` assets | open |+| Codespaces quickstart ([#716](https://github.com/beenuar/AiSOC/issues/716)) | done |+| arm64 service images (Apple Silicon could not pull any of them) | done |+| Screencast + `hero.gif` assets | moved to v8.2 — recording needs a stack to point a browser at, and the hosted OSS demo is down pending a billing action |---diff --git a/scripts/check_mock_data_gated.py b/scripts/check_mock_data_gated.pyindex 5e33825ab..91dd46e54 100644--- a/scripts/check_mock_data_gated.py+++ b/scripts/check_mock_data_gated.py@@ -46,6 +46,14 @@ FALLBACK_WITH_MOCK = re.compile(rf"fallbackData:.*{MOCK_NAME}")#: An assignment of a mock inside a file, e.g. `setRules(MOCK_RULES)`.MOCK_ASSIGN = re.compile(rf"\bset[A-Z]\w*\(\s*{MOCK_NAME}")+#: A *factory* that builds sample data, e.g. `setTimeline(makeDemoTimeline())`.+#: The two patterns above match a constant by name, which is one of the two+#: ways to render fabricated state — `InvestigationTimeline.tsx` used the other+#: and passed this gate while rendering a fully invented investigation+#: (a named analyst, a routable source IP, "Session suspended; email+#: dispatched") whenever no run was selected.+MOCK_FACTORY_ASSIGN = re.compile(r"\bset[A-Z]\w*\(\s*(?:make|build|get|create)(?:Mock|Demo|Sample|Fake|Fallback)\w*\(")+#: Files exempt by nature: the gate helper itself, tests, and stories.EXEMPT_SUFFIXES = (".test.ts", ".test.tsx", ".stories.tsx", "demoFallback.ts")@@ -98,6 +106,12 @@ def scan(root: pathlib.Path) -> list[str]:f"check in this file. Show an error or empty state instead.")+ if MOCK_FACTORY_ASSIGN.search(line) and not file_has_guard:+ problems.append(+ f"{rel}:{number}: a sample-data factory is assigned to state with no "+ f"canUseDemoData() check in this file. Show an error or empty state instead."+ )+return problemsdiff --git a/scripts/readme_gates.py b/scripts/readme_gates.pyindex 355164f73..c6dfe02e1 100644--- a/scripts/readme_gates.py+++ b/scripts/readme_gates.py@@ -53,31 +53,45 @@ KNOWN_UNPUBLISHED = {README_MAX_LINES = 250# Phrases that count as a "this is intentionally not yet published" guard.-# v8.0 shipped as the close-the-loop release, so the packaging milestone moved-# to v8.1 and the guard phrases moved with it. The v8.0 spellings are kept so-# older docs and blog posts that still carry them are not flagged, but new-# README text should use the v8.1 wording — a README shipped *as* v8.0 cannot-# coherently promise that something "lands in v8.0".+# The packaging milestone has moved twice, for the same reason each time: the+# blocker is registry credentials, not code, so it cannot be scheduled by+# writing a version number. v8.0 became "close the loop" and packaging moved+# to v8.1; v8.1 became wave-2 features and it moved to v8.2. Older spellings+# are kept so existing docs and blog posts are not flagged, but new README+# text must use the current one — a README shipped *as* vX cannot coherently+# promise that something lands in vX.+#+# Do not add the next version here speculatively. The phrase should move when+# the milestone does, so the list is a record of what was actually promised.V8_GUARDS = ("coming in v8.0","coming in v8.1",+ "coming in v8.2","coming to npm in v8.0","coming to npm in v8.1",+ "coming to npm in v8.2","lands in v8.0","lands in v8.1",+ "lands in v8.2","lands with v8.0","lands with v8.1",+ "lands with v8.2","lands with the v8.0","lands with the v8.1",+ "lands with the v8.2","packaging release","publish lands in v8.0","publish lands in v8.1",+ "publish lands in v8.2","ships in v8.0","ships in v8.1",+ "ships in v8.2","ships with v8.0","ships with v8.1",+ "ships with v8.2","ships with the v8.0","ships with the v8.1",+ "ships with the v8.2","v8.0 launch","with the next phase 2 visuals rollup",# Treat explicit monorepo-source-install references as their own guard:diff --git a/scripts/sync_vendored_llm_contract.py b/scripts/sync_vendored_llm_contract.pynew file mode 100755index 000000000..cfb2b8341--- /dev/null+++ b/scripts/sync_vendored_llm_contract.py@@ -0,0 +1,80 @@+#!/usr/bin/env python3+"""Keep ``services/api/app/_vendor/llm_contract_rules.py`` in lockstep with its source.++The reversible pseudonymizer lives canonically under+``services/agents/app/privacy/llm_contract_rules.py``. The public-replay publish flow in+the API service (``services/api/app/services/replay_redaction.py``) reuses it to+strip customer PII before a ledger snapshot is served at ``/r/<slug>``. Because+the ``aisoc-api`` Docker image is built with ``services/api`` as its build+context, anything under ``services/agents`` is unavailable at runtime, so we+ship a vendored mirror inside the API package.++Run modes+---------+* ``python scripts/sync_vendored_llm_contract.py`` — copy source → vendored.+* ``python scripts/sync_vendored_llm_contract.py --check`` — fail (exit 1) if the+ vendored file is missing or differs from the source. CI uses this mode.++The script is intentionally tiny and dependency-free so it can run in any CI+runner.++AiSOC — open-source AI Security Operations Center (MIT License).+"""++from __future__ import annotations++import argparse+import filecmp+import shutil+import sys+from pathlib import Path++REPO_ROOT = Path(__file__).resolve().parents[1]+SOURCE_FILE = REPO_ROOT / "services" / "agents" / "app" / "llm" / "contract_rules.py"+VENDORED_FILE = REPO_ROOT / "services" / "api" / "app" / "_vendor" / "llm_contract_rules.py"+++def _check() -> int:+ if not SOURCE_FILE.is_file():+ print(f"FAIL: source file missing: {SOURCE_FILE}", file=sys.stderr)+ return 1+ if not VENDORED_FILE.is_file():+ print(f"FAIL: vendored file missing: {VENDORED_FILE}", file=sys.stderr)+ return 1+ if not filecmp.cmp(SOURCE_FILE, VENDORED_FILE, shallow=False):+ print(+ "FAIL: vendored llm_contract_rules.py is out of sync with source.\n"+ f" Source: {SOURCE_FILE.relative_to(REPO_ROOT)}\n"+ f" Vendored: {VENDORED_FILE.relative_to(REPO_ROOT)}\n\n"+ "Re-run: python scripts/sync_vendored_llm_contract.py",+ file=sys.stderr,+ )+ return 1+ print("OK: vendored llm_contract_rules.py matches source.")+ return 0+++def _sync() -> int:+ if not SOURCE_FILE.is_file():+ print(f"FAIL: source file missing: {SOURCE_FILE}", file=sys.stderr)+ return 1+ VENDORED_FILE.parent.mkdir(parents=True, exist_ok=True)+ shutil.copy2(SOURCE_FILE, VENDORED_FILE)+ print(f"copied {SOURCE_FILE.relative_to(REPO_ROOT)} → {VENDORED_FILE.relative_to(REPO_ROOT)}")+ print("\nDone. Don't forget to commit services/api/app/_vendor/llm_contract_rules.py.")+ return 0+++def main() -> int:+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument(+ "--check",+ action="store_true",+ help="Fail with a non-zero exit code if the vendored file is out of sync.",+ )+ args = parser.parse_args()+ return _check() if args.check else _sync()+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/services/actions/app/api/router.py b/services/actions/app/api/router.pyindex c456decdb..abe1dd1a2 100644--- a/services/actions/app/api/router.py+++ b/services/actions/app/api/router.py@@ -13,13 +13,20 @@ from fastapi import APIRouter, Depends, HTTPException, Queryfrom fastapi.responses import HTMLResponsefrom app.core.config import get_settings-from app.models.action import ActionPrincipal, ActionRequest, ActionStatus, ActionType+from app.models.action import (+ ActionPrincipal,+ ActionRequest,+ ActionStatus,+ ActionType,+ ChatOpsApprover,+)from app.security.authz import (ActionAuthzError,authorize_action,authorize_approver,require_service_auth,)+from app.security.chatops_identity import resolve_approverfrom app.security.chatops_token import ChatOpsTokenError, verify_tokenfrom app.services.blast_radius import BlastRadiusGatefrom app.services.executor_registry import EXECUTOR_REGISTRY@@ -99,34 +106,80 @@ async def submit_action(request: ActionRequest, _auth: None = Depends(require_sereturn record+def _bind_approver(+ record: dict[str, Any],+ action_id: str,+ approver: ActionPrincipal | None,+ assertion: ChatOpsApprover | None,+ *,+ require: bool,+) -> ActionPrincipal | None:+ """Resolve and authorize the identity behind an approve/reject call.++ Returns the bound principal, or ``None`` when no identity was supplied and+ ``require`` is false. Raises ``HTTPException`` on denial.++ A ChatOps assertion carries identity only — never permissions — because a+ bot that asserted its own permissions could grant itself anything. The+ mapping from a verified platform user to a principal is operator+ configuration; an unmapped user is refused rather than admitted with an+ empty permission set.++ ``require`` is true for approve and false for reject. The asymmetry is+ deliberate: an approval with no identity cannot be evaluated against+ separation of duties, while a rejection causes no vendor effect and has no+ human at all when it comes from the approval-timeout scheduler — requiring+ one would leave expired requests stuck in ``awaiting_approval`` forever.+ """+ if approver is None and assertion is not None:+ approver = resolve_approver(assertion.platform, assertion.platform_user_id)+ if approver is None:+ logger.warning(+ "approval_denied_unmapped_identity",+ action_id=action_id,+ platform=assertion.platform,+ )+ detail = f"{assertion.platform} user is not mapped to an AiSOC approver. Add them to AISOC_CHATOPS_APPROVERS."+ raise HTTPException(status_code=403, detail=detail)++ if approver is None:+ settings = get_settings()+ if require and (settings.AISOC_ACTIONS_REQUIRE_APPROVER or settings.AISOC_ACTIONS_REQUIRE_PRINCIPAL):+ raise HTTPException(status_code=403, detail="an approver identity is required")+ return None++ try:+ authorize_approver(record, approver)+ except ActionAuthzError as exc:+ logger.warning("Approval denied", action_id=action_id, reason=str(exc))+ raise HTTPException(status_code=403, detail=str(exc)) from exc+ return approver++@router.post("/actions/{action_id}/approve")async def approve_action(action_id: str,approver: ActionPrincipal | None = None,+ chatops_approver: ChatOpsApprover | None = None,_auth: None = Depends(require_service_auth),):"""Approve a pending action (human-in-the-loop gate).- W4.4 — when an approver identity is supplied it is bound: the approver must- hold the action's required permission and must not be the requester. When- principals are required (``AISOC_ACTIONS_REQUIRE_PRINCIPAL``) an approver is- mandatory."""+ W4.4 — the approver is bound to the decision: they must hold the action's+ required permission and must not be the requester. T3.6 — an approval with+ no resolvable identity is refused by default+ (``AISOC_ACTIONS_REQUIRE_APPROVER``), because separation of duties cannot+ be evaluated against nobody. ChatOps callers send ``chatops_approver``+ (verified platform identity) and the mapping supplies the permissions."""record = _actions.get(action_id)if not record:raise HTTPException(status_code=404, detail="Action not found")if record["status"] != ActionStatus.AWAITING_APPROVAL:raise HTTPException(status_code=400, detail=f"Action is not awaiting approval (current: {record['status']})")- if approver is None:- if get_settings().AISOC_ACTIONS_REQUIRE_PRINCIPAL:- raise HTTPException(status_code=403, detail="an approver identity is required")- else:- try:- authorize_approver(record, approver)- except ActionAuthzError as exc:- logger.warning("Approval denied", action_id=action_id, reason=str(exc))- raise HTTPException(status_code=403, detail=str(exc)) from exc- record["approved_by_user_id"] = approver.user_id+ bound = _bind_approver(record, action_id, approver, chatops_approver, require=True)+ if bound is not None:+ record["approved_by_user_id"] = bound.user_id# Reconstruct request and executerequest = ActionRequest(@@ -152,13 +205,33 @@ async def approve_action(@router.post("/actions/{action_id}/reject")-async def reject_action(action_id: str, _auth: None = Depends(require_service_auth)):- """Reject a pending action."""+async def reject_action(+ action_id: str,+ approver: ActionPrincipal | None = None,+ chatops_approver: ChatOpsApprover | None = None,+ _auth: None = Depends(require_service_auth),+):+ """Reject a pending action.++ Binds the deciding identity on the same terms as approve. A rejection used+ to take no identity and record none, so "who declined to contain this+ host, and were they entitled to" had no answer — which matters as much as+ the approve side during an incident review.+ """record = _actions.get(action_id)if not record:raise HTTPException(status_code=404, detail="Action not found")++ bound = _bind_approver(record, action_id, approver, chatops_approver, require=False)+ if bound is not None:+ record["rejected_by_user_id"] = bound.user_id+record["status"] = ActionStatus.REJECTED- logger.info("Action rejected", action_id=action_id)+ logger.info(+ "Action rejected",+ action_id=action_id,+ rejected_by=bound.user_id if bound else None,+ )return recorddiff --git a/services/actions/app/core/config.py b/services/actions/app/core/config.pyindex 8f94cf477..bb0536218 100644--- a/services/actions/app/core/config.py+++ b/services/actions/app/core/config.py@@ -94,6 +94,24 @@ class ActionsSettings(BaseSettings):default=False,description="Require a structured ActionPrincipal on every action request.",)+ # T3.6 — the *approval* path, which is separate from the request path+ # above and defaults the other way. An approval with no identity cannot+ # satisfy separation of duties at all, so a principal-less approval is not+ # a legacy convenience, it is the control being absent. Slack and Teams+ # approvals ran in exactly that state: the bot verified who clicked, then+ # called approve with no approver.+ AISOC_ACTIONS_REQUIRE_APPROVER: bool = Field(+ default=True,+ description="Refuse approve/reject calls that carry no resolvable approver identity.",+ )+ # Maps a verified ChatOps identity onto an authorization principal. JSON+ # inline or `file:/path/to.json`. Unset means nobody can approve over+ # ChatOps, which is the correct default for a control that was absent.+ # See app/security/chatops_identity.py for the shape.+ AISOC_CHATOPS_APPROVERS: str = Field(+ default="",+ description="JSON (or file: path) mapping platform user ids to approver principals.",+ )@lru_cache(maxsize=1)diff --git a/services/actions/app/models/action.py b/services/actions/app/models/action.pyindex 21e30060a..9c9a59c95 100644--- a/services/actions/app/models/action.py+++ b/services/actions/app/models/action.py@@ -148,6 +148,21 @@ class ActionPrincipal(BaseModel):permissions: list[str] = Field(default_factory=list)+class ChatOpsApprover(BaseModel):+ """A platform identity a bot has already verified (T3.6).++ Carries identity and deliberately **not** permissions. The bot proves who+ clicked — Slack signs the interaction payload, Teams payloads are+ HMAC-signed — but it has no knowledge of what that person may do in AiSOC,+ and a bot permitted to assert its own permissions could grant itself+ anything. The actions service maps this onto a principal.+ """++ platform: str+ platform_user_id: str+ display_name: str | None = None++class ActionRequest(BaseModel):"""Request to execute an action."""diff --git a/services/actions/app/security/chatops_identity.py b/services/actions/app/security/chatops_identity.pynew file mode 100644index 000000000..61b336557--- /dev/null+++ b/services/actions/app/security/chatops_identity.py@@ -0,0 +1,152 @@+"""Resolve a verified ChatOps identity into an authorization principal (T3.6).++The Slack and Teams bots verify who clicked — Slack signs every interaction+payload, Teams payloads carry an HMAC — and then recorded that identity in an+audit event and *nothing else*. ``approve_action(action_id)`` sent no approver,+so the actions service ran :func:`authorize_approver` on nobody: the+permission-tier check and separation of duties were both skipped, and the only+trace of the human was a log line. An approval path that does not authorize is+worse than no approval path, because it reads as a control.++The bot cannot supply permissions itself. It knows a Slack user id; it has no+idea what that person may do in AiSOC, and a bot that asserted its own+permissions would be a bot that could grant itself anything. So the bot asserts+only *identity* and this module maps that identity onto a principal using+configuration the operator controls.++Mapping is deliberately operator-configured rather than read from a user+directory. The actions service owns no user table — the API does — and a+network lookup on the approval path would mean an approval whose authorization+depends on another service being reachable. A missing mapping therefore+resolves to ``None``, and the caller refuses the approval.++Configuration+=============++``AISOC_CHATOPS_APPROVERS`` holds JSON, either inline or as a ``file:`` path::++ {+ "slack": {+ "U123ABC": {+ "user_id": "[email protected]",+ "permissions": ["actions:execute:high"],+ "tenant_id": "0b4e...",+ "roles": ["soc-lead"]+ }+ },+ "teams": {"29:1xyz": {"user_id": "[email protected]",+ "permissions": ["actions:execute:low"]}}+ }++Platform keys are lower-cased. Platform user ids are matched exactly, because+Slack ids are case-sensitive opaque handles. Unset config means nobody can+approve over ChatOps — which is the correct default for a control that was+previously absent.+"""++from __future__ import annotations++import json+from functools import lru_cache+from pathlib import Path+from typing import Any++import structlog++from app.core.config import get_settings+from app.models.action import ActionPrincipal++logger = structlog.get_logger()++#: Platforms a bot may assert. An unknown platform is refused rather than+#: trusted, so a new integration cannot quietly inherit approval rights.+SUPPORTED_PLATFORMS = frozenset({"slack", "teams", "email"})+++class ChatOpsIdentityError(ValueError):+ """Raised when the approver map is present but unusable.++ Distinguished from "no mapping for this user" on purpose: a malformed map+ is an operator error that should be loud, while an unmapped user is a+ routine denial.+ """+++def _coerce_principal(platform: str, platform_user_id: str, raw: Any) -> ActionPrincipal:+ if not isinstance(raw, dict):+ raise ChatOpsIdentityError(f"approver entry for {platform}/{platform_user_id} is not an object")+ user_id = raw.get("user_id") or raw.get("email")+ if not user_id:+ raise ChatOpsIdentityError(f"approver entry for {platform}/{platform_user_id} has no user_id")+ return ActionPrincipal(+ user_id=str(user_id),+ tenant_id=raw.get("tenant_id"),+ email=raw.get("email") or (str(user_id) if "@" in str(user_id) else None),+ roles=[str(r) for r in (raw.get("roles") or [])],+ permissions=[str(p) for p in (raw.get("permissions") or [])],+ )+++def _load_raw_map(spec: str) -> dict[str, Any]:+ spec = spec.strip()+ if not spec:+ return {}+ if spec.startswith("file:"):+ path = Path(spec[len("file:") :]).expanduser()+ try:+ spec = path.read_text(encoding="utf-8")+ except OSError as exc:+ raise ChatOpsIdentityError(f"cannot read approver map at {path}: {exc}") from exc+ try:+ parsed = json.loads(spec)+ except ValueError as exc:+ raise ChatOpsIdentityError(f"approver map is not valid JSON: {exc}") from exc+ if not isinstance(parsed, dict):+ raise ChatOpsIdentityError("approver map must be a JSON object keyed by platform")+ return parsed+++@lru_cache(maxsize=1)+def _approver_map() -> dict[str, dict[str, Any]]:+ raw = _load_raw_map(get_settings().AISOC_CHATOPS_APPROVERS)+ normalised: dict[str, dict[str, Any]] = {}+ for platform, entries in raw.items():+ key = str(platform).strip().lower()+ if key not in SUPPORTED_PLATFORMS:+ raise ChatOpsIdentityError(f"unsupported approver platform '{platform}' (expected one of {sorted(SUPPORTED_PLATFORMS)})")+ if not isinstance(entries, dict):+ raise ChatOpsIdentityError(f"approver entries for '{platform}' must be an object")+ normalised[key] = entries+ return normalised+++def reset_cache() -> None:+ """Drop the memoised map. Tests and config reloads use this."""+ _approver_map.cache_clear()+++def resolve_approver(platform: str, platform_user_id: str) -> ActionPrincipal | None:+ """Map a verified ChatOps identity to a principal, or ``None``.++ ``None`` means "this identity is not authorised to approve", not "allow by+ default" — the caller must refuse. Returning a permission-less principal+ instead would be worse than returning nothing, because it would pass an+ identity check and then silently fail an authorization check for a reason+ the operator cannot distinguish from a misconfigured tier.+ """+ key = (platform or "").strip().lower()+ if key not in SUPPORTED_PLATFORMS:+ logger.warning("chatops_approver_unsupported_platform", platform=platform)+ return None+ if not platform_user_id:+ return None++ entry = _approver_map().get(key, {}).get(platform_user_id)+ if entry is None:+ logger.warning(+ "chatops_approver_not_mapped",+ platform=key,+ platform_user_id=platform_user_id[:64],+ )+ return None+ return _coerce_principal(key, platform_user_id, entry)diff --git a/services/actions/tests/test_approval_identity.py b/services/actions/tests/test_approval_identity.pynew file mode 100644index 000000000..81fd1131b--- /dev/null+++ b/services/actions/tests/test_approval_identity.py@@ -0,0 +1,233 @@+"""An approval must authorize somebody (T3.6).++Before this, the Slack and Teams bots verified who clicked, recorded them in+an audit event, and called ``approve_action(action_id)`` with no body. The+actions service ran :func:`authorize_approver` on ``None``, so the+permission-tier check and separation of duties were both skipped — the human+existed only in a log line. An approval path that does not authorize is worse+than no approval path, because it reads as a control.++Every test here fails against that behaviour.+"""++from __future__ import annotations++import json+from uuid import uuid4++import pytest+from app.api import router as router_module+from app.core.config import get_settings+from app.models.action import ActionPrincipal, ActionStatus, ActionType, ChatOpsApprover+from app.security import chatops_identity+from fastapi import HTTPException++APPROVER_MAP = {+ "slack": {+ "U_LEAD": {+ "user_id": "[email protected]",+ "permissions": ["actions:execute:high"],+ "roles": ["soc-lead"],+ },+ "U_JUNIOR": {+ "user_id": "[email protected]",+ "permissions": ["actions:execute:low"],+ },+ "U_REQUESTER": {+ "user_id": "[email protected]",+ "permissions": ["actions:execute:high"],+ },+ },+ "teams": {"29:abc": {"user_id": "[email protected]", "permissions": ["actions:execute:high"]}},+ "email": {"[email protected]": {"user_id": "[email protected]", "permissions": ["actions:execute:high"]}},+}++[email protected](autouse=True)+def _approver_map(monkeypatch: pytest.MonkeyPatch):+ monkeypatch.setenv("AISOC_CHATOPS_APPROVERS", json.dumps(APPROVER_MAP))+ get_settings.cache_clear()+ chatops_identity.reset_cache()+ yield+ get_settings.cache_clear()+ chatops_identity.reset_cache()+++def _pending(action_type: ActionType = ActionType.ISOLATE_HOST, *, requested_by: str | None = None) -> dict:+ return {+ "id": str(uuid4()),+ "incident_id": str(uuid4()),+ "tenant_id": str(uuid4()),+ "action_type": action_type.value,+ "target": "host-1",+ "rationale": "test",+ "status": ActionStatus.AWAITING_APPROVAL,+ "requested_by_user_id": requested_by,+ }+++# ── the identity resolver ──────────────────────────────────────────────────+++def test_a_mapped_slack_user_resolves_with_real_permissions() -> None:+ principal = chatops_identity.resolve_approver("slack", "U_LEAD")+ assert principal is not None+ assert principal.user_id == "[email protected]"+ assert principal.permissions == ["actions:execute:high"]+++def test_an_unmapped_user_resolves_to_nothing_rather_than_an_empty_principal() -> None:+ """Returning a permission-less principal would pass the identity check and+ then fail the tier check for a reason an operator cannot tell apart from a+ misconfigured tier."""+ assert chatops_identity.resolve_approver("slack", "U_NOBODY") is None+++def test_an_unknown_platform_is_refused_not_trusted() -> None:+ assert chatops_identity.resolve_approver("carrier-pigeon", "U_LEAD") is None+++def test_platform_matching_is_case_insensitive_but_user_ids_are_not() -> None:+ """Slack ids are case-sensitive opaque handles; the platform key is not."""+ assert chatops_identity.resolve_approver("SLACK", "U_LEAD") is not None+ assert chatops_identity.resolve_approver("slack", "u_lead") is None+++def test_a_malformed_map_is_loud_rather_than_silently_empty(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("AISOC_CHATOPS_APPROVERS", "{not json")+ get_settings.cache_clear()+ chatops_identity.reset_cache()+ with pytest.raises(chatops_identity.ChatOpsIdentityError, match="not valid JSON"):+ chatops_identity.resolve_approver("slack", "U_LEAD")+++def test_an_unset_map_means_nobody_can_approve(monkeypatch: pytest.MonkeyPatch) -> None:+ """The correct default for a control that was previously absent."""+ monkeypatch.setenv("AISOC_CHATOPS_APPROVERS", "")+ get_settings.cache_clear()+ chatops_identity.reset_cache()+ assert chatops_identity.resolve_approver("slack", "U_LEAD") is None+++# ── binding on the approve path ────────────────────────────────────────────+++def test_an_approval_with_no_identity_is_refused() -> None:+ """The regression. This used to return the record and execute."""+ record = _pending()+ with pytest.raises(HTTPException) as exc:+ router_module._bind_approver(record, record["id"], None, None, require=True)+ assert exc.value.status_code == 403+ assert "approver identity is required" in exc.value.detail+++def test_an_unmapped_chatops_user_cannot_approve() -> None:+ record = _pending()+ assertion = ChatOpsApprover(platform="slack", platform_user_id="U_NOBODY")+ with pytest.raises(HTTPException) as exc:+ router_module._bind_approver(record, record["id"], None, assertion, require=True)+ assert exc.value.status_code == 403+ assert "not mapped" in exc.value.detail+++def test_a_mapped_chatops_user_with_the_tier_can_approve() -> None:+ record = _pending()+ assertion = ChatOpsApprover(platform="slack", platform_user_id="U_LEAD")+ bound = router_module._bind_approver(record, record["id"], None, assertion, require=True)+ assert bound is not None and bound.user_id == "[email protected]"+++def test_a_mapped_user_below_the_required_tier_cannot_approve() -> None:+ """isolate_host is a high-blast action; actions:execute:low must not reach it."""+ record = _pending(ActionType.ISOLATE_HOST)+ assertion = ChatOpsApprover(platform="slack", platform_user_id="U_JUNIOR")+ with pytest.raises(HTTPException) as exc:+ router_module._bind_approver(record, record["id"], None, assertion, require=True)+ assert exc.value.status_code == 403+ assert "lacks" in exc.value.detail+++def test_separation_of_duties_applies_to_a_chatops_approval() -> None:+ """The requester cannot approve their own action, even over Slack.++ This was entirely unreachable before: with no approver bound there was no+ identity to compare against the requester.+ """+ record = _pending(requested_by="[email protected]")+ assertion = ChatOpsApprover(platform="slack", platform_user_id="U_REQUESTER")+ with pytest.raises(HTTPException) as exc:+ router_module._bind_approver(record, record["id"], None, assertion, require=True)+ assert exc.value.status_code == 403+ assert "separation of duties" in exc.value.detail+++def test_a_direct_principal_still_works_and_takes_precedence() -> None:+ """The console path supplies a full principal from its authenticated user."""+ record = _pending()+ principal = ActionPrincipal(user_id="[email protected]", permissions=["actions:*"])+ assertion = ChatOpsApprover(platform="slack", platform_user_id="U_NOBODY")+ bound = router_module._bind_approver(record, record["id"], principal, assertion, require=True)+ assert bound is not None and bound.user_id == "[email protected]"+++def test_a_teams_identity_resolves_against_the_teams_half_of_the_map() -> None:+ """A Teams user id must not resolve because a Slack id happens to match.++ The Teams bot imports the Slack bot's client when it is on the image, so+ the platform has to travel with the identity rather than being a constant+ in the client.+ """+ record = _pending()+ bound = router_module._bind_approver(+ record,+ record["id"],+ None,+ ChatOpsApprover(platform="teams", platform_user_id="29:abc"),+ require=True,+ )+ assert bound is not None and bound.user_id == "[email protected]"++ with pytest.raises(HTTPException):+ router_module._bind_approver(+ record,+ record["id"],+ None,+ ChatOpsApprover(platform="teams", platform_user_id="U_LEAD"),+ require=True,+ )+++# ── the reject path is deliberately asymmetric ─────────────────────────────+++def test_a_rejection_without_identity_is_allowed_but_records_none() -> None:+ """A timeout-driven rejection has no human by definition.++ Requiring one would leave an expired request stuck in awaiting_approval+ forever, and a rejection causes no vendor effect.+ """+ record = _pending()+ assert router_module._bind_approver(record, record["id"], None, None, require=False) is None+++def test_a_rejection_with_identity_still_authorizes_it() -> None:+ """Identity is optional on reject, but not unchecked when present —+ otherwise "who declined to contain this host" has an unverified answer."""+ record = _pending(requested_by="[email protected]")+ with pytest.raises(HTTPException) as exc:+ router_module._bind_approver(+ record,+ record["id"],+ None,+ ChatOpsApprover(platform="slack", platform_user_id="U_REQUESTER"),+ require=False,+ )+ assert exc.value.status_code == 403+++def test_the_requirement_can_be_disabled_for_a_legacy_deployment(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("AISOC_ACTIONS_REQUIRE_APPROVER", "false")+ monkeypatch.setenv("AISOC_ACTIONS_REQUIRE_PRINCIPAL", "false")+ get_settings.cache_clear()+ record = _pending()+ assert router_module._bind_approver(record, record["id"], None, None, require=True) is Nonediff --git a/services/agents/app/api/explain.py b/services/agents/app/api/explain.pyindex 575a65f34..0e9458196 100644--- a/services/agents/app/api/explain.py+++ b/services/agents/app/api/explain.py@@ -117,6 +117,7 @@ from fastapi.responses import StreamingResponsefrom pydantic import BaseModel, Fieldfrom app.core.rate_limit import RateLimitDecision, TokenBucketLimiter+from app.llm.contract import LLMContractViolation, safe_chat_completions_requestfrom app.security.llm_resolver import LlmConfig, resolve_llm_configlogger = structlog.get_logger()@@ -574,8 +575,6 @@ async def _llm_summary(return fallbacktry:- import httpx-base = llm_config.base_url.rstrip("/")url = f"{base}/v1/chat/completions"model = llm_config.model@@ -613,15 +612,24 @@ async def _llm_summary(},]- async with httpx.AsyncClient(timeout=20) as client:- resp = await client.post(- url,- headers={"Authorization": f"Bearer {llm_config.api_key}"},- json={"model": model, "messages": messages, "max_tokens": 320},- )- resp.raise_for_status()- return resp.json()["choices"][0]["message"]["content"].strip()+ # T2.3 — this was the one LLM call in services/agents that bypassed+ # the contract. It POSTed with raw httpx, and the no-bypass gate only+ # walked the AST for `.ainvoke` / `.astream`, so a raw-HTTP call was+ # invisible to it. `safe_chat_completions_request` exists for exactly+ # this shape and is already used by copilot.py and the NL translator.+ body = await safe_chat_completions_request(+ api_key=llm_config.api_key,+ model=model,+ messages=messages,+ url=url,+ timeout=20.0,+ max_tokens=320,+ )+ return str(body["choices"][0]["message"]["content"]).strip()+ except LLMContractViolation as exc:+ logger.warning("explain.llm_contract_violation", reason=exc.reason)+ return fallbackexcept Exception as exc:logger.warning("explain.llm_error", error=str(exc))return fallbackdiff --git a/services/agents/app/llm/contract.py b/services/agents/app/llm/contract.pyindex 8ab0a94c2..3bda14471 100644--- a/services/agents/app/llm/contract.py+++ b/services/agents/app/llm/contract.py@@ -27,9 +27,7 @@ in production this stays on by default.from __future__ import annotations-import jsonimport os-import reimport timefrom collections.abc import Iterablefrom typing import Any@@ -67,261 +65,22 @@ def _cache_parts(messages: list[Any]) -> tuple[str, str]:return "\n".join(prompt_parts), "\n".join(input_parts)-AGENTS_LLM_CONTRACT_ENFORCED_ENV = "AISOC_AGENTS_LLM_CONTRACT_ENFORCED"--_OCSF_KEYS = frozenset(- {- "class_uid",- "category_uid",- "activity_id",- "type_uid",- "metadata",- "time_dt",- "observables",- "raw_data",- }-)-_LOG_KEYS = frozenset(- {- "Event",- "EventData",- "Sysmon",- "RecordID",- "EventRecordID",- "Channel",- "Provider",- "_raw",- "_time",- "punct",- }-)--# Union of dict keys that must never appear in LLM-bound JSON strings-# (prompt serialization uses this to redact / shallow-summarize nested data).-CONTRACT_DICT_KEY_BLOCKLIST: frozenset[str] = frozenset(_OCSF_KEYS | _LOG_KEYS)--# Compact regex for the most common raw-log signatures we want to catch-# even when the payload is rendered as a string instead of a dict.-_LOG_SHAPE_PATTERNS = (- re.compile(r'"class_uid"\s*:\s*\d+'),- re.compile(r'"activity_id"\s*:\s*\d+'),- re.compile(r'"EventID"\s*:\s*\d+'),- re.compile(r'"EventRecordID"\s*:\s*\d+'),- re.compile(r'<Event xmlns="http://schemas\.microsoft\.com/win/'),- # Splunk / Sentinel "search head" envelope- re.compile(r'"_raw"\s*:\s*"'),- re.compile(r'"sourcetype"\s*:\s*"'),+# The contract's rules live in ``contract_rules.py``, which imports nothing+# beyond the stdlib so ``services/api`` can vendor the identical file. Keeping+# them here meant the API had no contract at all, because this module imports+# LangChain and the response cache. Re-exported so existing callers and tests+# are unaffected by the split.+from app.llm.contract_rules import ( # noqa: E402,F401 — re-exported+ AGENTS_LLM_CONTRACT_ENFORCED_ENV,+ CONTRACT_DICT_KEY_BLOCKLIST,+ LLMContractViolation,+ LLMInputContract,+ classify_message,+ is_contract_enforced,+ set_contract_enforcement,+ validate_messages,)-# Loose secret patterns — caught only as a last-resort guard. The vault-# layer (T*.4) is the primary defence; this is belt-and-braces.-_SECRET_PATTERNS = (- re.compile(r"(?i)(api[_-]?key|secret|password|token)\s*[:=]\s*['\"][A-Za-z0-9_\-]{16,}['\"]"),- re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----"),-)--_MAX_MESSAGE_CHARS = int(os.getenv("AISOC_AGENTS_LLM_CONTRACT_MAX_CHARS", "60000"))-_MAX_JSON_LINE_KEYS = 6 # tuple-of-keys threshold for "looks like a log line"---class LLMContractViolation(RuntimeError):- """Raised when a prompt about to be sent to an LLM violates the contract."""-- def __init__(self, reason: str, *, role: str | None = None, evidence: str | None = None) -> None:- msg = f"[LLMInputContract] {reason}"- if role:- msg += f" (role={role})"- if evidence:- msg += f" — evidence: {evidence[:200]!r}"- super().__init__(msg)- self.reason = reason- self.role = role- self.evidence = evidence---# ----------------------------------------------------------------------------# Enforcement toggle-# -----------------------------------------------------------------------------# Module-level cache so callers can flip enforcement at runtime via-# :func:`set_contract_enforcement`. The env var is the source of truth on-# fresh process start.---def _env_default_enforced() -> bool:- raw = os.getenv(AGENTS_LLM_CONTRACT_ENFORCED_ENV, "1").strip()- return raw not in {"0", "false", "False", "no", "off"}---_ENFORCED: bool = _env_default_enforced()---def is_contract_enforced() -> bool:- return _ENFORCED---def set_contract_enforcement(value: bool) -> bool:- """Override enforcement at runtime. Returns the previous value."""- global _ENFORCED # noqa: PLW0603- prev, _ENFORCED = _ENFORCED, bool(value)- return prev---# ----------------------------------------------------------------------------# Heuristic classifier — does this message look like raw log / OCSF?-# ------------------------------------------------------------------------------def _looks_like_ocsf(payload: dict[str, Any]) -> str | None:- matched = _OCSF_KEYS & set(payload.keys())- if matched:- return f"OCSF keys present: {sorted(matched)}"- metadata = payload.get("metadata")- if isinstance(metadata, dict) and {"product", "version"} <= set(metadata.keys()):- return "OCSF-style metadata.product/version block"- return None---def _looks_like_raw_log(payload: dict[str, Any]) -> str | None:- matched = _LOG_KEYS & set(payload.keys())- if matched:- return f"raw-log keys present: {sorted(matched)}"- if isinstance(payload.get("EventID"), int) and "Channel" in payload:- return "Windows event-log shape (EventID + Channel)"- return None---def _looks_like_log_string(text: str) -> str | None:- head = text[:4000]- for pattern in _LOG_SHAPE_PATTERNS:- m = pattern.search(head)- if m:- return f"raw-log signature matched: {m.group(0)[:80]}"- return None---def _looks_like_secret(text: str) -> str | None:- head = text[:4000]- for pattern in _SECRET_PATTERNS:- m = pattern.search(head)- if m:- return f"secret-shaped value detected: {m.group(0)[:60]}"- return None---def _try_load_json(text: str) -> Any | None:- """Parse ``text`` as JSON if it looks like one; return ``None`` otherwise."""- stripped = text.strip()- if not stripped or stripped[0] not in "[{":- return None- try:- return json.loads(stripped)- except (json.JSONDecodeError, ValueError):- return None---def classify_message(content: str, *, role: str = "user") -> str | None:- """Return a violation reason if ``content`` breaches the contract, else None."""- if not isinstance(content, str):- # Multi-modal (list-of-parts) messages aren't supported by the- # contract yet — reject them so we never leak them by accident.- return f"non-string message content (type={type(content).__name__})"-- if len(content) > _MAX_MESSAGE_CHARS:- return f"message exceeds size cap ({len(content)} > {_MAX_MESSAGE_CHARS} chars)"-- # 1) Substring scan — fastest path, catches log shapes embedded in prose.- log_hit = _looks_like_log_string(content)- if log_hit:- return log_hit-- secret_hit = _looks_like_secret(content)- if secret_hit:- return secret_hit-- # 2) JSON inspection — only when the message *looks* like JSON we try- # to parse it. Avoids paying parse cost on every prose message.- parsed = _try_load_json(content)- if isinstance(parsed, dict):- ocsf = _looks_like_ocsf(parsed)- if ocsf:- return ocsf- log = _looks_like_raw_log(parsed)- if log:- return log- elif isinstance(parsed, list) and parsed:- head = parsed[0]- if isinstance(head, dict):- if len(head) > _MAX_JSON_LINE_KEYS and (_looks_like_ocsf(head) or _looks_like_raw_log(head)):- return "raw event array detected (looks like log batch)"-- return None---# ----------------------------------------------------------------------------# Contract model-# ------------------------------------------------------------------------------class LLMInputContract:- """Validator for the message list handed to ``llm.ainvoke``.-- Implemented as a class with a ``validate`` classmethod (rather than a- Pydantic ``BaseModel``) because LangChain's ``BaseMessage`` subclasses- don't round-trip cleanly through Pydantic v2 validation. The contract- invariants are enforced via :func:`classify_message` per element.- """-- @classmethod- def validate(cls, messages: Iterable[Any]) -> list[dict[str, Any]]:- """Return the normalised view of ``messages`` if all pass the contract.-- Each returned dict has shape ``{"role": str, "content": str}``.- Raises :class:`LLMContractViolation` on the first breach.- """- normalised: list[dict[str, Any]] = []- for idx, msg in enumerate(messages):- role, content = _coerce_message(msg)- if is_contract_enforced():- reason = classify_message(content, role=role)- if reason:- raise LLMContractViolation(- f"message[{idx}] failed contract: {reason}",- role=role,- evidence=content[:200],- )- normalised.append({"role": role, "content": content})- return normalised---def _coerce_message(msg: Any) -> tuple[str, str]:- """Best-effort extract (role, content) from a chat-message-shaped object.-- Supports plain dicts, LangChain ``BaseMessage`` subclasses, and tuples- of ``(role, content)``. Falls back to ``("user", str(msg))`` so the- contract still has *something* to validate.- """- if isinstance(msg, dict):- role = str(msg.get("role") or "user")- content = msg.get("content")- return role, content if isinstance(content, str) else json.dumps(content, default=str)- if hasattr(msg, "type") and hasattr(msg, "content"):- # LangChain BaseMessage: ``.type`` is "system" / "human" / "ai" / "tool"- type_to_role = {"human": "user", "ai": "assistant", "system": "system", "tool": "tool"}- role = type_to_role.get(getattr(msg, "type", "user"), "user")- content = getattr(msg, "content", "")- return role, content if isinstance(content, str) else json.dumps(content, default=str)- if isinstance(msg, tuple) and len(msg) == 2:- role, content = msg- return str(role), content if isinstance(content, str) else json.dumps(content, default=str)- return "user", str(msg)---def validate_messages(messages: Iterable[Any]) -> list[dict[str, Any]]:- """Module-level convenience for one-off validation."""- return LLMInputContract.validate(messages)--# ---------------------------------------------------------------------------# Safe LLM invocation wrapper# ---------------------------------------------------------------------------diff --git a/services/agents/app/llm/contract_rules.py b/services/agents/app/llm/contract_rules.pynew file mode 100644index 000000000..b39d36acb--- /dev/null+++ b/services/agents/app/llm/contract_rules.py@@ -0,0 +1,280 @@+"""The LLM input contract's rules, with no runtime dependencies (T2.3).++Split out of ``contract.py`` so the *same* classifier can run in+``services/api``. It previously could not: ``contract.py`` imports LangChain,+the cost-telemetry recorder and the response cache, none of which ship in the+API image — so the API service had no input contract at all while seven of its+endpoints POSTed untrusted input straight to a chat-completions API. One of+them (`phishing.py`) forwards an attacker-authored email body by definition.++This module is byte-identical to+``services/api/app/_vendor/llm_contract_rules.py``, kept in lockstep by+``scripts/sync_vendored_llm_contract.py --check`` in CI. Keep it dependency-free+(stdlib + structlog only) or the vendored copy stops importing and the API+silently loses the contract again.++``contract.py`` re-exports everything here, so existing agents callers and+tests are unaffected.+"""++from __future__ import annotations++import json+import os+import re+from collections.abc import Iterable+from typing import Any++AGENTS_LLM_CONTRACT_ENFORCED_ENV = "AISOC_AGENTS_LLM_CONTRACT_ENFORCED"++_OCSF_KEYS = frozenset(+ {+ "class_uid",+ "category_uid",+ "activity_id",+ "type_uid",+ "metadata",+ "time_dt",+ "observables",+ "raw_data",+ }+)+_LOG_KEYS = frozenset(+ {+ "Event",+ "EventData",+ "Sysmon",+ "RecordID",+ "EventRecordID",+ "Channel",+ "Provider",+ "_raw",+ "_time",+ "punct",+ }+)++# Union of dict keys that must never appear in LLM-bound JSON strings+# (prompt serialization uses this to redact / shallow-summarize nested data).+CONTRACT_DICT_KEY_BLOCKLIST: frozenset[str] = frozenset(_OCSF_KEYS | _LOG_KEYS)++# Compact regex for the most common raw-log signatures we want to catch+# even when the payload is rendered as a string instead of a dict.+_LOG_SHAPE_PATTERNS = (+ re.compile(r'"class_uid"\s*:\s*\d+'),+ re.compile(r'"activity_id"\s*:\s*\d+'),+ re.compile(r'"EventID"\s*:\s*\d+'),+ re.compile(r'"EventRecordID"\s*:\s*\d+'),+ re.compile(r'<Event xmlns="http://schemas\.microsoft\.com/win/'),+ # Splunk / Sentinel "search head" envelope+ re.compile(r'"_raw"\s*:\s*"'),+ re.compile(r'"sourcetype"\s*:\s*"'),+)++# Loose secret patterns — caught only as a last-resort guard. The vault+# layer (T*.4) is the primary defence; this is belt-and-braces.+_SECRET_PATTERNS = (+ re.compile(r"(?i)(api[_-]?key|secret|password|token)\s*[:=]\s*['\"][A-Za-z0-9_\-]{16,}['\"]"),+ re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----"),+)++_MAX_MESSAGE_CHARS = int(os.getenv("AISOC_AGENTS_LLM_CONTRACT_MAX_CHARS", "60000"))+_MAX_JSON_LINE_KEYS = 6 # tuple-of-keys threshold for "looks like a log line"+++class LLMContractViolation(RuntimeError):+ """Raised when a prompt about to be sent to an LLM violates the contract."""++ def __init__(self, reason: str, *, role: str | None = None, evidence: str | None = None) -> None:+ msg = f"[LLMInputContract] {reason}"+ if role:+ msg += f" (role={role})"+ if evidence:+ msg += f" — evidence: {evidence[:200]!r}"+ super().__init__(msg)+ self.reason = reason+ self.role = role+ self.evidence = evidence+++# ---------------------------------------------------------------------------+# Enforcement toggle+# ---------------------------------------------------------------------------++# Module-level cache so callers can flip enforcement at runtime via+# :func:`set_contract_enforcement`. The env var is the source of truth on+# fresh process start.+++def _env_default_enforced() -> bool:+ raw = os.getenv(AGENTS_LLM_CONTRACT_ENFORCED_ENV, "1").strip()+ return raw not in {"0", "false", "False", "no", "off"}+++_ENFORCED: bool = _env_default_enforced()+++def is_contract_enforced() -> bool:+ return _ENFORCED+++def set_contract_enforcement(value: bool) -> bool:+ """Override enforcement at runtime. Returns the previous value."""+ global _ENFORCED # noqa: PLW0603+ prev, _ENFORCED = _ENFORCED, bool(value)+ return prev+++# ---------------------------------------------------------------------------+# Heuristic classifier — does this message look like raw log / OCSF?+# ---------------------------------------------------------------------------+++def _looks_like_ocsf(payload: dict[str, Any]) -> str | None:+ matched = _OCSF_KEYS & set(payload.keys())+ if matched:+ return f"OCSF keys present: {sorted(matched)}"+ metadata = payload.get("metadata")+ if isinstance(metadata, dict) and {"product", "version"} <= set(metadata.keys()):+ return "OCSF-style metadata.product/version block"+ return None+++def _looks_like_raw_log(payload: dict[str, Any]) -> str | None:+ matched = _LOG_KEYS & set(payload.keys())+ if matched:+ return f"raw-log keys present: {sorted(matched)}"+ if isinstance(payload.get("EventID"), int) and "Channel" in payload:+ return "Windows event-log shape (EventID + Channel)"+ return None+++def _looks_like_log_string(text: str) -> str | None:+ head = text[:4000]+ for pattern in _LOG_SHAPE_PATTERNS:+ m = pattern.search(head)+ if m:+ return f"raw-log signature matched: {m.group(0)[:80]}"+ return None+++def _looks_like_secret(text: str) -> str | None:+ head = text[:4000]+ for pattern in _SECRET_PATTERNS:+ m = pattern.search(head)+ if m:+ return f"secret-shaped value detected: {m.group(0)[:60]}"+ return None+++def _try_load_json(text: str) -> Any | None:+ """Parse ``text`` as JSON if it looks like one; return ``None`` otherwise."""+ stripped = text.strip()+ if not stripped or stripped[0] not in "[{":+ return None+ try:+ return json.loads(stripped)+ except (json.JSONDecodeError, ValueError):+ return None+++def classify_message(content: str, *, role: str = "user") -> str | None:+ """Return a violation reason if ``content`` breaches the contract, else None."""+ if not isinstance(content, str):+ # Multi-modal (list-of-parts) messages aren't supported by the+ # contract yet — reject them so we never leak them by accident.+ return f"non-string message content (type={type(content).__name__})"++ if len(content) > _MAX_MESSAGE_CHARS:+ return f"message exceeds size cap ({len(content)} > {_MAX_MESSAGE_CHARS} chars)"++ # 1) Substring scan — fastest path, catches log shapes embedded in prose.+ log_hit = _looks_like_log_string(content)+ if log_hit:+ return log_hit++ secret_hit = _looks_like_secret(content)+ if secret_hit:+ return secret_hit++ # 2) JSON inspection — only when the message *looks* like JSON we try+ # to parse it. Avoids paying parse cost on every prose message.+ parsed = _try_load_json(content)+ if isinstance(parsed, dict):+ ocsf = _looks_like_ocsf(parsed)+ if ocsf:+ return ocsf+ log = _looks_like_raw_log(parsed)+ if log:+ return log+ elif isinstance(parsed, list) and parsed:+ head = parsed[0]+ if isinstance(head, dict):+ if len(head) > _MAX_JSON_LINE_KEYS and (_looks_like_ocsf(head) or _looks_like_raw_log(head)):+ return "raw event array detected (looks like log batch)"++ return None+++# ---------------------------------------------------------------------------+# Contract model+# ---------------------------------------------------------------------------+++class LLMInputContract:+ """Validator for the message list handed to ``llm.ainvoke``.++ Implemented as a class with a ``validate`` classmethod (rather than a+ Pydantic ``BaseModel``) because LangChain's ``BaseMessage`` subclasses+ don't round-trip cleanly through Pydantic v2 validation. The contract+ invariants are enforced via :func:`classify_message` per element.+ """++ @classmethod+ def validate(cls, messages: Iterable[Any]) -> list[dict[str, Any]]:+ """Return the normalised view of ``messages`` if all pass the contract.++ Each returned dict has shape ``{"role": str, "content": str}``.+ Raises :class:`LLMContractViolation` on the first breach.+ """+ normalised: list[dict[str, Any]] = []+ for idx, msg in enumerate(messages):+ role, content = _coerce_message(msg)+ if is_contract_enforced():+ reason = classify_message(content, role=role)+ if reason:+ raise LLMContractViolation(+ f"message[{idx}] failed contract: {reason}",+ role=role,+ evidence=content[:200],+ )+ normalised.append({"role": role, "content": content})+ return normalised+++def _coerce_message(msg: Any) -> tuple[str, str]:+ """Best-effort extract (role, content) from a chat-message-shaped object.++ Supports plain dicts, LangChain ``BaseMessage`` subclasses, and tuples+ of ``(role, content)``. Falls back to ``("user", str(msg))`` so the+ contract still has *something* to validate.+ """+ if isinstance(msg, dict):+ role = str(msg.get("role") or "user")+ content = msg.get("content")+ return role, content if isinstance(content, str) else json.dumps(content, default=str)+ if hasattr(msg, "type") and hasattr(msg, "content"):+ # LangChain BaseMessage: ``.type`` is "system" / "human" / "ai" / "tool"+ type_to_role = {"human": "user", "ai": "assistant", "system": "system", "tool": "tool"}+ role = type_to_role.get(getattr(msg, "type", "user"), "user")+ content = getattr(msg, "content", "")+ return role, content if isinstance(content, str) else json.dumps(content, default=str)+ if isinstance(msg, tuple) and len(msg) == 2:+ role, content = msg+ return str(role), content if isinstance(content, str) else json.dumps(content, default=str)+ return "user", str(msg)+++def validate_messages(messages: Iterable[Any]) -> list[dict[str, Any]]:+ """Module-level convenience for one-off validation."""+ return LLMInputContract.validate(messages)diff --git a/services/agents/app/nl_query/translator.py b/services/agents/app/nl_query/translator.pyindex 19eb8006e..5de992be3 100644--- a/services/agents/app/nl_query/translator.py+++ b/services/agents/app/nl_query/translator.py@@ -902,8 +902,17 @@ async def enhance_with_llm(import jsonimport textwrap- from app.llm.contract import safe_chat_completions_request- from app.llm.factory import chat_completions_url, resolve_model_alias+ # This module is vendored byte-identically into services/api, where+ # `app.llm` does not exist — so importing only the agents path made+ # the ImportError below swallow the whole LLM branch, and /nl-query+ # silently returned the deterministic translation forever. Safe by+ # accident, and invisible. Resolve whichever package is present.+ try:+ from app.llm.contract import safe_chat_completions_request+ from app.llm.factory import chat_completions_url, resolve_model_alias+ except ImportError: # running inside services/api+ from app.services.llm_safety import safe_chat_completions_request+ from app.services.model_aliases import chat_completions_url, resolve_model_aliasprompt = textwrap.dedent(f"""diff --git a/services/agents/app/workers/business_context.py b/services/agents/app/workers/business_context.pyindex 4d39820ee..4fa76e16a 100644--- a/services/agents/app/workers/business_context.py+++ b/services/agents/app/workers/business_context.py@@ -40,6 +40,25 @@ import yamllogger = structlog.get_logger()_ALLOWED_SEVERITIES = {"info", "low", "medium", "high", "critical"}+#: Must match ``ALLOWED_ROUTES`` in+#: ``services/api/app/services/business_context/models.py``. Duplicated rather+#: than imported because the two services ship separate images, and kept in+#: lockstep by ``tests/test_business_context_not_clause.py``. The worker used+#: to accept any string here while the console validated against this set, so+#: the two halves of the same grammar disagreed.+_ALLOWED_ROUTES = frozenset(+ {+ "tier1",+ "tier2",+ "tier3",+ "ic",+ "cloud",+ "identity",+ "appsec",+ "soc-night",+ "soc-emea",+ }+)_ENABLED_ENV = "AISOC_BUSINESS_CONTEXT_ENABLED"_RULES_FILE_ENV = "AISOC_BUSINESS_CONTEXT_RULES_FILE"@@ -136,16 +155,49 @@ def evaluate_condition(cond: RuleCondition, alert: dict[str, Any]) -> bool:return False-def _parse_condition(node: dict[str, Any]) -> RuleCondition:- for logical in ("all", "any", "not"):+def _parse_condition(node: Any) -> RuleCondition:+ """Parse one condition node.++ ``not`` takes a **mapping** — a single negated condition — which is what+ the console's authoring grammar accepts and validates+ (``services/api/app/services/business_context/models.py``). This parser+ used to iterate every aggregator as a list, and iterating a mapping yields+ its string keys, so ``_parse_condition("field")`` called ``.get()`` on a+ ``str`` and raised ``AttributeError``. That propagated into the caller's+ catch, which set ``rules = []`` — so one console-accepted ``not`` rule+ silently discarded the tenant's entire rule set at triage, suppressions+ included, logged at ``warning``.++ A list is still accepted for ``not`` and treated as "none of these", which+ is what the old evaluator already did with the children it never managed+ to build.+ """+ if not isinstance(node, dict):+ raise ValueError(f"condition must be a mapping, got {type(node).__name__}")++ for logical in ("all", "any"):if logical in node:kids = node[logical] or []+ if not isinstance(kids, list):+ raise ValueError(f"'{logical}' must be a list of conditions, got {type(kids).__name__}")return RuleCondition(logical=logical, children=tuple(_parse_condition(k) for k in kids))++ if "not" in node:+ negated = node["not"] or {}+ kids = negated if isinstance(negated, list) else [negated]+ return RuleCondition(logical="not", children=tuple(_parse_condition(k) for k in kids))+return RuleCondition(field=node.get("field"), op=node.get("op"), value=node.get("value"))def load_rules_from_yaml(source: str) -> list[BusinessContextRule]:- """Parse rules YAML (single mapping or top-level ``rules:`` list)."""+ """Parse rules YAML (single mapping or top-level ``rules:`` list).++ A rule that fails to parse is skipped and the rest are kept. It used to+ raise, and the caller's catch turned that into ``rules = []`` — so one+ malformed rule disabled every other rule the tenant had written,+ suppressions included. The blast radius of a bad rule should be that rule.+ """if not source or not source.strip():return []doc = yaml.safe_load(source)@@ -167,13 +219,25 @@ def load_rules_from_yaml(source: str) -> list[BusinessContextRule]:sev = action.get("set_severity")if sev is not None and sev not in _ALLOWED_SEVERITIES:sev = None+ route = action.get("route_to")+ if route is not None and route not in _ALLOWED_ROUTES:+ # The console validates this; the worker did not, so a route the+ # authoring grammar would have rejected could reach the hot path+ # if the row was written by anything else.+ logger.warning("business_context.rule_route_rejected", rule_id=rid, route_to=route)+ route = None+ try:+ when = _parse_condition(entry.get("when") or {})+ except (ValueError, AttributeError, TypeError) as exc:+ logger.warning("business_context.rule_skipped", rule_id=rid, error=str(exc))+ continuerules.append(BusinessContextRule(id=rid,- when=_parse_condition(entry.get("when") or {}),+ when=when,then=RuleAction(set_severity=sev,- route_to=action.get("route_to"),+ route_to=route,tag=action.get("tag"),suppress=bool(action.get("suppress", False)),),diff --git a/services/agents/tests/test_business_context_not_clause.py b/services/agents/tests/test_business_context_not_clause.pynew file mode 100644index 000000000..388bbabde--- /dev/null+++ b/services/agents/tests/test_business_context_not_clause.py@@ -0,0 +1,166 @@+"""The two business-context evaluators must agree on the grammar (T3.5).++Business-context rules are parsed twice by two different implementations: the+console authors and validates them with+``services/api/app/services/business_context/models.py``, and the triage worker+re-parses the stored YAML with ``services/agents/app/workers/business_context``.++They disagreed on ``not``. The console requires a mapping — a single negated+condition — and the worker iterated every aggregator as a list. Iterating a+mapping yields its string keys, so ``_parse_condition("field")`` called+``.get()`` on a ``str`` and raised ``AttributeError``, which the caller's catch+turned into ``rules = []``.++The consequence was not a broken rule. **One console-accepted ``not`` rule+silently discarded that tenant's entire rule set at triage**, suppressions+included, logged at ``warning``. A rule that suppresses known-benign noise+stops suppressing, and nothing on the console says so.+"""++from __future__ import annotations++import ast+from pathlib import Path++from app.workers.business_context import (+ _ALLOWED_ROUTES,+ apply_rules,+ load_rules_from_yaml,+)++NOT_RULE_YAML = """+rules:+ - id: payments-not-info+ when:+ all:+ - {field: asset.tags, op: contains, value: payments}+ - not: {field: severity, op: eq, value: info}+ then:+ set_severity: critical+ - id: suppress-known-scanner+ when: {field: source_ip, op: eq, value: 10.1.2.3}+ then:+ suppress: true+"""+++def test_a_not_rule_parses_at_all() -> None:+ """The regression: this raised AttributeError."""+ rules = load_rules_from_yaml(NOT_RULE_YAML)+ assert [r.id for r in rules] == ["payments-not-info", "suppress-known-scanner"]+++def test_a_not_rule_does_not_take_the_rest_of_the_tenants_rules_with_it() -> None:+ """The severe part. The suppression rule is unrelated to the `not` rule+ and used to stop working because of it."""+ rules = load_rules_from_yaml(NOT_RULE_YAML)+ suppressors = [r for r in rules if r.then.suppress]+ assert len(suppressors) == 1, "the suppression rule was dropped"+++def test_the_negation_actually_negates() -> None:+ """Parsing is not enough — a `not` that always evaluated False would be a+ rule that silently never fires."""+ rules = load_rules_from_yaml(NOT_RULE_YAML)++ high = apply_rules({"asset": {"tags": ["payments"]}, "severity": "high"}, rules)+ assert high.alert["severity"] == "critical"+ assert "payments-not-info" in high.matched_rule_ids++ info = apply_rules({"asset": {"tags": ["payments"]}, "severity": "info"}, rules)+ assert info.alert["severity"] == "info", "the negated branch matched when it should not have"+ assert "payments-not-info" not in info.matched_rule_ids+++def test_not_also_accepts_a_list_meaning_none_of_these() -> None:+ """Kept for the shape the old evaluator's `not` branch implied."""+ rules = load_rules_from_yaml(+ """+rules:+ - id: neither+ when:+ not:+ - {field: severity, op: eq, value: info}+ - {field: severity, op: eq, value: low}+ then:+ tag: escalated+"""+ )+ assert apply_rules({"severity": "high"}, rules).matched_rule_ids == ["neither"]+ assert apply_rules({"severity": "low"}, rules).matched_rule_ids == []+++def test_one_malformed_rule_is_skipped_and_the_others_survive() -> None:+ """The blast radius of a bad rule should be that rule."""+ rules = load_rules_from_yaml(+ """+rules:+ - id: broken+ when:+ all: {not: a list}+ then:+ set_severity: high+ - id: fine+ when: {field: source, op: eq, value: okta}+ then:+ tag: identity+"""+ )+ assert [r.id for r in rules] == ["fine"]+++def test_an_unknown_route_is_dropped_rather_than_applied() -> None:+ """The console validates route_to; the worker did not, so a route the+ authoring grammar rejects could still reach the hot path."""+ rules = load_rules_from_yaml(+ """+rules:+ - id: bad-route+ when: {field: source, op: eq, value: okta}+ then:+ route_to: not-a-real-queue+"""+ )+ assert rules[0].then.route_to is None+++def test_a_known_route_still_applies() -> None:+ rules = load_rules_from_yaml(+ """+rules:+ - id: good-route+ when: {field: source, op: eq, value: okta}+ then:+ route_to: identity+"""+ )+ assert rules[0].then.route_to == "identity"+++def test_the_worker_route_list_matches_the_console_route_list() -> None:+ """Two copies of one grammar drift unless something pins them together.++ Read out of the API's source rather than imported: the two services ship+ as separate images and ``services/api`` is not importable from the agents+ test environment. An ``importorskip`` here would make this a gate that+ passes by skipping, which is the failure mode it exists to prevent — so it+ parses the literal instead, and fails loudly if the file moves.+ """+ services_dir = Path(__file__).resolve().parents[2]+ models_py = services_dir / "api" / "app" / "services" / "business_context" / "models.py"+ assert models_py.exists(), f"the console's grammar moved; update this path ({models_py})"++ tree = ast.parse(models_py.read_text(encoding="utf-8"))+ console_routes: set[str] | None = None+ for node in ast.walk(tree):+ if not isinstance(node, ast.AnnAssign) or not isinstance(node.target, ast.Name):+ continue+ if node.target.id != "ALLOWED_ROUTES" or node.value is None:+ continue+ # frozenset({...}) — pull the set literal out of the call.+ literal = node.value.args[0] if isinstance(node.value, ast.Call) and node.value.args else node.value+ console_routes = {elt.value for elt in literal.elts if isinstance(elt, ast.Constant)}+ break++ assert console_routes, "could not read ALLOWED_ROUTES out of the console's models.py"+ assert set(_ALLOWED_ROUTES) == console_routesdiff --git a/services/agents/tests/test_llm_contract_no_bypass.py b/services/agents/tests/test_llm_contract_no_bypass.pyindex deb1e8fd9..4dcd72ce8 100644--- a/services/agents/tests/test_llm_contract_no_bypass.py+++ b/services/agents/tests/test_llm_contract_no_bypass.py@@ -139,6 +139,131 @@ def _python_sources() -> list[Path]:return [p for p in _AGENTS_APP.rglob("*.py") if "__pycache__" not in p.parts and p not in _ALLOWED_FILES]+# ── Raw-HTTP LLM calls ─────────────────────────────────────────────────────+#+# The gate above walks the AST for `.ainvoke` / `.astream`, which proves the+# LangChain path is clean and says nothing about the other way to reach a+# model: POST to a chat-completions URL with httpx. `app/api/explain.py` did+# exactly that and was invisible here for several releases, under a test named+# "no bypass".+#+# The same shape is the whole story in `services/api`, which had no contract+# at all while seven endpoints POSTed untrusted input to a provider.++_API_APP = _AGENTS_APP.parent.parent / "api" / "app"++#: A URL fragment that means "this is a chat-completions endpoint".+_COMPLETIONS_MARKERS = ("chat/completions", "/completions")++#: Files that legitimately construct such a request: the safe wrappers+#: themselves, which validate before the POST.+_ALLOWED_HTTP_FILES: frozenset[Path] = frozenset(+ {+ _AGENTS_APP / "llm" / "contract.py",+ _API_APP / "services" / "llm_safety.py",+ # Vendored copy of the rules; carries no HTTP call, listed so a future+ # sync that adds one is a deliberate decision.+ _API_APP / "_vendor" / "llm_contract_rules.py",+ }+)+++#: ``.post`` receivers that are route registrars, not HTTP clients. A FastAPI+#: ``@router.post("/...")`` decorator is the same attribute name as an httpx+#: POST and means the opposite thing.+_NOT_HTTP_CLIENTS: frozenset[str] = frozenset({"router", "app", "api_router"})+++def _mentions_completions(source: str) -> bool:+ return any(marker in source for marker in _COMPLETIONS_MARKERS)+++def _find_raw_http_llm_calls(path: Path) -> list[tuple[int, str]]:+ """Flag a `client.post(...)`-shaped call in a file that names a+ completions endpoint and does not import a safe wrapper.++ Deliberately coarse. Proving that a particular `post` targets a+ completions URL requires following a variable through string formatting,+ which an AST walker cannot do reliably — so the test asks the answerable+ question instead: does this file both talk about a completions endpoint+ and issue its own POST? A file that routes through+ `safe_chat_completions_request` passes, because it no longer issues the+ POST itself.+ """+ source = path.read_text(encoding="utf-8")+ if not _mentions_completions(source):+ return []+ if "safe_chat_completions_request" in source:+ return []++ tree = ast.parse(source, filename=str(path))+ findings: list[tuple[int, str]] = []+ for node in ast.walk(tree):+ if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Attribute):+ continue+ if node.func.attr != "post":+ continue+ receiver = _receiver_name(node.func)+ if receiver in _NOT_HTTP_CLIENTS:+ continue+ findings.append((node.lineno, receiver))+ return findings+++def _http_sources() -> list[Path]:+ roots = [r for r in (_AGENTS_APP, _API_APP) if r.is_dir()]+ return [p for root in roots for p in root.rglob("*.py") if "__pycache__" not in p.parts and p not in _ALLOWED_HTTP_FILES]+++def test_no_raw_http_llm_calls() -> None:+ """An LLM call over raw HTTP must go through the safe wrapper too.++ This is the gate that was missing. `services/agents/app/api/explain.py`+ reached a model with `httpx.AsyncClient().post(...)` and never touched the+ contract, and every LLM call in `services/api` did the same — while the+ suite reported the contract fully enforced.+ """+ violations: list[str] = []+ for path in _http_sources():+ for lineno, receiver in _find_raw_http_llm_calls(path):+ try:+ rel = path.relative_to(_AGENTS_APP.parent.parent)+ except ValueError: # pragma: no cover - defensive+ rel = path+ violations.append(f"{rel}:{lineno} {receiver}.post(...) to a completions endpoint")++ assert not violations, (+ "Raw-HTTP LLM call detected — route it through "+ "safe_chat_completions_request (app.llm.contract in services/agents, "+ "app.services.llm_safety in services/api) so the input contract runs "+ "before the request rather than after it.\n " + "\n ".join(violations)+ )+++def test_the_http_gate_detects_a_synthetic_bypass(tmp_path: Path) -> None:+ """A gate nobody has seen fail is a gate nobody knows works."""+ bad = tmp_path / "sneaky.py"+ bad.write_text(+ "import httpx\n"+ "async def go(key):\n"+ " async with httpx.AsyncClient() as c:\n"+ ' return await c.post("https://api.openai.com/v1/chat/completions", json={})\n',+ encoding="utf-8",+ )+ assert _find_raw_http_llm_calls(bad), "the raw-HTTP walker missed an obvious bypass"+++def test_the_http_gate_accepts_a_wrapped_call(tmp_path: Path) -> None:+ good = tmp_path / "fine.py"+ good.write_text(+ "from app.services.llm_safety import safe_chat_completions_request\n"+ "async def go(key):\n"+ ' return await safe_chat_completions_request(api_key=key, model="m", messages=[], url="https://x/chat/completions")\n',+ encoding="utf-8",+ )+ assert not _find_raw_http_llm_calls(good)++def test_no_direct_ainvoke_or_astream_bypass() -> None:"""No file under services/agents/app/ may call .ainvoke/.astream directly on an LLM."""violations: list[str] = []diff --git a/services/api/app/_vendor/llm_contract_rules.py b/services/api/app/_vendor/llm_contract_rules.pynew file mode 100644index 000000000..b39d36acb--- /dev/null+++ b/services/api/app/_vendor/llm_contract_rules.py@@ -0,0 +1,280 @@+"""The LLM input contract's rules, with no runtime dependencies (T2.3).++Split out of ``contract.py`` so the *same* classifier can run in+``services/api``. It previously could not: ``contract.py`` imports LangChain,+the cost-telemetry recorder and the response cache, none of which ship in the+API image — so the API service had no input contract at all while seven of its+endpoints POSTed untrusted input straight to a chat-completions API. One of+them (`phishing.py`) forwards an attacker-authored email body by definition.++This module is byte-identical to+``services/api/app/_vendor/llm_contract_rules.py``, kept in lockstep by+``scripts/sync_vendored_llm_contract.py --check`` in CI. Keep it dependency-free+(stdlib + structlog only) or the vendored copy stops importing and the API+silently loses the contract again.++``contract.py`` re-exports everything here, so existing agents callers and+tests are unaffected.+"""++from __future__ import annotations++import json+import os+import re+from collections.abc import Iterable+from typing import Any++AGENTS_LLM_CONTRACT_ENFORCED_ENV = "AISOC_AGENTS_LLM_CONTRACT_ENFORCED"++_OCSF_KEYS = frozenset(+ {+ "class_uid",+ "category_uid",+ "activity_id",+ "type_uid",+ "metadata",+ "time_dt",+ "observables",+ "raw_data",+ }+)+_LOG_KEYS = frozenset(+ {+ "Event",+ "EventData",+ "Sysmon",+ "RecordID",+ "EventRecordID",+ "Channel",+ "Provider",+ "_raw",+ "_time",+ "punct",+ }+)++# Union of dict keys that must never appear in LLM-bound JSON strings+# (prompt serialization uses this to redact / shallow-summarize nested data).+CONTRACT_DICT_KEY_BLOCKLIST: frozenset[str] = frozenset(_OCSF_KEYS | _LOG_KEYS)++# Compact regex for the most common raw-log signatures we want to catch+# even when the payload is rendered as a string instead of a dict.+_LOG_SHAPE_PATTERNS = (+ re.compile(r'"class_uid"\s*:\s*\d+'),+ re.compile(r'"activity_id"\s*:\s*\d+'),+ re.compile(r'"EventID"\s*:\s*\d+'),+ re.compile(r'"EventRecordID"\s*:\s*\d+'),+ re.compile(r'<Event xmlns="http://schemas\.microsoft\.com/win/'),+ # Splunk / Sentinel "search head" envelope+ re.compile(r'"_raw"\s*:\s*"'),+ re.compile(r'"sourcetype"\s*:\s*"'),+)++# Loose secret patterns — caught only as a last-resort guard. The vault+# layer (T*.4) is the primary defence; this is belt-and-braces.+_SECRET_PATTERNS = (+ re.compile(r"(?i)(api[_-]?key|secret|password|token)\s*[:=]\s*['\"][A-Za-z0-9_\-]{16,}['\"]"),+ re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----"),+)++_MAX_MESSAGE_CHARS = int(os.getenv("AISOC_AGENTS_LLM_CONTRACT_MAX_CHARS", "60000"))+_MAX_JSON_LINE_KEYS = 6 # tuple-of-keys threshold for "looks like a log line"+++class LLMContractViolation(RuntimeError):+ """Raised when a prompt about to be sent to an LLM violates the contract."""++ def __init__(self, reason: str, *, role: str | None = None, evidence: str | None = None) -> None:+ msg = f"[LLMInputContract] {reason}"+ if role:+ msg += f" (role={role})"+ if evidence:+ msg += f" — evidence: {evidence[:200]!r}"+ super().__init__(msg)+ self.reason = reason+ self.role = role+ self.evidence = evidence+++# ---------------------------------------------------------------------------+# Enforcement toggle+# ---------------------------------------------------------------------------++# Module-level cache so callers can flip enforcement at runtime via+# :func:`set_contract_enforcement`. The env var is the source of truth on+# fresh process start.+++def _env_default_enforced() -> bool:+ raw = os.getenv(AGENTS_LLM_CONTRACT_ENFORCED_ENV, "1").strip()+ return raw not in {"0", "false", "False", "no", "off"}+++_ENFORCED: bool = _env_default_enforced()+++def is_contract_enforced() -> bool:+ return _ENFORCED+++def set_contract_enforcement(value: bool) -> bool:+ """Override enforcement at runtime. Returns the previous value."""+ global _ENFORCED # noqa: PLW0603+ prev, _ENFORCED = _ENFORCED, bool(value)+ return prev+++# ---------------------------------------------------------------------------+# Heuristic classifier — does this message look like raw log / OCSF?+# ---------------------------------------------------------------------------+++def _looks_like_ocsf(payload: dict[str, Any]) -> str | None:+ matched = _OCSF_KEYS & set(payload.keys())+ if matched:+ return f"OCSF keys present: {sorted(matched)}"+ metadata = payload.get("metadata")+ if isinstance(metadata, dict) and {"product", "version"} <= set(metadata.keys()):+ return "OCSF-style metadata.product/version block"+ return None+++def _looks_like_raw_log(payload: dict[str, Any]) -> str | None:+ matched = _LOG_KEYS & set(payload.keys())+ if matched:+ return f"raw-log keys present: {sorted(matched)}"+ if isinstance(payload.get("EventID"), int) and "Channel" in payload:+ return "Windows event-log shape (EventID + Channel)"+ return None+++def _looks_like_log_string(text: str) -> str | None:+ head = text[:4000]+ for pattern in _LOG_SHAPE_PATTERNS:+ m = pattern.search(head)+ if m:+ return f"raw-log signature matched: {m.group(0)[:80]}"+ return None+++def _looks_like_secret(text: str) -> str | None:+ head = text[:4000]+ for pattern in _SECRET_PATTERNS:+ m = pattern.search(head)+ if m:+ return f"secret-shaped value detected: {m.group(0)[:60]}"+ return None+++def _try_load_json(text: str) -> Any | None:+ """Parse ``text`` as JSON if it looks like one; return ``None`` otherwise."""+ stripped = text.strip()+ if not stripped or stripped[0] not in "[{":+ return None+ try:+ return json.loads(stripped)+ except (json.JSONDecodeError, ValueError):+ return None+++def classify_message(content: str, *, role: str = "user") -> str | None:+ """Return a violation reason if ``content`` breaches the contract, else None."""+ if not isinstance(content, str):+ # Multi-modal (list-of-parts) messages aren't supported by the+ # contract yet — reject them so we never leak them by accident.+ return f"non-string message content (type={type(content).__name__})"++ if len(content) > _MAX_MESSAGE_CHARS:+ return f"message exceeds size cap ({len(content)} > {_MAX_MESSAGE_CHARS} chars)"++ # 1) Substring scan — fastest path, catches log shapes embedded in prose.+ log_hit = _looks_like_log_string(content)+ if log_hit:+ return log_hit++ secret_hit = _looks_like_secret(content)+ if secret_hit:+ return secret_hit++ # 2) JSON inspection — only when the message *looks* like JSON we try+ # to parse it. Avoids paying parse cost on every prose message.+ parsed = _try_load_json(content)+ if isinstance(parsed, dict):+ ocsf = _looks_like_ocsf(parsed)+ if ocsf:+ return ocsf+ log = _looks_like_raw_log(parsed)+ if log:+ return log+ elif isinstance(parsed, list) and parsed:+ head = parsed[0]+ if isinstance(head, dict):+ if len(head) > _MAX_JSON_LINE_KEYS and (_looks_like_ocsf(head) or _looks_like_raw_log(head)):+ return "raw event array detected (looks like log batch)"++ return None+++# ---------------------------------------------------------------------------+# Contract model+# ---------------------------------------------------------------------------+++class LLMInputContract:+ """Validator for the message list handed to ``llm.ainvoke``.++ Implemented as a class with a ``validate`` classmethod (rather than a+ Pydantic ``BaseModel``) because LangChain's ``BaseMessage`` subclasses+ don't round-trip cleanly through Pydantic v2 validation. The contract+ invariants are enforced via :func:`classify_message` per element.+ """++ @classmethod+ def validate(cls, messages: Iterable[Any]) -> list[dict[str, Any]]:+ """Return the normalised view of ``messages`` if all pass the contract.++ Each returned dict has shape ``{"role": str, "content": str}``.+ Raises :class:`LLMContractViolation` on the first breach.+ """+ normalised: list[dict[str, Any]] = []+ for idx, msg in enumerate(messages):+ role, content = _coerce_message(msg)+ if is_contract_enforced():+ reason = classify_message(content, role=role)+ if reason:+ raise LLMContractViolation(+ f"message[{idx}] failed contract: {reason}",+ role=role,+ evidence=content[:200],+ )+ normalised.append({"role": role, "content": content})+ return normalised+++def _coerce_message(msg: Any) -> tuple[str, str]:+ """Best-effort extract (role, content) from a chat-message-shaped object.++ Supports plain dicts, LangChain ``BaseMessage`` subclasses, and tuples+ of ``(role, content)``. Falls back to ``("user", str(msg))`` so the+ contract still has *something* to validate.+ """+ if isinstance(msg, dict):+ role = str(msg.get("role") or "user")+ content = msg.get("content")+ return role, content if isinstance(content, str) else json.dumps(content, default=str)+ if hasattr(msg, "type") and hasattr(msg, "content"):+ # LangChain BaseMessage: ``.type`` is "system" / "human" / "ai" / "tool"+ type_to_role = {"human": "user", "ai": "assistant", "system": "system", "tool": "tool"}+ role = type_to_role.get(getattr(msg, "type", "user"), "user")+ content = getattr(msg, "content", "")+ return role, content if isinstance(content, str) else json.dumps(content, default=str)+ if isinstance(msg, tuple) and len(msg) == 2:+ role, content = msg+ return str(role), content if isinstance(content, str) else json.dumps(content, default=str)+ return "user", str(msg)+++def validate_messages(messages: Iterable[Any]) -> list[dict[str, Any]]:+ """Module-level convenience for one-off validation."""+ return LLMInputContract.validate(messages)diff --git a/services/api/app/_vendor/nl_query/translator.py b/services/api/app/_vendor/nl_query/translator.pyindex 19eb8006e..5de992be3 100644--- a/services/api/app/_vendor/nl_query/translator.py+++ b/services/api/app/_vendor/nl_query/translator.py@@ -902,8 +902,17 @@ async def enhance_with_llm(import jsonimport textwrap- from app.llm.contract import safe_chat_completions_request- from app.llm.factory import chat_completions_url, resolve_model_alias+ # This module is vendored byte-identically into services/api, where+ # `app.llm` does not exist — so importing only the agents path made+ # the ImportError below swallow the whole LLM branch, and /nl-query+ # silently returned the deterministic translation forever. Safe by+ # accident, and invisible. Resolve whichever package is present.+ try:+ from app.llm.contract import safe_chat_completions_request+ from app.llm.factory import chat_completions_url, resolve_model_alias+ except ImportError: # running inside services/api+ from app.services.llm_safety import safe_chat_completions_request+ from app.services.model_aliases import chat_completions_url, resolve_model_aliasprompt = textwrap.dedent(f"""diff --git a/services/api/app/api/v1/endpoints/detection_loop.py b/services/api/app/api/v1/endpoints/detection_loop.pyindex 07c581ec8..f42c3fe0d 100644--- a/services/api/app/api/v1/endpoints/detection_loop.py+++ b/services/api/app/api/v1/endpoints/detection_loop.py@@ -19,12 +19,12 @@ Endpointsfrom __future__ import annotationsimport json+import loggingimport textwrapimport uuidfrom datetime import UTC, datetimefrom typing import Any-import httpxfrom fastapi import APIRouter, HTTPException, statusfrom pydantic import BaseModel, Fieldfrom sqlalchemy import text@@ -32,6 +32,9 @@ from sqlalchemy import textfrom app.api.v1.deps import AuthUserfrom app.core.config import settingsfrom app.db.rls import TenantDBSession+from app.services.llm_safety import LLMContractViolation, safe_chat_completions_request++logger = logging.getLogger(__name__)router = APIRouter(prefix="/detection-loop", tags=["detection_rules", "detection_loop"])@@ -110,22 +113,22 @@ async def _llm_draft_sigma(indent=2,)try:- async with httpx.AsyncClient(timeout=30) as client:- resp = await client.post(- "https://api.openai.com/v1/chat/completions",- headers={"Authorization": f"Bearer {api_key}"},- json={- "model": "gpt-4o-mini",- "response_format": {"type": "json_object"},- "messages": [- {"role": "system", "content": _SYS_PROMPT},- {"role": "user", "content": user_msg},- ],- },- )- resp.raise_for_status()- raw = resp.json()["choices"][0]["message"]["content"]- return json.loads(raw)+ # T2.3 — `user_msg` embeds `alert_fields`, i.e. raw alert data, which+ # is the shape the contract exists to stop leaving the deployment.+ body = await safe_chat_completions_request(+ api_key=api_key,+ model="gpt-4o-mini",+ messages=[+ {"role": "system", "content": _SYS_PROMPT},+ {"role": "user", "content": user_msg},+ ],+ timeout=30.0,+ response_format={"type": "json_object"},+ )+ return json.loads(body["choices"][0]["message"]["content"])+ except LLMContractViolation as exc:+ logger.warning("detection_loop.llm_contract_violation", reason=exc.reason)+ return _template_fallback(current_sigma, alert_fields, analyst_note)except Exception:return _template_fallback(current_sigma, alert_fields, analyst_note)diff --git a/services/api/app/api/v1/endpoints/effective_permissions.py b/services/api/app/api/v1/endpoints/effective_permissions.pyindex 6b1f29676..6b90f48fe 100644--- a/services/api/app/api/v1/endpoints/effective_permissions.py+++ b/services/api/app/api/v1/endpoints/effective_permissions.py@@ -11,14 +11,25 @@ Routes------``GET /v1/identity/effective-permissions/providers``- Return the supported provider list + per-provider coverage status. The- UI uses this to render the provider switcher and grey-out the- scaffolded providers.+ Return the supported provider list + per-provider coverage status.+ The UI uses this to render the provider switcher.``GET /v1/identity/{principal_id}/effective-permissions?provider=...``- Return a :class:`ResolverResult` JSON envelope. Scaffolded providers- (Azure, GCP, Okta, GWS) return HTTP 501 with the same envelope shape so- the UI can still render the empty state.+ Return a :class:`ResolverResult` JSON envelope.++All five resolvers — AWS, Azure, GCP, Okta and Google Workspace — are+implemented and report ``coverage: "full"``. This docstring described Azure,+GCP, Okta and GWS as scaffolds returning HTTP 501 long after they stopped+being scaffolds, and the ``NotImplementedError`` branch below has been+unreachable for as long.++What *is* still limited is the **snapshot**, not the resolver. A resolver is a+pure function over a provider snapshot, and only Okta's is assembled from a+live connector today — the other four expect a connector to answer the+``__posture_snapshot__`` sentinel, and no connector implements it. With+``AISOC_EFFECTIVE_PERMISSIONS_LIVE=1`` those four therefore return **412**+("no policy snapshot ingested yet") rather than a fabricated snapshot. See+``app/services/effective_permissions/posture_loader.py``.The endpoint deliberately accepts an optional ``snapshot_b64`` query param(base64-encoded JSON) so an analyst can dry-run the resolver against a@@ -181,6 +192,15 @@ async def get_effective_permissions(snapshot=snapshot,)except NotImplementedError as exc:+ # Kept as a guard, not as a documented behaviour. Every registered+ # resolver is implemented, so reaching this means a new provider was+ # added to SUPPORTED_PROVIDERS without one — which should surface+ # loudly rather than as an empty result the UI renders as "no access".+ logger.error(+ "effective_permissions.resolver_not_implemented provider=%s err=%s",+ str(provider).replace("\r", "").replace("\n", " ")[:64],+ str(exc).replace("\r", "").replace("\n", " ")[:200],+ )raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED,detail={diff --git a/services/api/app/api/v1/endpoints/email_approval.py b/services/api/app/api/v1/endpoints/email_approval.pynew file mode 100644index 000000000..7f403089c--- /dev/null+++ b/services/api/app/api/v1/endpoints/email_approval.py@@ -0,0 +1,210 @@+"""Consume the signed email-approval links (T3.6).++`app/services/email_approval.py` shipped the issuer and the verifier and+pointed its URLs at ``/v1/actions/email-decide`` — a path that existed nowhere+in the tree. Every approve and deny button in a rendered approval email linked+to a 404, so the documented fallback for "Slack and Teams are unreachable" did+not work at the moment it was needed.++Three properties this route has to hold, none of which come for free from a+signed URL:++**The click carries an identity.** A bare signed link is a bearer credential:+whoever holds it approves, and the approval reaches the actions service with no+principal, so the permission tier and separation of duties are skipped. The+recipient address is signed into the token and forwarded as the approver, which+means an email approver must be mapped in ``AISOC_CHATOPS_APPROVERS`` under+``email`` exactly like a Slack or Teams one.++**A link works once.** Single-use falls out of the action's own state machine+rather than needing a nonce table: the actions service only accepts an approval+while the action is ``awaiting_approval``, so a replayed link gets a 400. That+is enough for approve. It is *not* enough to stop a forwarded link being+clicked by the wrong person, which is why identity is signed in rather than+inferred from the click.++**A failure says which failure.** An expired link, a tampered link and an+already-decided action are three different operator problems, and a generic+"invalid" page sends people looking at the signing key when the answer is that+somebody already approved it twenty minutes ago.+"""++from __future__ import annotations++import os++import httpx+import structlog+from fastapi import APIRouter, Query+from fastapi.responses import HTMLResponse++from app.services.email_approval import EmailApprovalError, verify_token++logger = structlog.get_logger(__name__)++router = APIRouter(prefix="/actions", tags=["actions"])++#: Matches the default in the actions service's own compose/Helm wiring.+_DEFAULT_ACTIONS_BASE_URL = "http://aisoc-actions:8085"+++def _actions_base_url() -> str:+ return os.environ.get("AISOC_ACTIONS_BASE_URL", _DEFAULT_ACTIONS_BASE_URL).rstrip("/")+++def _signing_secret() -> str:+ return os.environ.get("AISOC_EMAIL_APPROVAL_SECRET", "").strip()+++def _page(title: str, body: str, *, status_code: int) -> HTMLResponse:+ """Render a minimal self-contained result page.++ No external assets: this is opened from a mail client, often on a phone,+ frequently on a network that cannot reach a CDN.+ """+ safe_title = title.replace("<", "<").replace(">", ">")+ safe_body = body.replace("<", "<").replace(">", ">")+ html = (+ "<!doctype html><html lang='en'><head><meta charset='utf-8'>"+ "<meta name='viewport' content='width=device-width,initial-scale=1'>"+ f"<title>{safe_title}</title></head>"+ '<body style="font-family:Arial,Helvetica,sans-serif;max-width:34rem;'+ 'margin:3rem auto;padding:0 1rem;line-height:1.5">'+ f"<h1 style='font-size:1.25rem'>{safe_title}</h1>"+ f"<p>{safe_body}</p>"+ "</body></html>"+ )+ return HTMLResponse(content=html, status_code=status_code)++[email protected]("/email-decide", response_class=HTMLResponse)+async def email_decide(token: str = Query(..., description="Signed approval token")) -> HTMLResponse:+ """Verify a signed approval link and forward the decision.++ Unauthenticated by necessity — the recipient is reading email, not holding+ a session — so the token *is* the credential and every check that would+ otherwise come from a session has to come from the signature.+ """+ secret = _signing_secret()+ if not secret:+ # Fail closed and say so. Accepting tokens with an empty secret would+ # accept every token.+ logger.error("email_approval.no_secret_configured")+ return _page(+ "Email approvals are not configured",+ "AISOC_EMAIL_APPROVAL_SECRET is unset on the API service, so this "+ "link cannot be verified. Approve from the console or from Slack "+ "instead.",+ status_code=503,+ )++ try:+ parsed = verify_token(token, secret=secret)+ except EmailApprovalError as exc:+ reason = str(exc)+ logger.warning("email_approval.token_rejected", reason=reason)+ expired = "expired" in reason+ if expired:+ body = "Approval links are valid for one hour. Ask for a fresh one, or approve from the console."+ else:+ body = (+ f"The link could not be verified ({reason}). If you received it "+ "forwarded from someone else, that is why — links are bound to "+ "their recipient."+ )+ return _page(+ "This approval link has expired" if expired else "This approval link is not valid",+ body,+ status_code=410 if expired else 400,+ )++ if not parsed.approver:+ # A token minted before approver binding, or by a caller that skipped+ # it. Refused rather than forwarded: the actions service would have to+ # authorize nobody, which is the hole this route exists to avoid.+ logger.warning("email_approval.token_without_approver", action_id=parsed.action_id)+ return _page(+ "This approval link is missing its recipient",+ "The link does not identify who it was sent to, so the decision cannot be attributed. Approve from the console instead.",+ status_code=400,+ )++ verb = "approve" if parsed.decision == "approved" else "reject"+ payload = {+ "chatops_approver": {+ "platform": "email",+ "platform_user_id": parsed.approver,+ }+ }+ headers = {"Accept": "application/json"}+ service_token = os.environ.get("AISOC_ACTIONS_SERVICE_TOKEN", "").strip()+ if service_token:+ headers["Authorization"] = f"Bearer {service_token}"++ url = f"{_actions_base_url()}/api/v1/actions/{parsed.action_id}/{verb}"+ try:+ async with httpx.AsyncClient(timeout=15.0) as client:+ response = await client.post(url, json=payload, headers=headers)+ except httpx.HTTPError as exc:+ logger.warning("email_approval.upstream_unreachable", action_id=parsed.action_id, error=str(exc))+ return _page(+ "The action service could not be reached",+ "Your decision was not recorded. Try again, or use the console.",+ status_code=502,+ )++ if response.status_code == 400:+ return _page(+ "This action was already decided",+ "Somebody has already approved or rejected it, so this link no longer applies. Approval links work once.",+ status_code=409,+ )+ if response.status_code == 403:+ detail = _detail(response)+ logger.warning(+ "email_approval.not_authorized",+ action_id=parsed.action_id,+ approver=parsed.approver,+ detail=detail,+ )+ return _page(+ "You are not authorised to decide this action",+ f"{detail} An email approver must be mapped under 'email' in "+ "AISOC_CHATOPS_APPROVERS, and may not approve an action they "+ "requested themselves.",+ status_code=403,+ )+ if response.status_code == 404:+ return _page("Action not found", "It may have been removed since the email was sent.", status_code=404)+ if response.status_code >= 400:+ logger.warning(+ "email_approval.upstream_error",+ action_id=parsed.action_id,+ status=response.status_code,+ )+ return _page(+ "Your decision could not be recorded",+ f"The action service returned {response.status_code}. Try the console instead.",+ status_code=502,+ )++ logger.info(+ "email_approval.recorded",+ action_id=parsed.action_id,+ decision=parsed.decision,+ approver=parsed.approver,+ )+ return _page(+ "Action approved" if parsed.decision == "approved" else "Action rejected",+ f"Recorded as {parsed.approver}. You can close this page.",+ status_code=200,+ )+++def _detail(response: httpx.Response) -> str:+ try:+ body = response.json()+ except ValueError:+ return "The action service refused the decision."+ detail = body.get("detail") if isinstance(body, dict) else None+ return str(detail) if detail else "The action service refused the decision."diff --git a/services/api/app/api/v1/endpoints/hunts.py b/services/api/app/api/v1/endpoints/hunts.pyindex b1e19e7b2..69d561fcb 100644--- a/services/api/app/api/v1/endpoints/hunts.py+++ b/services/api/app/api/v1/endpoints/hunts.py@@ -38,6 +38,7 @@ from sqlalchemy import textfrom app.api.v1.deps import AuthUser, DBSessionfrom app.core.airgap import AirgapViolation, enforce_airgap_for_url+from app.services.llm_safety import LLMContractViolation, safe_chat_completions_requestfrom app.services.model_aliases import resolve_model_aliaslogger = logging.getLogger(__name__)@@ -148,22 +149,22 @@ async def _generate_queries(hypothesis: str, mitre: str | None) -> dict[str, strcompletions_url = f"{base_url}/chat/completions"enforce_airgap_for_url(completions_url)try:- async with httpx.AsyncClient(timeout=45) as client:- resp = await client.post(- completions_url,- headers={"Authorization": f"Bearer {api_key}"},- json={- "model": model,- "messages": [- {"role": "system", "content": _HUNT_SYSTEM},- {"role": "user", "content": user_msg},- ],- "temperature": 0.2,- "response_format": {"type": "json_object"},- },- )- resp.raise_for_status()- return json.loads(resp.json()["choices"][0]["message"]["content"])+ body = await safe_chat_completions_request( # T2.3+ api_key=api_key,+ model=model,+ messages=[+ {"role": "system", "content": _HUNT_SYSTEM},+ {"role": "user", "content": user_msg},+ ],+ url=completions_url,+ timeout=45.0,+ temperature=0.2,+ response_format={"type": "json_object"},+ )+ return json.loads(body["choices"][0]["message"]["content"])+ except LLMContractViolation as exc:+ logger.warning("hunts.llm_contract_violation", reason=exc.reason)+ return Noneexcept Exception:return Nonediff --git a/services/api/app/api/v1/endpoints/knowledge_base.py b/services/api/app/api/v1/endpoints/knowledge_base.pyindex c1c5a5001..8c6b8d319 100644--- a/services/api/app/api/v1/endpoints/knowledge_base.py+++ b/services/api/app/api/v1/endpoints/knowledge_base.py@@ -21,7 +21,6 @@ import uuidfrom datetime import UTC, datetimefrom typing import Any, Literal-import httpxfrom fastapi import APIRouter, HTTPException, statusfrom pydantic import BaseModel, Fieldfrom sqlalchemy import text@@ -29,6 +28,7 @@ from sqlalchemy import textfrom app.api.v1.deps import AuthUser, DBSessionfrom app.core.airgap import AirgapViolation, enforce_airgap_for_urlfrom app.services.kb_chunking import chunk_text+from app.services.llm_safety import LLMContractViolation, safe_chat_completions_requestfrom app.services.model_aliases import resolve_model_aliaslogger = logging.getLogger(__name__)@@ -121,21 +121,23 @@ async def _synthesise(question: str, chunks: list[KBChunk]) -> str | None:completions_url = f"{base_url}/chat/completions"enforce_airgap_for_url(completions_url)try:- async with httpx.AsyncClient(timeout=45) as client:- resp = await client.post(- completions_url,- headers={"Authorization": f"Bearer {api_key}"},- json={- "model": model,- "messages": [- {"role": "system", "content": _SYNTH_SYSTEM},- {"role": "user", "content": f"CONTEXT:\n{context}\n\nQUESTION: {question}"},- ],- "temperature": 0.2,- },- )- resp.raise_for_status()- return resp.json()["choices"][0]["message"]["content"].strip()+ # T2.3 — the retrieved KB chunks are the untrusted half here: a+ # document ingested from a vendor advisory can carry a log excerpt.+ body = await safe_chat_completions_request(+ api_key=api_key,+ model=model,+ messages=[+ {"role": "system", "content": _SYNTH_SYSTEM},+ {"role": "user", "content": f"CONTEXT:\n{context}\n\nQUESTION: {question}"},+ ],+ url=completions_url,+ timeout=45.0,+ temperature=0.2,+ )+ return str(body["choices"][0]["message"]["content"]).strip()+ except LLMContractViolation as exc:+ logger.warning("knowledge_base.llm_contract_violation", reason=exc.reason)+ return Noneexcept Exception:return Nonediff --git a/services/api/app/api/v1/endpoints/nl_detection.py b/services/api/app/api/v1/endpoints/nl_detection.pyindex 0e240c897..6540102cb 100644--- a/services/api/app/api/v1/endpoints/nl_detection.py+++ b/services/api/app/api/v1/endpoints/nl_detection.py@@ -13,6 +13,7 @@ functional in all deployment environments.from __future__ import annotations+import jsonimport osimport uuidfrom datetime import UTC, datetime@@ -27,6 +28,7 @@ from app.core.airgap import AirgapViolation, enforce_airgap_for_urlfrom app.models.detection_proposal import DetectionRuleProposalfrom app.services.detection_eval import evaluate_candidate_rulefrom app.services.fixture_synth import derive_fixtures_from_sigma+from app.services.llm_safety import LLMContractViolation, safe_chat_completions_requestlogger = structlog.get_logger()@@ -141,36 +143,35 @@ async def _llm_translate(request: NLDetectionRequest) -> dict[str, str | None]:logger.info("nl_detection.airgap_block", url=completions_url, reason=str(exc))return _template_fallback(request)+ model = os.environ.get("OPENAI_MODEL", "gpt-4o-mini")try:- import httpx-- async with httpx.AsyncClient(timeout=30.0) as client:- resp = await client.post(- completions_url,- headers={"Authorization": f"Bearer {api_key}"},- json={- "model": os.environ.get("OPENAI_MODEL", "gpt-4o-mini"),- "messages": [- {"role": "system", "content": _SYSTEM_PROMPT},- {"role": "user", "content": user_prompt},- ],- "response_format": {"type": "json_object"},- "temperature": 0.1,- "max_tokens": 2000,- },- )- resp.raise_for_status()- import json-- content = resp.json()["choices"][0]["message"]["content"]- rules = json.loads(content)- return {- "sigma": rules.get("sigma") if "sigma" in request.target_platforms else None,- "kql": rules.get("kql") if "kql" in request.target_platforms else None,- "spl": rules.get("spl") if "spl" in request.target_platforms else None,- "esql": rules.get("esql") if "esql" in request.target_platforms else None,- "_model": os.environ.get("OPENAI_MODEL", "gpt-4o-mini"),- }+ # T2.3 — the description is analyst-authored but routinely contains a+ # pasted log line, which is exactly what the contract refuses to+ # forward.+ body = await safe_chat_completions_request(+ api_key=api_key,+ model=model,+ messages=[+ {"role": "system", "content": _SYSTEM_PROMPT},+ {"role": "user", "content": user_prompt},+ ],+ url=completions_url,+ timeout=30.0,+ response_format={"type": "json_object"},+ temperature=0.1,+ max_tokens=2000,+ )+ rules = json.loads(body["choices"][0]["message"]["content"])+ return {+ "sigma": rules.get("sigma") if "sigma" in request.target_platforms else None,+ "kql": rules.get("kql") if "kql" in request.target_platforms else None,+ "spl": rules.get("spl") if "spl" in request.target_platforms else None,+ "esql": rules.get("esql") if "esql" in request.target_platforms else None,+ "_model": model,+ }+ except LLMContractViolation as exc:+ logger.warning("nl_detection.llm_contract_violation", reason=exc.reason)+ return _template_fallback(request)except Exception as exc:logger.warning("nl_detection.llm_error", error=str(exc))return _template_fallback(request)diff --git a/services/api/app/api/v1/endpoints/phishing.py b/services/api/app/api/v1/endpoints/phishing.pyindex 4705c39f1..994c045c1 100644--- a/services/api/app/api/v1/endpoints/phishing.py+++ b/services/api/app/api/v1/endpoints/phishing.py@@ -21,13 +21,13 @@ import uuidfrom datetime import UTC, datetimefrom typing import Any, Literal-import httpxfrom fastapi import APIRouter, HTTPException, Query, statusfrom pydantic import BaseModel, Fieldfrom sqlalchemy import textfrom app.api.v1.deps import AuthUser, DBSessionfrom app.core.airgap import AirgapViolation, enforce_airgap_for_url+from app.services.llm_safety import LLMContractViolation, safe_chat_completions_requestfrom app.services.model_aliases import resolve_model_aliaslogger = logging.getLogger(__name__)@@ -104,22 +104,23 @@ async def _triage(artifact_kind: str, content: str, urls: list[str]) -> TriageRe# AirgapViolation propagates to the caller so the endpoint can surface 503.enforce_airgap_for_url(completions_url)try:- async with httpx.AsyncClient(timeout=45) as client:- resp = await client.post(- completions_url,- headers={"Authorization": f"Bearer {api_key}"},- json={- "model": model,- "messages": [- {"role": "system", "content": _SYSTEM},- {"role": "user", "content": user_msg},- ],- "temperature": 0.1,- "response_format": {"type": "json_object"},- },- )- resp.raise_for_status()- data = json.loads(resp.json()["choices"][0]["message"]["content"])+ # T2.3 — the contract runs before the request. This body is a+ # submitted email, so it is attacker-authored by definition and is+ # the single most likely place in the product to ship a raw log or a+ # secret to a third party.+ body = await safe_chat_completions_request(+ api_key=api_key,+ model=model,+ messages=[+ {"role": "system", "content": _SYSTEM},+ {"role": "user", "content": user_msg},+ ],+ url=completions_url,+ timeout=45.0,+ temperature=0.1,+ response_format={"type": "json_object"},+ )+ data = json.loads(body["choices"][0]["message"]["content"])return TriageResult(verdict=data.get("verdict", "unknown"),confidence=float(data.get("confidence", 0.5)),@@ -127,6 +128,12 @@ async def _triage(artifact_kind: str, content: str, urls: list[str]) -> TriageRemitre_technique=data.get("mitre_technique"),summary=data.get("summary", ""),)+ except LLMContractViolation as exc:+ # Degrading to heuristic triage is the right outcome, but it must be+ # visible: this `except` used to swallow everything, so a refused+ # prompt was indistinguishable from a missing API key.+ logger.warning("phishing.llm_contract_violation", reason=exc.reason)+ return Noneexcept Exception:return Nonediff --git a/services/api/app/api/v1/endpoints/translation.py b/services/api/app/api/v1/endpoints/translation.pyindex 066b7b2ff..8fb08651a 100644--- a/services/api/app/api/v1/endpoints/translation.py+++ b/services/api/app/api/v1/endpoints/translation.py@@ -14,16 +14,19 @@ Endpointsfrom __future__ import annotationsimport json+import loggingimport osfrom typing import Any, Literal-import httpxfrom fastapi import APIRouter, HTTPException, statusfrom pydantic import BaseModel, Fieldfrom app.core.airgap import AirgapViolation, enforce_airgap_for_url+from app.services.llm_safety import LLMContractViolation, safe_chat_completions_requestfrom app.services.model_aliases import resolve_model_alias+logger = logging.getLogger(__name__)+router = APIRouter(prefix="/translation", tags=["translation"])# ────────────────────────────────────────────────────────────────────────────@@ -122,23 +125,25 @@ async def _llm_translate(req: TranslateRequest) -> dict[str, Any] | None:except AirgapViolation:raisetry:- async with httpx.AsyncClient(timeout=60) as client:- resp = await client.post(- completions_url,- headers={"Authorization": f"Bearer {api_key}"},- json={- "model": model,- "messages": [- {"role": "system", "content": _SYSTEM},- {"role": "user", "content": _user_prompt(req)},- ],- "temperature": 0.1,- "response_format": {"type": "json_object"},- },- )- resp.raise_for_status()- content = resp.json()["choices"][0]["message"]["content"]- return json.loads(content)+ # T2.3 — the contract runs before the request, so a vendor rule+ # pasted in with a raw log sample attached is refused rather than+ # forwarded.+ body = await safe_chat_completions_request(+ api_key=api_key,+ model=model,+ messages=[+ {"role": "system", "content": _SYSTEM},+ {"role": "user", "content": _user_prompt(req)},+ ],+ url=completions_url,+ timeout=60.0,+ temperature=0.1,+ response_format={"type": "json_object"},+ )+ return json.loads(body["choices"][0]["message"]["content"])+ except LLMContractViolation as exc:+ logger.warning("translation.llm_contract_violation", reason=exc.reason)+ return Noneexcept Exception:return Nonediff --git a/services/api/app/api/v1/router.py b/services/api/app/api/v1/router.pyindex 752d4946d..0b3465477 100644--- a/services/api/app/api/v1/router.py+++ b/services/api/app/api/v1/router.py@@ -28,6 +28,7 @@ from app.api.v1.endpoints import (detection_rules,easm,effective_permissions,+ email_approval,federated,feedback,fusion,@@ -147,6 +148,13 @@ api_router.include_router(replay.public_router)# edges in Neo4j. Backs apps/web/src/app/(app)/identity/permissions.api_router.include_router(effective_permissions.router)+# Signed email-approval links (T3.6). Unauthenticated by necessity — the+# recipient is in a mail client, not a session — so the HMAC token is the+# credential. `app/services/email_approval.py` had minted URLs pointing at+# /v1/actions/email-decide, which no router served, so every approve and deny+# button in a rendered email linked to a 404.+api_router.include_router(email_approval.router)+# Cost dashboard — WS-H1 (buyer-value plan).# Aggregates LLM spend / token volume from aisoc_run_costs joined with# investigation_runs, plus action counts from audit_log and BYOK savingsdiff --git a/services/api/app/services/alert_explain.py b/services/api/app/services/alert_explain.pyindex c5f9203e6..74e60cfbe 100644--- a/services/api/app/services/alert_explain.py+++ b/services/api/app/services/alert_explain.py@@ -51,7 +51,6 @@ from dataclasses import dataclassfrom datetime import UTC, datetime, timedeltafrom typing import Any-import httpxfrom sqlalchemy import and_, func, selectfrom sqlalchemy.ext.asyncio import AsyncSession@@ -60,6 +59,7 @@ from app.models.alert import Alertfrom app.models.detection_rule import DetectionRulefrom app.services.cost_dashboard import _impute_public_costfrom app.services.llm_resolver import LlmConfig, resolve_llm_config+from app.services.llm_safety import LLMContractViolation, safe_chat_completions_requestlogger = logging.getLogger(__name__)@@ -753,14 +753,29 @@ async def _call_llm_for_summary()try:- async with httpx.AsyncClient(timeout=20) as client:- resp = await client.post(- url,- headers={"Authorization": f"Bearer {llm_config.api_key}"},- json={"model": llm_config.model, "messages": messages, "max_tokens": 360},- )- resp.raise_for_status()- payload = resp.json()+ # T2.3 — the contract runs before the request. The user message is a+ # JSON dump of the alert, so this is the API's most direct path for+ # raw event data to reach a third party.+ payload = await safe_chat_completions_request(+ api_key=llm_config.api_key,+ model=llm_config.model,+ messages=messages,+ url=url,+ timeout=20.0,+ max_tokens=360,+ )+ except LLMContractViolation as exc:+ # Reported as its own error string rather than folded into the+ # generic branch, so an operator can tell "we refused to send this"+ # apart from "the provider was unreachable".+ return _LlmCallResult(+ text=None,+ model=llm_config.model,+ prompt_tokens=0,+ completion_tokens=0,+ latency_ms=(time.monotonic() - started) * 1000.0,+ error=f"llm_contract_violation: {exc.reason}",+ )except Exception as exc: # noqa: BLE001return _LlmCallResult(text=None,diff --git a/services/api/app/services/effective_permissions/service.py b/services/api/app/services/effective_permissions/service.pyindex a478d6fb3..0be16eb2e 100644--- a/services/api/app/services/effective_permissions/service.py+++ b/services/api/app/services/effective_permissions/service.py@@ -113,8 +113,11 @@ def resolve_effective_permissions(the API endpoint after the result is built — keeping this functionpure makes it trivial to unit-test.* Either ``snapshot`` or ``snapshot_loader`` must produce a non-empty- dict for full providers; scaffolds raise ``NotImplementedError``- regardless.+ dict. Every registered resolver reports ``coverage: "full"``; there are+ no scaffolds left, which this line claimed for several releases after+ they were implemented. A provider registered without a resolver raises+ ``NotImplementedError``, which the endpoint logs at ``error`` rather+ than treating as an expected state."""resolver_cls = SUPPORTED_PROVIDERS.get(provider)diff --git a/services/api/app/services/email_approval.py b/services/api/app/services/email_approval.pyindex c79083dc0..67e728931 100644--- a/services/api/app/services/email_approval.py+++ b/services/api/app/services/email_approval.py@@ -28,10 +28,18 @@ Design notesalongside the rest of the payload so an attacker can't extend itclient-side.-The endpoint that consumes these tokens (``GET /v1/actions/email-decide``-or similar) is wired in a follow-up — this module ships the *issuer*-side plus the verifier, so any web route can adopt it with three lines-of glue.+* **The approver is signed into the token.** Without that a signed URL+ is a bearer credential: anyone holding the link approves, and the+ resulting approval carries no identity for the actions service to+ authorize — the same hole the ChatOps path had. The recipient address+ travels inside the signature, and+ ``app/api/v1/endpoints/email_approval.py`` forwards it as the+ approver so the permission tier and separation of duties apply.++The consuming endpoint is ``GET /api/v1/actions/email-decide``. It did+not exist for several releases while ``approval_url`` defaulted to+``/v1/actions/email-decide``, a path present nowhere else in the tree,+so every rendered approve and deny button linked to a 404."""from __future__ import annotations@@ -71,6 +79,11 @@ class ApprovalToken:action_id: strcase_id: strexpires_at: int+ #: The recipient the link was minted for. Signed, so the click carries an+ #: identity the actions service can authorize — without it a signed URL is+ #: a bearer credential that approves as nobody, which is the same hole the+ #: ChatOps path had.+ approver: str = ""@propertydef is_expired(self) -> bool:@@ -86,8 +99,13 @@ def _b64url_decode(token: str) -> bytes:return base64.urlsafe_b64decode(token + pad)-def _canonical_payload(decision: str, action_id: str, case_id: str, expires_at: int) -> str:- return f"{decision}|{action_id}|{case_id}|{int(expires_at)}"+def _canonical_payload(decision: str, action_id: str, case_id: str, expires_at: int, approver: str = "") -> str:+ # The approver is appended rather than inserted so a token minted before+ # approver binding still verifies (it signs the empty string). The+ # endpoint refuses such a token anyway, because an approval needs an+ # identity — but it should fail as "no approver" rather than as a+ # signature mismatch, which would send an operator hunting a key problem.+ return f"{decision}|{action_id}|{case_id}|{int(expires_at)}|{approver}"def _hmac_hex(payload: str, *, secret: str) -> str:@@ -100,6 +118,7 @@ def issue_token(action_id: str,case_id: str,secret: str,+ approver: str = "",ttl_seconds: int = DEFAULT_TTL_SECONDS,now: float | None = None,) -> str:@@ -109,6 +128,11 @@ def issue_token(``decision`` must be ``"approved"`` or ``"rejected"`` so the emailtemplate generates one URL per choice and the recipient's click isself-describing.++ ``approver`` is the recipient address the link is minted for. It is signed+ into the token so a click carries an identity the actions service can+ authorize against; a token without one is a bearer credential that+ approves as nobody."""if decision not in {"approved", "rejected"}:raise EmailApprovalError(f"unsupported decision {decision!r}")@@ -119,7 +143,7 @@ def issue_token(issued = float(now if now is not None else time.time())expires_at = int(issued + max(60, int(ttl_seconds)))- canonical = _canonical_payload(decision, action_id, case_id, expires_at)+ canonical = _canonical_payload(decision, action_id, case_id, expires_at, approver)signature = _hmac_hex(canonical, secret=secret)envelope = json.dumps({@@ -127,6 +151,7 @@ def issue_token("a": action_id,"c": case_id,"e": expires_at,+ "p": approver,"s": signature,},separators=(",", ":"),@@ -157,6 +182,7 @@ def verify_token(token: str, *, secret: str, now: float | None = None) -> Approvaction_id = str(envelope.get("a") or "")case_id = str(envelope.get("c") or "")expires_at_raw = envelope.get("e")+ approver = str(envelope.get("p") or "")signature = str(envelope.get("s") or "")if decision not in {"approved", "rejected"}:@@ -166,7 +192,7 @@ def verify_token(token: str, *, secret: str, now: float | None = None) -> Approvif not isinstance(expires_at_raw, int):raise EmailApprovalError("token missing expires_at")- canonical = _canonical_payload(decision, action_id, case_id, int(expires_at_raw))+ canonical = _canonical_payload(decision, action_id, case_id, int(expires_at_raw), approver)expected = _hmac_hex(canonical, secret=secret)if not hmac.compare_digest(expected, signature):raise EmailApprovalError("signature mismatch")@@ -180,26 +206,34 @@ def verify_token(token: str, *, secret: str, now: float | None = None) -> Approvaction_id=action_id,case_id=case_id,expires_at=int(expires_at_raw),+ approver=approver,)def approval_url(*,base_url: str,- endpoint_path: str = "/v1/actions/email-decide",+ endpoint_path: str = "/api/v1/actions/email-decide",decision: str,action_id: str,case_id: str,secret: str,+ approver: str = "",ttl_seconds: int = DEFAULT_TTL_SECONDS,now: float | None = None,) -> str:- """Build the full signed URL embedded in the approval email."""+ """Build the full signed URL embedded in the approval email.++ The default path is the route that exists. It previously defaulted to+ ``/v1/actions/email-decide``, which appeared nowhere else in the tree — so+ every approve and deny button in a rendered email linked to a 404.+ """token = issue_token(decision=decision,action_id=action_id,case_id=case_id,secret=secret,+ approver=approver,ttl_seconds=ttl_seconds,now=now,)diff --git a/services/api/app/services/llm_safety.py b/services/api/app/services/llm_safety.pynew file mode 100644index 000000000..68c73493a--- /dev/null+++ b/services/api/app/services/llm_safety.py@@ -0,0 +1,108 @@+"""Fail-closed LLM input contract for ``services/api`` (T2.3).++Seven endpoints in this service POSTed untrusted input straight to a+chat-completions API with no contract of any kind:++* ``phishing.py`` — a submitted email body. Attacker-authored by definition.+* ``translation.py`` — a vendor rule pasted into a fenced block.+* ``knowledge_base.py`` — retrieved KB chunks plus the question.+* ``hunts.py`` — an analyst hypothesis.+* ``nl_detection.py`` — a detection description.+* ``detection_loop.py`` — ``alert_fields``, i.e. raw alert data.+* ``services/alert_explain.py`` — alert title, description and tags.++``services/agents`` has had a fail-closed contract since T2.3 landed there, and+the module this file replaces was described in the repo's own notes as already+existing here. It did not: ``services/api/app/services/llm_safety.py`` was+absent from the tree, so the API half of the same contract was never written.++The classifier is the *same* one the agents service runs, vendored at+``app/_vendor/llm_contract_rules.py`` and kept byte-identical by+``scripts/sync_vendored_llm_contract.py --check``. Two heuristics that disagreed+about what counts as a raw log would be worse than one, because a prompt+rejected in one service and accepted in the other reads as a bug in the+rejection.++What this is and is not+=======================++It is a **minimum-leak** control: it aborts a call that is about to ship raw+OCSF, vendor log lines, Sysmon XML or secret-shaped values to a third party. It+is **not** an injection sanitizer — that is `PromptInjectionGuard` in the agents+service, which detects and demotes rather than refusing.++Enforcement follows the agents service's flag+(``AISOC_AGENTS_LLM_CONTRACT_ENFORCED``, default on) so one setting governs both+halves. Disabling it in one service only would leave a contract that holds on+whichever path the traffic did not take.+"""++from __future__ import annotations++from collections.abc import Iterable+from typing import Any++import httpx+import structlog++from app._vendor.llm_contract_rules import (+ LLMContractViolation,+ LLMInputContract,+ classify_message,+ is_contract_enforced,+ validate_messages,+)++logger = structlog.get_logger(__name__)++__all__ = [+ "LLMContractViolation",+ "LLMInputContract",+ "classify_message",+ "is_contract_enforced",+ "safe_chat_completions_request",+ "validate_messages",+]++DEFAULT_COMPLETIONS_URL = "https://api.openai.com/v1/chat/completions"+++async def safe_chat_completions_request(+ *,+ api_key: str,+ model: str,+ messages: Iterable[Any],+ url: str = DEFAULT_COMPLETIONS_URL,+ timeout: float = 30.0,+ extra_headers: dict[str, str] | None = None,+ client: httpx.AsyncClient | None = None,+ **extra_body: Any,+) -> dict[str, Any]:+ """Validate ``messages``, then POST them to a chat-completions endpoint.++ Raises :class:`LLMContractViolation` **before** the network call, so a+ prompt that breaches the contract never reaches the provider. That ordering+ is the whole point: a check that runs after the request is a log line, not+ a control.++ Mirrors the signature of the agents service's function of the same name so+ a call site can move between services without rewriting. ``client`` is+ accepted so callers that already hold a pooled ``AsyncClient`` — and tests+ — do not each construct one.+ """+ validated = LLMInputContract.validate(messages)++ headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}+ if extra_headers:+ headers.update(extra_headers)+ payload: dict[str, Any] = {"model": model, "messages": validated, **extra_body}++ if client is not None:+ response = await client.post(url, headers=headers, json=payload, timeout=timeout)+ response.raise_for_status()+ return dict(response.json())++ async with httpx.AsyncClient(timeout=timeout) as owned:+ response = await owned.post(url, headers=headers, json=payload)+ response.raise_for_status()+ return dict(response.json())diff --git a/services/api/app/services/model_aliases.py b/services/api/app/services/model_aliases.pyindex 94983cde8..9893a09e1 100644--- a/services/api/app/services/model_aliases.py+++ b/services/api/app/services/model_aliases.py@@ -20,7 +20,37 @@ import osROLES = frozenset({"triage", "recon", "investigation", "copilot", "summary", "report", "nl"})+DEFAULT_OPENAI_CHAT_COMPLETIONS_URL = "https://api.openai.com/v1/chat/completions"++def resolve_model_alias(role: str) -> str:"""Return the ``aisoc-<role>`` alias, honouring an ``AISOC_MODEL_PIN_<ROLE>`` override."""override = os.environ.get(f"AISOC_MODEL_PIN_{role.upper()}", "").strip()return override or f"aisoc-{role}"+++def resolve_base_url() -> str | None:+ """OpenAI-compatible base URL for live calls, or ``None`` for the default.++ Mirrors :func:`services.agents.app.llm.factory.resolve_base_url`, including+ its deliberate refusal to auto-adopt ``LLM_GATEWAY_URL``: routing through+ the gateway is an explicit choice so it is never ambiguous whether the+ bearer token is the gateway master key or a provider key.+ """+ return os.environ.get("OPENAI_BASE_URL", "").strip() or os.environ.get("LLM_BASE_URL", "").strip() or None+++def chat_completions_url() -> str:+ """Full chat-completions URL for the raw-HTTP path.++ Exists so the NL-query translator — one file vendored into both services —+ can resolve the same two helpers from either package. Its LLM path used to+ import ``app.llm.factory``, which does not exist in the API process, and+ the resulting ``ImportError`` was swallowed by a broad ``except``. So+ ``/nl-query`` silently never reached a model and always returned the+ deterministic translation: safe by accident, and invisible.+ """+ base = resolve_base_url()+ if base:+ return base.rstrip("/") + "/chat/completions"+ return DEFAULT_OPENAI_CHAT_COMPLETIONS_URLdiff --git a/services/api/tests/test_email_approval_endpoint.py b/services/api/tests/test_email_approval_endpoint.pynew file mode 100644index 000000000..c0f482e80--- /dev/null+++ b/services/api/tests/test_email_approval_endpoint.py@@ -0,0 +1,214 @@+"""The signed email-approval link must resolve, and must carry an identity.++`app/services/email_approval.py` shipped a complete issuer and verifier whose+URLs pointed at ``/v1/actions/email-decide`` — a path that appeared nowhere+else in the tree. Every approve and deny button in a rendered approval email+linked to a 404, so the documented fallback for "Slack and Teams are+unreachable" failed exactly when it was needed.++The token also signed only decision, action and case. A link with no recipient+in it is a bearer credential: whoever holds it approves, and the approval+reaches the actions service with no principal, so the permission tier and+separation of duties are skipped — the same hole the ChatOps path had.+"""++from __future__ import annotations++import base64+import json++import httpx+import pytest+from app.api.v1.endpoints import email_approval as endpoint+from app.services.email_approval import EmailApprovalError, approval_url, issue_token, verify_token+from fastapi import FastAPI+from fastapi.testclient import TestClient++SECRET = "test-signing-secret"+++def client(monkeypatch: pytest.MonkeyPatch) -> TestClient:+ monkeypatch.setenv("AISOC_EMAIL_APPROVAL_SECRET", SECRET)+ app = FastAPI()+ app.include_router(endpoint.router, prefix="/api/v1")+ return TestClient(app)+++def _token(**kwargs) -> str:+ params = {+ "decision": "approved",+ "action_id": "act-1",+ "case_id": "case-1",+ "secret": SECRET,+ "approver": "[email protected]",+ }+ params.update(kwargs)+ return issue_token(**params)+++class _StubResponse:+ def __init__(self, status_code: int, payload: dict | None = None) -> None:+ self.status_code = status_code+ self._payload = payload or {}++ def json(self) -> dict:+ return self._payload+++def _stub_post(monkeypatch: pytest.MonkeyPatch, response: _StubResponse, recorder: list | None = None):+ class _Client:+ async def __aenter__(self):+ return self++ async def __aexit__(self, *exc):+ return False++ async def post(self, url, json=None, headers=None):+ if recorder is not None:+ recorder.append({"url": url, "json": json, "headers": headers})+ return response++ monkeypatch.setattr(endpoint.httpx, "AsyncClient", lambda **_: _Client())+++# ── the route exists at the path the emails link to ────────────────────────+++def test_the_url_the_issuer_mints_is_the_url_the_router_serves(client: TestClient) -> None:+ """The regression. The default used to be /v1/actions/email-decide, a path+ no router served, so every button in a rendered email 404'd."""+ url = approval_url(+ base_url="https://console.example",+ decision="approved",+ action_id="act-1",+ case_id="case-1",+ secret=SECRET,+ approver="[email protected]",+ )+ path = url.split("https://console.example", 1)[1].split("?", 1)[0]+ assert path == "/api/v1/actions/email-decide"++ # Asserted by requesting it rather than by inspecting `app.routes`: a+ # route table can list a path that the mounted prefix does not actually+ # serve, and a 404 here is precisely the bug. Any status other than 404+ # means the path resolves — the token is deliberately absent, so a 422+ # for the missing required query parameter is the expected answer.+ assert client.get(path).status_code != 404+++# ── the approver is signed in ──────────────────────────────────────────────+++def test_the_recipient_is_signed_into_the_token() -> None:+ parsed = verify_token(_token(), secret=SECRET)+ assert parsed.approver == "[email protected]"+++def test_swapping_the_recipient_breaks_the_signature() -> None:+ """Otherwise a forwarded link could be re-pointed at the forwarder."""+ raw = json.loads(base64.urlsafe_b64decode(_token() + "=="))+ raw["p"] = "[email protected]"+ tampered = base64.urlsafe_b64encode(json.dumps(raw, separators=(",", ":"), sort_keys=True).encode()).rstrip(b"=").decode()+ with pytest.raises(EmailApprovalError, match="signature mismatch"):+ verify_token(tampered, secret=SECRET)+++def test_the_decision_forwards_the_recipient_as_the_approver(client: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:+ calls: list[dict] = []+ _stub_post(monkeypatch, _StubResponse(200, {"status": "approved"}), calls)++ res = client.get("/api/v1/actions/email-decide", params={"token": _token()})++ assert res.status_code == 200+ assert len(calls) == 1+ assert calls[0]["url"].endswith("/api/v1/actions/act-1/approve")+ assert calls[0]["json"] == {"chatops_approver": {"platform": "email", "platform_user_id": "[email protected]"}}+++def test_a_reject_token_routes_to_the_reject_verb(client: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:+ calls: list[dict] = []+ _stub_post(monkeypatch, _StubResponse(200, {"status": "rejected"}), calls)++ res = client.get("/api/v1/actions/email-decide", params={"token": _token(decision="rejected")})++ assert res.status_code == 200+ assert calls[0]["url"].endswith("/api/v1/actions/act-1/reject")+++def test_a_token_without_a_recipient_is_refused_not_forwarded(client: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:+ """Forwarding it would make the actions service authorize nobody."""+ calls: list[dict] = []+ _stub_post(monkeypatch, _StubResponse(200), calls)++ res = client.get("/api/v1/actions/email-decide", params={"token": _token(approver="")})++ assert res.status_code == 400+ assert calls == []+ assert "missing its recipient" in res.text+++# ── failures name the right failure ────────────────────────────────────────+++def test_an_expired_link_says_expired(client: TestClient) -> None:+ stale = issue_token(+ decision="approved",+ action_id="act-1",+ case_id="case-1",+ secret=SECRET,+ approver="[email protected]",+ ttl_seconds=60,+ now=0,+ )+ res = client.get("/api/v1/actions/email-decide", params={"token": stale})+ assert res.status_code == 410+ assert "expired" in res.text.lower()+++def test_a_tampered_link_is_rejected(client: TestClient) -> None:+ res = client.get("/api/v1/actions/email-decide", params={"token": "not-a-token"})+ assert res.status_code == 400+++def test_an_already_decided_action_says_so_rather_than_failing_opaquely(client: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:+ """Single-use falls out of the action's own state machine: the actions+ service only accepts an approval while the action awaits one, so a+ replayed link gets a 400 upstream."""+ _stub_post(monkeypatch, _StubResponse(400, {"detail": "Action is not awaiting approval"}))+ res = client.get("/api/v1/actions/email-decide", params={"token": _token()})+ assert res.status_code == 409+ assert "already" in res.text.lower()+++def test_an_unauthorized_approver_is_told_why(client: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:+ _stub_post(monkeypatch, _StubResponse(403, {"detail": "email user is not mapped to an AiSOC approver."}))+ res = client.get("/api/v1/actions/email-decide", params={"token": _token()})+ assert res.status_code == 403+ assert "AISOC_CHATOPS_APPROVERS" in res.text+++def test_an_unset_secret_fails_closed(monkeypatch: pytest.MonkeyPatch) -> None:+ """Verifying against an empty secret would accept every token."""+ monkeypatch.setenv("AISOC_EMAIL_APPROVAL_SECRET", "")+ app = FastAPI()+ app.include_router(endpoint.router, prefix="/api/v1")+ res = TestClient(app).get("/api/v1/actions/email-decide", params={"token": _token()})+ assert res.status_code == 503+++def test_an_unreachable_actions_service_does_not_claim_success(client: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:+ class _Client:+ async def __aenter__(self):+ return self++ async def __aexit__(self, *exc):+ return False++ async def post(self, *a, **k):+ raise httpx.ConnectError("refused")++ monkeypatch.setattr(endpoint.httpx, "AsyncClient", lambda **_: _Client())+ res = client.get("/api/v1/actions/email-decide", params={"token": _token()})+ assert res.status_code == 502+ assert "not recorded" in res.textdiff --git a/services/api/tests/test_llm_safety.py b/services/api/tests/test_llm_safety.pynew file mode 100644index 000000000..63defab22--- /dev/null+++ b/services/api/tests/test_llm_safety.py@@ -0,0 +1,187 @@+"""The API service must have an LLM input contract, and run it before the POST.++`services/agents` has had a fail-closed contract since T2.3 landed there. The+API service had none: seven endpoints POSTed untrusted input straight to a+chat-completions provider, and the module the repo's own notes described as+living here — ``app/services/llm_safety.py`` — was simply absent from the tree.++The most direct case is ``phishing.py``, which forwards a submitted email body,+attacker-authored by definition.+"""++from __future__ import annotations++import ast+from pathlib import Path++import httpx+import pytest+from app.services.llm_safety import (+ LLMContractViolation,+ classify_message,+ safe_chat_completions_request,+)++RAW_OCSF = '{"class_uid": 2001, "activity_id": 1, "metadata": {"product": {"name": "x"}, "version": "1.0"}}'++API_APP = Path(__file__).resolve().parents[1] / "app"+++class _Recorder:+ """Records whether a request was ever issued."""++ def __init__(self) -> None:+ self.calls: list[dict] = []++ async def __aenter__(self):+ return self++ async def __aexit__(self, *exc):+ return False++ async def post(self, url, headers=None, json=None, timeout=None):+ self.calls.append({"url": url, "headers": headers, "json": json})+ # `raise_for_status` needs a bound request, so build one rather than+ # returning a bare Response.+ return httpx.Response(+ 200,+ json={"choices": [{"message": {"content": "ok"}}]},+ request=httpx.Request("POST", url),+ )+++# ── the contract itself ────────────────────────────────────────────────────+++def test_the_api_runs_the_same_classifier_as_the_agents_service() -> None:+ """Two heuristics that disagreed about what counts as a raw log would be+ worse than one: a prompt refused in one service and accepted in the other+ reads as a bug in the refusal."""+ assert classify_message(RAW_OCSF) is not None+ assert classify_message("A user signed in from an unfamiliar ASN.") is None+++async def test_a_breaching_prompt_never_reaches_the_provider() -> None:+ """Ordering is the whole point. A check that runs after the request is a+ log line, not a control."""+ recorder = _Recorder()+ with pytest.raises(LLMContractViolation):+ await safe_chat_completions_request(+ api_key="k",+ model="m",+ messages=[{"role": "user", "content": RAW_OCSF}],+ client=recorder,+ )+ assert recorder.calls == [], "the request was issued despite the violation"+++async def test_a_clean_prompt_is_forwarded_with_the_normalised_messages() -> None:+ recorder = _Recorder()+ body = await safe_chat_completions_request(+ api_key="k",+ model="gpt-x",+ messages=[{"role": "user", "content": "Explain this alert."}],+ url="https://provider.test/v1/chat/completions",+ client=recorder,+ temperature=0.1,+ )+ assert body["choices"][0]["message"]["content"] == "ok"+ assert len(recorder.calls) == 1+ sent = recorder.calls[0]+ assert sent["url"] == "https://provider.test/v1/chat/completions"+ assert sent["json"]["model"] == "gpt-x"+ assert sent["json"]["temperature"] == 0.1+ assert sent["json"]["messages"] == [{"role": "user", "content": "Explain this alert."}]+ assert sent["headers"]["Authorization"] == "Bearer k"+++async def test_a_secret_shaped_value_is_refused() -> None:+ """The contract matches an assignment shape (`token: "..."`), not a bare+ high-entropy string — a bare one is indistinguishable from a hostname or+ a hash, both of which are legitimate prompt content."""+ recorder = _Recorder()+ with pytest.raises(LLMContractViolation):+ await safe_chat_completions_request(+ api_key="k",+ model="m",+ messages=[{"role": "user", "content": 'the config had api_key: "AKIAIOSFODNN7EXAMPLE1"'}],+ client=recorder,+ )+ assert recorder.calls == []+++# ── every call site actually uses it ───────────────────────────────────────++#: The endpoints the audit found POSTing untrusted input with no contract.+GUARDED_CALL_SITES = (+ "api/v1/endpoints/phishing.py",+ "api/v1/endpoints/translation.py",+ "api/v1/endpoints/knowledge_base.py",+ "api/v1/endpoints/hunts.py",+ "api/v1/endpoints/nl_detection.py",+ "api/v1/endpoints/detection_loop.py",+ "services/alert_explain.py",+)++[email protected]("relpath", GUARDED_CALL_SITES)+def test_the_call_site_routes_through_the_contract(relpath: str) -> None:+ """A module-by-module assertion rather than one aggregate, so a+ regression names the endpoint that lost its guard."""+ source = (API_APP / relpath).read_text(encoding="utf-8")+ assert "safe_chat_completions_request" in source, f"{relpath} does not route through the contract"++[email protected]("relpath", GUARDED_CALL_SITES)+def test_the_call_site_no_longer_posts_to_a_completions_endpoint(relpath: str) -> None:+ """The guard is only real if the raw POST is gone.++ Importing the wrapper while leaving the old call in place would pass a+ string-search gate and change nothing.++ Only POSTs aimed at a completions endpoint count. ``hunts.py`` also POSTs+ an ES|QL query to Elasticsearch, which is a different thing entirely and+ must not be flagged.+ """+ path = API_APP / relpath+ source = path.read_text(encoding="utf-8")+ tree = ast.parse(source, filename=str(path))++ offenders: list[int] = []+ for node in ast.walk(tree):+ if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Attribute):+ continue+ if node.func.attr != "post":+ continue+ if isinstance(node.func.value, ast.Name) and node.func.value.id in {"router", "app"}:+ continue+ target = node.args[0] if node.args else next((kw.value for kw in node.keywords if kw.arg == "url"), None)+ if target is None:+ continue+ rendered = ast.get_source_segment(source, target) or ""+ # The URL is usually a variable (`completions_url`) rather than a+ # literal, so match the name as well as the string.+ if "completions" in rendered:+ offenders.append(node.lineno)++ assert not offenders, f"{relpath} still POSTs to a completions endpoint at line(s) {offenders}"+++def test_the_nl_query_llm_path_can_resolve_its_imports() -> None:+ """It could not, and the failure was silent.++ The vendored translator imported ``app.llm.contract`` and+ ``app.llm.factory``, neither of which exists in the API process. The+ resulting ImportError was swallowed by a broad ``except``, so+ ``/nl-query`` always returned the deterministic translation and never+ reached a model — safe by accident, and invisible.+ """+ from app.services.llm_safety import safe_chat_completions_request as api_wrapper+ from app.services.model_aliases import chat_completions_url, resolve_model_alias++ assert callable(api_wrapper)+ assert chat_completions_url().endswith("/chat/completions")+ assert resolve_model_alias("nl")diff --git a/services/api/tests/test_posture_snapshot_coverage.py b/services/api/tests/test_posture_snapshot_coverage.pynew file mode 100644index 000000000..bceebfc15--- /dev/null+++ b/services/api/tests/test_posture_snapshot_coverage.py@@ -0,0 +1,93 @@+"""Which providers can resolve permissions *live* must be stated, not implied.++All five resolvers (AWS, Azure, GCP, Okta, Google Workspace) are implemented+and report ``coverage: "full"``. That describes the resolver, which is a pure+function over a provider snapshot — and says nothing about whether a snapshot+can be obtained.++Only Okta's is assembled from a live connector. The other four expect a+connector to answer the ``__posture_snapshot__`` sentinel from+``get_resource_config``, and **no connector implements it**, so with+``AISOC_EFFECTIVE_PERMISSIONS_LIVE=1`` they return 412 rather than a+fabricated snapshot.++That is an honest state, but nothing recorded it, so "coverage: full" was the+only number a reader saw. These tests pin the real shape of the gap: if a+connector implements the sentinel, the allow-list below must shrink, and if a+resolver is registered without one, that fails too. The gap is allowed to+exist; it is not allowed to be invisible.+"""++from __future__ import annotations++import inspect+from pathlib import Path++import pytest+from app.services.effective_permissions.posture_loader import (+ POSTURE_SNAPSHOT_ID,+ PROVIDER_CONNECTOR,+)+from app.services.effective_permissions.service import SUPPORTED_PROVIDERS++#: Providers whose snapshot cannot yet be collected live, with the reason.+#: Shrink this as connectors implement the sentinel; never grow it silently.+NO_LIVE_SNAPSHOT = {+ "aws": "aws_security_hub does not answer __posture_snapshot__",+ "azure": "azure_entra implements no get_resource_config at all",+ "gcp": "gcp_scc treats the id as an SCC finding name, not a posture request",+ "gws": "google_workspace implements no get_resource_config at all",+}++CONNECTORS_DIR = Path(__file__).resolve().parents[2] / "connectors" / "app" / "connectors"+++def test_every_registered_resolver_has_a_snapshot_source_declared() -> None:+ """A resolver with no entry in PROVIDER_CONNECTOR can never run live, and+ would report `coverage: full` while always 412-ing."""+ missing = set(SUPPORTED_PROVIDERS) - set(PROVIDER_CONNECTOR)+ assert not missing, f"{sorted(missing)} have a resolver but no declared snapshot source"+++def test_the_live_gap_is_exactly_the_four_cloud_providers() -> None:+ """Okta is the only provider assembled end-to-end today."""+ live = set(PROVIDER_CONNECTOR) - set(NO_LIVE_SNAPSHOT)+ assert live == {"okta"}, f"the set of live-capable providers changed to {sorted(live)} — update NO_LIVE_SNAPSHOT and the docs"++[email protected](not CONNECTORS_DIR.is_dir(), reason="services/connectors is not in this checkout")[email protected]("provider", sorted(NO_LIVE_SNAPSHOT))+def test_a_provider_on_the_gap_list_really_cannot_collect_a_snapshot(provider: str) -> None:+ """The reverse direction, which is the one that rots.++ A one-directional gate would only check that listed providers stay+ listed. This asserts the listing is still *true*: if the connector starts+ handling the sentinel, the allow-list is stale and must shrink — otherwise+ a capability that now works keeps being reported as missing.+ """+ connector_id = PROVIDER_CONNECTOR[provider]+ source_file = CONNECTORS_DIR / f"{connector_id}.py"+ if not source_file.is_file():+ pytest.fail(f"{provider} maps to connector '{connector_id}', which has no module at {source_file}")++ source = source_file.read_text(encoding="utf-8")+ assert POSTURE_SNAPSHOT_ID not in source, (+ f"{connector_id} now references {POSTURE_SNAPSHOT_ID}, so '{provider}' may be able to "+ f"collect a live snapshot. Remove it from NO_LIVE_SNAPSHOT and update the endpoint docstring."+ )+++def test_no_resolver_claims_scaffold_coverage() -> None:+ """The endpoint docstring described four providers as scaffolds returning+ 501 long after they were implemented, which made the 501 branch+ unreachable documentation."""+ for provider, cls in SUPPORTED_PROVIDERS.items():+ assert cls.coverage == "full", f"{provider} reports coverage={cls.coverage!r}"+++def test_the_endpoint_docstring_does_not_call_them_scaffolds() -> None:+ """Prose drifts from code silently, so assert on the prose."""+ from app.api.v1.endpoints import effective_permissions as endpoint++ doc = inspect.getdoc(endpoint) or ""+ assert "Scaffolded providers" not in doc, "the endpoint docstring still describes implemented resolvers as scaffolds"diff --git a/services/connectors/app/api/router.py b/services/connectors/app/api/router.pyindex e7660e385..cc1f3c8fc 100644--- a/services/connectors/app/api/router.py+++ b/services/connectors/app/api/router.py@@ -29,19 +29,31 @@ import refrom typing import Anyimport structlog-from fastapi import APIRouter, HTTPException, status+from fastapi import APIRouter, HTTPException, Query, statusfrom pydantic import BaseModelfrom pydantic import Field as PydFieldfrom app.connectors import CONNECTOR_REGISTRY, list_connector_schemasfrom app.connectors.base import Capability+from app.db.connector_repo import fetch_enabled_connectors+from app.db.engine import get_enginefrom app.federated.query import QueryError, parse_unified_query+from app.security.credential_vault import CredentialVaultError, get_vaultlogger = structlog.get_logger()router = APIRouter()_CTRL_RE = re.compile(r"[\x00-\x1f\x7f]")+#: Keys stored on a connector instance that are scheduler knobs rather than+#: constructor arguments. Passing them through raises ``TypeError`` and turns a+#: working connector into a 422. Mirrors the filter in ``ConnectorScheduler``.+_SCHEDULER_ONLY_CONFIG_KEYS = frozenset({"poll_interval_seconds", "checkpoint", "filter_rules"})+++def _connector_kwargs(connector_config: dict[str, Any]) -> dict[str, Any]:+ return {k: v for k, v in connector_config.items() if k not in _SCHEDULER_ONLY_CONFIG_KEYS}+def _safe_log_val(value: str) -> str:"""Strip ASCII control characters (incl. newlines) from a string before logging.@@ -285,6 +297,86 @@ async def test_connector_connection(connector_id: str, payload: TestConnectionRereturn result[email protected]("/connectors/instances/{instance_id}/resource-config")+async def get_instance_resource_config(+ instance_id: str,+ resource_id: str = Query(..., description="Vendor-native resource id"),+ ts: str | None = Query(None, description="Point in time (RFC 3339)"),+):+ """Fetch a resource's configuration for a **saved connector instance**.++ The POST route below takes credentials in the body, which works for the+ API service — it owns the vault — and cannot work for `services/ingest`.+ The Go config-snapshotter has no credentials to send, so it called a GET+ endpoint that did not exist; a 404 maps to `ErrNotImplemented`, which the+ snapshotter treats as a soft skip. An operator therefore saw+ "snapshots enabled" and zero Configuration nodes, with nothing logged.++ This route resolves the instance and decrypts `auth_config` the same way+ `ConnectorScheduler` does at poll time, so the caller needs no secrets.+ That also means the ingest service never handles credentials, which is the+ reason the original contract could not simply be renamed into place.+ """+ try:+ engine = get_engine()+ async with engine.begin() as conn:+ instances = await fetch_enabled_connectors(conn)+ except Exception as exc: # noqa: BLE001 — surfaced as 503, never silent+ logger.exception("connector.resource_config.instance_load_failed")+ raise HTTPException(+ status_code=status.HTTP_503_SERVICE_UNAVAILABLE,+ detail="could not load connector instances",+ ) from exc++ target = next((i for i in instances if str(i.id) == instance_id), None)+ if target is None:+ raise HTTPException(+ status_code=status.HTTP_404_NOT_FOUND,+ detail=f"no enabled connector instance '{_safe_log_val(instance_id)}'",+ )++ cls = CONNECTOR_REGISTRY.get(target.connector_type)+ if cls is None:+ raise HTTPException(+ status_code=status.HTTP_404_NOT_FOUND,+ detail=f"connector type '{_safe_log_val(target.connector_type)}' is not in this build",+ )++ try:+ auth = get_vault().decrypt_dict(target.auth_config or {})+ except CredentialVaultError as exc:+ logger.error("connector.resource_config.decrypt_failed instance=%s", _safe_log_val(instance_id))+ raise HTTPException(+ status_code=status.HTTP_502_BAD_GATEWAY,+ detail="could not decrypt stored credentials",+ ) from exc++ kwargs = {**auth, **_connector_kwargs(target.connector_config or {})}+ try:+ connector = cls(**kwargs)+ except TypeError as exc:+ raise HTTPException(+ status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,+ detail=f"connector config does not match schema: {exc}",+ ) from exc++ try:+ config = await connector.get_resource_config(resource_id, ts)+ except NotImplementedError as exc:+ # 501 rather than an error: most connectors legitimately cannot+ # time-travel a resource's configuration, and the snapshotter skips+ # them without counting a failure.+ raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED, detail=str(exc)) from exc+ except Exception as exc: # noqa: BLE001+ logger.exception("connector.resource_config.runtime_error instance=%s", _safe_log_val(instance_id))+ raise HTTPException(+ status_code=status.HTTP_502_BAD_GATEWAY,+ detail="Resource-config fetch failed. Check connector configuration and connectivity.",+ ) from exc++ return config++@router.post("/connectors/{connector_id}/resource_config")async def get_resource_config(connector_id: str, payload: ResourceConfigRequest):"""Fetch one resource's live configuration (Phase C2 posture collection).diff --git a/services/ingest/internal/config_snapshot/http_provider_test.go b/services/ingest/internal/config_snapshot/http_provider_test.gonew file mode 100644index 000000000..71abda460--- /dev/null+++ b/services/ingest/internal/config_snapshot/http_provider_test.go@@ -0,0 +1,183 @@+// The HTTP provider's URL has to match the route the connectors service+// actually serves (T1.2).+//+// It did not, for four independent reasons at once — method, path prefix, path+// separator, and payload — and every one of them was invisible. A 404 maps to+// ErrNotImplemented, which the snapshotter treats as a soft skip, so an+// operator saw "T1.2 config snapshots enabled" and zero Configuration nodes+// with nothing written to the log.+//+// Nothing compared the two halves of the contract. These tests pin the shape+// of the request so a rename on either side fails here rather than in+// production silence.+package config_snapshot++import (+ "context"+ "net/http"+ "net/http/httptest"+ "strings"+ "testing"+ "time"++ "github.com/beenuar/aisoc/services/ingest/internal/graph"+)++func TestHTTPProvider_RequestMatchesTheServedRoute(t *testing.T) {+ var gotMethod, gotPath, gotResourceID, gotTS string++ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ gotMethod = r.Method+ gotPath = r.URL.Path+ gotResourceID = r.URL.Query().Get("resource_id")+ gotTS = r.URL.Query().Get("ts")+ w.Header().Set("Content-Type", "application/json")+ _, _ = w.Write([]byte(`{"public": true}`))+ }))+ defer srv.Close()++ ts := time.Date(2026, 9, 23, 12, 0, 0, 0, time.UTC)+ cfg, err := NewHTTPProvider(srv.URL, time.Second).+ GetResourceConfig(context.Background(), "inst-123", "arn:aws:s3:::bucket", ts)+ if err != nil {+ t.Fatalf("GetResourceConfig: %v", err)+ }+ if cfg["public"] != true {+ t.Fatalf("config not returned: %#v", cfg)+ }++ if gotMethod != http.MethodGet {+ t.Errorf("method = %q, want GET", gotMethod)+ }+ // The instance-scoped route. The old URL omitted /api and used an+ // underscore, so it reached no handler.+ if want := "/api/v1/connectors/instances/inst-123/resource-config"; gotPath != want {+ t.Errorf("path = %q, want %q", gotPath, want)+ }+ if gotResourceID != "arn:aws:s3:::bucket" {+ t.Errorf("resource_id = %q", gotResourceID)+ }+ if gotTS != "2026-09-23T12:00:00Z" {+ t.Errorf("ts = %q", gotTS)+ }+}++func TestHTTPProvider_EscapesVendorSuppliedIdentifiers(t *testing.T) {+ // A resource id is vendor-supplied and can contain & / # — unescaped,+ // those truncate the URL or inject a parameter.+ var gotResourceID, gotTS string+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ gotResourceID = r.URL.Query().Get("resource_id")+ gotTS = r.URL.Query().Get("ts")+ _, _ = w.Write([]byte(`{}`))+ }))+ defer srv.Close()++ hostile := "bucket?ts=1970-01-01T00:00:00Z&resource_id=other"+ if _, err := NewHTTPProvider(srv.URL, time.Second).+ GetResourceConfig(context.Background(), "inst-1", hostile, time.Unix(0, 0).UTC()); err != nil {+ t.Fatalf("GetResourceConfig: %v", err)+ }+ if gotResourceID != hostile {+ t.Errorf("resource_id was not round-tripped intact: %q", gotResourceID)+ }+ if gotTS != "1970-01-01T00:00:00Z" {+ t.Errorf("ts was overridden by the injected parameter: %q", gotTS)+ }+}++func TestHTTPProvider_TrailingSlashOnBaseURLDoesNotDoubleUp(t *testing.T) {+ var gotPath string+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ gotPath = r.URL.Path+ _, _ = w.Write([]byte(`{}`))+ }))+ defer srv.Close()++ if _, err := NewHTTPProvider(srv.URL+"/", time.Second).+ GetResourceConfig(context.Background(), "inst-1", "res-1", time.Now()); err != nil {+ t.Fatalf("GetResourceConfig: %v", err)+ }+ if strings.Contains(gotPath, "//") {+ t.Errorf("path has a doubled separator: %q", gotPath)+ }+}++func TestHTTPProvider_NotImplementedIsDistinctFromAnError(t *testing.T) {+ // 501 means "this connector cannot time-travel a config", which is a+ // routine skip. Anything else is a failure the operator should see.+ for _, tc := range []struct {+ status int+ soft bool+ }{+ {http.StatusNotImplemented, true},+ {http.StatusNotFound, true},+ {http.StatusBadGateway, false},+ {http.StatusInternalServerError, false},+ } {+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {+ w.WriteHeader(tc.status)+ }))+ _, err := NewHTTPProvider(srv.URL, time.Second).+ GetResourceConfig(context.Background(), "inst-1", "res-1", time.Now())+ srv.Close()++ if err == nil {+ t.Fatalf("status %d: expected an error", tc.status)+ }+ isSoft := err == ErrNotImplemented+ if isSoft != tc.soft {+ t.Errorf("status %d: soft-skip = %v, want %v (err=%v)", tc.status, isSoft, tc.soft, err)+ }+ }+}++func TestApply_WritesTheBiTemporalEdgeProperties(t *testing.T) {+ // schemas/graph-schema.yaml declares valid_from / valid_to / is_current+ // and the published schema doc advertises an O(1) latest-config lookup+ // via `:CONFIGURED_AS {is_current: true}`. None of the three was ever+ // written, so that query matched zero edges. The drift gate could not+ // catch it: it only validates properties on edges declared+ // `event_edge: true`, and CONFIGURED_AS is structural.+ ts := mustParseTime(t, "2026-05-01T13:00:00Z")+ provider := NewStaticProvider(map[string]map[string][]ConfigSnapshot{+ "aws_security_hub": {+ "arn:aws:s3:::demo": {+ {Recorded: ts.Add(-time.Hour), Data: map[string]interface{}{"public": true}},+ },+ },+ })+ s, err := New(Config{Provider: provider, TTL: time.Minute})+ if err != nil {+ t.Fatal(err)+ }+ defer s.Close()++ ev := newAWSEvent(ts, "arn:aws:s3:::demo")+ s.Apply(context.Background(), ev)++ var rel *graph.Edge+ for i := range ev.Edges {+ if ev.Edges[i].Type == graph.RelConfiguredAs {+ rel = &ev.Edges[i]+ break+ }+ }+ if rel == nil {+ t.Fatal("no CONFIGURED_AS edge was attached")+ }+ if rel.Properties["is_current"] != true {+ t.Errorf("is_current = %v, want true", rel.Properties["is_current"])+ }+ if got := rel.Properties["valid_from"]; got != ts.UTC().Format(time.RFC3339Nano) {+ t.Errorf("valid_from = %v", got)+ }+ if v, ok := rel.Properties["snapshot_id"].(string); !ok || v == "" {+ t.Errorf("snapshot_id is required by the schema, got %v", rel.Properties["snapshot_id"])+ }+ // An open interval, not one that closed at the epoch: a reader filtering+ // `valid_to < now` would otherwise drop the current configuration.+ if _, present := rel.Properties["valid_to"]; present {+ t.Errorf("valid_to should be absent while the interval is open, got %v", rel.Properties["valid_to"])+ }+}diff --git a/services/ingest/internal/config_snapshot/snapshotter.go b/services/ingest/internal/config_snapshot/snapshotter.goindex 323409b97..539e1682b 100644--- a/services/ingest/internal/config_snapshot/snapshotter.go+++ b/services/ingest/internal/config_snapshot/snapshotter.go@@ -46,7 +46,9 @@ import ("fmt""io""net/http"+ urlpkg "net/url""sort"+ "strings""sync/atomic""time"@@ -134,12 +136,27 @@ func (p *StaticProvider) GetResourceConfig(_ context.Context, connectorID, resou//// Endpoint contract://-// GET {BaseURL}/v1/connectors/{connector_id}/resource-config?+// GET {BaseURL}/api/v1/connectors/instances/{instance_id}/resource-config?// resource_id={resource_id}&ts={rfc3339}//-// 200 JSON body → return as map+// 200 JSON body → return as map// 404 / 501 / "not_implemented" → ErrNotImplemented (soft skip)// other non-2xx → error (snapshotter logs + skips)+//+// This previously pointed at `/v1/connectors/{id}/resource-config`, which no+// router served: the real route was a POST at+// `/api/v1/connectors/{id}/resource_config` taking decrypted credentials in+// the body. Four mismatches at once — method, prefix, separator, payload —+// and the last one is not a typo. This service has no vault, so it cannot+// supply `auth_config` at all; renaming the URL would have turned a silent+// 404 into a silent 422. The instance-scoped route above resolves the+// credentials itself, the same way the connector scheduler does at poll time.+//+// Both failures were invisible because a 404 maps to ErrNotImplemented, which+// the snapshotter treats as a soft skip — so an operator saw+// "T1.2 config snapshots enabled" and zero Configuration nodes, with nothing+// in the log. `snapshotsSkippedTotal` is now reported so a permanent skip is+// distinguishable from a connector that genuinely cannot time-travel.type HTTPProvider struct {BaseURL stringClient *http.Client@@ -162,9 +179,17 @@ func (p *HTTPProvider) GetResourceConfig(ctx context.Context, connectorID, resouif p.BaseURL == "" {return nil, ErrNotImplemented}+ // Query values are escaped: a resource id is vendor-supplied (an ARN, an+ // Okta app id) and can contain `&`, `/` and `#`, which would otherwise+ // truncate the URL or inject a parameter.url := fmt.Sprintf(- "%s/v1/connectors/%s/resource-config?resource_id=%s&ts=%s",- p.BaseURL, connectorID, resourceID, ts.UTC().Format(time.RFC3339),+ "%s/api/v1/connectors/instances/%s/resource-config?%s",+ strings.TrimRight(p.BaseURL, "/"),+ urlpkg.PathEscape(connectorID),+ urlpkg.Values{+ "resource_id": {resourceID},+ "ts": {ts.UTC().Format(time.RFC3339)},+ }.Encode(),)req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)if err != nil {@@ -323,13 +348,32 @@ func (s *Snapshotter) Apply(ctx context.Context, ev *graph.Event) {TenantID: ev.TenantID,Properties: props,})+ // `valid_from` / `valid_to` / `is_current` are declared in+ // schemas/graph-schema.yaml and the published graph-schema doc+ // advertises an O(1) "latest configuration" lookup via+ // `:CONFIGURED_AS {is_current: true}`. Nothing wrote any of the three,+ // so that documented query matched zero edges. The drift gate could+ // not catch it because it only validates properties on edges declared+ // `event_edge: true`, and this one is structural.+ //+ // `valid_to` is left nil rather than zero: an open interval is not the+ // same as one that closed at the epoch, and a reader filtering+ // `valid_to < now` would otherwise exclude the current configuration.+ // Closing the previous interval needs a read-modify-write against the+ // graph, which the ingest hot path deliberately does not do — so+ // `is_current` is true on write and a traversal takes the newest+ // `valid_from`, with the caveat recorded in the schema doc.+ validFrom := ev.TS.UTC().Format(time.RFC3339Nano)ev.Edges = append(ev.Edges, graph.Edge{Type: graph.RelConfiguredAs,FromLabel: graph.NodeResource, FromKey: ref.NaturalKey,ToLabel: graph.NodeConfiguration, ToKey: configKey,Properties: map[string]interface{}{- "ts": ev.TS.UTC().Format(time.RFC3339Nano),+ "ts": validFrom,"connector_id": connectorID,+ "snapshot_id": configKey,+ "valid_from": validFrom,+ "is_current": true,},})digestParts = append(digestParts, configKey)diff --git a/services/slack-bot/app/interactions.py b/services/slack-bot/app/interactions.pyindex 743bc34c5..1a99deb61 100644--- a/services/slack-bot/app/interactions.py+++ b/services/slack-bot/app/interactions.py@@ -200,7 +200,16 @@ async def handle_action_decision(is_approve = action_id_event == APPROVE_ACTION_IDtry:- action = await actions_client.approve_action(action_id) if is_approve else await actions_client.reject_action(action_id)+ # `user_id` comes off the Slack-signed interaction payload, so it is+ # attested rather than claimed. Passing it is what makes the actions+ # service able to enforce the permission tier and separation of+ # duties; without it the approval authorized nobody.+ approver = actions_client.chatops_approver("slack", user_id)+ action = (+ await actions_client.approve_action(action_id, approver=approver)+ if is_approve+ else await actions_client.reject_action(action_id, approver=approver)+ )except AisocClientError as exc:await sink.record(ApprovalAuditEvent(diff --git a/services/slack-bot/app/services/aisoc_clients.py b/services/slack-bot/app/services/aisoc_clients.pyindex dd56089bd..c9d910b2c 100644--- a/services/slack-bot/app/services/aisoc_clients.py+++ b/services/slack-bot/app/services/aisoc_clients.py@@ -327,26 +327,76 @@ class AisocActionsClient(_BaseClient):except ValueError as exc:raise AisocClientError("submit action failed: invalid JSON") from exc- async def approve_action(self, action_id: str) -> dict[str, Any]:- """Approve a pending action (called from the Slack approve button)."""+ @staticmethod+ def chatops_approver(platform: str, platform_user_id: str | None) -> dict[str, Any] | None:+ """Build the body carrying an identity the platform itself verified.++ Slack signs every interaction payload and Teams payloads are+ HMAC-signed, so the user id on a button click is attested rather than+ claimed. It is sent as identity only — the actions service maps it to+ permissions — because this bot has no idea what a given Slack user may+ do in AiSOC, and a bot permitted to assert its own permissions could+ grant itself anything.++ The platform is a parameter rather than a constant because the Teams+ bot imports this client when it is on the image, and stamping "slack"+ onto a Teams user would resolve against the wrong half of the approver+ map.++ Until this was wired, approve/reject sent no body at all, so the+ actions service authorized nobody: the permission tier and separation+ of duties were both skipped, and the human survived only in a log line.+ """+ if not platform_user_id:+ return None+ return {+ "chatops_approver": {+ "platform": platform,+ "platform_user_id": platform_user_id,+ }+ }++ async def approve_action(+ self,+ action_id: str,+ *,+ approver: dict[str, Any] | None = None,+ ) -> dict[str, Any]:+ """Approve a pending action (called from the approve button).++ ``approver`` is the payload from :meth:`chatops_approver`. Omitting it+ makes the actions service refuse by default — which is why the+ approval-timeout scheduler only ever rejects.+ """safe_id = quote(action_id, safe="")response = await self._request("POST",f"/api/v1/actions/{safe_id}/approve",context="approve action",+ json=approver,)try:return response.json()except ValueError as exc:raise AisocClientError("approve action failed: invalid JSON") from exc- async def reject_action(self, action_id: str) -> dict[str, Any]:- """Reject a pending action (called from the Slack deny button)."""+ async def reject_action(+ self,+ action_id: str,+ *,+ approver: dict[str, Any] | None = None,+ ) -> dict[str, Any]:+ """Reject a pending action (called from the deny button).++ Identity is recorded when supplied but not required: a rejection+ causes no vendor effect, and a timeout-driven rejection has no human.+ """safe_id = quote(action_id, safe="")response = await self._request("POST",f"/api/v1/actions/{safe_id}/reject",context="reject action",+ json=approver,)try:return response.json()diff --git a/services/slack-bot/tests/test_interactions.py b/services/slack-bot/tests/test_interactions.pyindex 26d3a7067..18b0508df 100644--- a/services/slack-bot/tests/test_interactions.py+++ b/services/slack-bot/tests/test_interactions.py@@ -55,17 +55,28 @@ class FakeActionsClient:self._raise_on = raise_onself.approve_calls: list[str] = []self.reject_calls: list[str] = []+ # T3.6 — the approver payload the handler sent with each call. The+ # handler used to send none, so the actions service authorized nobody.+ self.approvers: list[dict[str, Any] | None] = []- async def approve_action(self, action_id: str) -> dict[str, Any]:+ @staticmethod+ def chatops_approver(platform: str, platform_user_id: str | None) -> dict[str, Any] | None:+ if not platform_user_id:+ return None+ return {"chatops_approver": {"platform": platform, "platform_user_id": platform_user_id}}++ async def approve_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:if self._raise_on == "approve":raise AisocClientError("upstream approve boom", status_code=502)self.approve_calls.append(action_id)+ self.approvers.append(approver)return self._approve_response- async def reject_action(self, action_id: str) -> dict[str, Any]:+ async def reject_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:if self._raise_on == "reject":raise AisocClientError("upstream reject boom", status_code=502)self.reject_calls.append(action_id)+ self.approvers.append(approver)return self._reject_response@@ -97,6 +108,45 @@ async def test_approve_replaces_card_and_records_decider():assert "approved" in rendered.lower()+async def test_approve_sends_the_clicking_slack_user_as_the_approver():+ """T3.6 — the identity has to reach the actions service, not just the log.++ `user_id` comes off the Slack-signed interaction payload, so it is+ attested. The handler used to call `approve_action(action_id)` with no+ body: the actions service then ran its approver authorization against+ `None`, which skipped the permission tier and separation of duties and+ left the human recorded only in an audit line. This test fails against+ that behaviour.+ """+ actions = FakeActionsClient()+ await handle_action_decision(+ action_id_event=APPROVE_ACTION_ID,+ button_value="act-7|case-3",+ user_id="U42",+ actions_client=actions,+ )+ assert actions.approvers == [{"chatops_approver": {"platform": "slack", "platform_user_id": "U42"}}]+++async def test_the_approver_platform_is_slack_not_inferred_downstream():+ """The platform travels with the identity.++ The Teams bot imports this client when it is on the image, so a platform+ baked into the client as a constant would stamp "slack" onto a Teams user+ and resolve against the wrong half of the approver map.+ """+ actions = FakeActionsClient()+ await handle_action_decision(+ action_id_event=DENY_ACTION_ID,+ button_value="act-8|case-3",+ user_id="U99",+ actions_client=actions,+ )+ assert actions.approvers[0]["chatops_approver"]["platform"] == "slack"++@pytest.mark.asyncioasync def test_deny_replaces_card_and_calls_reject_client():actions = FakeActionsClient()diff --git a/services/slack-bot/tests/test_main.py b/services/slack-bot/tests/test_main.pyindex fb2f39573..1d2bdcd29 100644--- a/services/slack-bot/tests/test_main.py+++ b/services/slack-bot/tests/test_main.py@@ -43,17 +43,29 @@ class _StubActionsClient:self._raise_on = raise_onself.approve_calls: list[str] = []self.reject_calls: list[str] = []-- async def approve_action(self, action_id: str) -> dict[str, Any]:+ # T3.6 — the verified platform identity the handler now forwards, so+ # the actions service has somebody to authorize. It used to send+ # nothing at all.+ self.approvers: list[dict[str, Any] | None] = []++ @staticmethod+ def chatops_approver(platform: str, platform_user_id: str | None) -> dict[str, Any] | None:+ if not platform_user_id:+ return None+ return {"chatops_approver": {"platform": platform, "platform_user_id": platform_user_id}}++ async def approve_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:if self._raise_on == "approve":raise AisocClientError("upstream boom", status_code=502)self.approve_calls.append(action_id)+ self.approvers.append(approver)return {"id": action_id, "status": "approved", "action_type": "isolate_host"}- async def reject_action(self, action_id: str) -> dict[str, Any]:+ async def reject_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:if self._raise_on == "reject":raise AisocClientError("upstream boom", status_code=502)self.reject_calls.append(action_id)+ self.approvers.append(approver)return {"id": action_id, "status": "rejected", "action_type": "isolate_host"}@@ -125,10 +137,10 @@ def test_lifespan_builds_and_closes_clients(monkeypatch):# ``ApprovalTimeoutScheduler`` at startup (T3.6 ChatOps timeout# path), so the mock has to expose them — no actual call is# made during the lifespan, but ``getattr`` is.- async def approve_action(self, action_id: str) -> dict[str, Any]:+ async def approve_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:return {"id": action_id, "status": "approved"}- async def reject_action(self, action_id: str) -> dict[str, Any]:+ async def reject_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:return {"id": action_id, "status": "rejected"}monkeypatch.setattr(main_module, "AisocApiClient", _RecordingApiClient)diff --git a/services/teams-bot/app/callbacks.py b/services/teams-bot/app/callbacks.pyindex 1c6b7d6c0..723fe54de 100644--- a/services/teams-bot/app/callbacks.py+++ b/services/teams-bot/app/callbacks.py@@ -39,13 +39,30 @@ class _ActionsClient(Protocol):# CodeQL ``py/ineffectual-statement`` (it flags ellipsis as a# discarded expression statement). Semantically identical for an# unimplemented Protocol contract.- async def approve_action(self, action_id: str) -> dict[str, Any]:+ async def approve_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:pass- async def reject_action(self, action_id: str) -> dict[str, Any]:+ async def reject_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:pass+def _chatops_approver(client: Any, approver_id: str | None) -> dict[str, Any] | None:+ """Build the approver payload, tolerating a client without the helper.++ `build_actions_client` may return the Slack bot's client, this package's+ fallback, or a test double. All of the real ones expose+ `chatops_approver`; a double may not, so fall back to constructing the+ payload directly rather than dropping the identity — silently omitting it+ is what made approvals authorize nobody in the first place.+ """+ if not approver_id:+ return None+ helper = getattr(client, "chatops_approver", None)+ if callable(helper):+ return helper("teams", approver_id)+ return {"chatops_approver": {"platform": "teams", "platform_user_id": approver_id}}++@dataclass(slots=True, frozen=True)class _AuditEvent:case_id: str@@ -138,10 +155,15 @@ async def handle_card_action()try:+ # `approver_id` was verified by the inbound HMAC check above, so it is+ # attested rather than claimed. Passing it is what lets the actions+ # service enforce the permission tier and separation of duties; the+ # callback previously recorded it in the audit event only.+ approver = _chatops_approver(actions_client, approver_id)if decision_label == "approved":- await actions_client.approve_action(action_id)+ await actions_client.approve_action(action_id, approver=approver)else:- await actions_client.reject_action(action_id)+ await actions_client.reject_action(action_id, approver=approver)except Exception as exc: # noqa: BLE001 — surfaced as audit errorlog.warning("teams_callback.upstream_failed",diff --git a/services/teams-bot/app/services/aisoc_clients.py b/services/teams-bot/app/services/aisoc_clients.pyindex a65c23e16..d30185fe4 100644--- a/services/teams-bot/app/services/aisoc_clients.py+++ b/services/teams-bot/app/services/aisoc_clients.py@@ -28,10 +28,10 @@ class _ActionsClient(Protocol):# Protocol method bodies use ``pass`` rather than ``...`` to silence# CodeQL ``py/ineffectual-statement``. Semantically identical for an# unimplemented Protocol contract.- async def approve_action(self, action_id: str) -> dict[str, Any]:+ async def approve_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:pass- async def reject_action(self, action_id: str) -> dict[str, Any]:+ async def reject_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:passasync def aclose(self) -> None:@@ -61,13 +61,26 @@ class _FallbackActionsClient:headers["Authorization"] = f"Bearer {self._token}"self._client = httpx.AsyncClient(base_url=self._base_url, headers=headers, timeout=10.0)- async def approve_action(self, action_id: str) -> dict[str, Any]:- r = await self._client.post(f"/api/v1/actions/{action_id}/approve")+ @staticmethod+ def chatops_approver(platform: str, platform_user_id: str | None) -> dict[str, Any] | None:+ """Mirror of the Slack client's helper, so either client works here.++ `build_actions_client` prefers the Slack bot's client when it is on+ the image and falls back to this one, so both have to accept the same+ approver payload — otherwise approvals authorize or don't depending on+ which image the Teams bot happens to be running.+ """+ if not platform_user_id:+ return None+ return {"chatops_approver": {"platform": platform, "platform_user_id": platform_user_id}}++ async def approve_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:+ r = await self._client.post(f"/api/v1/actions/{action_id}/approve", json=approver)r.raise_for_status()return r.json()- async def reject_action(self, action_id: str) -> dict[str, Any]:- r = await self._client.post(f"/api/v1/actions/{action_id}/reject")+ async def reject_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:+ r = await self._client.post(f"/api/v1/actions/{action_id}/reject", json=approver)r.raise_for_status()return r.json()diff --git a/services/teams-bot/tests/test_callbacks_approver.py b/services/teams-bot/tests/test_callbacks_approver.pynew file mode 100644index 000000000..5a5921371--- /dev/null+++ b/services/teams-bot/tests/test_callbacks_approver.py@@ -0,0 +1,160 @@+"""A Teams approval must carry the identity the HMAC already proved (T3.6).++`handle_card_action` verified the inbound signature, recorded `approver_id` in+an audit event, and then called `approve_action(action_id)` with nothing else.+The actions service therefore authorized nobody: the permission-tier check and+separation of duties were both skipped, and the clicking user existed only in+the audit trail.++The platform has to travel with the identity rather than being a constant in+the client, because `build_actions_client` prefers the Slack bot's client when+it is present on the image — stamping "slack" onto a Teams user would resolve+against the wrong half of the approver map.+"""++from __future__ import annotations++import time+from typing import Any++import pytest+from app.callbacks import _chatops_approver, handle_card_action+from app.services.hmac_signer import sign_card_data++SECRET = "teams-test-secret"+++class _FakeActionsClient:+ def __init__(self) -> None:+ self.approve_calls: list[tuple[str, dict[str, Any] | None]] = []+ self.reject_calls: list[tuple[str, dict[str, Any] | None]] = []++ @staticmethod+ def chatops_approver(platform: str, platform_user_id: str | None) -> dict[str, Any] | None:+ if not platform_user_id:+ return None+ return {"chatops_approver": {"platform": platform, "platform_user_id": platform_user_id}}++ async def approve_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:+ self.approve_calls.append((action_id, approver))+ return {"id": action_id, "status": "approved"}++ async def reject_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:+ self.reject_calls.append((action_id, approver))+ return {"id": action_id, "status": "rejected"}+++class _ClientWithoutHelper:+ """A double that predates `chatops_approver`, as a test stub might."""++ def __init__(self) -> None:+ self.approve_calls: list[tuple[str, dict[str, Any] | None]] = []++ async def approve_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:+ self.approve_calls.append((action_id, approver))+ return {"id": action_id, "status": "approved"}++ async def reject_action(self, action_id: str, *, approver: dict[str, Any] | None = None) -> dict[str, Any]:+ return {"id": action_id, "status": "rejected"}+++def _signed(verb: str, action_id: str = "act-1", case_id: str = "case-1") -> dict[str, Any]:+ """Mint the signed `data` payload a real Adaptive Card button carries.++ The verb is the wire value (`approve` / `reject` / `need_info`), which+ `handle_card_action` maps to a decision label.+ """+ return sign_card_data(+ verb=verb,+ action_id=action_id,+ case_id=case_id,+ issued_at=int(time.time()),+ secret=SECRET,+ )+++# ── the payload builder ────────────────────────────────────────────────────+++def test_the_platform_is_teams_not_the_client_default() -> None:+ built = _chatops_approver(_FakeActionsClient(), "29:1abc")+ assert built == {"chatops_approver": {"platform": "teams", "platform_user_id": "29:1abc"}}+++def test_a_client_without_the_helper_still_sends_the_identity() -> None:+ """Silently omitting it is what made approvals authorize nobody, so the+ fallback builds the payload rather than dropping it."""+ built = _chatops_approver(_ClientWithoutHelper(), "29:1abc")+ assert built is not None+ assert built["chatops_approver"]["platform"] == "teams"+++def test_no_approver_id_means_no_payload() -> None:+ assert _chatops_approver(_FakeActionsClient(), None) is None+ assert _chatops_approver(_FakeActionsClient(), "") is None+++# ── end to end through the callback ────────────────────────────────────────+++async def test_an_approval_forwards_the_verified_identity() -> None:+ client = _FakeActionsClient()+ result = await handle_card_action(+ payload=_signed("approve"),+ approver_id="29:1abc",+ secret=SECRET,+ max_age_seconds=300,+ actions_client=client,+ )+ assert result["ok"] is True+ assert client.approve_calls == [("act-1", {"chatops_approver": {"platform": "teams", "platform_user_id": "29:1abc"}})]+++async def test_a_rejection_forwards_it_too() -> None:+ """Identity is optional on reject but still recorded, so "who declined to+ contain this host" has a checked answer."""+ client = _FakeActionsClient()+ await handle_card_action(+ payload=_signed("reject"),+ approver_id="29:1abc",+ secret=SECRET,+ max_age_seconds=300,+ actions_client=client,+ )+ assert client.reject_calls[0][1]["chatops_approver"]["platform_user_id"] == "29:1abc"+++async def test_a_tampered_payload_never_reaches_the_actions_service() -> None:+ payload = _signed("approve")+ payload["action_id"] = "act-somebody-elses"+ client = _FakeActionsClient()++ result = await handle_card_action(+ payload=payload,+ approver_id="29:1abc",+ secret=SECRET,+ max_age_seconds=300,+ actions_client=client,+ )++ assert result["ok"] is False+ assert client.approve_calls == []+ assert client.reject_calls == []+++async def test_need_info_is_non_terminal_and_calls_nothing() -> None:+ client = _FakeActionsClient()+ result = await handle_card_action(+ payload=_signed("need_info"),+ approver_id="29:1abc",+ secret=SECRET,+ max_age_seconds=300,+ actions_client=client,+ )+ assert result["decision"] == "need_info"+ assert client.approve_calls == []+ assert client.reject_calls == []