diff-sentry 0.10.0__tar.gz → 0.11.0__tar.gz

{diff_sentry-0.10.0 → diff_sentry-0.11.0}/.claude/rules/monitoring.md

@@ -52,3 +52,11 @@ paths:
 - **Paths are where pip puts them.** A wheel's `x.data/purelib/` and `platlib/` map to the site-packages root, `x.data/scripts/` to `{scripts}/`, `x.dist-info/` to `{dist-info}/`; an sdist member loses its top directory, and one at the root keeps its path (pip builds from the root when the members share no top directory). `RECORD`, `WHEEL` and `METADATA` of a wheel, and `PKG-INFO` and `*.egg-info/` of an sdist, are derived and not diffed; `Requires-Dist` is read from `METADATA`.
 - **The previous release** is the highest version below the new one with a file that is not yanked; a pre-release is compared only when the new one is a pre-release too. Members are compared by content across all artifacts of a kind, so a payload in one platform's wheel shows.
 - **State is per file.** First sight of a package (even an empty one) records every file as the baseline. After that, each file not yet recorded is judged with the other new files of its release, against the previous release, so a wheel uploaded after its release was judged, or added to an old release, is judged too. A file is recorded only after its comparison is screened, and the index's ETag only after every new file of it is: a watcher stopped mid-comparison judges the same files on its next pass. A failed comparison is retried on every pass (the ETag is not sent while one is pending), superseded when the files to judge change, and kept as `error` after five, with an alert that it was not compared. A `--check` runs under `...-check` and never stands in for the watcher's judgment. An alert the SIEM did not accept is re-sent from `screened/` a few per poll.
+
+## 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.
+- **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.
+- **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.10.0 → diff_sentry-0.11.0}/.env.example

@@ -79,3 +79,5 @@ DS_API_KEY=sk-...
 # DS_RELEASE_PACKAGES=litellm,requests     # release-watch: PyPI projects (or --packages / --packages-file)
 # DS_RELEASE_INTERVAL=300                  # release-watch: seconds between polls of each project's index
 # DS_RELEASE_MAX_ARTIFACT_MB=256           # release-watch: a larger wheel or sdist is not compared, which alerts
+# DS_RELEASE_IMAGES=ghcr.io/owner/name     # release-watch: container images compared by build provenance (or --images)
+# DS_RELEASE_IMAGE_TAGS=latest             # release-watch: floating tags whose moves are judged (or --image-tags)

{diff_sentry-0.10.0 → diff_sentry-0.11.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, and `releases` reads PyPI's own hosts only, as data that is never installed. 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` reads PyPI's own hosts only, 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`).
 - **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`, `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`, `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).
 - **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: comparing a release's sdist with its git tag, and npm releases beside PyPI's; 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: comparing a release's sdist with its git tag, an image's new layers by content, and npm releases beside PyPI's; 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.10.0 → diff_sentry-0.11.0}/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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.11.0
+
+Upgrade from 0.10.0: `release-watch` can now watch container images. The GitHub Action's scan is unchanged, nothing needs configuring, and `rlm-harness==1.22.0` is unchanged.
+
+### Added
+- **`release-watch --images` compares GHCR and Docker Hub images by their build provenance.** litellm's 1.107.0 images, and the `latest` and `main-stable` tags moved onto them, carried the same payload as the wheels. Each new tag, each move of a watched floating tag, and each re-push of a recent release is judged against the repositories and workflows the image is known to be built from and by. A source or building repository whose owner imitates a known one is `critical`. An unknown owner, a build from an unprotected ref by a workflow that used protected ones, or an image without the provenance the repository's images carry is `high`. Another workflow of a known owner, such as a nightly build, is `medium`. Images are read anonymously and never pulled; the provenance is unsigned, so only a mismatch is evidence, and a layer's content is not read. See [Container images](docs/release-watch.md#container-images).
+
 ## 0.10.0
 
 Upgrade from 0.9.0: the GitHub Action now flags a GitHub owner that imitates your repository's own, so a workflow change it passed before can fail it now, and `release-watch` compares who published each release. Nothing needs configuring: the Action reads the repository from `GITHUB_REPOSITORY`. `rlm-harness==1.22.0` is unchanged.

{diff_sentry-0.10.0 → diff_sentry-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: diff-sentry
-Version: 0.10.0
+Version: 0.11.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.10.0
+      - uses: qazbnm456/diff-sentry@v0.11.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.10.0 → diff_sentry-0.11.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.10.0
+      - uses: qazbnm456/diff-sentry@v0.11.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.10.0 → diff_sentry-0.11.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.10.0'
+    default: '0.11.0'
 
 outputs:
   failed:

{diff_sentry-0.10.0 → diff_sentry-0.11.0}/diff_sentry/__init__.py

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

{diff_sentry-0.10.0 → diff_sentry-0.11.0}/diff_sentry/cli.py

@@ -14,6 +14,7 @@ import json
 import math
 import os
 import sys
+import time
 from collections.abc import Callable
 from dataclasses import dataclass
 
@@ -77,6 +78,7 @@ async def detect_from_event(
 
 def _baseline_indicators(event: dict, *, content_hits: list[IndicatorHit] | None = None) -> list[dict]:
     """The host-side deterministic evidence recorded in run_start meta BEFORE the planner runs: the text detectors over the raw content ∪ the provenance detectors over the ingest facts. Both re-source into the evidence union on read (MF3), so a false-benign SUBMIT can skew the verdict but never suppress these."""
+    from .images import scan_image
     from .indicators import keep_worse, scan_change, scan_provenance
     from .releases import release_scope, scan_release, scan_release_change
 
@@ -84,7 +86,8 @@ def _baseline_indicators(event: dict, *, content_hits: list[IndicatorHit] | None
     release = event.get("kind") == "release"
     scan = scan_release_change if release else scan_change
     hits = (scan(event) if content_hits is None else release_scope(list(content_hits)) if release else list(content_hits)) \
-        + scan_provenance(event.get("provenance") or {}) + scan_release(event.get("release") or {})
+        + scan_provenance(event.get("provenance") or {}) + scan_release(event.get("release") or {}) \
+        + scan_image((event.get("release") or {}).get("image") or {})
     # Hits an EARLIER version of this same change raised ride along, so an edit that removes the payload cannot also remove the evidence (the watcher supplies them; a change scanned on its own has none).
     for raw in event.get("prior_indicators") or []:
         if isinstance(raw, IndicatorHit):
@@ -333,6 +336,7 @@ def _cmd_release_watch(args) -> int:
     import logging
     import signal
 
+    from .images import ImageWatcher
     from .releases import ReleaseWatcher, parse_packages
 
     logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
@@ -347,7 +351,15 @@ def _cmd_release_watch(args) -> int:
         packages = parse_packages(texts)
         if args.check:
             packages = parse_packages([args.check[0]])
-        watcher = ReleaseWatcher(packages, state_dir=args.state, out_dir=args.out, emit=not args.no_emit)
+        images = [i for text in [*args.images, os.getenv("DS_RELEASE_IMAGES", "")] for i in text.replace(",", " ").split()]
+        floating = tuple(args.image_tags or os.getenv("DS_RELEASE_IMAGE_TAGS", "latest").replace(",", " ").split())
+        image_watcher = ImageWatcher([] if args.check else images, state_dir=args.state, out_dir=args.out,
+                                     floating=floating, emit=not args.no_emit)
+        try:
+            watcher = ReleaseWatcher(packages, state_dir=args.state, out_dir=args.out, emit=not args.no_emit)
+        except BaseException:
+            image_watcher.close()
+            raise
     except (OSError, ValueError, RuntimeError) as exc:
         print(f"release-watch: {exc}", file=sys.stderr)
         return 2
@@ -356,22 +368,29 @@ def _cmd_release_watch(args) -> int:
             result = watcher.check(packages[0], args.check[1])
             print(json.dumps(result, indent=2, default=str))
             return 1 if "error" in result else 0
-        if not packages:
-            print("release-watch: no packages (--packages, --packages-file or DS_RELEASE_PACKAGES)", file=sys.stderr)
+        if not packages and not images:
+            print("release-watch: nothing to watch (--packages, --packages-file, --images, or DS_RELEASE_PACKAGES / "
+                  "DS_RELEASE_IMAGES)", file=sys.stderr)
             return 2
         if args.once:
-            for result in watcher.poll_once():
+            for result in watcher.poll_once() + image_watcher.poll_once():
                 print(json.dumps(result, default=str))
             return 0
         stopping = []
         signal.signal(signal.SIGTERM, lambda *_: stopping.append(True))
         try:
-            watcher.run(args.interval, stop=lambda: bool(stopping))
+            while not stopping:
+                started = time.monotonic()
+                watcher.poll_once()
+                image_watcher.poll_once()
+                while not stopping and time.monotonic() - started < args.interval:
+                    time.sleep(min(1.0, args.interval))
         except KeyboardInterrupt:
             pass
         return 0
     finally:
         watcher.close()
+        image_watcher.close()
 
 
 def _cmd_render(args) -> int:
@@ -636,6 +655,11 @@ def build_parser() -> argparse.ArgumentParser:
                         help="compare each new release of watched PyPI packages with the one before it (no model)")
     rw.add_argument("--packages", nargs="+", default=[], help="PyPI project names (or set DS_RELEASE_PACKAGES)")
     rw.add_argument("--packages-file", help="a file of project names, one per line (# comments allowed)")
+    rw.add_argument("--images", nargs="+", default=[],
+                    help="container images (ghcr.io/owner/name, docker.io/owner/name) whose tags are compared by provenance "
+                         "(or set DS_RELEASE_IMAGES)")
+    rw.add_argument("--image-tags", nargs="+", default=None,
+                    help="floating tags whose moves are judged (DS_RELEASE_IMAGE_TAGS, default: latest)")
     rw.add_argument("--out", default="./output")
     rw.add_argument("--state", default=os.getenv("DS_WATCH_STATE_DIR", "./output/state"),
                     help="state directory: releases.db, snapshots/")