fix(supply-chain): pin scanner images and stop Semgrep scanning the engine - #191

…cope

- schemas/scanner-images.schema.json: the per-image constraints sat behind
  `$ref: '#/$defs/image'`, and this repo's jq-based schema validation does not
  resolve $ref — so required/format constraints on every image were
  unenforced at the schema layer. The subschema is inlined.
- doctor.sh: the .semgrepignore exclusion check matched only `path` and
  `path/`, so the other spellings Semgrep honours (`/path`, `path/**`,
  `/path/**`) produced a false WARN on a correctly configured project — a
  check that cries wolf teaches adopters to ignore it. It now accepts every
  spelling and still fails closed on an unrelated exclusion. The remediation
  hint joined several unexcluded paths into one nonsense token ('a b/'); it
  emits one suggestion per path. 283 covers all six spellings, the negative
  control, and the multi-path hint.
- docs: the tag-by-default guidance and the Dependency-Check `latest`
  exception were left standing beside the new digest-by-default contract, so
  a reader could still find instructions contradicting what
  validate-scanner-images.sh enforces. Both are struck through and marked
  superseded in scanner-image-digest-pinning.md and
  supply-chain-reproducibility.md (§4, §8 checklist, References).
- docs/managed-file-inventory.md: hardened-enterprise was missing entirely, so
  its managed .semgrepignore was undocumented. Added, and 268 now asserts that
  every profile manifest AND every managed target it declares appears in the
  inventory, so the next profile cannot ship undocumented.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…make the contract non-bypassable

- config/scanner-images.json + templates: Semgrep, Gitleaks, Grype and
  Dockle shipped as VERSION TAGS. A tag is a mutable registry pointer — the
  publisher can retarget it, so shipped workflows could execute changed
  scanner bytes with no repository change, and `templates` mode only checked
  the reference text while registry drift detection is opt-in. Every shipped
  default is now `repository@sha256:…`; the readable tag survives as
  `resolved_from` and as the trailing comment. The engine's own CI had the
  same problem inline (`${VAR:-semgrep/semgrep:1.165.0}`, a hardcoded
  `zricethezav/gitleaks:v8.18.4`) and is pinned to the same digests.
- tool-provenance-audit.sh: a BARE image reference (no tag, no digest) left
  the tag empty, so the mutable-tag check was skipped for exactly the
  reference Docker resolves to `:latest`. Bare now classifies as `latest`.
- tool-provenance-audit.sh: a MALFORMED contract was collapsed into "no
  contract", which silently switched OFF mutable-tag and digest-drift
  enforcement — corrupting the file was a way to disable the check the file
  exists to perform. Absent is still tolerated; malformed now exits 2.
- validate-scanner-images.sh: a JSON-valid but structurally broken contract
  reached the modes, where a missing `.images` read as "nothing to check".
  Shape is validated before ANY mode. Value rules (full-length digest,
  default_pin enum) stay in `contract` mode so its documented exit-code
  contract is unchanged.
- 283: the Semgrep-scope sweep piped the resolver through `2>/dev/null ||
  printf ''`, so a resolver crash or an unknown profile produced an empty
  policy — which the case below treats as "this profile does not select
  Semgrep", passing it WITHOUT checking its ignore file. Fail-open in the one
  suite whose job is to make self-scanning impossible to reintroduce
  unnoticed. It now fails explicitly on a non-zero resolver exit.
- 282: adds the contract-cannot-be-disabled cases (non-JSON, empty images,
  an image record missing its fields, no mode able to run) plus assertions
  that the schema inlines its per-image constraints and that every shipped
  default is a digest.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…ks, no stale pinning prose

Code:
- doctor.sh interpolated SENTINEL_SHIELD_PATH straight into an ERE, so the
  leading dot every default path starts with matched ANY character — the
  .semgrepignore exclusion check was more permissive than it claimed and
  would have accepted a subtly wrong ignore line. The path is escaped now.
- validate-release-status.sh reported SWEEP_EMPTY (a contract violation, exit
  1) when `git ls-files` returned nothing — which is what happens in a
  tarball or a vendored copy. A missing tool is exit 3 by the documented
  contract; the repository is no longer blamed for the absence of git.
- 281 required the BARE ref literal in every template while the validator
  strips quotes and trailing comments (its own t4 case codifies the quoted
  form), so a legitimately quoted template would have failed the suite. The
  ref is also escaped, for the same ERE reason as above.
- 268's per-target inventory check searched the WHOLE document, so a missing
  row passed because the same target name appears under other profiles. It
  now slices the profile's own section — verified by deleting the
  hardened-enterprise .semgrepignore row, which the scoped check catches and
  the unscoped one did not.
- 268's stale-claim sweep matched one exact phrasing, so
  "(engine-only; off by default in existing modes)" and "additive, off by
  default in existing modes" walked straight past it. The pattern now covers
  every phrasing, and five more docs are corrected.

Profiles:
- hardened-enterprise extends BOTH the Laravel and Node stacks but shipped
  the Laravel-only ignore file, so Semgrep scanned .next/, .turbo/,
  generated/ and *.generated.* as application code. It now ships its own
  ignore file carrying both scopes.

Prose that contradicted the digest-pinning change in the same PR: the
ci-security image comment, the template header comments, the resolution date
(now taken from the contract's own resolved_at), the pinning-status paragraph
in the template inventory, the shipped-default table, the supersession note in
supply-chain-reproducibility, the v0.1.0 first-run reference in the example,
and the upgrade guidance in upgrading.md / v2.2.0-known-limitations.md.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

'for which enforce in which mode' was grammatically incomplete; it now reads
'for which gates are enforced in which modes'.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…gnore file

CodeRabbit review follow-up on the scanner-pinning / Semgrep-scope work.

`.semgrepignore` shipped as `create-if-missing`, so a project that adopted before the
exclusion existed kept its old file and NEVER received `tools/sentinel-shield/`. Semgrep then
scanned the embedded engine checkout as application code and the scope guarantee — the whole
point of the file — was silently lost. `doctor.sh` reported the gap, but a warning does not
close it.

New manifest mode `merge-required-lines`: the file stays project-owned (nothing is
overwritten, reordered or removed) and every non-comment line of the shipped template is
treated as REQUIRED — the missing ones are appended under a marker comment. Matching is on
exact rule text, so the merge is idempotent. `install-baseline.sh` still only creates
(and points at the sync when the file already exists); `sync-baseline.sh` performs the merge.
Applied to the five profiles that ship a `.semgrepignore`.

Also from the same review:
- tool-provenance-audit: validate the per-image RECORDS, not just the containers.
  `{"images":{"x":{}},"mutable_tags":[]}` used to pass and then left every lookup empty —
  an unenforceable contract that read as an enforced one. Now matches
  validate-scanner-images.sh: non-empty mutable tags, and a sha256 digest on every record.
- tool-provenance-audit: a tag can only live in the FINAL path component. Matching `*:*`
  against the whole reference read the REGISTRY PORT of `registry.internal:5000/dep-check`
  as a tag, so that bare reference dodged the implicit-`latest` rule.
- self-test: the cheap ignore-template guard skipped profiles/hardened-enterprise.
- docs: MD028 blank line inside the historical blockquote; `analyses` -> `analyzes`;
  fenced block language.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…guidance

CodeRabbit review follow-up.

- scanner-image-digest-pinning.md: the retained v0.1.28 block still read as operational advice —
  a table recommending readable tags for development and a bullet saying default templates stay
  tag-based. Under the v2.2+ approved-image contract no shipped template may execute a mutable
  tag in any context, so a reader could copy an insecure default out of a section meant to be a
  historical record. The block is now explicitly framed as history and struck through.
- v2.2.0-known-limitations.md: the document warns that several gates block from `baseline` and
  from every mode, then closed with "Existing mode defaults are unchanged: a project that
  upgrades and changes nothing sees no new blocking gate" — the opposite guarantee, in the
  authoritative limitations document referenced by GATE 10. Corrected to match the matrix.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

CodeRabbit review follow-up.

`sync-baseline.sh` exits 2 without `--target`, so the hint the installer printed —
`run sync-baseline.sh --apply` — failed before it could merge anything. The installer knows
both the target and the profile, so it now prints the full command, and the quickstart
troubleshooting row does the same. Verified by running the printed command verbatim: it merges
the required rules into the existing project file.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

CodeRabbit review follow-up.

- validate-scanner-images.sh: `pass "declared templates exist"` ran unconditionally right after
  the loop that checks them, so a report could carry both DECLARED_TEMPLATE_MISSING and
  "declared templates exist" — a reader scanning for the pass line would read a broken contract
  as satisfied. Now conditional, matching check_templates(). Confirmed with a contract
  declaring a template that does not exist: previously both lines appeared, now only the
  failure.
- tool-provenance-audit.sh: the contract check accepted any digest STARTING with `sha256:`, so
  a truncated or malformed digest passed structural validation and was then compared against a
  resolved digest it could never match. Requires the full `sha256:` + 64 lowercase hex form.
- config/scanner-images.json: the Semgrep rationale said "templates keep the readable form for
  legibility; production pins the digest" and then "shipped default is the DIGEST" in the same
  paragraph. The first half described the superseded policy; removed.
- sentinel-shield-main.yml: the comment above the image block still advertised readable tags as
  the default with digests as the production override. It is the other way round.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…one declared

CodeRabbit flagged a mutable Gitleaks tag shipping in two workflow templates. The tag is
the symptom; this is the reason the contract validator never saw it.

`check_templates` swept `SENTINEL_SHIELD_*_IMAGE: <value>` ASSIGNMENT lines only. A template
does not execute a declaration, it executes a command, and an image named inline — as a
literal or as a `${VAR:-default}` fallback — matched nothing in that sweep. The file header
has promised "no template executes a mutable tag" since it was written; nothing enforced it.

Three fixes, each with a negative control in tests/prod/282:

1. EXECUTION sweep. Every reference to an approved repository anywhere in a declared
   template (whole-line comments excluded — those are documentation) must equal the approved
   reference. A moving tag reports MUTABLE_TAG_EXECUTED, anything else IMAGE_DRIFT_EXECUTED.
   Reading a contract variable the template never declares is IMAGE_VAR_UNDECLARED: the
   inline fallback is what runs, and the declaration sweep sees nothing to check.

2. `ref_tag` parsed the tag as the text after the LAST ':' in the whole reference, so a
   ported registry — registry.example.com:5000/team/img — was read as carrying the tag
   '5000/team/img'. The separator is only a ':' after the last '/'.

3. `[ "$_decl_ok" -eq 1 ] && pass …` was the last command in check_contract, making the
   function's exit status the test's. Under `set -eu` a missing declared template killed the
   script there: no summary, and in `all` mode the template sweep never ran — the run
   reported strictly less than it had already found.

The sweep count over the real tree goes 8 -> 18 inspected references; all pass. The two
templates that actually carry the moving tag are fixed on the branch that introduced them.

…rift in the known

Both existing sweeps start FROM the approved contract and look for those repositories in the
template. That can only ever find drift in an image we already approved. An entirely unknown
image has no repository pattern to search for, so this passed validation cleanly:

    docker run --rm -v "$PWD:/repo" evilcorp/backdoor:latest

An allowlist that cannot reject an unlisted entry is not an allowlist.

The OPERAND sweep runs the other way round: take every image the template actually executes
and require it to BE an approved reference. It reads both shapes that carry one — the operand
of `docker run` (after its flags and the values they take) and a job/service `image:` key —
and reports `IMAGE_NOT_APPROVED` for an unknown literal and `IMAGE_VAR_UNKNOWN` for an image
chosen by a variable that is not in the contract at all.

Running it immediately found a real one: the engine's own CI executes `rhysd/actionlint:1.7.7`
in ci-self-test.yml and ci-security.yml. Two other workflows already pinned that image by
digest, so this was inconsistent as well as mutable. actionlint is now in the approved contract
(digest resolved from the registry: sha256:887a2599…147e9, matching what the pinned workflows
already used) and both bare-tag invocations are pinned.

`repo:tag@sha256:X` is accepted as equivalent to `repo@sha256:X`. When both are present the
DIGEST is what the daemon resolves, so the reference is immutable and the tag is a readability
annotation; rejecting that spelling would have pushed the two already-correct workflows to
look wrong.

A bare `$VAR` operand is skipped rather than treated as the image: in these templates it holds
flags (`$MOUNTS` expands to several -v pairs). If one ever held an image, the token after it
would be read and reported as unapproved — noisy, but the fail-closed direction.

tests/prod/282 covers all three new refusals plus the digest-form acceptance. One existing
assertion moved from "exactly one IMAGE_DRIFT_EXECUTED" to "at least one": both sweeps now
legitimately report that fixture, which is duplicate noise rather than a wrong answer.

Found while checking that the shared normaliser preserves every supported reference form, as
the review asked. It did not.

`${ref%%:*}` cuts at the FIRST colon, which on a ported registry is the PORT:

    registry.example.com:5000/team/img:v1@sha256:bbbb
      -> registry.example.com@sha256:bbbb        (before)
      -> registry.example.com:5000/team/img@sha256:bbbb   (now)

That discarded the repository path entirely, so every image on a given ported host
canonicalised to the same string — two different private-registry images would have compared
equal against the approved contract. Consolidating three sweeps onto one parser is only safer
if the parser is right; this is the failure mode that consolidation creates.

The tag separator is the `:` after the last `/`, the same rule ref_tag already uses, and a tag
is only stripped when the reference carries a digest to fall back on.

tests/prod/282 now pins all seven forms — tag-only, digest-only, tag+digest, ported registry in
each of those shapes, and a bare repository — plus the property that actually matters: two
different images on one ported host do not canonicalise to the same string.