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.

fix(ci): build the console image natively per architecture so the published image tracks main (#889)

Beenu Arora41ad1f4ca5bf
diff --git a/.github/workflows/image-availability.yml b/.github/workflows/image-availability.yml
new file mode 100644
index 000000000..6e70d04fa
--- /dev/null
+++ b/.github/workflows/image-availability.yml
@@ -0,0 +1,88 @@
+name: Image availability
+
+# The registry has to hold what the deployment files tell people to pull.
+#
+# Nothing checked that, and the result was not hypothetical: `aisoc-web:latest`
+# — what `docker compose up` pulls for the console — spent a day built from a
+# commit two releases behind `main`, `aisoc-web:v11.0.0` was never pushed while
+# the rest of that release was, and three images `docker-compose.yml` names had
+# never been published once. Every workflow was green throughout, because a
+# green workflow says a job ran, not that the registry holds anything.
+#
+# Only the registry can answer this, so scripts/check_published_images.py asks
+# it — and the answer is about `main`, never about a pull request, which is why
+# the schedule is the gate here and the pull-request job proves only that the
+# gate still detects what it claims to.
+#
+# The loop is also closed at the point of publishing: publish-images.yml and
+# release.yml each run this same script after their manifests are pushed, so a
+# half-published release fails the run that half-published it rather than
+# waiting for tomorrow.
+
+on:
+ schedule:
+ # 06:42 UTC daily. Off the hour because the runner pool is busiest on it,
+ # and a job that queues past its window is a job that did not run.
+ - cron: '42 6 * * *'
+ workflow_dispatch:
+ pull_request:
+ branches: [main]
+ paths:
+ - 'docker-compose.yml'
+ - 'infra/helm/aisoc/**'
+ - 'scripts/check_published_images.py'
+ - 'scripts/gate_toolkit.py'
+ - '.github/workflows/image-availability.yml'
+
+permissions:
+ contents: read
+
+concurrency:
+ group: image-availability-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ registry:
+ name: Every image the deployment files name exists
+ # Only against `main`. A pull request cannot change what is in the
+ # registry, and a PR that adds a service to docker-compose.yml names an
+ # image that cannot exist until that PR has merged and published — so
+ # asking the registry there would block the one change that fixes it.
+ if: github.event_name != 'pull_request'
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+ with:
+ # The freshness half reads `VERSION` as of the commit each published
+ # image records in org.opencontainers.image.revision. A shallow
+ # clone cannot, and the gate reports that as unverified rather than
+ # clean — correct, but useless as a gate.
+ fetch-depth: 0
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: '3.11'
+ - run: python -m pip install --quiet pyyaml
+
+ # Self-test first, on the same tree: a gate that has quietly stopped
+ # detecting anything fails here rather than printing OK below.
+ - name: The gate detects the drift it claims to
+ run: python3 scripts/check_published_images.py --self-test
+
+ # --require-network because this job exists to ask the registry. A skip
+ # would be a green run that verified nothing, which is the shape the
+ # gate was written against.
+ - name: Every reference resolves, at the version the tree is on
+ run: python3 scripts/check_published_images.py --require-fresh --require-network --list
+
+ self-test:
+ name: The image-availability gate still works
+ if: github.event_name == 'pull_request'
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: '3.11'
+ - run: python -m pip install --quiet pyyaml
+ - name: The gate detects the drift it claims to
+ run: python3 scripts/check_published_images.py --self-test
diff --git a/.github/workflows/publish-images.yml b/.github/workflows/publish-images.yml
index a6f62ad65..aab335b07 100644
--- a/.github/workflows/publish-images.yml
+++ b/.github/workflows/publish-images.yml
@@ -20,9 +20,22 @@ on:
- '.github/workflows/publish-images.yml'
workflow_dispatch:
+# Deliberately NOT cancel-in-progress.
+#
+# Cancelling a test run discards a result nobody needs. Cancelling a run that
+# *pushes artefacts* leaves the registry holding a partial set, and that is
+# not hypothetical: on the v11.0.0 merge this job was cancelled mid-build by
+# the next push while twelve of thirteen images had already published, so the
+# console image alone stayed two commits behind `main` and the run reported
+# `cancelled` rather than `failed`. Nothing was red, and the image a
+# self-hoster pulls was not the product on `main`.
+#
+# Queuing instead costs runner minutes and can leave `:latest` a few minutes
+# behind on a busy day. GitHub runs a concurrency group in order, so the last
+# push still wins the moving tags, and every run completes its push.
concurrency:
group: publish-images-${{ github.ref }}
- cancel-in-progress: true
+ cancel-in-progress: false
permissions:
contents: read
@@ -31,12 +44,65 @@ permissions:
id-token: write
jobs:
+ # ── Per-architecture build, each on a runner of that architecture ────────
+ #
+ # This used to be one job per image building both architectures together,
+ # with QEMU emulating arm64 on an amd64 runner. Measured against the v11.0.0
+ # release, per BuildKit's own step timings:
+ #
+ # pnpm install --frozen-lockfile amd64 15.0s arm64 114.2s
+ # pnpm --filter … build (Next.js) amd64 45.0s arm64 281.6s
+ #
+ # so emulation cost roughly 7x on a good run — and on a bad one it did not
+ # finish at all. In the v11.0.0 release run the arm64 `pnpm install` ran for
+ # 6,358 seconds and was still going when the job was killed, 56x its own
+ # normal time, while the amd64 leg of the same build completed in 100s. Node
+ # under QEMU user-mode emulation does this unpredictably; the slow step is
+ # the dependency install rather than the compile, which is why no amount of
+ # Next.js tuning would have touched it.
+ #
+ # Building each architecture natively removes the emulator rather than
+ # budgeting for it, so the livelock class is gone and arm64 costs about what
+ # amd64 does. arm64 itself stays: Apple Silicon is the majority of
+ # contributor laptops and an amd64-only manifest makes `pnpm aisoc:demo`
+ # fall back to a long silent build there. The original comment argued a
+ # first run that cannot start is worse than a slower release; that is still
+ # true, and it is now also no longer the choice on offer.
+ #
+ # Each leg pushes by digest only. The tags are attached once, by the merge
+ # job below, so a half-finished multi-arch build can never claim `:latest`.
build:
- name: ${{ matrix.service }}
- runs-on: ubuntu-latest
+ name: ${{ matrix.service }} (${{ matrix.platform }})
+ runs-on: ${{ matrix.platform == 'arm64' && 'ubuntu-24.04-arm' || 'ubuntu-24.04' }}
+ # A build that stops making progress must say so rather than run until
+ # GitHub's six-hour ceiling. The slowest image on a cold cache is the
+ # console at roughly five minutes per architecture; 30 leaves room for a
+ # cache miss and still fails the same morning.
+ timeout-minutes: 30
strategy:
fail-fast: false
matrix:
+ platform: [amd64, arm64]
+ service:
+ - api
+ - agents
+ - realtime
+ - web
+ - web-demo
+ - ingest
+ - enrichment
+ - fusion
+ - actions
+ - connectors
+ - threatintel
+ - ueba
+ - slack-bot
+ - honeytokens
+ - purple-team
+ - osquery-tls
+ # `include` entries whose `service` matches an existing combination add
+ # their remaining keys to it rather than creating new ones, so each
+ # block below applies to both platforms of that one service.
include:
# Demo-stack images (must always be fresh; pnpm aisoc:demo pulls these by tag).
- service: api
@@ -110,17 +176,27 @@ jobs:
context: services/slack-bot
dockerfile: Dockerfile
image: ghcr.io/beenuar/aisoc-slack-bot
+
+ # Named by docker-compose.yml and the Helm chart since they were
+ # written, and published by nothing until now — so `docker compose
+ # --profile extras up` silently built them from source every time,
+ # and `helm install` could only ever have produced ImagePullBackOff.
+ # scripts/check_published_images.py is what stops that recurring.
+ - service: honeytokens
+ context: services/honeytokens
+ dockerfile: Dockerfile
+ image: ghcr.io/beenuar/aisoc-honeytokens
+ - service: purple-team
+ context: services/purple-team
+ dockerfile: Dockerfile
+ image: ghcr.io/beenuar/aisoc-purple-team
+ - service: osquery-tls
+ context: services/osquery-tls
+ dockerfile: Dockerfile
+ image: ghcr.io/beenuar/aisoc-osquery-tls
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@99012661954931238ded8c8b007157a8430204e1 # v4
-
- uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4
- uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
@@ -129,18 +205,13 @@ jobs:
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
+ # Labels only. The tags are the merge job's business — a per-architecture
+ # image is half a manifest and must never be reachable by a name an
+ # operator pulls.
- id: meta
uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6
with:
images: ${{ matrix.image }}
- # The demo build shares the repository but never the moving tags a
- # self-hoster pulls. `latest` and `main` are the product.
- tags: |
- type=raw,value=main,enable=${{ github.ref == 'refs/heads/main' && matrix.demo != 'true' }}
- type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' && matrix.demo != 'true' }}
- type=sha,prefix=sha-,format=short,enable=${{ matrix.demo != 'true' }}
- type=raw,value=demo,enable=${{ github.ref == 'refs/heads/main' && matrix.demo == 'true' }}
- type=sha,prefix=demo-sha-,format=short,enable=${{ matrix.demo == 'true' }}
# Only the `demo` tag gets the NEXT_PUBLIC_DEMO_* flags. Next inlines
# them at build time, so this is the whole difference between the two
@@ -169,29 +240,153 @@ jobs:
with:
context: ${{ matrix.context }}
file: ${{ matrix.context }}/${{ matrix.dockerfile }}
- push: true
- tags: ${{ steps.meta.outputs.tags }}
+ platforms: linux/${{ matrix.platform }}
labels: ${{ steps.meta.outputs.labels }}
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 }}
- # 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
+ # Scoped per architecture now that the two are separate jobs: one
+ # scope written by two concurrent jobs is a cache each of them can
+ # only partially trust.
+ cache-from: type=gha,scope=${{ matrix.service }}-${{ matrix.platform }}
+ cache-to: type=gha,mode=max,scope=${{ matrix.service }}-${{ matrix.platform }}
+ outputs: type=image,name=${{ matrix.image }},push-by-digest=true,name-canonical=true,push=true
# SLSA provenance + SPDX SBOM attached to the image by BuildKit.
provenance: mode=max
sbom: true
+ # The digest is all the merge job needs, and an empty file named after it
+ # is the smallest thing that carries it between jobs.
+ - name: Export digest
+ env:
+ DIGEST: ${{ steps.build.outputs.digest }}
+ run: |
+ set -euo pipefail
+ test -n "$DIGEST"
+ mkdir -p /tmp/digests
+ touch "/tmp/digests/${DIGEST#sha256:}"
+
+ - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+ with:
+ name: digest-${{ matrix.service }}-${{ matrix.platform }}
+ path: /tmp/digests/*
+ if-no-files-found: error
+ retention-days: 1
+
+ # ── Assemble the manifest list and attach the tags ──────────────────────
+ #
+ # Both architectures exist before any operator-visible name points at them,
+ # so `:latest` moves atomically or not at all. Signing and the SBOM
+ # attestation live here too, over the index digest, which is what
+ # `cosign verify` is given in docs/operations/verifying-releases.md.
+ merge:
+ name: manifest (${{ matrix.service }})
+ runs-on: ubuntu-24.04
+ needs: build
+ timeout-minutes: 15
+ strategy:
+ fail-fast: false
+ matrix:
+ service:
+ - api
+ - agents
+ - realtime
+ - web
+ - web-demo
+ - ingest
+ - enrichment
+ - fusion
+ - actions
+ - connectors
+ - threatintel
+ - ueba
+ - slack-bot
+ - honeytokens
+ - purple-team
+ - osquery-tls
+ include:
+ - service: api
+ image: ghcr.io/beenuar/aisoc-core-api
+ - service: agents
+ image: ghcr.io/beenuar/aisoc-agents
+ - service: realtime
+ image: ghcr.io/beenuar/aisoc-realtime
+ - service: web
+ image: ghcr.io/beenuar/aisoc-web
+ - service: web-demo
+ image: ghcr.io/beenuar/aisoc-web
+ demo: 'true'
+ - service: ingest
+ image: ghcr.io/beenuar/aisoc-ingest
+ - service: enrichment
+ image: ghcr.io/beenuar/aisoc-enrichment
+ - service: fusion
+ image: ghcr.io/beenuar/aisoc-fusion
+ - service: actions
+ image: ghcr.io/beenuar/aisoc-actions
+ - service: connectors
+ image: ghcr.io/beenuar/aisoc-connectors
+ - service: threatintel
+ image: ghcr.io/beenuar/aisoc-threatintel
+ - service: ueba
+ image: ghcr.io/beenuar/aisoc-ueba
+ - service: slack-bot
+ image: ghcr.io/beenuar/aisoc-slack-bot
+ - service: honeytokens
+ image: ghcr.io/beenuar/aisoc-honeytokens
+ - service: purple-team
+ image: ghcr.io/beenuar/aisoc-purple-team
+ - service: osquery-tls
+ image: ghcr.io/beenuar/aisoc-osquery-tls
+ steps:
+ - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+ with:
+ path: /tmp/digests
+ pattern: digest-${{ matrix.service }}-*
+ merge-multiple: true
+
+ - uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4
+
+ - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
+ with:
+ registry: ghcr.io
+ username: ${{ github.actor }}
+ password: ${{ secrets.GITHUB_TOKEN }}
+
+ # The demo build shares the repository but never the moving tags a
+ # self-hoster pulls. `latest` and `main` are the product.
+ - id: meta
+ uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6
+ with:
+ images: ${{ matrix.image }}
+ tags: |
+ type=raw,value=main,enable=${{ github.ref == 'refs/heads/main' && matrix.demo != 'true' }}
+ type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' && matrix.demo != 'true' }}
+ type=sha,prefix=sha-,format=short,enable=${{ matrix.demo != 'true' }}
+ type=raw,value=demo,enable=${{ github.ref == 'refs/heads/main' && matrix.demo == 'true' }}
+ type=sha,prefix=demo-sha-,format=short,enable=${{ matrix.demo == 'true' }}
+
+ - name: Create manifest list and push
+ id: manifest
+ working-directory: /tmp/digests
+ env:
+ IMAGE: ${{ matrix.image }}
+ run: |
+ set -euo pipefail
+ # One digest file per architecture. Fewer means a leg did not run,
+ # and publishing a single-architecture manifest under `:latest` is
+ # the silent half-publish this job exists to prevent.
+ count=$(find . -type f | wc -l | tr -d ' ')
+ if [ "$count" -ne 2 ]; then
+ echo "::error::expected 2 per-architecture digests for ${IMAGE}, found ${count}" >&2
+ exit 1
+ fi
+ mapfile -t tags < <(jq -r '.tags[]' <<< "$DOCKER_METADATA_OUTPUT_JSON")
+ docker buildx imagetools create \
+ "${tags[@]/#/--tag=}" \
+ $(printf "${IMAGE}@sha256:%s " *)
+ digest=$(docker buildx imagetools inspect "${tags[0]}" --format '{{json .Manifest}}' | jq -r '.digest')
+ echo "digest=${digest}" >> "$GITHUB_OUTPUT"
+ echo "Published ${IMAGE} @ ${digest} as: ${tags[*]}"
+
# ── Supply-chain attestation (Phase 2 continuation) ──────────────────
# 1. cosign keyless (OIDC) signature over the pushed digest.
# 2. CycloneDX SBOM generated by syft and attached as a cosign
@@ -208,12 +403,12 @@ jobs:
- name: Sign image (cosign keyless)
env:
- DIGEST: ${{ steps.build.outputs.digest }}
+ DIGEST: ${{ steps.manifest.outputs.digest }}
run: cosign sign --yes "${{ matrix.image }}@${DIGEST}"
- name: Attach CycloneDX SBOM attestation
env:
- DIGEST: ${{ steps.build.outputs.digest }}
+ DIGEST: ${{ steps.manifest.outputs.digest }}
run: |
set -euo pipefail
syft "${{ matrix.image }}@${DIGEST}" -o cyclonedx-json > /tmp/sbom.cdx.json
@@ -221,3 +416,27 @@ jobs:
--type cyclonedx \
--predicate /tmp/sbom.cdx.json \
"${{ matrix.image }}@${DIGEST}"
+
+ # ── Prove the registry now holds what the deployment files name ─────────
+ #
+ # The loop this workflow never closed. It reported success on the v11.0.0
+ # merge while `aisoc-web:latest` stayed two commits behind `main`, because
+ # "the job ran" and "the registry holds the image" are different facts and
+ # only the first was ever checked. This asks the registry.
+ verify:
+ name: Published images match the tree
+ runs-on: ubuntu-24.04
+ needs: merge
+ timeout-minutes: 10
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+ with:
+ # The gate reads VERSION as of the commit each image records in
+ # org.opencontainers.image.revision; a shallow clone cannot.
+ fetch-depth: 0
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: '3.11'
+ - run: python -m pip install --quiet pyyaml
+ - name: Every image docker-compose.yml and the chart name resolves
+ run: python3 scripts/check_published_images.py --require-fresh --require-network --list
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 452d820f8..283ae2af1 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -4,6 +4,25 @@ on:
push:
tags:
- 'v*.*.*'
+ # Re-run the image half of a release that only partly published.
+ #
+ # v11.0.0 is the case: twelve images carried the tag and the console did
+ # not, because its arm64 leg livelocked under QEMU and was still running
+ # hours later. Without this the only way to finish that release was to
+ # invent a new tag for a commit that had already shipped — so the registry
+ # stayed wrong because correcting it was more disruptive than leaving it.
+ #
+ # Dispatch this from `main` so the current workflow definition runs, and
+ # name the tag to publish; the build checks that tag out for its source.
+ # The GitHub Release, npm and PyPI jobs are push-only and stay skipped,
+ # because re-publishing a package version is not a thing registries allow
+ # and re-cutting a release note is not a thing anyone wants.
+ workflow_dispatch:
+ inputs:
+ tag:
+ description: 'Existing release tag whose images should be (re)published, e.g. v11.0.0'
+ required: true
+ type: string
permissions:
contents: write
@@ -15,6 +34,7 @@ jobs:
release:
name: Create GitHub Release
runs-on: ubuntu-latest
+ if: github.event_name == 'push'
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
with:
@@ -28,7 +48,7 @@ jobs:
# to travel through a step output into an action *input*, which becomes a
# process argument — and v10.0.0's section is 263,761 characters, so the
# runner died with `Argument list too long` before the API was reached.
- # Because docker-push, npm-publish and pypi-publish all `needs: release`,
+ # Because docker-build, npm-publish and pypi-publish all `needs: release`,
# one oversized note skipped every image and every package in the
# release: the whole publish, lost to a shell limit.
#
@@ -176,13 +196,51 @@ jobs:
# whose `:main` / `:latest` tag is published on push-to-main also needs a
# pinned `:vX.Y.Z` tag on release, so users who set `AISOC_VERSION=vX.Y.Z`
# in their .env get a reproducible deploy across the full stack.
- docker-push:
- name: Docker — Build & Push (${{ matrix.service }})
- runs-on: ubuntu-latest
+ # ── Per-architecture build, each on a runner of that architecture ────────
+ #
+ # Same split, and the same reason, as publish-images.yml. It was this
+ # workflow that proved the point: in the v11.0.0 release run every image
+ # published except the console, whose arm64 `pnpm install --frozen-lockfile`
+ # ran for 6,358 seconds under QEMU without finishing — 56x its own normal
+ # 114s — while the amd64 leg of the identical build completed in 100s. The
+ # release was green, `aisoc-web:v11.0.0` simply never existed, and a partial
+ # release is worse than a failed one because nothing says so.
+ #
+ # Native runners remove the emulator rather than budgeting for it. arm64
+ # stays because Apple Silicon is the majority of contributor laptops and an
+ # amd64-only manifest turns the quickstart into a long silent build there.
+ docker-build:
+ name: Docker — Build (${{ matrix.service }}, ${{ matrix.platform }})
+ runs-on: ${{ matrix.platform == 'arm64' && 'ubuntu-24.04-arm' || 'ubuntu-24.04' }}
needs: release
+ # `needs` alone would skip this whenever `release` is skipped, which is
+ # every dispatched run — the one path that exists to publish images.
+ if: always() && needs.release.result != 'failure' && needs.release.result != 'cancelled'
+ timeout-minutes: 30
strategy:
fail-fast: false
matrix:
+ platform: [amd64, arm64]
+ service:
+ - api
+ - agents
+ - realtime
+ - web
+ - web-demo
+ - ingest
+ - enrichment
+ - fusion
+ - actions
+ - connectors
+ - threatintel
+ - ueba
+ - slack-bot
+ - honeytokens
+ - purple-team
+ - osquery-tls
+ # `include` entries whose `service` matches an existing combination add
+ # their remaining keys to it rather than creating new ones, so each
+ # block below applies to both platforms of that one service.
include:
# Demo-stack images (pulled by `pnpm aisoc:demo`).
- service: api
@@ -247,23 +305,44 @@ jobs:
context: services/slack-bot
dockerfile: Dockerfile
image: ghcr.io/beenuar/aisoc-slack-bot
+
+ # Named by docker-compose.yml and the Helm chart since they were
+ # written, and published by nothing until now. The chart has no
+ # build fallback, so `helm install` could only ever have produced
+ # ImagePullBackOff for these three.
+ - service: honeytokens
+ context: services/honeytokens
+ dockerfile: Dockerfile
+ image: ghcr.io/beenuar/aisoc-honeytokens
+ - service: purple-team
+ context: services/purple-team
+ dockerfile: Dockerfile
+ image: ghcr.io/beenuar/aisoc-purple-team
+ - service: osquery-tls
+ context: services/osquery-tls
+ dockerfile: Dockerfile
+ image: ghcr.io/beenuar/aisoc-osquery-tls
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@99012661954931238ded8c8b007157a8430204e1 # v4
+ with:
+ ref: ${{ inputs.tag || github.ref_name }}
- uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4
+
- uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
+ # Labels only. The release tags are attached by docker-manifest below,
+ # once both architectures exist — a `vX.Y.Z` tag that resolves to half a
+ # manifest is not a release anybody can reproduce.
+ - id: meta
+ uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6
+ with:
+ images: ${{ matrix.image }}
+
# Only the demo build gets the NEXT_PUBLIC_DEMO_* flags, and only it is
# published under a demo tag. Mirrors publish-images.yml. Other images
# gate demo behaviour at runtime via AISOC_DEMO_MODE so they need no
@@ -282,6 +361,115 @@ jobs:
echo 'EOF'
} >> "$GITHUB_OUTPUT"
+ - id: build
+ uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
+ with:
+ context: ${{ matrix.context }}
+ file: ${{ matrix.context }}/${{ matrix.dockerfile }}
+ platforms: linux/${{ matrix.platform }}
+ labels: ${{ steps.meta.outputs.labels }}
+ build-args: ${{ steps.web-build-args.outputs.build_args }}
+ # Scoped per architecture now that the two are separate jobs, and
+ # shared with publish-images.yml so a release reuses the layers the
+ # merge that preceded it already built.
+ cache-from: type=gha,scope=${{ matrix.service }}-${{ matrix.platform }}
+ cache-to: type=gha,mode=max,scope=${{ matrix.service }}-${{ matrix.platform }}
+ outputs: type=image,name=${{ matrix.image }},push-by-digest=true,name-canonical=true,push=true
+ # SLSA provenance + SPDX SBOM attached to the image by BuildKit.
+ provenance: mode=max
+ sbom: true
+
+ - name: Export digest
+ env:
+ DIGEST: ${{ steps.build.outputs.digest }}
+ run: |
+ set -euo pipefail
+ test -n "$DIGEST"
+ mkdir -p /tmp/digests
+ touch "/tmp/digests/${DIGEST#sha256:}"
+
+ - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+ with:
+ name: digest-${{ matrix.service }}-${{ matrix.platform }}
+ path: /tmp/digests/*
+ if-no-files-found: error
+ retention-days: 1
+
+ # ── Assemble the manifest list and attach the release tags ──────────────
+ docker-manifest:
+ name: Docker — Publish (${{ matrix.service }})
+ runs-on: ubuntu-24.04
+ needs: docker-build
+ timeout-minutes: 15
+ strategy:
+ fail-fast: false
+ matrix:
+ service:
+ - api
+ - agents
+ - realtime
+ - web
+ - web-demo
+ - ingest
+ - enrichment
+ - fusion
+ - actions
+ - connectors
+ - threatintel
+ - ueba
+ - slack-bot
+ - honeytokens
+ - purple-team
+ - osquery-tls
+ include:
+ - service: api
+ image: ghcr.io/beenuar/aisoc-core-api
+ - service: agents
+ image: ghcr.io/beenuar/aisoc-agents
+ - service: realtime
+ image: ghcr.io/beenuar/aisoc-realtime
+ - service: web
+ image: ghcr.io/beenuar/aisoc-web
+ - service: web-demo
+ image: ghcr.io/beenuar/aisoc-web
+ demo: 'true'
+ - service: ingest
+ image: ghcr.io/beenuar/aisoc-ingest
+ - service: enrichment
+ image: ghcr.io/beenuar/aisoc-enrichment
+ - service: fusion
+ image: ghcr.io/beenuar/aisoc-fusion
+ - service: actions
+ image: ghcr.io/beenuar/aisoc-actions
+ - service: connectors
+ image: ghcr.io/beenuar/aisoc-connectors
+ - service: threatintel
+ image: ghcr.io/beenuar/aisoc-threatintel
+ - service: ueba
+ image: ghcr.io/beenuar/aisoc-ueba
+ - service: slack-bot
+ image: ghcr.io/beenuar/aisoc-slack-bot
+ - service: honeytokens
+ image: ghcr.io/beenuar/aisoc-honeytokens
+ - service: purple-team
+ image: ghcr.io/beenuar/aisoc-purple-team
+ - service: osquery-tls
+ image: ghcr.io/beenuar/aisoc-osquery-tls
+ steps:
+ - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+ with:
+ path: /tmp/digests
+ pattern: digest-${{ matrix.service }}-*
+ merge-multiple: true
+
+ - uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4
+
+ - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
+ with:
+ registry: ghcr.io
+ username: ${{ github.actor }}
+ password: ${{ secrets.GITHUB_TOKEN }}
+
# `vX.Y.Z-demo` is pinnable the same way `vX.Y.Z` is, and `demo` tracks
# the newest one. Neither `vX.Y.Z` nor `latest` ever carries a demo
# bundle.
@@ -290,41 +478,38 @@ jobs:
{
echo 'tags<<EOF'
if [ "${{ matrix.demo }}" = "true" ]; then
- echo "${{ matrix.image }}:${{ github.ref_name }}-demo"
+ echo "${{ matrix.image }}:${{ inputs.tag || github.ref_name }}-demo"
echo "${{ matrix.image }}:demo"
else
- echo "${{ matrix.image }}:${{ github.ref_name }}"
+ echo "${{ matrix.image }}:${{ inputs.tag || github.ref_name }}"
echo "${{ matrix.image }}:latest"
fi
echo 'EOF'
} >> "$GITHUB_OUTPUT"
- - id: build
- uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
- with:
- context: ${{ matrix.context }}
- file: ${{ matrix.context }}/${{ matrix.dockerfile }}
- push: true
- tags: ${{ steps.image-tags.outputs.tags }}
- 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 }}
- # 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
+ - name: Create manifest list and push
+ id: manifest
+ working-directory: /tmp/digests
+ env:
+ IMAGE: ${{ matrix.image }}
+ TAGS: ${{ steps.image-tags.outputs.tags }}
+ run: |
+ set -euo pipefail
+ # One digest file per architecture. Fewer means a leg did not run,
+ # and a `vX.Y.Z` tag resolving to a single-architecture manifest is
+ # the silent half-release this job exists to prevent.
+ count=$(find . -type f | wc -l | tr -d ' ')
+ if [ "$count" -ne 2 ]; then
+ echo "::error::expected 2 per-architecture digests for ${IMAGE}, found ${count}" >&2
+ exit 1
+ fi
+ mapfile -t tags <<< "$TAGS"
+ docker buildx imagetools create \
+ "${tags[@]/#/--tag=}" \
+ $(printf "${IMAGE}@sha256:%s " *)
+ digest=$(docker buildx imagetools inspect "${tags[0]}" --format '{{json .Manifest}}' | jq -r '.digest')
+ echo "digest=${digest}" >> "$GITHUB_OUTPUT"
+ echo "Published ${IMAGE} @ ${digest} as: ${tags[*]}"
# ── Supply-chain attestation (mirrors publish-images.yml) ────────────
# Keyless cosign signature + CycloneDX SBOM attestation per released
@@ -339,12 +524,12 @@ jobs:
- name: Sign image (cosign keyless)
env:
- DIGEST: ${{ steps.build.outputs.digest }}
+ DIGEST: ${{ steps.manifest.outputs.digest }}
run: cosign sign --yes "${{ matrix.image }}@${DIGEST}"
- name: Attach CycloneDX SBOM attestation
env:
- DIGEST: ${{ steps.build.outputs.digest }}
+ DIGEST: ${{ steps.manifest.outputs.digest }}
run: |
set -euo pipefail
syft "${{ matrix.image }}@${DIGEST}" -o cyclonedx-json > /tmp/sbom.cdx.json
@@ -371,6 +556,7 @@ jobs:
name: npm — publish ${{ matrix.pkg }}
runs-on: ubuntu-latest
needs: release
+ if: github.event_name == 'push'
permissions:
contents: read
id-token: write # npm provenance attestation
@@ -467,6 +653,7 @@ jobs:
name: PyPI — publish ${{ matrix.pkg }}
runs-on: ubuntu-latest
needs: release
+ if: github.event_name == 'push'
permissions:
contents: read
id-token: write # PyPI trusted publishing
@@ -512,3 +699,26 @@ jobs:
if: vars.AISOC_PYPI_TRUSTED_PUBLISHING != 'true'
run: |
echo "::warning title=PyPI::Trusted publishing is not enabled, so ${{ matrix.pkg }} was built and validated but not uploaded. Set the AISOC_PYPI_TRUSTED_PUBLISHING repository variable to 'true' once the pending publishers exist — see docs/operations/publishing.md."
+
+ # ── Prove the release actually published every image ────────────────────
+ #
+ # v11.0.0 is why this exists: twelve images carried the tag, the console did
+ # not, and the release reported success because every job that finished had
+ # finished. A release is the set of artefacts it published, so it has to be
+ # checked against the registry rather than against its own job statuses.
+ docker-verify:
+ name: Docker — Released images match the tree
+ runs-on: ubuntu-24.04
+ needs: docker-manifest
+ timeout-minutes: 10
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+ with:
+ ref: ${{ inputs.tag || github.ref_name }}
+ fetch-depth: 0
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: '3.11'
+ - run: python -m pip install --quiet pyyaml
+ - name: Every image docker-compose.yml and the chart name resolves
+ run: python3 scripts/check_published_images.py --require-fresh --require-network --list
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8593fcaa4..34e361ecb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -81,8 +81,87 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
which was actively misleading, because the banner copy is an inlined
constant present in the HTML either way.
+- **The console image a self-hoster pulls now tracks `main`, and a release
+ that publishes only some of its images now fails.** The fix above shipped to
+ nobody: `ghcr.io/beenuar/aisoc-web:latest` — what the documented
+ `docker compose up` pulls — was built from a commit two releases behind
+ `main`, and `aisoc-web:v11.0.0` was never pushed at all while
+ `aisoc-core-api`, `aisoc-fusion` and `aisoc-ingest` all carried that tag.
+ Every workflow was green throughout, which is the whole problem: a green
+ workflow says a job ran, not that the registry holds anything.
+
+ The cause was arm64 cross-building under QEMU on an amd64 runner. Measured
+ from BuildKit's own step timings in the v11.0.0 release run, emulation cost
+ roughly 7x on a good run — `pnpm install --frozen-lockfile` 15.0s on amd64
+ against 114.2s on arm64, the Next.js build 45.0s against 281.6s — and on a
+ bad run it did not converge at all: that release's arm64 `pnpm install` ran
+ **6,358 seconds without finishing**, 56x its own normal time, while the
+ amd64 leg of the identical build completed in 100s. The slow step is the
+ dependency install rather than the compile, so it was never a Next.js
+ problem, and it is intermittent rather than a steady cost — the same build
+ succeeded in five minutes on another runner while that one was still stuck.
+
+ Both `publish-images.yml` and `release.yml` now build each architecture on a
+ runner of that architecture and merge the two into a manifest list, so the
+ emulator is gone rather than budgeted for. arm64 itself stays: Apple Silicon
+ is the majority of contributor laptops, and an amd64-only manifest turns the
+ quickstart into a long silent build there. Every leg pushes by digest and
+ the tags are attached once, after both exist, so `:latest` can no longer
+ resolve to half a manifest.
+
+ `publish-images.yml` also no longer cancels itself. `cancel-in-progress` is
+ thrift on a test run and a correctness bug on a run that pushes artefacts —
+ it is what left twelve images at the new commit and the thirteenth two
+ behind, reported as `cancelled` rather than `failed`. Runs now queue. And
+ `release.yml` gained a `workflow_dispatch` that republishes the images for
+ an existing tag, because the only way to finish a half-published release was
+ previously to invent a new tag for a commit that had already shipped.
+
+- **`aisoc-honeytokens`, `aisoc-purple-team` and `aisoc-osquery-tls` are
+ published.** All three were named by `docker-compose.yml` since it was
+ written and built by nothing, so `--profile extras` silently compiled them
+ from source every time. The Helm chart has no such fallback and named two of
+ them, so those pods could only ever have reached `ImagePullBackOff`.
+
+- **The Helm chart could not install at all.** Every image tag defaults to
+ `Chart.AppVersion`, which read `5.2.0` — a tag that exists for no image in
+ the registry — so a default `helm install` would have failed to pull on
+ every pod. It now pins a tag that exists. The chart also named
+ `ghcr.io/beenuar/aisoc-alert-fusion`, which has never existed under any tag;
+ the image the publish matrix builds is `aisoc-fusion`.
+
+- **Deployment docs named four images that have never been published.**
+ `deployment/kubernetes.md` listed seven images at `v5.2.0` — including
+ `aisoc-api` and `aisoc-mcp`, neither of which exists under any tag — and its
+ `helm install` passed `--set api.image.tag=…`, a path no template reads,
+ since every service lives under `services.<name>`. The overrides therefore
+ changed nothing and the tag they set existed for nothing. `deployment/
+ docker.md`, the Vault connector page, and the Azure and GCP Terraform
+ defaults — the `api_image` variable a `terraform apply` uses, which pointed
+ at `aisoc-api` — named the same non-existent images. The gate now
+ resolves fully-written first-party references in tracked prose too —
+ existence only, since a release note naming an older image is describing
+ history rather than instructing anybody.
+
### Added
+- `scripts/check_published_images.py` — the gate none of the above had. It
+ resolves every image reference in `docker-compose.yml` and the Helm chart
+ the way the tooling that reads them does (`${AISOC_VERSION:-latest}` to its
+ default, an empty chart `tag:` to `Chart.AppVersion`) and asks GHCR whether
+ each one is there, optionally checking that the version inside matches the
+ tree. Against `main` before this change it reported 14 findings across both
+ files. Third-party images are counted and named but not resolved: this
+ checks the images *this project publishes*, and upstream availability is not
+ a claim this repository makes. Offline it prints `SKIPPED` and never `OK`,
+ because a skip is not a pass; `--require-network` makes unreachable a
+ failure, which is what the scheduled job uses. `--self-test` covers 28
+ assertions including every shape the registry was actually in.
+
+- `.github/workflows/image-availability.yml` — runs that gate daily against
+ `main`, and `publish-images.yml` and `release.yml` each run it over their own
+ output, so a half-published release fails the run that half-published it.
+
- `apps/docs/docs/deployment/single-host.md` — the path for a server you reach
over the network: publishing the console, pointing it at your services,
confirming what the deployment thinks it is, and what changes on the way to
diff --git a/RELEASES.md b/RELEASES.md
index aa78dede0..a23391bf1 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 `v11.0.0`, released 2026-09-25 — a release about the gap between what this project published and what a stranger actually got. Following the documented quick start broke the credential vault; `make up` then reported the stack broken on every machine while it was healthy; and the profile a new user runs had no real data and no model behind it. **It is a major because upgrading requires action on two items** — the ingest API now demands a credential instead of believing a caller-supplied tenant header, and CORE now needs 8 GB of memory and 20 GB of disk. Every product claim is backed by a failing CI test (claim-to-gate matrix: 145 rows — 137 GATED / 8 PARTIAL / 0 NO GATE, counted from the table by `scripts/check_claim_gate_matrix.py`). The latest GitHub release with notes and downloads: <https://github.com/beenuar/AiSOC/releases/latest>.
+> **TL;DR for first-time visitors:** AiSOC is on `v11.0.0`, released 2026-09-25 — a release about the gap between what this project published and what a stranger actually got. Following the documented quick start broke the credential vault; `make up` then reported the stack broken on every machine while it was healthy; and the profile a new user runs had no real data and no model behind it. **It is a major because upgrading requires action on two items** — the ingest API now demands a credential instead of believing a caller-supplied tenant header, and CORE now needs 8 GB of memory and 20 GB of disk. Every product claim is backed by a failing CI test (claim-to-gate matrix: 146 rows — 138 GATED / 8 PARTIAL / 0 NO GATE, counted from the table by `scripts/check_claim_gate_matrix.py`). The latest GitHub release with notes and downloads: <https://github.com/beenuar/AiSOC/releases/latest>.
---
diff --git a/ROADMAP.md b/ROADMAP.md
index 1656950b3..8711cb171 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 **145 rows — 137 GATED / 8 PARTIAL / 0 NO GATE** — **every product claim is backed by a failing test** and the ratchet (`MAX_NO_GATE=0`) forbids any regression. The 8 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. The six lettered deferrals are scoped in [`docs/audit/DEFERRED_SUBPHASES.md`](docs/audit/DEFERRED_SUBPHASES.md).
+The claim-to-gate matrix stands at **146 rows — 138 GATED / 8 PARTIAL / 0 NO GATE** — **every product claim is backed by a failing test** and the ratchet (`MAX_NO_GATE=0`) forbids any regression. The 8 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. The six lettered deferrals are scoped in [`docs/audit/DEFERRED_SUBPHASES.md`](docs/audit/DEFERRED_SUBPHASES.md).
## v4.0 — Shipped
diff --git a/apps/docs/docs/compliance/evidence-pack.md b/apps/docs/docs/compliance/evidence-pack.md
index 112179941..9d75c738c 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: 137 rows
+The last row is the one worth reading first. It is the honest index: 138 rows
`GATED`, 8 `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/connectors/vault.md b/apps/docs/docs/connectors/vault.md
index e02ae5f09..c8a08822c 100644
--- a/apps/docs/docs/connectors/vault.md
+++ b/apps/docs/docs/connectors/vault.md
@@ -52,7 +52,7 @@ Add a `file` audit device on the Vault server:
vault audit enable file file_path=/var/log/vault/audit.log
```
-Then run the AiSOC Vault sidecar (image at `ghcr.io/beenuar/aisoc-vault-sidecar`) with read access to `/var/log/vault/audit.log` and the AiSOC connectors service URL in `AISOC_CONNECTORS_URL`. The sidecar `tail -F`s the file and posts each JSON line to `POST /v1/_/audit_ingest`, which the AiSOC connectors service holds in an in-memory ring buffer keyed by tenant. The connector's poll loop drains the buffer.
+Then run the AiSOC Vault sidecar — no image is published for it, so build it from `services/connectors` — with read access to `/var/log/vault/audit.log` and the AiSOC connectors service URL in `AISOC_CONNECTORS_URL`. The sidecar `tail -F`s the file and posts each JSON line to `POST /v1/_/audit_ingest`, which the AiSOC connectors service holds in an in-memory ring buffer keyed by tenant. The connector's poll loop drains the buffer.
### Topology B — Pull (small / single-node Vault)
diff --git a/apps/docs/docs/deployment/docker.md b/apps/docs/docs/deployment/docker.md
index d726b393e..a3e8b84ce 100644
--- a/apps/docs/docs/deployment/docker.md
+++ b/apps/docs/docs/deployment/docker.md
@@ -132,7 +132,7 @@ docker compose build agents
For releases, prebuilt and signed images are published to GHCR:
```
-ghcr.io/beenuar/aisoc-api:<version>
+ghcr.io/beenuar/aisoc-core-api:<version>
ghcr.io/beenuar/aisoc-agents:<version>
ghcr.io/beenuar/aisoc-actions:<version>
ghcr.io/beenuar/aisoc-fusion:<version>
@@ -144,7 +144,6 @@ ghcr.io/beenuar/aisoc-connectors:<version>
ghcr.io/beenuar/aisoc-osquery-tls:<version>
ghcr.io/beenuar/aisoc-slack-bot:<version>
ghcr.io/beenuar/aisoc-realtime:<version>
-ghcr.io/beenuar/aisoc-mcp:<version>
ghcr.io/beenuar/aisoc-ingest:<version>
ghcr.io/beenuar/aisoc-enrichment:<version>
ghcr.io/beenuar/aisoc-web:<version>
@@ -180,7 +179,7 @@ release artifact before deploying it into a sensitive environment:
cosign verify \
--certificate-identity-regexp '^https://github.com/beenuar/AiSOC' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
- ghcr.io/beenuar/aisoc-api:<version>
+ ghcr.io/beenuar/aisoc-core-api:<version>
```
The certificate identity is bound to this repository's workflow, so a
diff --git a/apps/docs/docs/deployment/kubernetes.md b/apps/docs/docs/deployment/kubernetes.md
index 3877816cd..64bb6ea39 100644
--- a/apps/docs/docs/deployment/kubernetes.md
+++ b/apps/docs/docs/deployment/kubernetes.md
@@ -24,15 +24,20 @@ helm dependency update infra/helm/aisoc
helm install aisoc infra/helm/aisoc \
--namespace aisoc --create-namespace \
- --set api.image.tag=v5.2.0 \
- --set agents.image.tag=v5.2.0 \
- --set realtime.image.tag=v5.2.0 \
- --set mcp.image.tag=v5.2.0 \
- --set web.image.tag=v5.2.0 \
--set secrets.openai.apiKey=sk-... \
--set postgresql.auth.password=changeme
```
+The image tags come from the chart's `appVersion`, so there is nothing to
+override for a working install. To pin a different release, note that every
+service lives under `services.<name>` — `--set api.image.tag=...` addresses a
+path no template reads and silently changes nothing:
+
+```bash
+ --set services.api.image.tag=v11.0.0 \
+ --set services.web.image.tag=v11.0.0
+```
+
Override any of the defaults in [`infra/helm/aisoc/values.yaml`](https://github.com/beenuar/AiSOC/blob/main/infra/helm/aisoc/values.yaml). For production deployments, walk through the [Hardening Runbook](https://github.com/beenuar/AiSOC/blob/main/docs/runbooks/HARDENING.md) before exposing the platform on the public internet.
## Container images
@@ -40,33 +45,44 @@ Override any of the defaults in [`infra/helm/aisoc/values.yaml`](https://github.
All images are published to GHCR and Cosign-signed:
```
-ghcr.io/beenuar/aisoc-api:v5.2.0
-ghcr.io/beenuar/aisoc-agents:v5.2.0
-ghcr.io/beenuar/aisoc-realtime:v5.2.0
-ghcr.io/beenuar/aisoc-mcp:v5.2.0
-ghcr.io/beenuar/aisoc-ingest:v5.2.0
-ghcr.io/beenuar/aisoc-enrichment:v5.2.0
-ghcr.io/beenuar/aisoc-web:v5.2.0
+ghcr.io/beenuar/aisoc-core-api:v11.0.0
+ghcr.io/beenuar/aisoc-agents:v11.0.0
+ghcr.io/beenuar/aisoc-realtime:v11.0.0
+ghcr.io/beenuar/aisoc-ingest:v11.0.0
+ghcr.io/beenuar/aisoc-enrichment:v11.0.0
+ghcr.io/beenuar/aisoc-web:v11.0.0
```
+`scripts/check_published_images.py` resolves every one of these against GHCR
+daily, so a name or tag that stops existing fails a build rather than a
+`helm install`. This list read `v5.2.0` until v11.1.0 — a tag no image has
+ever carried — and two of the names, `aisoc-api` and `aisoc-mcp`, have never
+been published at all. The API image is `aisoc-core-api`; the MCP server ships
+inside it rather than as its own image.
+
Verify a signature before deploying:
```bash
cosign verify \
--certificate-identity-regexp '^https://github.com/beenuar/AiSOC' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
- ghcr.io/beenuar/aisoc-api:v5.2.0
+ ghcr.io/beenuar/aisoc-core-api:v11.0.0
```
## Scaling
+The chart deploys `api`, `ingest`, `enrichment`, `alert-fusion`, `agents`,
+`web` and `realtime`; `ueba`, `honeytokens` and `purpleTeam` are off by
+default. There is no `mcp` deployment — the MCP server runs inside the API.
+
```bash
kubectl scale deployment aisoc-agents --replicas=3 -n aisoc
kubectl scale deployment aisoc-api --replicas=2 -n aisoc
-kubectl scale deployment aisoc-mcp --replicas=2 -n aisoc
```
-Horizontal Pod Autoscaler manifests are included in the chart — enable them with `--set api.autoscaling.enabled=true` (and similarly for `agents`, `realtime`, `mcp`).
+Horizontal Pod Autoscaler manifests are included in the chart — enable them
+with `--set services.api.autoscaling.enabled=true` (and similarly for
+`agents`, `realtime`). As above, the `services.` prefix is load-bearing.
## Ingress
diff --git a/docker-compose.yml b/docker-compose.yml
index ea8b0d2d8..0d2069203 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -771,7 +771,6 @@ services:
build:
context: ./services/osquery-tls
dockerfile: Dockerfile
- # Not in publish-images.yml matrix yet — pull falls back to local build.
image: ghcr.io/beenuar/aisoc-osquery-tls:${AISOC_VERSION:-latest}
pull_policy: missing
container_name: aisoc-osquery-tls
@@ -1033,14 +1032,17 @@ services:
honeytokens:
# Gated behind the `extras` profile: image isn't published to GHCR yet, so
- # `aisoc serve` skips it by default. Opt in with `--profile extras` and the
- # local Dockerfile build will run.
+ # `aisoc serve` skips it by default. Opt in with `--profile extras`.
+ # `pull_policy: build` used to be the only thing that worked here,
+ # because the image this names had never been published; it is in the
+ # publish matrix now, so `--profile extras` pulls like every other
+ # service instead of spending ten minutes building one.
profiles: ["extras"]
build:
context: ./services/honeytokens
dockerfile: Dockerfile
image: ghcr.io/beenuar/aisoc-honeytokens:${AISOC_VERSION:-latest}
- pull_policy: build
+ pull_policy: missing
container_name: aisoc-honeytokens
depends_on:
postgres:
@@ -1085,14 +1087,17 @@ services:
purple-team:
# Gated behind the `extras` profile: image isn't published to GHCR yet, so
- # `aisoc serve` skips it by default. Opt in with `--profile extras` and the
- # local Dockerfile build will run.
+ # `aisoc serve` skips it by default. Opt in with `--profile extras`.
+ # `pull_policy: build` used to be the only thing that worked here,
+ # because the image this names had never been published; it is in the
+ # publish matrix now, so `--profile extras` pulls like every other
+ # service instead of spending ten minutes building one.
profiles: ["extras"]
build:
context: ./services/purple-team
dockerfile: Dockerfile
image: ghcr.io/beenuar/aisoc-purple-team:${AISOC_VERSION:-latest}
- pull_policy: build
+ pull_policy: missing
container_name: aisoc-purple-team
depends_on:
postgres:
diff --git a/docs/audit/CLAIM_TO_GATE_MATRIX.md b/docs/audit/CLAIM_TO_GATE_MATRIX.md
index 2eb5fc98e..489e86805 100644
--- a/docs/audit/CLAIM_TO_GATE_MATRIX.md
+++ b/docs/audit/CLAIM_TO_GATE_MATRIX.md
@@ -153,10 +153,11 @@ Statuses: `GATED` (a CI job fails when the claim stops being true) · `PARTIAL`
| The corpus figure the product executes is distinguished from the corpus on disk | landing page, `docs/detections/truth-table.md` | `ci.yml :: python-lint` (`generate_corpus_stats.py --check` emits `executable` and `onDisk`/`quarantined` as separate fields and the UI leads with `EXECUTABLE_DETECTION_COUNT`; ~85% of the indexed corpus sits under `_quarantine/` and is never loaded, so quoting the on-disk figure as the detection capability presents quarantined rules as executable) | GATED | - |
| The retracted 75.3% alert-reduction figure is never presented as a measurement | `apps/docs/docs/benchmark.md`, `benchmarks/alert-reduction.md`, `BenchmarkResults.tsx`, `ComparisonTable.tsx`, `benchmark/page.tsx` | `ci.yml :: python-lint` (`check_alert_reduction_claims.py --check` — scans every published surface: no file may assert the legacy harness runs the production grouping ("faithful re-implementation", "same logic"), any file quoting 75.3% must carry the retraction, the `alert_reduction` suite card may not be declared `kind: 'measurement'`, and every surface publishing the real figure must quote `PUBLISHED_REDUCTION_PCT` from `services/fusion/tests/test_alert_reduction_real.py`, which that test asserts against its own measurement — so the chain from measurement to prose has no hand-copied link. `benchmark.md` had withdrawn the claim while two other surfaces went on asserting it, and `benchmark.md` itself re-asserted it in its own intro blockquote) | GATED | - |
| The same verb is graded identically whichever dispatch door it arrives through | README (graduated autonomy); `concepts/live-actions.md` | `ci.yml` actions job (`test_approval_doors_agree.py` — both live doors driven over 23 capabilities x 5 tiers x 3 confidence bands, 345 combinations, asserting the same answer to "did a vendor get touched without a human". A dry-run preview does not count as a touch, since the registry door downgrades an over-tier request to one. Against the previous tree it reports 5 disagreements: `search_siem` is read_only and automatic and sat in the analyst queue at the default tier while executing through the other door, because `TIER_MAX_AUTOMATIC["L1"]` said a tier the ladder defines as "MINIMAL blast-radius actions are automatic" auto-executes nothing; and `update_alert_disposition` was the one ActionType with no `ACTION_BLAST_RADIUS` entry, which is not a missing entry but two different ones, since the four readers of that table supply two different fallbacks. Structural checks alongside it fail a door that imports the raw matrix or compares against a specific `ActionImpact` inside its grading path — the shape a re-introduced bypass has — and require every `ActionType` to carry an explicit blast radius so neither fallback decides anything) | GATED | the grading itself is one function, `approval_matrix.evaluate_contract`, rather than two kept in agreement by discipline; the sweep exists for the axis it cannot unify, which is each door's separate blast-radius layer |
+| An image the deployment files tell an operator to pull exists, at the tag they will request | README quickstart (`docker compose up`), `docs/deployment/*`, `infra/helm/aisoc` | `image-availability.yml` (daily) + the `verify` job of `publish-images.yml` and `release.yml` (`scripts/check_published_images.py` — resolves every reference in `docker-compose.yml` and the chart the way the tooling that reads them does, `${AISOC_VERSION:-latest}` to its default and an empty chart `tag:` to `Chart.AppVersion`, then asks GHCR. `--require-fresh` also compares the version the tag names, or the `VERSION` at the commit the image records in `org.opencontainers.image.revision`, against the tree. Against `main` before this gate existed it reported 14 findings: `aisoc-web:latest` two releases behind, `aisoc-web:v11.0.0` never pushed, three images named by compose that had never been published once, and a chart whose every tag defaulted to a `Chart.AppVersion` no image carried. Offline it prints SKIPPED rather than OK, and `--require-network` makes that a failure) | GATED | Third-party images (`postgres`, `redis`, `ghcr.io/berriai/litellm`) are named and counted but not resolved: the claim is about the images this project publishes, and anonymous third-party registry reads are rate-limited per runner IP. Existence is not asked on a pull request, because a PR that adds a service names an image that cannot exist until it has merged and published |
## Summary
-- GATED: 137
+- GATED: 138
- PARTIAL: 8
- NO GATE: 0 (**every claim is backed by a failing test.** The last NO GATE — the weekly benchmark scoreboard running live against `main` — closed in Phase E1: `scripts/check_scoreboard.py` ties the published scoreboard to a deterministic per-PR live-agent MITRE-accuracy run, while the funded weekly `wet-eval.yml` appends the LLM-tier rows. The remaining PARTIAL rows are honest, named deferrals — each states the specific gap and what closes it — not unproven claims.)
diff --git a/docs/operations/publishing.md b/docs/operations/publishing.md
index 1f2862b93..d2ea33b5b 100644
--- a/docs/operations/publishing.md
+++ b/docs/operations/publishing.md
@@ -119,6 +119,37 @@ commit as the `CHANGELOG.md` promotion, then tag:
git tag vX.Y.Z && git push --tags
```
+Bump `appVersion` in `infra/helm/aisoc/Chart.yaml` to the tag you are cutting
+in that same commit. Every image tag in the chart's values defaults to it, so
+a chart left on the previous release pins operators to the previous release —
+and one left on a version that was never published pins them to nothing at
+all, which is the state the chart shipped in until v11.1.0: `appVersion` read
+`5.2.0`, a tag no image has ever carried, so a default `helm install` could
+only reach `ImagePullBackOff`. `scripts/check_published_images.py` resolves
+that value the same way the templates do and fails when it names nothing, so
+this is a gated step rather than a remembered one.
+
+`honeytokens` and `purpleTeam` pin `latest` rather than an empty tag until
+they have a `vX.Y.Z` to point at — they were first published on the merge that
+added them to the build matrix, so their first release tag is v11.1.0. Move
+them back to `tag: ""` in that release.
+
+## Recovering a release that only partly published
+
+A release is the set of artefacts it published, not the set of jobs that
+finished. If `check_published_images.py` reports an image missing at a tag
+that has already shipped, republish the images for that tag rather than
+cutting a new one:
+
+```bash
+gh workflow run release.yml --ref main -f tag=vX.Y.Z
+```
+
+Dispatch it from `main` so the current workflow definition runs; the build
+checks the named tag out for its source. The GitHub Release, npm and PyPI jobs
+are push-only and stay skipped, because a registry will not accept a package
+version twice.
+
## Verifying a publish
```bash
diff --git a/infra/helm/README.md b/infra/helm/README.md
index 327c31383..ddaa1519d 100644
--- a/infra/helm/README.md
+++ b/infra/helm/README.md
@@ -77,7 +77,7 @@ services:
replicaCount: 4 # explicit replicas (HPA still applies)
image:
repository: my-registry/aisoc-core-api
- tag: "5.2.0"
+ tag: "v11.0.0" # defaults to Chart.appVersion
env: # extra env vars merged into the pod
LOG_LEVEL: debug
hpa:
diff --git a/infra/helm/aisoc/Chart.yaml b/infra/helm/aisoc/Chart.yaml
index edaceb7a8..aa0c32efb 100644
--- a/infra/helm/aisoc/Chart.yaml
+++ b/infra/helm/aisoc/Chart.yaml
@@ -2,8 +2,13 @@ apiVersion: v2
name: aisoc
description: AiSOC - the open-source, AI-native Security Operations Center
type: application
-version: 5.2.0
-appVersion: "5.2.0"
+version: 5.3.0
+# Used as the image tag wherever a `tag:` in values.yaml is left empty, so
+# it has to be a tag the registry actually holds — it read "5.2.0", which
+# exists for no image, so every pod of a default install would have gone to
+# ImagePullBackOff. scripts/check_published_images.py resolves it the same
+# way the templates do and fails when it names nothing.
+appVersion: "v11.0.0"
keywords:
- security
diff --git a/infra/helm/aisoc/values.yaml b/infra/helm/aisoc/values.yaml
index 8411ecec8..6e5a962b3 100644
--- a/infra/helm/aisoc/values.yaml
+++ b/infra/helm/aisoc/values.yaml
@@ -118,7 +118,7 @@ services:
alert-fusion:
image:
- repository: ghcr.io/beenuar/aisoc-alert-fusion
+ repository: ghcr.io/beenuar/aisoc-fusion
tag: ""
pullPolicy: IfNotPresent
replicaCount: 2
@@ -303,7 +303,10 @@ honeytokens:
otelEndpoint: ""
image:
repository: ghcr.io/beenuar/aisoc-honeytokens
- tag: ""
+ # First published on the merge that added it to publish-images.yml,
+ # so it has no vX.Y.Z tag until the next release; empty here would
+ # resolve to Chart.AppVersion and 404. Move it to "" at that point.
+ tag: "latest"
pullPolicy: IfNotPresent
autoscaling:
enabled: false
@@ -326,7 +329,10 @@ purpleTeam:
otelEndpoint: ""
image:
repository: ghcr.io/beenuar/aisoc-purple-team
- tag: ""
+ # First published on the merge that added it to publish-images.yml,
+ # so it has no vX.Y.Z tag until the next release; empty here would
+ # resolve to Chart.AppVersion and 404. Move it to "" at that point.
+ tag: "latest"
pullPolicy: IfNotPresent
autoscaling:
enabled: false
diff --git a/infra/terraform/azure/terraform.tfvars.example b/infra/terraform/azure/terraform.tfvars.example
index a922a0fe6..6c8448604 100644
--- a/infra/terraform/azure/terraform.tfvars.example
+++ b/infra/terraform/azure/terraform.tfvars.example
@@ -44,7 +44,7 @@
# Defaults point at the public GHCR demo images so the skeleton runs with zero
# CI work. Override with images you've pushed to the ACR this stack provisions.
-# api_image = "ghcr.io/beenuar/aisoc-api:latest"
+# api_image = "ghcr.io/beenuar/aisoc-core-api:latest"
# web_image = "ghcr.io/beenuar/aisoc-web:latest"
# ingest_image = "ghcr.io/beenuar/aisoc-ingest:latest"
diff --git a/infra/terraform/azure/variables.tf b/infra/terraform/azure/variables.tf
index 06315afd7..b572051d8 100644
--- a/infra/terraform/azure/variables.tf
+++ b/infra/terraform/azure/variables.tf
@@ -129,7 +129,7 @@ variable "redis_capacity" {
variable "api_image" {
description = "Container image for the API service (FastAPI). Defaults to the GHCR demo image."
type = string
- default = "ghcr.io/beenuar/aisoc-api:latest"
+ default = "ghcr.io/beenuar/aisoc-core-api:latest"
}
variable "web_image" {
diff --git a/infra/terraform/gcp/terraform.tfvars.example b/infra/terraform/gcp/terraform.tfvars.example
index d1ad66bfe..edde05cdb 100644
--- a/infra/terraform/gcp/terraform.tfvars.example
+++ b/infra/terraform/gcp/terraform.tfvars.example
@@ -45,7 +45,7 @@ project_id = "your-gcp-project-id"
# zero CI work. Override with images from the Artifact Registry repo this
# stack provisions for production.
-# api_image = "ghcr.io/beenuar/aisoc-api:latest"
+# api_image = "ghcr.io/beenuar/aisoc-core-api:latest"
# web_image = "ghcr.io/beenuar/aisoc-web:latest"
# ingest_image = "ghcr.io/beenuar/aisoc-ingest:latest"
diff --git a/infra/terraform/gcp/variables.tf b/infra/terraform/gcp/variables.tf
index 3ed748caf..86b1d8357 100644
--- a/infra/terraform/gcp/variables.tf
+++ b/infra/terraform/gcp/variables.tf
@@ -111,7 +111,7 @@ variable "redis_version" {
variable "api_image" {
description = "Container image for the API service (FastAPI). Defaults to the GHCR demo image."
type = string
- default = "ghcr.io/beenuar/aisoc-api:latest"
+ default = "ghcr.io/beenuar/aisoc-core-api:latest"
}
variable "web_image" {
diff --git a/scripts/check_published_images.py b/scripts/check_published_images.py
new file mode 100644
index 000000000..1ace1ea3b
--- /dev/null
+++ b/scripts/check_published_images.py
@@ -0,0 +1,866 @@
+#!/usr/bin/env python3
+"""An image the deployment files tell an operator to pull has to exist.
+
+Why this exists
+---------------
+Nothing in this repository checked that. The result was not a hypothetical:
+
+* ``ghcr.io/beenuar/aisoc-web:latest`` — what ``docker compose up`` pulls for
+ the console — was built from a commit two releases behind ``main``, so every
+ honest-state fix, fabrication removal and first-run improvement of the week
+ was invisible to anyone following the documented quickstart. The publish
+ workflow was green throughout, because it *was* green: the web job was
+ repeatedly killed by ``cancel-in-progress`` and the run reported cancelled,
+ not failed, while the other twelve images published normally.
+* ``aisoc-web:v11.0.0`` was never pushed at all, while the same release's
+ ``aisoc-core-api``, ``aisoc-fusion`` and ``aisoc-ingest`` tags all were. A
+ partial release is not a state any workflow noticed.
+* ``aisoc-honeytokens``, ``aisoc-purple-team`` and ``aisoc-osquery-tls`` were
+ named by ``docker-compose.yml`` and had never been published *once*. Compose
+ falls back to a local build, so this was a silent twenty-minute first run
+ rather than an error — but the Helm chart has no such fallback, and named
+ two of the same three.
+* The chart's images all default to ``Chart.AppVersion``, which read ``5.2.0``
+ — a tag that exists for no image in the registry. ``helm install`` could
+ only ever have produced ``ImagePullBackOff`` on every pod.
+
+A green workflow proves a job ran. It does not prove the registry holds what
+the README, the compose file and the chart tell people to pull. Only the
+registry can answer that, so this asks it.
+
+What it checks
+--------------
+``exists``
+ Every first-party image reference in ``docker-compose.yml`` and the Helm
+ chart resolves, at the tag an operator will actually request — the
+ ``${AISOC_VERSION:-latest}`` default for compose, ``Chart.AppVersion`` for
+ a chart value left empty. Resolving the tag is half the check: a reference
+ read literally is a reference nobody pulls.
+
+``fresh`` (``--require-fresh``)
+ And the version *inside* it matches the tree. Read from
+ ``org.opencontainers.image.revision`` — the commit the image was built
+ from — then ``git show <commit>:VERSION``. That is the check that would
+ have caught the state above, since existence alone would have passed:
+ ``:latest`` was present the whole time, just old.
+
+ Off by default because a release commit bumps ``VERSION`` and the images
+ for it cannot exist until that commit has merged and published. Enforcing
+ freshness on a pull request would fail every release PR for being a
+ release PR. It is a scheduled question, asked of ``main``, where a stale
+ ``:latest`` is a real defect and not a race.
+
+Third-party references — ``postgres:16-alpine``, ``redis:7-alpine``,
+``ghcr.io/berriai/litellm`` — are counted and named but not resolved. This
+gate exists to check the images *this project publishes*; upstream
+availability is not a claim this repository makes, and anonymous pulls against
+a third-party registry are rate-limited per runner IP, which would make the
+answer depend on who else shares the runner.
+
+Offline
+-------
+A skip is not a pass, and the output says which happened every time. Without
+``--require-network`` an unreachable registry prints ``SKIPPED`` and never
+``OK``, so a contributor with no network is not told the tree is wrong; with
+it, unreachable is a hard failure, which is what the scheduled job uses.
+
+The empty-tree refusal happens before the first request, so the answer does
+not depend on whether the probe running it had a network at all.
+
+Usage
+-----
+ python3 scripts/check_published_images.py
+ python3 scripts/check_published_images.py --require-fresh --require-network
+ python3 scripts/check_published_images.py --list
+ python3 scripts/check_published_images.py --json
+ python3 scripts/check_published_images.py --self-test
+
+Exit codes: 0 clean (or an announced skip), 1 findings, 2 the scan could not run.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+import yaml
+
+# `scripts/` is on sys.path when this file is run as a program, but not when a
+# test loads it by path with importlib. gate_toolkit sits beside it either way.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from gate_toolkit import refuses_an_empty_tree, repo_root, scratch_tree # noqa: E402
+
+COMPOSE_REL = Path("docker-compose.yml")
+CHART_REL = Path("infra/helm/aisoc")
+VERSION_REL = Path("VERSION")
+
+#: The registry this project publishes to. A reference anywhere else belongs
+#: to somebody else and is reported rather than resolved — see the docstring.
+REGISTRY = "ghcr.io"
+
+#: Tags that move. Their content is whatever the last successful publish put
+#: there, so "does it exist" and "is it current" are different questions and
+#: only the first is asked on a pull request.
+MOVING_TAGS = frozenset({"latest", "main", "edge", "nightly", "demo"})
+
+#: ``${AISOC_VERSION:-latest}`` and friends. Compose expands these at up time;
+#: read literally the tag is a string no registry has ever held.
+_INTERPOLATION = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)(?::?-([^}]*))?\}")
+
+#: A fully-written first-party image reference in prose. Deliberately not
+#: matching a placeholder registry or an unresolved variable: those are
+#: illustrations, and resolving them would test the example rather than
+#: anything an operator would run.
+_DOCS_IMAGE = re.compile(r"(ghcr\.io/beenuar/[a-z0-9._-]+):([A-Za-z0-9][A-Za-z0-9._-]*)")
+
+_TIMEOUT = 20
+
+_MANIFEST_TYPES = (
+ "application/vnd.oci.image.index.v1+json",
+ "application/vnd.oci.image.manifest.v1+json",
+ "application/vnd.docker.distribution.manifest.list.v2+json",
+ "application/vnd.docker.distribution.manifest.v2+json",
+)
+
+PRESENT = "present"
+ABSENT = "absent"
+UNREACHABLE = "unreachable"
+
+
+class Offline(RuntimeError):
+ """The registry could not be reached, which is not the same as absent."""
+
+
+class ScanError(RuntimeError):
+ """An input could not be read. Never downgraded to a passing result."""
+
+
+@dataclass(frozen=True)
+class Reference:
+ """One image an operator is told to pull, with its tag already resolved."""
+
+ source: str
+ service: str
+ repository: str
+ tag: str
+ #: How the tag was arrived at, so a finding can say what to edit.
+ tag_origin: str
+ #: Whether this reference is expected to track the tree. A deployment file
+ #: is; prose naming an older release is not wrong for naming it.
+ tracks_tree: bool = True
+
+ @property
+ def ref(self) -> str:
+ return f"{self.repository}:{self.tag}"
+
+ @property
+ def first_party(self) -> bool:
+ return self.repository.startswith(f"{REGISTRY}/beenuar/")
+
+ @property
+ def moving(self) -> bool:
+ return self.tag in MOVING_TAGS
+
+
+@dataclass
+class Resolution:
+ """What the registry said about one reference."""
+
+ state: str
+ #: ``org.opencontainers.image.revision`` — the commit it was built from.
+ revision: str = ""
+ detail: str = ""
+
+
+# --------------------------------------------------------------------------
+# Reading the deployment files
+# --------------------------------------------------------------------------
+def _expand(value: str) -> tuple[str, bool]:
+ """``${VAR:-default}`` -> ``default``. Returns (expanded, was_interpolated).
+
+ The default is what an operator who sets nothing gets, and setting nothing
+ is the documented path. A variable with no default expands to empty, which
+ is not a tag anybody can pull, and is reported as such rather than guessed.
+ """
+ interpolated = bool(_INTERPOLATION.search(value))
+ return _INTERPOLATION.sub(lambda m: m.group(2) or "", value), interpolated
+
+
+def _split(image: str) -> tuple[str, str]:
+ """``repo:tag`` -> (repo, tag), tolerating a port in the registry host."""
+ if "@" in image:
+ repository, _, digest = image.partition("@")
+ return repository, digest
+ head, sep, tail = image.rpartition(":")
+ if sep and "/" not in tail:
+ return head, tail
+ return image, "latest"
+
+
+def collect_compose_references(root: Path) -> list[Reference]:
+ """Every ``image:`` under ``services:``, at the tag ``docker compose up`` requests."""
+ path = root / COMPOSE_REL
+ if not path.is_file():
+ raise ScanError(f"no {COMPOSE_REL} to read: {path}")
+ try:
+ document = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+ except yaml.YAMLError as exc:
+ raise ScanError(f"{COMPOSE_REL} is not readable as YAML: {exc}") from exc
+
+ references: list[Reference] = []
+ for name, service in sorted((document.get("services") or {}).items()):
+ if not isinstance(service, dict) or not isinstance(service.get("image"), str):
+ continue
+ expanded, interpolated = _expand(service["image"])
+ repository, tag = _split(expanded)
+ origin = "the default in ${AISOC_VERSION:-…}" if interpolated else "written literally"
+ references.append(Reference(str(COMPOSE_REL), name, repository, tag, origin))
+ return references
+
+
+def collect_helm_references(root: Path) -> list[Reference]:
+ """Every ``{repository, tag}`` pair in the chart's values, tag resolved.
+
+ Found by walking the document rather than by naming the six places they
+ live today: ``services.*``, ``ueba``, ``honeytokens``, ``purpleTeam`` and
+ ``backup`` are five different shapes already, and a sixth added next to
+ them must not be able to arrive unchecked.
+ """
+ values = root / CHART_REL / "values.yaml"
+ chart = root / CHART_REL / "Chart.yaml"
+ if not values.is_file() or not chart.is_file():
+ raise ScanError(f"no Helm chart to read at {CHART_REL}")
+ try:
+ document = yaml.safe_load(values.read_text(encoding="utf-8")) or {}
+ metadata = yaml.safe_load(chart.read_text(encoding="utf-8")) or {}
+ except yaml.YAMLError as exc:
+ raise ScanError(f"the Helm chart is not readable as YAML: {exc}") from exc
+
+ app_version = str(metadata.get("appVersion") or "")
+ references: list[Reference] = []
+
+ def walk(node: object, trail: str) -> None:
+ if not isinstance(node, dict):
+ if isinstance(node, list):
+ for index, item in enumerate(node):
+ walk(item, f"{trail}[{index}]")
+ return
+ repository = node.get("repository")
+ if isinstance(repository, str) and "tag" in node:
+ declared = str(node.get("tag") or "")
+ # `tag: ""` is not "no tag": every template that reads one of these
+ # writes `| default .Chart.AppVersion`, so an empty value in
+ # values.yaml is a live reference to whatever the chart calls its
+ # app version — which is exactly how the chart came to request a
+ # tag that had never been published.
+ tag = declared or app_version
+ origin = "written literally" if declared else f"empty, so Chart.AppVersion ({app_version or 'unset'})"
+ references.append(Reference(f"{CHART_REL}/values.yaml", trail, repository, tag, origin))
+ return
+ for key, value in sorted(node.items()):
+ walk(value, f"{trail}.{key}" if trail else str(key))
+
+ walk(document, "")
+ return references
+
+
+def collect_docs_references(root: Path) -> list[Reference]:
+ """Fully-written ``ghcr.io/beenuar/<image>:<tag>`` strings in tracked prose.
+
+ A published page telling somebody to pull an image is the same claim the
+ compose file makes, and it was wrong in the same way:
+ ``apps/docs/docs/deployment/kubernetes.md`` listed seven images at ``v5.2.0``, a
+ no image carries, and two of the names — ``aisoc-api`` and ``aisoc-mcp`` —
+ have never existed under any tag at all.
+
+ Existence only. A release note naming an older image is describing history
+ rather than instructing anybody, so freshness is not asked of prose.
+ Placeholders like ``my-registry/aisoc-core-api`` are outside the pattern
+ and are not resolved.
+
+ Only a complete ``repository:tag`` matches, which is also the escape for
+ prose *about* a broken reference: naming the repository alone
+ (``aisoc-api``) describes it without telling anybody to pull it. This
+ changelog entry needed that, which is the sort of thing a gate discovers
+ about itself the first time it reads its own release notes.
+ """
+ out = subprocess.run( # noqa: S603 - fixed argv, no shell
+ ["git", "ls-files", "-z", "*.md", "*.mdx"],
+ capture_output=True,
+ text=True,
+ check=False,
+ cwd=root,
+ )
+ if out.returncode != 0:
+ # Not a git checkout, or git is absent. The deployment files are the
+ # gate's subject either way, so this degrades to "prose not scanned"
+ # rather than failing the run — and says so in the summary.
+ return []
+ references: list[Reference] = []
+ seen: set[tuple[str, str, str]] = set()
+ for name in filter(None, out.stdout.split("\0")):
+ path = root / name
+ try:
+ text = path.read_text(encoding="utf-8", errors="replace")
+ except OSError:
+ continue
+ for match in _DOCS_IMAGE.finditer(text):
+ repository, tag = match.group(1), match.group(2)
+ key = (name, repository, tag)
+ if key in seen:
+ continue
+ seen.add(key)
+ references.append(Reference(name, "prose", repository, tag, "written literally", tracks_tree=False))
+ return references
+
+
+def tree_version(root: Path) -> str:
+ path = root / VERSION_REL
+ if not path.is_file():
+ raise ScanError(f"no {VERSION_REL} to compare against: {path}")
+ return path.read_text(encoding="utf-8").strip()
+
+
+def version_from_tag(tag: str) -> str:
+ """The version a tag name promises, or "" when it promises none.
+
+ ``v11.0.0`` claims a version; ``latest`` and ``16-alpine`` do not. Read
+ from the name rather than from the image because that is the claim an
+ operator pinning the tag is relying on — and because release images pushed
+ before this workflow attached OCI labels carry nothing else to read.
+ """
+ return tag[1:] if re.fullmatch(r"v\d+\.\d+\.\d+(?:[-+].*)?", tag or "") else ""
+
+
+def version_at(root: Path, commit: str) -> str:
+ """``VERSION`` as of ``commit``, or "" when this checkout cannot say.
+
+ A shallow clone genuinely does not know, and answering anyway would be
+ inventing the number this gate exists to verify.
+ """
+ if not re.fullmatch(r"[0-9a-f]{7,40}", commit or ""):
+ return ""
+ out = subprocess.run( # noqa: S603 - fixed argv, no shell
+ ["git", "show", f"{commit}:{VERSION_REL}"],
+ capture_output=True,
+ text=True,
+ check=False,
+ cwd=root,
+ )
+ return out.stdout.strip() if out.returncode == 0 else ""
+
+
+# --------------------------------------------------------------------------
+# Asking the registry
+# --------------------------------------------------------------------------
+class GhcrClient:
+ """Anonymous reads against GHCR. Public packages need no credential."""
+
+ def __init__(self, timeout: int = _TIMEOUT) -> None:
+ self._timeout = timeout
+ self._tokens: dict[str, str | None] = {}
+
+ def _get(self, url: str, headers: dict[str, str]) -> object:
+ request = urllib.request.Request(url, headers=headers)
+ with urllib.request.urlopen(request, timeout=self._timeout) as response: # noqa: S310 - fixed https host
+ return json.load(response)
+
+ def _token(self, repository: str) -> str | None:
+ """A pull token, or None when the package does not exist at all.
+
+ GHCR refuses to mint an anonymous token for a repository nobody has
+ ever pushed, which is how a never-published image is distinguished
+ from a published one missing a tag. Both are findings; they need
+ different sentences.
+ """
+ if repository not in self._tokens:
+ url = f"https://{REGISTRY}/token?scope=repository:{repository}:pull&service={REGISTRY}"
+ try:
+ payload = self._get(url, {"Accept": "application/json"})
+ except urllib.error.HTTPError:
+ self._tokens[repository] = None
+ except (urllib.error.URLError, TimeoutError, OSError) as exc:
+ raise Offline(f"{REGISTRY} unreachable: {exc}") from exc
+ else:
+ self._tokens[repository] = (payload or {}).get("token") if isinstance(payload, dict) else None
+ return self._tokens[repository]
+
+ def resolve(self, reference: Reference) -> Resolution:
+ repository = reference.repository.split("/", 1)[1]
+ if not reference.tag:
+ return Resolution(ABSENT, detail="the reference carries no tag at all")
+ token = self._token(repository)
+ if token is None:
+ return Resolution(ABSENT, detail="no such package in the registry — it has never been published")
+ headers = {"Authorization": f"Bearer {token}", "Accept": ", ".join(_MANIFEST_TYPES)}
+ url = f"https://{REGISTRY}/v2/{repository}/manifests/{reference.tag}"
+ try:
+ manifest = self._get(url, headers)
+ except urllib.error.HTTPError as exc:
+ if exc.code in (404, 403):
+ return Resolution(ABSENT, detail=f"the package exists but has no {reference.tag!r} tag")
+ raise Offline(f"{reference.ref} returned {exc.code}") from exc
+ except (urllib.error.URLError, TimeoutError, OSError) as exc:
+ raise Offline(f"{reference.ref} unreachable: {exc}") from exc
+ return Resolution(PRESENT, revision=self._revision(repository, manifest, headers))
+
+ def _revision(self, repository: str, manifest: object, headers: dict[str, str]) -> str:
+ """``org.opencontainers.image.revision``, from wherever this image carries it.
+
+ A multi-arch push records it three ways depending on how the manifest
+ was assembled — index annotations, the per-platform manifest's
+ annotations, or the image config's labels — so all three are tried
+ before reporting that the image does not say.
+ """
+ if not isinstance(manifest, dict):
+ return ""
+ key = "org.opencontainers.image.revision"
+ annotated = (manifest.get("annotations") or {}).get(key)
+ if annotated:
+ return str(annotated)
+ try:
+ if "manifests" in manifest:
+ for entry in manifest.get("manifests") or []:
+ platform = (entry.get("platform") or {}).get("architecture")
+ if platform in (None, "unknown"):
+ continue
+ child = self._get(f"https://{REGISTRY}/v2/{repository}/manifests/{entry['digest']}", headers)
+ found = self._revision(repository, child, headers)
+ if found:
+ return found
+ return ""
+ digest = (manifest.get("config") or {}).get("digest")
+ if not digest:
+ return ""
+ config = self._get(
+ f"https://{REGISTRY}/v2/{repository}/blobs/{digest}",
+ {**headers, "Accept": "application/json"},
+ )
+ except (urllib.error.HTTPError, urllib.error.URLError, TimeoutError, OSError):
+ return ""
+ if not isinstance(config, dict):
+ return ""
+ labels = (config.get("config") or {}).get("Labels") or {}
+ return str(labels.get(key) or "")
+
+
+# --------------------------------------------------------------------------
+# Verdict
+# --------------------------------------------------------------------------
+@dataclass
+class Report:
+ """Everything one run learned, so the printer and the tests share a shape."""
+
+ references: list[Reference] = field(default_factory=list)
+ resolutions: dict[str, Resolution] = field(default_factory=dict)
+ versions: dict[str, str] = field(default_factory=dict)
+ tree: str = ""
+ skipped: str = ""
+
+ @property
+ def first_party(self) -> list[Reference]:
+ return [r for r in self.references if r.first_party]
+
+ @property
+ def third_party(self) -> list[Reference]:
+ return [r for r in self.references if not r.first_party]
+
+
+def evaluate(report: Report, *, require_fresh: bool) -> list[tuple[str, str]]:
+ """Every finding, as (code, detail). Pure, so the self-test can drive it."""
+ findings: list[tuple[str, str]] = []
+ for reference in report.first_party:
+ resolution = report.resolutions.get(reference.ref)
+ if resolution is None or resolution.state == UNREACHABLE:
+ continue
+ where = f"{reference.source} ({reference.service})"
+ if resolution.state == ABSENT:
+ kind = "A deployment file" if reference.tracks_tree else "A published page"
+ findings.append(
+ (
+ "image-missing",
+ f"{where} tells an operator to pull {reference.ref} — tag {reference.tag} from "
+ f"{reference.tag_origin} — and {resolution.detail}. Either publish it or stop naming it: "
+ f"{kind.lower()} pointing at an image that has never existed is a false claim whether "
+ "or not something else quietly covers for it.",
+ )
+ )
+ continue
+ if not require_fresh or not reference.tracks_tree:
+ continue
+ # Two independent sources, and which one exists depends on the tag.
+ # `claimed` is what the tag name promises — the whole point of a
+ # pinned tag, and the only source for release images pushed before
+ # this workflow started applying OCI labels. `built` is what the image
+ # records about the commit behind it, which is all a moving tag has.
+ claimed = version_from_tag(reference.tag)
+ built = report.versions.get(reference.ref, "")
+ if claimed and built and claimed != built:
+ findings.append(
+ (
+ "version-mismatch",
+ f"{where}: {reference.ref} is tagged as {claimed} and was built from a commit carrying "
+ f"version {built}. The tag does not describe its own contents, so pinning to it pins to "
+ "something other than what it says.",
+ )
+ )
+ continue
+ effective = claimed or built
+ if not effective:
+ findings.append(
+ (
+ "version-unreadable",
+ f"{where}: {reference.ref} is published, its tag names no version, and it does not record "
+ "which commit it was built from — or that commit is not in this checkout. Whether it "
+ "matches the tree is unverified, and unverified is reported rather than assumed clean.",
+ )
+ )
+ elif effective != report.tree:
+ stale = "is a moving tag and has fallen behind" if reference.moving else "is pinned to an older release"
+ findings.append(
+ (
+ "version-stale",
+ f"{where}: {reference.ref} holds version {effective} while the tree is {report.tree}. The "
+ f"tag {stale} ({reference.tag_origin}). Anyone following the documented deployment path "
+ f"gets {effective}, not what this repository says it is.",
+ )
+ )
+ return findings
+
+
+def scan(root: Path, client: GhcrClient | None, *, require_fresh: bool) -> Report:
+ """Read the deployment files, then ask the registry about what they name.
+
+ The deployment files are read before ``VERSION`` and long before the first
+ request, so a refusal names the subject that is missing and the answer does
+ not depend on whether the caller had a network.
+ """
+ report = Report()
+ report.references = collect_compose_references(root) + collect_helm_references(root) + collect_docs_references(root)
+ if not report.first_party:
+ raise ScanError(
+ f"{COMPOSE_REL} and {CHART_REL} name no {REGISTRY}/beenuar image at all. Found nothing and scanned "
+ "nothing print the same word, so this is a refusal rather than a clean result."
+ )
+ report.tree = tree_version(root)
+ if client is None:
+ return report
+ for reference in report.first_party:
+ if reference.ref in report.resolutions:
+ continue
+ resolution = client.resolve(reference)
+ report.resolutions[reference.ref] = resolution
+ if require_fresh and resolution.state == PRESENT:
+ report.versions[reference.ref] = version_at(root, resolution.revision)
+ return report
+
+
+# --------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ parser.add_argument("--repo-root", type=Path, default=None, help="the tree to inspect (default: git rev-parse)")
+ parser.add_argument(
+ "--require-fresh",
+ action="store_true",
+ help="also require the version inside each image to match the tree",
+ )
+ parser.add_argument(
+ "--require-network",
+ action="store_true",
+ help="fail instead of skipping when the registry cannot be reached",
+ )
+ parser.add_argument("--list", action="store_true", help="print every reference with its state")
+ parser.add_argument("--json", action="store_true")
+ parser.add_argument("--self-test", action="store_true", help="prove this gate detects the drift it claims to")
+ args = parser.parse_args(argv)
+
+ if args.self_test:
+ return self_test()
+
+ root = (args.repo_root or repo_root()).resolve()
+ client = GhcrClient()
+ try:
+ report = scan(root, client, require_fresh=args.require_fresh)
+ except ScanError as exc:
+ print(f"check_published_images: FAILED to run the scan: {exc}", file=sys.stderr)
+ return 2
+ except Offline as exc:
+ if args.require_network:
+ print(f"check_published_images: FAILED — {exc}", file=sys.stderr)
+ return 2
+ # Deliberately not "OK". The registry was never asked, so nothing here
+ # was verified, and the word for that is SKIPPED.
+ print(f"SKIPPED — the registry was not reachable, so nothing was verified: {exc}")
+ print(" Re-run with --require-network to make this a failure instead.")
+ return 0
+
+ findings = evaluate(report, require_fresh=args.require_fresh)
+
+ if args.json:
+ print(
+ json.dumps(
+ {
+ "repo_root": str(root),
+ "tree_version": report.tree,
+ "references": [asdict(r) for r in report.references],
+ "resolutions": {k: asdict(v) for k, v in report.resolutions.items()},
+ "versions": report.versions,
+ "findings": [{"code": c, "detail": d} for c, d in findings],
+ },
+ indent=2,
+ sort_keys=True,
+ )
+ )
+ return 1 if findings else 0
+
+ print(f"repo root {root}")
+ print(f"tree version {report.tree}")
+ prose = sum(1 for r in report.first_party if not r.tracks_tree)
+ print(f"sources {COMPOSE_REL}, {CHART_REL}/values.yaml, and {prose} reference(s) in tracked prose")
+ print(
+ f"references {len(report.first_party)} first-party ({REGISTRY}/beenuar), {len(report.third_party)} third-party not resolved"
+ )
+ print(f"freshness {'enforced' if args.require_fresh else 'reported only (pass --require-fresh to enforce)'}")
+ print()
+
+ if args.list:
+ width = max((len(r.ref) for r in report.first_party), default=10)
+ for reference in report.first_party:
+ resolution = report.resolutions.get(reference.ref, Resolution(UNREACHABLE))
+ built = report.versions.get(reference.ref)
+ suffix = f" holds {built}" if built else ""
+ print(f" {resolution.state:<10} {reference.ref:{width}} {reference.source} ({reference.service}){suffix}")
+ if report.third_party:
+ print()
+ print(f" not resolved (published by somebody else): {', '.join(sorted({r.ref for r in report.third_party}))}")
+ print()
+
+ if findings:
+ print(f"PUBLISHED-IMAGES GATE FAILED — {len(findings)} finding(s):", file=sys.stderr)
+ for code, detail in findings:
+ print(f" [{code}] {detail}", file=sys.stderr)
+ return 1
+
+ checked = len(report.first_party)
+ verified = "and the version inside each matches the tree" if args.require_fresh else "(freshness not enforced on this run)"
+ print(f"OK — all {checked} first-party image reference(s) resolve in {REGISTRY} {verified}.")
+ return 0
+
+
+# --------------------------------------------------------------------------
+# Self-test
+# --------------------------------------------------------------------------
+def _reference(**overrides: object) -> Reference:
+ base: dict[str, object] = {
+ "source": "docker-compose.yml",
+ "service": "web",
+ "repository": f"{REGISTRY}/beenuar/aisoc-web",
+ "tag": "latest",
+ "tag_origin": "the default in ${AISOC_VERSION:-…}",
+ }
+ base.update(overrides)
+ return Reference(**base) # type: ignore[arg-type]
+
+
+def _report(resolution: Resolution, *, built: str = "11.0.0", tree: str = "11.0.0", **overrides: object) -> Report:
+ reference = _reference(**overrides)
+ return Report(
+ references=[reference],
+ resolutions={reference.ref: resolution},
+ versions={reference.ref: built},
+ tree=tree,
+ )
+
+
+def self_test() -> int:
+ """Inject each defect this gate exists to catch and require it to be caught."""
+
+ def codes(report: Report, *, fresh: bool = True) -> set[str]:
+ return {code for code, _ in evaluate(report, require_fresh=fresh)}
+
+ print("check_published_images self-test")
+ print("baseline: one published, current image — 0 findings (every case below perturbs exactly that)\n")
+
+ checks: list[tuple[str, bool]] = []
+
+ def record(description: str, passed: bool, detail: str = "") -> None:
+ checks.append((description, passed))
+ print(f" {'PASS' if passed else 'FAIL'} {description}")
+ if detail:
+ print(f" {detail}")
+
+ baseline = codes(_report(Resolution(PRESENT, revision="abc1234")))
+ record("the unperturbed baseline reports nothing", not baseline, f"got {sorted(baseline) or 'nothing'}")
+
+ # The three states today's registry is actually in.
+ cases: list[tuple[str, str, set[str]]] = [
+ (
+ "a tag the compose file names that the registry does not hold",
+ "image-missing",
+ codes(_report(Resolution(ABSENT, detail="the package exists but has no 'v11.0.0' tag"), tag="v11.0.0")),
+ ),
+ (
+ "an image name that has never been published at all",
+ "image-missing",
+ codes(
+ _report(
+ Resolution(ABSENT, detail="no such package in the registry — it has never been published"),
+ repository=f"{REGISTRY}/beenuar/aisoc-honeytokens",
+ )
+ ),
+ ),
+ (
+ "prose telling an operator to pull an image that does not exist",
+ "image-missing",
+ codes(
+ _report(
+ Resolution(ABSENT, detail="no such package in the registry — it has never been published"),
+ source="apps/docs/docs/deployment/kubernetes.md",
+ service="prose",
+ repository=f"{REGISTRY}/beenuar/aisoc-api",
+ tag="v5.2.0",
+ tracks_tree=False,
+ )
+ ),
+ ),
+ (
+ "a published image whose version is behind the tree — green workflow, stale artefact",
+ "version-stale",
+ codes(_report(Resolution(PRESENT, revision="d704c25b"), built="10.0.0", tree="11.0.0")),
+ ),
+ (
+ "a chart pinned to a release older than the tree",
+ "version-stale",
+ codes(
+ _report(
+ Resolution(PRESENT, revision="aaaaaaa"),
+ built="",
+ tree="11.0.0",
+ source="infra/helm/aisoc/values.yaml",
+ tag="v5.2.0",
+ tag_origin="empty, so Chart.AppVersion (v5.2.0)",
+ )
+ ),
+ ),
+ (
+ "a tag that does not describe its own contents",
+ "version-mismatch",
+ codes(_report(Resolution(PRESENT, revision="d704c25b"), built="10.0.0", tree="11.0.0", tag="v11.0.0")),
+ ),
+ (
+ "a moving tag on an image that does not say which commit built it is unverified, not clean",
+ "version-unreadable",
+ codes(_report(Resolution(PRESENT, revision=""), built="")),
+ ),
+ ]
+ for description, expected, found in cases:
+ record(description, expected in found, f"expected [{expected}] got {sorted(found) or 'nothing'}")
+
+ # Things that must NOT be findings.
+ quiet: list[tuple[str, set[str]]] = [
+ (
+ "a stale image is not a finding when freshness is not being enforced",
+ codes(_report(Resolution(PRESENT, revision="d704c25b"), built="10.0.0", tree="11.0.0"), fresh=False),
+ ),
+ (
+ "a third-party reference is neither resolved nor credited",
+ codes(_report(Resolution(ABSENT), repository="docker.io/library/postgres", tag="16-alpine")),
+ ),
+ (
+ "an unreachable registry is never read as a missing image",
+ codes(_report(Resolution(UNREACHABLE, detail="timed out"))),
+ ),
+ (
+ "a pinned tag answers for itself when the image carries no OCI label",
+ codes(_report(Resolution(PRESENT, revision=""), built="", tree="11.0.0", tag="v11.0.0")),
+ ),
+ (
+ "prose naming an older release is describing history, not instructing anybody",
+ codes(
+ _report(
+ Resolution(PRESENT, revision="aaaaaaa"),
+ built="9.0.0",
+ tree="11.0.0",
+ source="RELEASES.md",
+ service="prose",
+ tag="v9.0.0",
+ tracks_tree=False,
+ )
+ ),
+ ),
+ ]
+ for description, found in quiet:
+ record(description, not found, f"got {sorted(found) or 'nothing'}")
+
+ # The readers. Every case above is only as good as the claim that a tag was
+ # resolved the way an operator's tooling resolves it.
+ readers: list[tuple[str, object, object]] = [
+ (
+ "${AISOC_VERSION:-latest} resolves to the default an operator gets",
+ _expand("ghcr.io/x:${AISOC_VERSION:-latest}")[0],
+ "ghcr.io/x:latest",
+ ),
+ ("a variable with no default resolves to no tag, not to a guess", _expand("ghcr.io/x:${AISOC_VERSION}")[0], "ghcr.io/x:"),
+ ("a literal tag is left alone", _expand("postgres:16-alpine"), ("postgres:16-alpine", False)),
+ ("a tagless reference means latest", _split("ghcr.io/beenuar/aisoc-web"), ("ghcr.io/beenuar/aisoc-web", "latest")),
+ ("a registry port is not mistaken for a tag", _split("localhost:5000/aisoc-web"), ("localhost:5000/aisoc-web", "latest")),
+ ("a digest reference keeps its digest", _split("ghcr.io/x@sha256:abc")[1], "sha256:abc"),
+ ("ghcr.io/beenuar is first-party", _reference().first_party, True),
+ ("ghcr.io/berriai is not", _reference(repository="ghcr.io/berriai/litellm").first_party, False),
+ ("latest is a moving tag", _reference().moving, True),
+ ("v11.0.0 is not", _reference(tag="v11.0.0").moving, False),
+ ("v11.0.0 names a version", version_from_tag("v11.0.0"), "11.0.0"),
+ ("a prerelease tag names one too", version_from_tag("v11.1.0-rc.1"), "11.1.0-rc.1"),
+ ("latest names none", version_from_tag("latest"), ""),
+ ("an upstream tag that merely looks numeric names none", version_from_tag("16-alpine"), ""),
+ ]
+ for description, got, want in readers:
+ record(f"READER: {description}", got == want, f"expected {want!r} got {got!r}")
+
+ # And the chart reader, against the shape that made the chart uninstallable:
+ # a tag left empty is a live reference to Chart.AppVersion, not to nothing.
+ with scratch_tree() as tree:
+ chart = tree / CHART_REL
+ chart.mkdir(parents=True)
+ (chart / "Chart.yaml").write_text('appVersion: "9.9.9"\n', encoding="utf-8")
+ (chart / "values.yaml").write_text(
+ 'services:\n api:\n image:\n repository: ghcr.io/beenuar/aisoc-core-api\n tag: ""\n'
+ 'ueba:\n image:\n repository: ghcr.io/beenuar/aisoc-ueba\n tag: "1.2.3"\n',
+ encoding="utf-8",
+ )
+ parsed = {r.service: (r.repository, r.tag) for r in collect_helm_references(tree)}
+ record(
+ "CHART: an empty tag resolves to Chart.AppVersion rather than to nothing",
+ parsed.get("services.api.image") == ("ghcr.io/beenuar/aisoc-core-api", "9.9.9"),
+ f"got {parsed.get('services.api.image')!r}",
+ )
+ record(
+ "CHART: a nested block outside services/ is found by walking, not by being named",
+ parsed.get("ueba.image") == ("ghcr.io/beenuar/aisoc-ueba", "1.2.3"),
+ f"got {parsed.get('ueba.image')!r}",
+ )
+
+ # The shared floor every gate here answers to, run the way CI runs this one.
+ refused, detail = refuses_an_empty_tree(Path(__file__).name, ["--require-fresh"])
+ record("refuses a tree with no content rather than reporting it clean", refused, detail.replace("\n", " | "))
+
+ print()
+ if not all(passed for _description, passed in checks):
+ print("check_published_images.py: self-test FAILED — this gate did not catch drift it claims to catch")
+ return 1
+ print(f"check_published_images.py: self-test OK ({len(checks)} assertions)")
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/tests/test_first_run_gate.py b/tests/test_first_run_gate.py
index 6f6b3b9ea..fe4c80806 100644
--- a/tests/test_first_run_gate.py
+++ b/tests/test_first_run_gate.py
@@ -157,35 +157,51 @@ def test_no_client_component_hardcodes_a_demo_credential(source: pathlib.Path) -
)
-def _matrix(workflow: pathlib.Path, job: str) -> list[dict]:
+def _build_job(workflow: pathlib.Path) -> tuple[str, dict]:
+ """The job that builds images, found by what it does rather than by name.
+
+ Named lookup broke the moment the release workflow split its build in two:
+ the test asked for `docker-push`, which no longer existed, and a gate that
+ fails because a job was renamed says nothing about the property it guards.
+ The demo build args are the structural signal — exactly one job sets them.
+ """
spec = yaml.safe_load(workflow.read_text())
- return spec["jobs"][job]["strategy"]["matrix"]["include"]
+ named = [
+ (name, job)
+ for name, job in spec["jobs"].items()
+ if any("NEXT_PUBLIC_DEMO_MODE=true" in str(step.get("run", "")) for step in job.get("steps", []))
+ ]
+ assert len(named) == 1, f"{workflow.name}: expected exactly one job setting NEXT_PUBLIC_DEMO_MODE, found {[n for n, _ in named]}"
+ return named[0]
-def _demo_build_step(workflow: pathlib.Path, job: str) -> dict:
- spec = yaml.safe_load(workflow.read_text())
- for step in spec["jobs"][job]["steps"]:
+def _matrix(workflow: pathlib.Path) -> list[dict]:
+ return _build_job(workflow)[1]["strategy"]["matrix"]["include"]
+
+
+def _demo_build_step(workflow: pathlib.Path) -> dict:
+ for step in _build_job(workflow)[1]["steps"]:
if "NEXT_PUBLIC_DEMO_MODE=true" in str(step.get("run", "")):
return step
raise AssertionError(f"{workflow.name}: no step sets NEXT_PUBLIC_DEMO_MODE")
@pytest.mark.parametrize(
- ("workflow", "job"),
- [(PUBLISH_WORKFLOW, "build"), (RELEASE_WORKFLOW, "docker-push")],
+ "workflow",
+ [PUBLISH_WORKFLOW, RELEASE_WORKFLOW],
ids=["publish-images", "release"],
)
-def test_the_demo_bundle_is_built_by_its_own_matrix_entry(workflow: pathlib.Path, job: str) -> None:
+def test_the_demo_bundle_is_built_by_its_own_matrix_entry(workflow: pathlib.Path) -> None:
"""The demo build must be a separate image, not a flag on the product one.
It was a flag on the product one, which is how `latest` — what `make up`
pulls — came to carry a bundle that disabled every write control.
"""
- demo_entries = [e for e in _matrix(workflow, job) if str(e.get("demo", "")) == "true"]
+ demo_entries = [e for e in _matrix(workflow) if str(e.get("demo", "")) == "true"]
assert len(demo_entries) == 1, f"{workflow.name}: expected exactly one matrix entry with `demo: 'true'`, found {len(demo_entries)}"
assert demo_entries[0]["image"].endswith("aisoc-web")
- step = _demo_build_step(workflow, job)
+ step = _demo_build_step(workflow)
assert "matrix.demo" in str(step.get("if", "")), (
f"{workflow.name}: the demo build args are not gated on `matrix.demo`, so a "
f"product build can still receive them (if: {step.get('if')!r})"