Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

Three wave-2 gaps where the control existed and authorized nothing (#723)

Beenu Arora4595d504ef9f
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
index 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 node
WORKDIR /workspaces/AiSOC
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index 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.sh
new file mode 100755
index 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.yml
index 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 sync
run: 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 the
diff --git a/.github/workflows/devcontainer-coldstart.yml b/.github/workflows/devcontainer-coldstart.yml
index 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 pipefail
start=$(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 pipefail
echo "── node ──"; node --version
@@ -115,6 +141,18 @@ jobs:
echo "── docker compose ──"; docker compose version
echo "── ripgrep ──"; rg --version | head -1
echo "── 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." >&2
exit 1
fi
+
+ - 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 || true
diff --git a/.github/workflows/publish-images.yml b/.github/workflows/publish-images.yml
index 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=max
sbom: true
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 6c39e5405..69104311a 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -155,6 +155,14 @@ jobs:
image: ghcr.io/beenuar/aisoc-slack-bot
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
with:
@@ -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=max
sbom: true
diff --git a/.github/workflows/screencast.yml b/.github/workflows/screencast.yml
index 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: false
type: 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 spec
working-directory: apps/web
env:
- 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.md
index 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.** It
classified rules by file path and by the key names inside `detection:`, never
consulting 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.0
deliberately so**: what remains is a funded provider key for the live-agent
eval, not code. Marking it done would be the exact failure the program exists
to 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 the
catalogue.** #697 made ids position-independent by pinning
diff --git a/README.md b/README.md
index 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 workbench
A 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&#124;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/do
AiSOC 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.md
index 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.md
index 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 — Shipped
diff --git a/apps/docs/docs/architecture/graph-schema.md b/apps/docs/docs/architecture/graph-schema.md
index 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.md
index 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 refuses
to let a row sit at `NO GATE`.
diff --git a/apps/docs/docs/integrations/github-action.md b/apps/docs/docs/integrations/github-action.md
index 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), and
secret scanning — and posts verdicts, suppression rationale, and prioritization
as 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-latest
steps:
- - uses: beenuar/aisoc-action@v1
+ - uses: beenuar/AiSOC/packages/[email protected]
with:
mode: pr-comment
min-severity: low
@@ -57,7 +70,7 @@ jobs:
digest:
runs-on: ubuntu-latest
steps:
- - 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.md
new file mode 100644
index 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.md
index 6863bd8bf..f7ccb2e5d 100644
--- a/apps/docs/docs/operations/codespaces.md
+++ b/apps/docs/docs/operations/codespaces.md
@@ -31,6 +31,44 @@ The source lives at
the 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 budget
The 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.md
index 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.ts
index 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.tsx
index 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.ts
index 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.md
index 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 |
## Summary
diff --git a/docs/demo/SCREENCAST_SHOTLIST.md b/docs/demo/SCREENCAST_SHOTLIST.md
index 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 alert
card animates in from the top (the seed dataset includes a Crowdstrike
EDR 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.yaml
index 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.md
index 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 release
The existing tag-driven flow is unchanged — see the release section of
diff --git a/docs/roadmap/v8-progress.md b/docs/roadmap/v8-progress.md
index 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 investigation
contract, and a SOC-agent benchmark a third party can run against their own
agent.
-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**. Recount
with `python3 scripts/check_claim_gate_matrix.py`; do not quote a remembered
figure.
@@ -62,14 +62,21 @@ Each item is audited against the tree before any code is written, because the
v8.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.py
index 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 problems
diff --git a/scripts/readme_gates.py b/scripts/readme_gates.py
index 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.py
new file mode 100755
index 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.py
index 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, Query
from fastapi.responses import HTMLResponse
from 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_approver
from app.security.chatops_token import ChatOpsTokenError, verify_token
from app.services.blast_radius import BlastRadiusGate
from app.services.executor_registry import EXECUTOR_REGISTRY
@@ -99,34 +106,80 @@ async def submit_action(request: ActionRequest, _auth: None = Depends(require_se
return 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 execute
request = 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 record
diff --git a/services/actions/app/core/config.py b/services/actions/app/core/config.py
index 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.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 None
diff --git a/services/agents/app/api/explain.py b/services/agents/app/api/explain.py
index 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 StreamingResponse
from pydantic import BaseModel, Field
from app.core.rate_limit import RateLimitDecision, TokenBucketLimiter
+from app.llm.contract import LLMContractViolation, safe_chat_completions_request
from app.security.llm_resolver import LlmConfig, resolve_llm_config
logger = structlog.get_logger()
@@ -574,8 +575,6 @@ async def _llm_summary(
return fallback
try:
- 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 fallback
except Exception as exc:
logger.warning("explain.llm_error", error=str(exc))
return fallback
diff --git a/services/agents/app/llm/contract.py b/services/agents/app/llm/contract.py
index 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 json
import os
-import re
import time
from collections.abc import Iterable
from 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.py
new file mode 100644
index 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.py
index 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 json
import 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_alias
prompt = textwrap.dedent(
f"""
diff --git a/services/agents/app/workers/business_context.py b/services/agents/app/workers/business_context.py
index 4d39820ee..4fa76e16a 100644
--- a/services/agents/app/workers/business_context.py
+++ b/services/agents/app/workers/business_context.py
@@ -40,6 +40,25 @@ import yaml
logger = 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))
+ continue
rules.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.py
new file mode 100644
index 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_routes
diff --git a/services/agents/tests/test_llm_contract_no_bypass.py b/services/agents/tests/test_llm_contract_no_bypass.py
index 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.py
new file mode 100644
index 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.py
index 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 json
import 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_alias
prompt = textwrap.dedent(
f"""
diff --git a/services/api/app/api/v1/endpoints/detection_loop.py b/services/api/app/api/v1/endpoints/detection_loop.py
index 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 @@ Endpoints
from __future__ import annotations
import json
+import logging
import textwrap
import uuid
from datetime import UTC, datetime
from typing import Any
-import httpx
from fastapi import APIRouter, HTTPException, status
from pydantic import BaseModel, Field
from sqlalchemy import text
@@ -32,6 +32,9 @@ from sqlalchemy import text
from app.api.v1.deps import AuthUser
from app.core.config import settings
from 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.py
index 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.py
new file mode 100644
index 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("<", "&lt;").replace(">", "&gt;")
+ safe_body = body.replace("<", "&lt;").replace(">", "&gt;")
+ 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.py
index 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 text
from app.api.v1.deps import AuthUser, DBSession
from app.core.airgap import AirgapViolation, enforce_airgap_for_url
+from app.services.llm_safety import LLMContractViolation, safe_chat_completions_request
from app.services.model_aliases import resolve_model_alias
logger = logging.getLogger(__name__)
@@ -148,22 +149,22 @@ async def _generate_queries(hypothesis: str, mitre: str | None) -> dict[str, str
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": _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 None
except Exception:
return None
diff --git a/services/api/app/api/v1/endpoints/knowledge_base.py b/services/api/app/api/v1/endpoints/knowledge_base.py
index 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 uuid
from datetime import UTC, datetime
from typing import Any, Literal
-import httpx
from fastapi import APIRouter, HTTPException, status
from pydantic import BaseModel, Field
from sqlalchemy import text
@@ -29,6 +28,7 @@ from sqlalchemy import text
from app.api.v1.deps import AuthUser, DBSession
from app.core.airgap import AirgapViolation, enforce_airgap_for_url
from app.services.kb_chunking import chunk_text
+from app.services.llm_safety import LLMContractViolation, safe_chat_completions_request
from app.services.model_aliases import resolve_model_alias
logger = 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 None
except Exception:
return None
diff --git a/services/api/app/api/v1/endpoints/nl_detection.py b/services/api/app/api/v1/endpoints/nl_detection.py
index 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 json
import os
import uuid
from datetime import UTC, datetime
@@ -27,6 +28,7 @@ from app.core.airgap import AirgapViolation, enforce_airgap_for_url
from app.models.detection_proposal import DetectionRuleProposal
from app.services.detection_eval import evaluate_candidate_rule
from app.services.fixture_synth import derive_fixtures_from_sigma
+from app.services.llm_safety import LLMContractViolation, safe_chat_completions_request
logger = 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.py
index 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 uuid
from datetime import UTC, datetime
from typing import Any, Literal
-import httpx
from fastapi import APIRouter, HTTPException, Query, status
from pydantic import BaseModel, Field
from sqlalchemy import text
from app.api.v1.deps import AuthUser, DBSession
from app.core.airgap import AirgapViolation, enforce_airgap_for_url
+from app.services.llm_safety import LLMContractViolation, safe_chat_completions_request
from app.services.model_aliases import resolve_model_alias
logger = 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]) -> TriageRe
mitre_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 None
except Exception:
return None
diff --git a/services/api/app/api/v1/endpoints/translation.py b/services/api/app/api/v1/endpoints/translation.py
index 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 @@ Endpoints
from __future__ import annotations
import json
+import logging
import os
from typing import Any, Literal
-import httpx
from fastapi import APIRouter, HTTPException, status
from pydantic import BaseModel, Field
from app.core.airgap import AirgapViolation, enforce_airgap_for_url
+from app.services.llm_safety import LLMContractViolation, safe_chat_completions_request
from 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:
raise
try:
- 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 None
except Exception:
return None
diff --git a/services/api/app/api/v1/router.py b/services/api/app/api/v1/router.py
index 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 savings
diff --git a/services/api/app/services/alert_explain.py b/services/api/app/services/alert_explain.py
index 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 dataclass
from datetime import UTC, datetime, timedelta
from typing import Any
-import httpx
from sqlalchemy import and_, func, select
from sqlalchemy.ext.asyncio import AsyncSession
@@ -60,6 +59,7 @@ from app.models.alert import Alert
from app.models.detection_rule import DetectionRule
from app.services.cost_dashboard import _impute_public_cost
from app.services.llm_resolver import LlmConfig, resolve_llm_config
+from app.services.llm_safety import LLMContractViolation, safe_chat_completions_request
logger = 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: BLE001
return _LlmCallResult(
text=None,
diff --git a/services/api/app/services/effective_permissions/service.py b/services/api/app/services/effective_permissions/service.py
index 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 function
pure 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.py
index c79083dc0..67e728931 100644
--- a/services/api/app/services/email_approval.py
+++ b/services/api/app/services/email_approval.py
@@ -28,10 +28,18 @@ Design notes
alongside the rest of the payload so an attacker can't extend it
client-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: str
case_id: str
expires_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 = ""
@property
def 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 email
template generates one URL per choice and the recipient's click is
self-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) -> Approv
action_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) -> Approv
if 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) -> Approv
action_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.py
new file mode 100644
index 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.py
index 94983cde8..9893a09e1 100644
--- a/services/api/app/services/model_aliases.py
+++ b/services/api/app/services/model_aliases.py
@@ -20,7 +20,37 @@ import os
ROLES = 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_URL
diff --git a/services/api/tests/test_email_approval_endpoint.py b/services/api/tests/test_email_approval_endpoint.py
new file mode 100644
index 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.text
diff --git a/services/api/tests/test_llm_safety.py b/services/api/tests/test_llm_safety.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index e7660e385..cc1f3c8fc 100644
--- a/services/connectors/app/api/router.py
+++ b/services/connectors/app/api/router.py
@@ -29,19 +29,31 @@ import re
from typing import Any
import structlog
-from fastapi import APIRouter, HTTPException, status
+from fastapi import APIRouter, HTTPException, Query, status
from pydantic import BaseModel
from pydantic import Field as PydField
from app.connectors import CONNECTOR_REGISTRY, list_connector_schemas
from app.connectors.base import Capability
+from app.db.connector_repo import fetch_enabled_connectors
+from app.db.engine import get_engine
from app.federated.query import QueryError, parse_unified_query
+from app.security.credential_vault import CredentialVaultError, get_vault
logger = 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: TestConnectionRe
return 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.go
new file mode 100644
index 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.go
index 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 string
Client *http.Client
@@ -162,9 +179,17 @@ func (p *HTTPProvider) GetResourceConfig(ctx context.Context, connectorID, resou
if 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.py
index 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_ID
try:
- 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.py
index 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.py
index 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_on
self.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.asyncio
async 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.py
index 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_on
self.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.py
index 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 error
log.warning(
"teams_callback.upstream_failed",
diff --git a/services/teams-bot/app/services/aisoc_clients.py b/services/teams-bot/app/services/aisoc_clients.py
index 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]:
pass
async 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.py
new file mode 100644
index 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 == []