diff-sentry 0.13.0__tar.gz → 0.14.0__tar.gz

{diff_sentry-0.13.0 → diff_sentry-0.14.0}/.claude/rules/monitoring.md

@@ -63,8 +63,9 @@ paths:
 
 ## Image watch (`images.py`, `release-watch --images`)
 
-- **Provenance only, never a layer.** `image_provenance` reads an image's index, each BuildKit attestation manifest and its SLSA provenance layer; `provenance_facts` keeps the source repository (`vcs:source`; `owner/name` only for a URL whose host is exactly github.com, any other source as written, so a lookalike is only judged between GitHub repositories), revision, building repository, workflow without its ref, ref and ref protection. An attestation counts only when its `vnd.docker.reference.digest` is a platform image of the same index and the provenance's `subject` names that image (BuildKit always writes one); a platform image no attestation names is a note. A layer's content is a known gap.
+- **Provenance from the attestation.** `image_provenance` reads an image's index, each BuildKit attestation manifest and its SLSA provenance layer; `provenance_facts` keeps the source repository (`vcs:source`; `owner/name` only for a URL whose host is exactly github.com, any other source as written, so a lookalike is only judged between GitHub repositories), revision, building repository, workflow without its ref, ref and ref protection. An attestation counts only when its `vnd.docker.reference.digest` is a platform image of the same index and the provenance's `subject` names that image (BuildKit always writes one); a platform image no attestation names is a note. The layers are read separately (`layer_change`, below).
 - **Judged against what is known, never against the last image.** A repository holds images from several workflows, so `images.known` holds the sources, the builders (repository and workflow) and the workflows seen building from protected refs: seeded at first sight from the watched floating tags and the newest `_SAMPLED_VERSIONS` version tags, and extended by every image judged clean. An image that signals never extends it, so one bad image cannot vouch for the next. On GHCR the namespace (`_namespace`) is a known owner from the start. `scan_image` grades by owner, since one organisation's repositories share a trust boundary: a source or building repository whose owner imitates a known owner is `image-source-lookalike` / `image-builder-lookalike` (critical, via `indicators.lookalike_owner`); one of an unknown owner is `image-source-changed` / `image-builder-changed` (high); another repository or workflow of a known owner is `medium` (`image-workflow-changed`, a nightly or branch build); an unprotected ref under a workflow known protected is `image-ref-unprotected` (high); an image without provenance while the repository's images carry it, a single manifest included, is `image-provenance-dropped` (high); notes are `release-not-fully-read` (high). A first-sight sample whose owners imitate each other is screened as `image-source-lookalike` (critical) and learns neither: both owners are kept as `known.suspect`, every image of the repository is `image-owner-unresolved` (high) and none is learned until the state is reset, and the suspect owners count among those an image's owner is checked for imitating (`_without_lookalikes`). The first-sight alert has a fixed run id and an `image_judgments` row, so it is sent once and re-sent when refused. An empty owner (Docker Hub has no namespace; a build outside GitHub Actions has no building repository) is never a known owner, and a first sight that read nothing and learned nothing is no baseline (retried next poll). The provenance is unsigned: a match proves nothing, only a mismatch is evidence.
 - **What is judged**: a new tag (cosign's `sha256-<digest>.sig/.att/.sbom` skipped, newest first by the version numbers a tag starts with, at most `_MAX_NEW_TAGS` a poll), a watched floating tag that points at another digest, and one of the newest `_RECHECKED_VERSIONS` plain release tags (`_releases`: no `-nightly` or `-rc` suffix, so one version's pre-releases cannot crowd the current release out) pushed again. The first-sight sample takes the newest plain releases the same way. Digests are read with HEAD requests, which Docker Hub does not count toward its pull limit.
 - **Registries are read anonymously and only from their own hosts**: GHCR and Docker Hub (`registry-1.docker.io`), a Bearer token asked for only from a realm on an allowed host, kept per registry and repository and asked for again on a 401 (Docker Hub's expire in minutes), a blob redirect followed only to their CDN hosts (`pkg-containers.githubusercontent.com`, Docker Hub's `production.cloudfront.docker.com` and `production.cloudflare.docker.com`); every response is bounded. A 429 (`RateLimited`) stops that image's poll and counts as no failure.
+- **Layers by content** (`layer_change`): a judged image is compared with the image it replaces, `previous` in `judge` (a moved tag's stored digest; for a new tag, `_predecessor`: the newest release tag below it by `_version_key` whose digest is stored). Per platform (`_platforms`, attestation manifests aside; a platform the previous image lacks is a note), only the layers the two do not share are downloaded (`_MAX_LAYER_BYTES` each, `DS_RELEASE_MAX_LAYER_MB`, 1 GiB; `_MAX_LAYERS_BYTES`, 4 GiB, a comparison; each checked against its sha256 digest), and each run of layers is applied as a runtime applies it (`_filesystem`: a later layer's file replaces an earlier one's, whiteouts remove what is beneath, `_layer_path` keeps the whole path and drops `..`). The two file systems go through `releases.release_files` in the same two passes as a release (digests first, then text for what changed only), labelled `<platform>/<path>`; the files join the event and its `unread_code` and `notes` join `event["release"]`, so `scan_release` and every text rule read them. A layer that is too large, zstd (`releases._decompressed` names it), not read to its end (`_MAX_LAYER_READ`, 8 GiB decompressed) or not matching its digest is a note (`release-not-fully-read`). A `.pyc` member's digest is of its code past the 16-byte header (`pyc:` prefix), which holds the source's mtime and size and changes with every rebuild. Changed `__pycache__` bytecode whose source the artifact ships is checked against it (`releases._check_bytecode`, `pycheck.check_bytecode`, wheels too): a `python3.N -I -S` process whose magic number matches the pyc (found on `PATH`, or this interpreter) compiles the source and unmarshals the bytecode, runs neither, and compares the code objects (equality ignores the file name). The same code (line numbers included, so a pyc compiled from a shifted copy of the source alerts) is not `release-code-not-read`; other code, or no interpreter of that version here, is. The child runs under `RLIMIT_AS` (2 GiB) and `RLIMIT_CPU` (`pycheck._limits`, where the platform enforces them) and a timeout, since `marshal` is not safe against crafted data. A layer's whiteouts apply to the layers beneath before its own files (an opaque whiteout never hides what its layer adds), the first image of a platform is compared and a second is a note, attestation entries are dropped before `_MAX_PLATFORMS` applies, a member past `_MAX_MEMBER_BYTES` is hashed in chunks (`releases._large_member`) and never held whole (a Python source or bytecode up to `_MAX_CHECKED_BYTES`, 16 MiB, is kept, untexted, for the bytecode check), and a new tag with no release below it is compared with a watched floating tag's image. Each platform's config blob (`_config`, digest-checked, 4 MiB) is compared even when every layer is shared: rendered as Dockerfile lines (`_render_config`) into `<platform>/{config}` for the text rules, with a changed `_RUN_KEYS` setting as `image-run-config-changed` (high) and a `_LOADER_ENV` variable or any `LD_`/`DYLD_` one set or changed as `image-loader-env` (high), both read by `scan_image`; an unreadable config, the previous image's included, is a note, and nothing is compared unless both configs were read.
 - **Like releases**, a comparison that fails is retried on later polls and, after five, screened as not compared (`release-not-fully-read`, which alerts); an alert the SIEM did not accept is re-sent from `screened/` a few per poll.

{diff_sentry-0.13.0 → diff_sentry-0.14.0}/.env.example

@@ -82,4 +82,5 @@ DS_API_KEY=sk-...
 # DS_RELEASE_NPM=@scope/name,left-pad    # release-watch: npm packages (or --npm)
 # DS_RELEASE_SOURCES=litellm=BerriAI/litellm  # release-watch: the GitHub repository each package is built from, compared by tag (or --sources)
 # DS_RELEASE_IMAGES=ghcr.io/owner/name     # release-watch: container images compared by build provenance (or --images)
+# DS_RELEASE_MAX_LAYER_MB=1024            # release-watch: a larger image layer is not read, which alerts
 # DS_RELEASE_IMAGE_TAGS=latest             # release-watch: floating tags whose moves are judged (or --image-tags)

{diff_sentry-0.13.0 → diff_sentry-0.14.0}/AGENTS.md

@@ -31,10 +31,10 @@ rlm-harness is an exact PyPI pin (`rlm-harness==X.Y.Z` in `pyproject.toml`, lock
 - **The budget is hard: `max_retries=1`, no whole-RLM retry inside a run.** One change = one trajectory, so the trace stays valid training data. (`watch` may run a change again, but only when the previous attempt produced no result at all, an infrastructure failure; `cli.run` resets that run id's trace first, so exactly one trajectory per run id survives.) A failed run is infra before it is a schema bug; see `.claude/rules/detect-setup.md` for how the failure names itself.
 - **A second model-judgement is a TOOL, never the sub-LM.** `deep_classify` (on rlm-harness's `make_model_tool`) is the swappable second-stage seam the planner chooses to call, so the decision is a `tool_call` in the trajectory. The analyst intercept (`intercept_sub_lm`) is tracing-only, zero transforms. Swapping the backend touches only `classify_backend` / `_selfclassify_chat`. The planner passes distilled findings, never the whole diff.
 - **Sandboxed code builds no sub-agents.** In dspy 3.4.1 and later, sandboxed code can construct dspy programs that run on the host, call the analyst, can drive the task's tools, and record as one `sub_call` with no inner turns. The kit's default allows it, so `setup` passes `sandbox_sub_agents=False` explicitly, and production never injects an interpreter (which would bypass it); `test_program_offers_no_sub_agents` holds the behaviour.
-- **GitHub ingest, monitoring, and SIEM emission are host-side plumbing, never planner tools.** `ingest.py` shells out to `gh` host-side (transport injectable); `emit.emit_signal` POSTs and never raises; `watch`, `actors` and `snapshot` poll, remember, and archive outside the trajectory, `releases` and `npm` read PyPI's and npm's own hosts, and the refs and trees of a package's GitHub repository, as data that is never installed, and `images` reads the GHCR and Docker Hub APIs only (manifests and provenance, never a layer). Only choices the policy makes are tools; delivering a finished result is plumbing. What the store learns reaches the signal only as provenance facts through `scan_provenance`, never as a second derivation (see `.claude/rules/monitoring.md`).
+- **GitHub ingest, monitoring, and SIEM emission are host-side plumbing, never planner tools.** `ingest.py` shells out to `gh` host-side (transport injectable); `emit.emit_signal` POSTs and never raises; `watch`, `actors` and `snapshot` poll, remember, and archive outside the trajectory, `releases` and `npm` read PyPI's and npm's own hosts, and the refs and trees of a package's GitHub repository, as data that is never installed, and `images` reads the GHCR and Docker Hub APIs only (manifests, provenance, and the layers two images do not share, as data in memory, never unpacked or run). `pycheck` compiles a release's Python source and unmarshals its bytecode in a separate interpreter to compare them, and runs neither. Only choices the policy makes are tools; delivering a finished result is plumbing. What the store learns reaches the signal only as provenance facts through `scan_provenance`, never as a second derivation (see `.claude/rules/monitoring.md`).
 - **This is a ROLLOUT source: trajectories, not reward.** `rl_export` passes `reward=None`; labels read the assembled verdict and metrics are objective effort counters. `deep_classify` tool_calls train the classifier; every other action is the planner's. A metric keeps ONE meaning across rlm-harness versions (the corpus mixes them; `run_start.payload.rlm_harness` names the writer): a quantity a newer kit makes observable gets a NEW key that is None where the trace cannot say (e.g. `analyst_failures`). The ATLAS rubric and the eval member stay reward-free too; see `.claude/rules/rubric-and-eval.md`.
 - **Attack knowledge lives in `diff_sentry/skills/`, not the prompt.** The skill catalog is injected (`load_skills_as_tools(discovery="inject")`) and `read_skill(name)` pulls a body on demand. Fix a wrong convention by editing or adding a skill; `detect.INSTRUCTIONS` holds only identity, the MISSION frame, the tool cost model, the triage loop, and output-gating rules. Skills ship via `packages = ["diff_sentry"]`; a force-include duplicates them and breaks the build.
-- **Keep the dspy-free modules dspy-free.** `config`, `schema`, `normalize`, `indicators`, `shelllex`, `linewide`, `assemble`, `response`, `emit`, `ingest`, `hosts`, `dbutil`, `actors`, `snapshot`, `watch`, `releases`, `npm`, `images`, `rl_export`, and `rubric` must not import dspy at module top, and `import diff_sentry` must not import dspy (`ClassifyChange` / `setup` / `run` / `screen` / `detect_from_event` are lazy PEP 562 re-exports).
+- **Keep the dspy-free modules dspy-free.** `config`, `schema`, `normalize`, `indicators`, `shelllex`, `linewide`, `assemble`, `response`, `emit`, `ingest`, `hosts`, `dbutil`, `actors`, `snapshot`, `watch`, `releases`, `npm`, `images`, `pycheck`, `rl_export`, and `rubric` must not import dspy at module top, and `import diff_sentry` must not import dspy (`ClassifyChange` / `setup` / `run` / `screen` / `detect_from_event` are lazy PEP 562 re-exports).
 - **The trace self-describes the run.** `run_start` meta carries the normalized event, instructions, source echo, `baseline_indicators`, `emit_on`, role→model names, budgets, and the rubric skeleton, so an offline re-render/export re-derives the same `signal` (reading `emit_on` from meta, never current config). Any new per-run config that affects read-time derivation must ride in meta.
 
 ## Topic guides
@@ -54,5 +54,5 @@ Claude Code loads each rule automatically when you touch a matching file; other
 
 - rlm-harness owns the generic cores: `make_model_tool` (chat → retry → validate → circuit-break) under `deep_classify`, and the SSRF primitives (`is_safe_url`, `resolved_host_is_safe`, `parse_cidrs`) under `fetch_tool`, which adds the GitHub allowlist, the httpx provider, and tracing.
 - When this consumer needs a workaround, fix the reusable gap in rlm-harness generically; never special-case diff-sentry there. Consumer values (`DS_*` roles, the verdict schema, indicator rules, the SIEM payload shape) stay here.
-- The deterministic tier ships as `cli.screen`, `watch` and `release-watch` (host-side, in front of `cli.run`). Next increments: an image's new layers by content; an optional small single-shot model call inside that tier; a GH Archive backfill for account history older than the Events API's 30 days; per-repository workflow awareness (which repos run `issue_comment` or `pull_request_target` workflows) to weight the slash-command rule.
+- The deterministic tier ships as `cli.screen`, `watch` and `release-watch` (host-side, in front of `cli.run`). Next increments: an optional small single-shot model call inside that tier; a GH Archive backfill for account history older than the Events API's 30 days; per-repository workflow awareness (which repos run `issue_comment` or `pull_request_target` workflows) to weight the slash-command rule.
 - Two workspace members, never in the `diff_sentry` wheel: `studio/` (`diff-sentry-studio`, the detection console, behind its `live` extra) and `eval/` (`diff-sentry-eval`, the reward-free scorecard). Both read the trace / `DetectionResponse` contract through the public surface only. Keep the root wheel at `packages = ["diff_sentry"]` so `uv build` never sweeps them in.

{diff_sentry-0.13.0 → diff_sentry-0.14.0}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to diff-sentry, a BewAIre-style detector that classifies one GitHub change (PR, issue or push) for malicious intent on [`rlm-harness`](https://github.com/qazbnm456/rlm-harness).
 
+## 0.14.0
+
+Upgrade from 0.13.0: `release-watch --images` now reads what each image changes, and checks compiled bytecode against its source. The GitHub Action's scan is unchanged, and `rlm-harness==1.24.0` is unchanged. For the bytecode check, install the Python version an image or wheel uses (`python3.N` on `PATH`) beside the watcher; without it, changed bytecode alerts that it could not be checked.
+
+### Added
+- **`release-watch --images` compares an image's files with the image it replaces.** A moved tag is compared with the image it pointed at, and a new tag with the newest release below it. Only the layers the two do not share are downloaded and checked against their digests, then applied as a runtime applies them, and the files that changed are screened by the same rules as a release, so a `.pth` startup hook in an image's site-packages alerts as it does in a wheel. A layer it cannot read, a new platform, and two images for one platform alert that the image was not fully read. A layer can be capped with `DS_RELEASE_MAX_LAYER_MB` (1024 by default).
+- **An image's run configuration is compared too**, even when every layer is reused: another entrypoint, command, shell, user, working directory, healthcheck or build trigger is `image-run-config-changed` (`high`), and an environment variable that loads code (`LD_PRELOAD`, `PYTHONPATH`, `PYTHONWARNINGS`, `NODE_OPTIONS`, `PATH` and the like) is `image-loader-env` (`high`).
+- **Compiled bytecode is checked against its source**, in images and wheels. Python can run a cached `.pyc` instead of the source beside it, so a changed `.pyc` is compared with its source compiled, in a separate, bounded interpreter of the same Python version that runs neither. Bytecode that is not its source compiled alerts.
+
+### Changed
+- **A `.pyc` is compared by its code, not its header**, which every rebuild rewrites, so a rebuilt image or wheel no longer alerts on unchanged bytecode.
+
 ## 0.13.0
 
 Upgrade from 0.12.0: `release-watch` can watch npm packages. The GitHub Action's scan is unchanged, nothing needs configuring, and `rlm-harness==1.24.0` is unchanged.

{diff_sentry-0.13.0 → diff_sentry-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: diff-sentry
-Version: 0.13.0
+Version: 0.14.0
 Summary: Catch malicious pull requests before they merge: scan a diff for supply-chain attack patterns with deterministic evidence a model cannot suppress.
 Author: Boik Su
 License-Expression: MIT
@@ -43,7 +43,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0          # the scan diffs against the PR base
-      - uses: qazbnm456/diff-sentry@v0.13.0
+      - uses: qazbnm456/diff-sentry@v0.14.0
 ```
 
 That is the whole setup. The job fails when an indicator at or above `high` fires. Add `push` to `on:` to also scan commits pushed straight to a branch. A push that bypasses branch protection can also delete this workflow, so `watch` and `release-watch` read the repository and its releases from outside.

{diff_sentry-0.13.0 → diff_sentry-0.14.0}/README.md

@@ -21,7 +21,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0          # the scan diffs against the PR base
-      - uses: qazbnm456/diff-sentry@v0.13.0
+      - uses: qazbnm456/diff-sentry@v0.14.0
 ```
 
 That is the whole setup. The job fails when an indicator at or above `high` fires. Add `push` to `on:` to also scan commits pushed straight to a branch. A push that bypasses branch protection can also delete this workflow, so `watch` and `release-watch` read the repository and its releases from outside.

{diff_sentry-0.13.0 → diff_sentry-0.14.0}/action.yml

@@ -40,7 +40,7 @@ inputs:
       that PR rather than by the ones already on main.
     required: false
     # KEEP IN STEP WITH [project].version. release.yml fails the build if this drifts from the tag being released, because a stale default here would silently run an old scanner under a new action tag.
-    default: '0.13.0'
+    default: '0.14.0'
 
 outputs:
   failed:

{diff_sentry-0.13.0 → diff_sentry-0.14.0}/diff_sentry/__init__.py

@@ -72,7 +72,7 @@ __all__ = [
     "screen",
 ]
 
-__version__ = "0.13.0"
+__version__ = "0.14.0"
 
 
 def __getattr__(name: str):  # PEP 562: defer the dspy import to first use

{diff_sentry-0.13.0 → diff_sentry-0.14.0}/diff_sentry/cli.py

@@ -33,8 +33,7 @@ async def detect_from_event(
     on_event: Callable[[dict], None] | None = None,
     extra_tools=(),
 ):
-    """Run the classifier on one change event and return the planner's JUDGEMENT (`ChangeVerdict`).
-    Call `assemble.assemble_verdict(verdict, events)` to attach the deterministic indicators + signal."""
+    """Run the classifier on one change event and return the planner's JUDGEMENT (`ChangeVerdict`). Call `assemble.assemble_verdict(verdict, events)` to attach the deterministic indicators + signal."""
     import rlm_harness
 
     from .detect import ClassifyChange, setup

{diff_sentry-0.13.0 → diff_sentry-0.14.0}/diff_sentry/images.py

@@ -1,24 +1,17 @@
-"""Image watch: each new or moved tag of a watched container image, judged by its build provenance against what the
-repository's images have been built from before.
-
-litellm 1.107.0's images on GHCR and Docker Hub, `latest` and `main-stable` among them, were built by its own release
-workflow from the attacker's `Berri-AI/litellm`, and BuildKit wrote that in each image's SLSA provenance (`vcs:source`).
-So the provenance of an image names where it was built from and what built it, without reading a layer. A repository
-holds images from several workflows (releases, nightlies, branch builds), so an image is judged against the set of
-sources and builders the repository is known to use, learned from a sample at first sight and from every image judged
-clean since, never from one that raised an alert. The comparison is screened like a release (`kind="release"`, facts
-in `release.image`), and `scan_image` turns it into baseline hits.
-
-Host-side plumbing, like `releases`: it reads the registry's API only (manifests, the provenance attestation), from
-the registries' own hosts and anonymous pull tokens, with every response bounded. Layers are never downloaded. Pure
-stdlib + httpx; no dspy.
+"""Image watch: each new or moved tag of a watched container image, judged by its build provenance against what the repository's images have been built from before, and by the files it changes.
+
+litellm 1.107.0's images on GHCR and Docker Hub, `latest` and `main-stable` among them, were built by its own release workflow from the attacker's `Berri-AI/litellm`, and BuildKit wrote that in each image's SLSA provenance (`vcs:source`). So the provenance of an image names where it was built from and what built it. A repository holds images from several workflows (releases, nightlies, branch builds), so an image is judged against the set of sources and builders the repository is known to use, learned from a sample at first sight and from every image judged clean since, never from one that raised an alert. The provenance is unsigned, so the image's content is read too: the layers it does not share with the image it replaces, compared file by file (`layer_change`). The comparison is screened like a release (`kind="release"`, facts in `release.image`, changed files as the event's files), and `scan_image` turns the provenance into baseline hits.
+
+Host-side plumbing, like `releases`: it reads the registry's API only (manifests, the provenance attestation, the layers two images do not share), from the registries' own hosts and anonymous pull tokens, with every response bounded. A layer is read as data in memory, never unpacked to disk or run. Pure stdlib + httpx; no dspy.
 """
 
 from __future__ import annotations
 
+import hashlib
 import json
 import logging
 import os
+import posixpath
 import re
 import time
 from collections.abc import Callable
@@ -27,12 +20,12 @@ from datetime import UTC, datetime
 from urllib.parse import quote, urlsplit
 
 from .dbutil import open_versioned
+from .releases import Artifact
 from .schema import IndicatorHit
 
 log = logging.getLogger(__name__)
 
-# A fetch maps (url, request headers, byte limit) to (status, response headers, body), and never follows a redirect. A
-# request header `X-Method: HEAD` asks for a HEAD (a digest without the manifest, which Docker Hub does not count).
+# A fetch maps (url, request headers, byte limit) to (status, response headers, body), and never follows a redirect. A request header `X-Method: HEAD` asks for a HEAD (a digest without the manifest, which Docker Hub does not count).
 Fetch = Callable[[str, dict, int], tuple[int, dict, bytes]]
 
 # The registries an image may be read from, the hosts their tokens come from, and the hosts their blobs redirect to.
@@ -108,9 +101,7 @@ class RateLimited(RuntimeError):
 
 
 class Registry:
-    """A registry's API read anonymously: a pull token is asked for when the registry answers 401 with a Bearer
-    challenge (again when a token expires), from the realm it names (an allowed host), kept per registry and repository;
-    a blob's redirect is followed to an allowed host only."""
+    """A registry's API read anonymously: a pull token is asked for when the registry answers 401 with a Bearer challenge (again when a token expires), from the realm it names (an allowed host), kept per registry and repository; a blob's redirect is followed to an allowed host only."""
 
     def __init__(self, fetch: Fetch):
         self.fetch = fetch
@@ -191,15 +182,13 @@ class Registry:
 # ── provenance ───────────────────────────────────────────────────────────────────────────────────────────
 
 def _source_repo(url: str) -> str:
-    """`owner/name` of a GitHub repository URL, lower case; any other source as written, lower case (never read as a
-    GitHub owner, so a lookalike is only ever judged between GitHub repositories)."""
+    """`owner/name` of a GitHub repository URL, lower case; any other source as written, lower case (never read as a GitHub owner, so a lookalike is only ever judged between GitHub repositories)."""
     m = _GITHUB_REPO_RE.fullmatch((url or "").strip())
     return m.group(1).lower() if m else (url or "").strip().lower()
 
 
 def provenance_facts(statement: dict) -> dict:
-    """What a BuildKit SLSA provenance (v0.2 or v1) says about where an image was built from and what built it: the
-    source repository and revision, and the GitHub repository, workflow (without its ref) and ref protection of the run."""
+    """What a BuildKit SLSA provenance (v0.2 or v1) says about where an image was built from and what built it: the source repository and revision, and the GitHub repository, workflow (without its ref) and ref protection of the run."""
     predicate = statement.get("predicate") or {}
     meta = ((predicate.get("runDetails") or {}).get("metadata") or predicate.get("metadata") or {})
     vcs = (meta.get("buildkit_metadata") or meta.get("https://mobyproject.org/buildkit@v1#metadata") or {}).get("vcs") or {}
@@ -223,10 +212,7 @@ def provenance_facts(statement: dict) -> dict:
 
 
 def image_provenance(registry: Registry, ref: ImageRef, reference: str) -> tuple[str, list[dict], list[str], bool]:
-    """The image's digest, the provenance facts of each platform it carries, notes on what could not be read, and
-    whether it is a multi-platform index (a single manifest carries no BuildKit attestation). An attestation counts only
-    when it names (`vnd.docker.reference.digest`) a platform image of the same index; a platform image no attestation
-    names is a note."""
+    """The image's digest, the provenance facts of each platform it carries, notes on what could not be read, and whether it is a multi-platform index (a single manifest carries no BuildKit attestation). An attestation counts only when it names (`vnd.docker.reference.digest`) a platform image of the same index; a platform image no attestation names is a note."""
     digest, top = registry.manifest(ref, reference)
     notes: list[str] = []
     if top.get("mediaType") not in _INDEX_TYPES and "manifests" not in top:
@@ -264,6 +250,176 @@ def image_provenance(registry: Registry, ref: ImageRef, reference: str) -> tuple
     return digest, facts, notes, True
 
 
+# ── layers ───────────────────────────────────────────────────────────────────────────────────────────────
+
+_MAX_LAYER_BYTES = int(os.getenv("DS_RELEASE_MAX_LAYER_MB", "1024") or "1024") << 20   # one compressed layer
+_MAX_LAYERS_BYTES = 4 << 30        # every differing layer of one comparison, both images and all platforms
+_MAX_LAYER_READ = 8 << 30          # what one layer may decompress to
+
+
+def _platform(desc: dict) -> str:
+    p = desc.get("platform") or {}
+    return "-".join(str(x) for x in (p.get("os"), p.get("architecture"), p.get("variant")) if x) or "default"
+
+
+def _platforms(registry: Registry, ref: ImageRef, digest: str, notes: list[str]) -> dict[str, dict]:
+    """Each platform image of an index (attestation manifests aside), or the one image of a single manifest, by platform. A runtime pulls the first entry for its platform, so that one is kept, and a second entry for a platform is a note."""
+    _, top = registry.manifest(ref, digest)
+    if top.get("mediaType") not in _INDEX_TYPES and "manifests" not in top:
+        return {"default": top}
+    images = [d for d in top.get("manifests") or [] if isinstance(d, dict)
+              and (d.get("annotations") or {}).get("vnd.docker.reference.type") != "attestation-manifest"]
+    if len(images) > _MAX_PLATFORMS:
+        notes.append(f"{len(images)} platform images, the first {_MAX_PLATFORMS} compared")
+    out: dict[str, dict] = {}
+    for desc in images[:_MAX_PLATFORMS]:
+        key = _platform(desc)
+        if key in out:
+            notes.append(f"{key}: two images for one platform; the first, which a runtime pulls, is compared")
+            continue
+        out[key] = registry.manifest(ref, desc["digest"])[1]
+    return out
+
+
+def _layer_path(name: str) -> str | None:
+    """A layer member's path in the image's file system (`./usr/bin/x` and `/usr/bin/x` are `usr/bin/x`)."""
+    parts = [p for p in name.split("/") if p not in ("", ".")]
+    return None if not parts or ".." in parts or name.endswith("/") else "/".join(parts)
+
+
+def _filesystem(kind: str, layers: list[tuple[str, bytes]], budget) -> Artifact:
+    """The files a run of layers leaves, applied in order as a container runtime applies them: a layer's whiteouts (`.wh.name`, `.wh..wh..opq`) first remove what the layers beneath it hold, then its files replace earlier ones (no shadow)."""
+    from .releases import _read_tar, _Spent
+
+    merged = Artifact(kind, kind)
+    for digest, body in layers:
+        layer = Artifact(f"{kind} layer {digest[7:19]}", kind)
+        try:
+            _read_tar(layer, body, budget, path_of=_layer_path, limit=_MAX_LAYER_READ)
+        except _Spent:
+            layer.notes.append(f"{layer.filename}: not read to its end (more than {_MAX_LAYER_READ >> 30} GiB decompressed)")
+        except Exception as exc:  # noqa: BLE001 (fail CLOSED: a layer this cannot read is evidence)
+            layer.notes.append(f"{layer.filename}: not read to its end ({str(exc)[:80] or type(exc).__name__})")
+        merged.notes += layer.notes
+        # a layer's whiteouts remove what the layers beneath it hold, never what the layer itself adds (the OCI layer spec): so they apply first
+        for member in layer.members.values():
+            folder, base = posixpath.split(member.path)
+            if base == ".wh..wh..opq":
+                for gone in [k for k in merged.members if k.startswith(f"{folder}/" if folder else "")]:
+                    del merged.members[gone]
+            elif base.startswith(".wh."):
+                target = posixpath.join(folder, base[4:])
+                for gone in [k for k in merged.members if k == target or k.startswith((f"{target}/", f"{target}\0"))]:
+                    del merged.members[gone]
+        for key, member in layer.members.items():
+            if not posixpath.basename(member.path).startswith(".wh."):
+                merged.members[key] = member
+    return merged
+
+
+# what the config sets that decides what a container runs, and the environment variables that load code into a process
+_RUN_KEYS = ("Entrypoint", "Cmd", "Shell", "User", "WorkingDir", "OnBuild", "Healthcheck")
+_LOADER_ENV = frozenset({"PATH", "PYTHONWARNINGS", "PYTHONEXECUTABLE", "PYTHONPLATLIBDIR", "GCONV_PATH", "NODE_EXTRA_CA_CERTS", "LD_PRELOAD", "LD_LIBRARY_PATH", "LD_AUDIT", "PYTHONPATH", "PYTHONSTARTUP", "PYTHONHOME",
+                         "PYTHONINSPECT", "PYTHONUSERBASE", "NODE_OPTIONS", "NODE_PATH", "BASH_ENV", "ENV", "PERL5OPT",
+                         "PERL5LIB", "RUBYOPT", "RUBYLIB", "JAVA_TOOL_OPTIONS", "_JAVA_OPTIONS", "DYLD_INSERT_LIBRARIES"})
+_MAX_CONFIG_BYTES = 4 << 20
+
+
+def _config(registry: Registry, ref: ImageRef, manifest: dict, notes: list[str]) -> dict | None:
+    """A platform image's run configuration (its config blob's `config`), checked against its digest; None, with a note, when it cannot be read."""
+    desc = manifest.get("config") if isinstance(manifest.get("config"), dict) else {}
+    digest = str(desc.get("digest") or "")
+    try:
+        body = registry.blob(ref, digest, _MAX_CONFIG_BYTES)
+        if not digest.startswith("sha256:") or hashlib.sha256(body).hexdigest() != digest[7:]:
+            raise ValueError("does not match its digest")
+        config = json.loads(body.decode("utf-8")).get("config") or {}
+        return config if isinstance(config, dict) else {}
+    except RateLimited:
+        raise
+    except (RuntimeError, ValueError, AttributeError) as exc:
+        notes.append(f"the image config {digest[7:19]} was not read ({str(exc)[:80]})")
+        return None
+
+
+def _env(config: dict) -> dict[str, str]:
+    return {str(e).split("=", 1)[0]: str(e).split("=", 1)[-1] for e in config.get("Env") or [] if isinstance(e, str)}
+
+
+def _render_config(config: dict) -> str:
+    """The run configuration as a Dockerfile would write it, one setting a line, so the text rules read its commands."""
+    lines = [f"{key.upper()} {json.dumps(config[key])}" for key in _RUN_KEYS if config.get(key) not in (None, [], "")]
+    lines += [f"ENV {k}={v}" for k, v in sorted(_env(config).items())]
+    return "\n".join(lines) + "\n"
+
+
+def layer_change(registry: Registry, ref: ImageRef, digest: str, previous: str) -> tuple[list[dict], list[str], list[str], dict]:
+    """The files an image changes against the image it replaces, platform by platform, and its run configuration against the replaced one's (`{config}`, rendered as Dockerfile lines, with the run settings and loader variables it changes as facts): only the layers the two do not share are read (a shared layer is the same bytes), in two passes like a release (`releases.release_event`), and their files compared by path, so a rebuilt layer shows only what changed in it. Returns the change's files, the members that run and were not shown as text, and notes on what was not read. Layers are read as DATA, in memory, and never unpacked or run."""
+    from .releases import _Budget, _patch, pyc_source, release_files
+
+    files: list[dict] = []
+    unread: list[str] = []
+    notes: list[str] = []
+    runs: list[str] = []
+    loaders: list[str] = []
+    now, before = _platforms(registry, ref, digest, notes), _platforms(registry, ref, previous, [])
+    budget = [_MAX_LAYERS_BYTES]
+
+    def download(layers: list[dict]) -> list[tuple[str, bytes]]:
+        out = []
+        for layer in layers:
+            size, digest_ = int(layer.get("size") or 0), str(layer.get("digest") or "")
+            if size > _MAX_LAYER_BYTES or size > budget[0]:
+                notes.append(f"layer {digest_[7:19]}: {size} bytes, not read (more than DS_RELEASE_MAX_LAYER_MB, or the comparison's budget)")
+                continue
+            body = registry.blob(ref, digest_, _MAX_LAYER_BYTES)
+            if not digest_.startswith("sha256:") or hashlib.sha256(body).hexdigest() != digest_[7:]:
+                notes.append(f"layer {digest_[7:19]}: the download does not match its digest")
+                continue
+            budget[0] -= len(body)
+            out.append((digest_, body))
+        return out
+
+    for platform, manifest in now.items():
+        old = before.get(platform)
+        if old is None:
+            notes.append(f"{platform}: a platform the previous image did not have, so its layers were not compared")
+            continue
+        config, before_config = _config(registry, ref, manifest, notes), _config(registry, ref, old, notes)
+        if config is not None and before_config is not None and config != before_config:
+            patch, added, removed, _ = _patch(_render_config(before_config), _render_config(config))
+            files.append({"filename": f"{platform}/{{config}}", "status": "modified", "additions": added,
+                          "deletions": removed, "patch": patch})
+            for key in _RUN_KEYS:
+                if config.get(key) != before_config.get(key):
+                    runs.append(f"{platform} {key}: {json.dumps(config.get(key))}"[:200])
+            env, before_env = _env(config), _env(before_config)
+            loaders.extend(f"{platform} {k}={v}"[:200] for k, v in sorted(env.items())
+                           if (k in _LOADER_ENV or k.startswith(("LD_", "DYLD_"))) and before_env.get(k) != v)
+        mine = [layer for layer in manifest.get("layers") or [] if isinstance(layer, dict)]
+        theirs = [layer for layer in old.get("layers") or [] if isinstance(layer, dict)]
+        shared = {layer.get("digest") for layer in mine} & {layer.get("digest") for layer in theirs}
+        if all(layer.get("digest") in shared for layer in mine):
+            continue
+        new_bodies = download([layer for layer in mine if layer.get("digest") not in shared])
+        old_bodies = download([layer for layer in theirs if layer.get("digest") not in shared])
+        skim = _Budget(keep=lambda path, digest_: False)
+        old_digests = {(m.path, m.digest) for m in _filesystem(platform, old_bodies, skim).members.values()}
+        wanted = {(m.path, m.digest) for m in _filesystem(platform, new_bodies, skim).members.values()
+                  if (m.path, m.digest) not in old_digests}
+        paths = {p for p, _ in wanted}
+        sources = {src for p in paths if (src := pyc_source(p))}       # read too, to check the bytecode against
+        text = _Budget()
+        new = _filesystem(platform, new_bodies, _Budget.share(
+            text, lambda path, digest_, w=wanted, s=sources: (path, digest_) in w or path in s))
+        old_fs = _filesystem(platform, old_bodies, _Budget.share(text, lambda path, digest_, p=paths: path in p))
+        notes += new.notes
+        changed, missed = release_files([new], [old_fs])
+        files += changed
+        unread += missed
+    return files, unread[:50], notes[:50], {"config_run_changed": runs[:50], "config_loader_env": loaders[:50]}
+
+
 # ── facts as evidence ────────────────────────────────────────────────────────────────────────────────────
 
 def _owner(repo: str) -> str:
@@ -277,14 +433,7 @@ def _imitates(owner: str, owners: set[str]) -> bool:
 
 
 def scan_image(facts: dict) -> list[IndicatorHit]:
-    """An image's provenance against what its repository is known to be built from and by (`known`) and, on GHCR, the
-    namespace it is published under (a GitHub owner). A source or building repository whose owner imitates a known owner
-    is `critical`; one of an owner not known is `high`; another repository or workflow of a known owner is `medium` (a
-    repository's nightly and branch builds run other workflows, even from another repository of the same organisation); a build from an unprotected
-    ref by a workflow whose known builds ran from protected refs is `high` (litellm's attacker turned protection off
-    first). An image without provenance where the repository's images carry it is `high`, and so is anything that could
-    not be read. The provenance is unsigned: whoever controls the push can write any statement, so a match proves
-    nothing and only a mismatch is evidence."""
+    """An image's provenance against what its repository is known to be built from and by (`known`) and, on GHCR, the namespace it is published under (a GitHub owner). A source or building repository whose owner imitates a known owner is `critical`; one of an owner not known is `high`; another repository or workflow of a known owner is `medium` (a repository's nightly and branch builds run other workflows, even from another repository of the same organisation); a build from an unprotected ref by a workflow whose known builds ran from protected refs is `high` (litellm's attacker turned protection off first). An image without provenance where the repository's images carry it is `high`, and so is anything that could not be read. The provenance is unsigned: whoever controls the push can write any statement, so a match proves nothing and only a mismatch is evidence."""
     from .indicators import _hit
 
     if not isinstance(facts, dict) or not facts:
@@ -341,6 +490,14 @@ def scan_image(facts: dict) -> list[IndicatorHit]:
             hits.append(_hit("image-ref-unprotected", "high",
                              "a workflow whose known builds ran from protected refs built this image from an unprotected one",
                              f"{item.get('workflow')} @ {item.get('ref')}"[:240], location=where))
+    if facts.get("config_run_changed"):
+        hits.append(_hit("image-run-config-changed", "high",
+                         "the image runs another entrypoint, command, shell, user, healthcheck or build trigger than the image it replaces",
+                         "; ".join(str(x) for x in facts["config_run_changed"])[:240], location=where))
+    if facts.get("config_loader_env"):
+        hits.append(_hit("image-loader-env", "high",
+                         "the image sets an environment variable that loads code into its processes (LD_PRELOAD, PYTHONPATH, NODE_OPTIONS...)",
+                         "; ".join(str(x) for x in facts["config_loader_env"])[:240], location=where))
     notes = [str(n) for n in facts.get("notes") or []]
     if notes:
         hits.append(_hit("release-not-fully-read", "high", "part of the image's provenance was not read",
@@ -358,10 +515,7 @@ def _learn(known: dict, facts: list[dict]) -> dict:
 
 
 def _without_lookalikes(known: dict, namespace: str) -> tuple[dict, list[str]]:
-    """`known` without any source or building repository whose owner imitates another known owner or the namespace: a
-    first-sight sample that already holds a lookalike cannot tell which side is the real one, so neither is learned: both
-    owners are kept as `suspect`, and every image from either is `high` (`image-owner-unresolved`) until the state is
-    reset after an investigation."""
+    """`known` without any source or building repository whose owner imitates another known owner or the namespace: a first-sight sample that already holds a lookalike cannot tell which side is the real one, so neither is learned: both owners are kept as `suspect`, and every image from either is `high` (`image-owner-unresolved`) until the state is reset after an investigation."""
     repos = set(known.get("sources") or []) | {b.split(" ", 1)[0] for b in known.get("builders") or []}
     owners = {_owner(r) for r in repos} | {namespace}
     suspect = {o for o in owners if o and _imitates(o, owners - {o})}
@@ -402,8 +556,7 @@ _VERSION_NUMBERS_RE = re.compile(r"v?(\d{1,9}(?:\.\d{1,9}){0,3})")
 
 
 def _version_key(tag: str) -> tuple:
-    """Order tags by the version numbers they start with (`v1.106.2` after `v1.83.9-nightly`), a plain release after its
-    suffixed builds, and tags without numbers before every version; ties by name."""
+    """Order tags by the version numbers they start with (`v1.106.2` after `v1.83.9-nightly`), a plain release after its suffixed builds, and tags without numbers before every version; ties by name."""
     m = _VERSION_NUMBERS_RE.match(tag)
     if not m:
         return ((), 0, tag)
@@ -412,8 +565,7 @@ def _version_key(tag: str) -> tuple:
 
 
 def _releases(tags: list[str]) -> list[str]:
-    """The version tags that are plain releases (`v1.106.2`, `1.106.2`, not `-nightly` or `-rc.1`), oldest first: the
-    images a re-push would hurt, which a run of one version's pre-releases must not crowd out of a window."""
+    """The version tags that are plain releases (`v1.106.2`, `1.106.2`, not `-nightly` or `-rc.1`), oldest first: the images a re-push would hurt, which a run of one version's pre-releases must not crowd out of a window."""
     return sorted((t for t in tags if _VERSION_TAG_RE.fullmatch(t) and _version_key(t)[1] == 1), key=_version_key)
 
 
@@ -423,10 +575,7 @@ def _namespace(ref: ImageRef) -> str:
 
 
 class ImageWatcher:
-    """Polls each image's tags. On first sight every tag is the baseline, and the provenance of the watched floating tags
-    and the newest version tags seeds what the repository is known to be built from and by. After that a new tag (cosign's
-    `.sig`/`.att`/`.sbom` tags aside, at most `_MAX_NEW_TAGS` a poll), a watched floating tag that points at another image,
-    and one of the newest version tags re-pushed, are judged; an image judged clean adds what built it to what is known."""
+    """Polls each image's tags. On first sight every tag is the baseline, and the provenance of the watched floating tags and the newest version tags seeds what the repository is known to be built from and by. After that a new tag (cosign's `.sig`/`.att`/`.sbom` tags aside, at most `_MAX_NEW_TAGS` a poll), a watched floating tag that points at another image, and one of the newest version tags re-pushed, are judged; an image judged clean adds what built it to what is known."""
 
     def __init__(self, images: list[str], *, state_dir: str, out_dir: str, floating: tuple[str, ...] = ("latest",),
                  fetch: Fetch | None = None, emit: bool = True, poster=None, config=None,
@@ -511,7 +660,7 @@ class ImageWatcher:
         fresh = sorted((t for t in tags if t not in known or t in pending), key=_version_key, reverse=True)[:_MAX_NEW_TAGS]
         results = []
         for tag in fresh:                           # newest first: junk tags cannot hold a new release back
-            result = self.judge(ref, tag, record=True)
+            result = self.judge(ref, tag, record=True, previous=known.get(tag) or self._predecessor(tag, known))
             if result.get("rate_limited"):
                 return results
             results.append(result)
@@ -521,13 +670,13 @@ class ImageWatcher:
                 continue
             digest = self.registry.digest(ref, tag)
             if known.get(tag) != digest:
-                results.append(self.judge(ref, tag, record=True, digest=digest))
+                results.append(self.judge(ref, tag, record=True, digest=digest,
+                                          previous=known.get(tag) or self._predecessor(tag, known)))
         return results
 
-    def judge(self, ref: ImageRef, tag: str, *, record: bool = False, digest: str | None = None) -> dict:
-        """Judge the image a tag names against what the repository is known to use, screen it (the early SIEM alert when
-        its evidence reaches the floor), and record it; a comparison that fails is retried, then screened as not compared
-        (`release-not-fully-read`, which alerts). Never raises."""
+    def judge(self, ref: ImageRef, tag: str, *, record: bool = False, digest: str | None = None,
+              previous: str | None = None) -> dict:
+        """Judge the image a tag names against what the repository is known to use, screen it (the early SIEM alert when its evidence reaches the floor), and record it; a comparison that fails is retried, then screened as not compared (`release-not-fully-read`, which alerts). Never raises."""
         from .cli import screen
 
         stamp = self._stamp()
@@ -536,9 +685,14 @@ class ImageWatcher:
             digest, facts, notes, index = image_provenance(self.registry, ref, digest or tag)
             image = {"image": ref.label, "tag": tag, "digest": digest, "index": index, "provenance": facts, "known": known,
                      "namespace": _namespace(ref), "notes": notes[:50]}
+            event = self._event(ref, tag, image)
+            if previous and previous != digest:     # the files the image changes against the one it replaces
+                files, unread, layer_notes, config_facts = layer_change(self.registry, ref, digest, previous)
+                event["files"] = files
+                image.update(config_facts)
+                event["release"].update({"previous": previous, "unread_code": unread, "notes": layer_notes})
             run_id = image_run_id(ref, tag, digest)
-            art = screen(self._event(ref, tag, image), run_id=run_id, outdir=self.out_dir, config=self.config,
-                         emit=self.emit, poster=self.poster)
+            art = screen(event, run_id=run_id, outdir=self.out_dir, config=self.config, emit=self.emit, poster=self.poster)
         except RateLimited as exc:                 # not a failure of the image: the next poll tries again
             log.warning("image %s:%s: %s", ref.label, tag, exc)
             return {"image": ref.label, "tag": tag, "rate_limited": True}
@@ -557,6 +711,14 @@ class ImageWatcher:
                 "floor": resp.floor_indicator_severity, "path": art.path,
                 "indicators": [(h.rule, h.severity, h.location) for h in resp.indicators]}
 
+    def _predecessor(self, tag: str, known: dict[str, str | None]) -> str | None:
+        """The image a new tag is compared with: the newest release tag below it (by the version numbers it starts with) whose digest is known, or the newest such release when the tag carries no version; without one, a watched floating tag's image (a repository tagged only `latest` and `sha-…`)."""
+        releases = [t for t in _releases([t for t, d in known.items() if d]) if t != tag]
+        below = [t for t in releases if _version_key(t) < _version_key(tag)] if _VERSION_NUMBERS_RE.match(tag) else releases
+        if below:
+            return known[below[-1]]
+        return next((known[t] for t in self.floating if known.get(t) and t != tag), None)
+
     @staticmethod
     def _event(ref: ImageRef, tag: str, image: dict) -> dict:
         return {"repo": f"oci/{ref.label}", "kind": "release", "number": None, "author": "", "body": "", "files": [],