supply-chain-guard 5.28.1 → 6.0.0

package/README.md

@@ -73,7 +73,9 @@ For a deep dive into how GlassWorm infiltrates the software supply chain and the
 ### Infrastructure & CI/CD
 - GitHub Actions: unpinned actions, secrets exfiltration, encoded payloads, curl piping
 - Agentic workflows (GitLost class): AI-agent steps and gh-aw `.github/workflows/*.md` that ingest untrusted issue/PR text, hold a cross-repo token, and can post publicly - the prompt-injection data-leak posture
-- Dockerfile: curl pipe, unpinned base images, hardcoded secrets, SUID bits
+- Dockerfile / Containerfile: curl pipe, base images on a moving channel tag or without a digest,
+  hardcoded secrets, SUID bits. Compose `image:` values are out of scope for every Docker rule
+  (see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#base-image-pinning-decision-record))
 - Terraform/IaC: inline scripts, external modules, hardcoded secrets
 - Package manager configs (.npmrc, .yarnrc, pip.conf): HTTP registries, exposed tokens
 - Git hooks and submodule security
@@ -112,14 +114,14 @@ Links individual findings into incident-level attack chains:
 - 15+ correlation rules with confidence scoring
 
 ### Trust Breakdown (v4.2)
-4-dimension trust scoring for every scan:
-- Publisher Trust (40%) / Code Quality (30%) / Dependency Trust (20%) / Release Process (10%)
+Multi-dimension trust scoring for package and repository inspections:
+- Publisher Trust (40%) / Code Quality (30%) / Dependency Trust (20%) / Release Process (10%) (all 4 dimensions populated for `npm`, `pypi`, `repo`, and remote `scan <github-url>` modes; local directory scans evaluate Code Quality and Dependency Trust with renormalised weights).
 
 ## Installation
 
-**Requires Node.js 22 or newer.** Node 20 reached end of life on
-2026-04-30; it still installs and is still covered by CI as a transition lane, but it
-is out of support and that lane is removed in 5.29.0. Full policy, including what the
+**Requires Node.js 22 or newer.** Every release runs its complete test suite, and
+installs and executes its own packed tarball, on Node 22 and on Node 24, the current
+Active LTS. Full policy, including what the
 package is published from and what the Action and container image run on:
 [`docs/node-support.md`](docs/node-support.md).
 
@@ -140,7 +142,7 @@ Run the scanner as a [pre-commit](https://pre-commit.com) hook (Python-ecosystem
 ```yaml
 repos:
   - repo: https://github.com/homeofe/supply-chain-guard
-    rev: v5.28.1
+    rev: v6.0.0
     hooks:
       - id: supply-chain-guard
 ```
@@ -149,6 +151,22 @@ The scanner writes its risk history to `.scg-history/` in the scanned repo;
 it is not written when `--no-history` is set, which the hook now uses. For
 plain scans without that flag, add the folder to your `.gitignore`.
 
+**If a file in `.scg-history/` cannot be read, the scan says so and fails.** The
+two stores there, `risk-history.json` and `triage-decisions.json`, are the
+baseline that trend, forecast and triage-governance rules compare against. A
+store that is absent is a first scan and stays silent, which is the normal case
+on a fresh checkout or a hosted runner. A store that exists but does not parse,
+because a scan was interrupted mid-write or the file was edited by hand, is lost
+evidence, and the two are deliberately not reported the same way: the scan emits
+`RISK_HISTORY_UNREADABLE` or `TRIAGE_STORE_UNREADABLE` at `high`, sets
+`partialScan: true`, and exits nonzero regardless of `--fail-on`, because an
+unusable baseline is an indeterminate result rather than a clean one. The
+unreadable file is left on disk rather than overwritten, so complete entries can
+still be recovered from it, usually by closing the truncated JSON array by hand.
+Delete the file to start a new baseline once you have decided the old trend is
+expendable. `--no-history` does not silence this: that flag stops the write, not
+the read, so a corrupt store still degrades the verdict and is still reported.
+
 The hook scans the repository root on every commit and fails on high or critical findings.
 
 ### Docker
@@ -156,7 +174,7 @@ The hook scans the repository root on every commit and fails on high or critical
 Run the scanner without a Node toolchain via the official multi-arch image (linux/amd64, linux/arm64), published to GHCR on every release tag:
 
 ```bash
-docker run --rm -v ${PWD}:/scan ghcr.io/homeofe/supply-chain-guard:5.28.1 scan /scan
+docker run --rm -v ${PWD}:/scan ghcr.io/homeofe/supply-chain-guard:6.0.0 scan /scan
 ```
 
 `${PWD}` works in bash, zsh, and PowerShell; in cmd.exe use `%cd%` instead.
@@ -194,6 +212,9 @@ supply-chain-guard org my-github-org
 # Scan only files changed since a commit (diff mode)
 supply-chain-guard scan ./project --since HEAD~5
 
+# Scan with registry version-drift check (requires network)
+supply-chain-guard scan ./project --check-registry
+
 # Monitor a Solana C2 wallet
 supply-chain-guard monitor <wallet-address> --once
 ```
@@ -207,7 +228,7 @@ supply-chain-guard scan ./project --format html   # Standalone HTML report
 supply-chain-guard scan ./project --format markdown # Markdown (for PR comments)
 supply-chain-guard scan ./project --format sarif  # SARIF 2.1.0 (GitHub Code Scanning)
 supply-chain-guard scan ./project --format sbom   # CycloneDX 1.6 SBOM with real dependency inventory
-supply-chain-guard scan ./project --sbom-output sbom.json  # Write SBOM to file separately
+supply-chain-guard scan ./project --sbom-output sbom.json  # The same SBOM, written to a file instead of stdout
 supply-chain-guard scan ./project --format badge   # Shields.io endpoint JSON
 supply-chain-guard scan ./project --format gitlab  # GitLab Dependency Scanning report (security-report-schemas 15.2.4, see examples/gitlab-ci.yml)
 supply-chain-guard scan ./project --format markdown --json-output canonical.json  # Same scan, human report plus canonical JSON
@@ -290,10 +311,14 @@ Practically: the default gate exits non-zero on `critical` and `high` only, so *
 
 ```yaml
 rules:
-  disable: [INTERNAL_PRIVATE_IP, INTERNAL_HOSTNAME, INTERNAL_SERVICE_ENDPOINT,
-            INTERNAL_GIT_REMOTE, INTERNAL_DEV_PATH, INTERNAL_SINGLE_LABEL_URL]
+  disable:
+    INTERNAL_PRIVATE_IP: RFC1918 addresses are expected in this repository's fixtures
+    INTERNAL_HOSTNAME: internal names are already covered by a separate review
 ```
 
+The parser reads block style only; a flow sequence on one line
+(`disable: [A, B]`) is reported as `POLICY_UNKNOWN_KEY` and disables nothing.
+
 ### False-positive controls
 
 A rule that screams on every README gets switched off, and a switched-off rule protects nothing. Three independent layers keep this quiet.
@@ -416,6 +441,29 @@ SCG_INTERNAL_DISCLOSURE_FILE=~/.config/scg/internal-terms supply-chain-guard sca
 
 The external file is one entry per line, `#` for comments, `sha256:<digest>` for a hashed entry, `/pattern/flags` for a regex, anything else is a case-insensitive literal. If the file is configured but absent (a shared CI runner that never received it), you get an `INTERNAL_DENYLIST_UNAVAILABLE` finding at `info` severity rather than silence: a deny-list that quietly stopped running looks exactly like a repository that is clean. An entry that cannot be compiled is reported the same way (`INTERNAL_DENYLIST_INVALID_ENTRY`, medium). Neither finding ever prints the entry, and the environment variable is named but its value is not, because a path can itself contain an account name.
 
+**The two sources are not equally trusted, and the difference is deliberate.** `SCG_INTERNAL_DISCLOSURE_FILE` is set by whoever runs the scan, so it may name any path on the machine and carry any pattern. `internalDisclosure.externalFile` and `internalDisclosure.patterns` live in the committed policy file, which travels inside the repository being scanned, and scanning a repository you do not own is the ordinary case for this tool. Entries from there are therefore bounded:
+
+- `externalFile` must stay inside the scanned directory. An absolute path is refused, a relative path that climbs out with `..` is refused, and so is one that leaves through a symbolic link. The file is not opened, so nothing about a path outside the tree reaches the report. The bound is the scanned directory and nothing narrower: a path that stays inside it is still read, `.git/config` included, so a committed `externalFile` can still point at whatever your runner wrote into the workspace. Matches from it stay redacted.
+- A regular expression from `patterns`, **or from an `externalFile` that is inside the tree**, is capped at 200 characters and refused when it quantifies a group that already contains a variable quantifier (`(a+)+`, `(a?)*`, and the like). That shape can take exponential time to report no match, so one committed line would otherwise occupy a runner until the workflow times out.
+- Whatever survives those checks runs under a wall-clock budget for the whole scan. On overrun the file reports `INTERNAL_DISCLOSURE_TRUNCATED` rather than running on.
+
+A refusal is an `INTERNAL_DENYLIST_REFUSED` finding at `medium` severity, and like every other coverage finding it marks the scan partial rather than passing quietly. In the published Action a partial scan exits 1 on its own, independently of `fail-on`. None of this applies to the environment-variable source.
+
+**Two limits of the shape check, both worth knowing before you upgrade.**
+
+It refuses more than it has to, and the shape it most often refuses is the ordinary one. A chained label group is how an internal hostname is normally written, and it is rejected even though it is linear in practice:
+
+```yaml
+internalDisclosure:
+  patterns:
+    - /(?:[a-z0-9-]+\.)+corp\.example/   # REFUSED: quantified group holding "+"
+    - /[a-z0-9.-]+\.corp\.example/       # accepted, and matches the same hosts
+```
+
+If you have the first form today, in `patterns` or in your own gitignored `externalFile`, rewrite it before you upgrade. Left as it is, the term stops being looked for, the scan becomes partial, and the Action exits 1.
+
+It also refuses less than it has to, so an accepted pattern is not a promise about time. The check reads the source text, which cannot see ambiguity that comes from overlapping alternation, so `/(a|a)+$/` and `/(a|ab)+$/` are accepted and are still catastrophic, and the wall-clock budget cannot interrupt a match that is already running. Availability from a committed pattern is narrowed here, not closed; the remaining case is tracked on [issue 169](https://github.com/homeofe/supply-chain-guard/issues/169).
+
 **One more note on the paradox.** `allowlist.domains` also answers `INTERNAL_HOSTNAME`, `INTERNAL_SERVICE_ENDPOINT` and `INTERNAL_GIT_REMOTE` for a given host, which is convenient and publishes the host name. If that is not acceptable, suppress by path instead, which names nothing:
 
 ```yaml
@@ -431,9 +479,12 @@ Create `.supply-chain-guard.yml` in your project root to customize behavior:
 
 ```yaml
 rules:
+  # Every disabled rule needs a written reason, the same bar `suppress` has met
+  # since v5.3. The bare list form (`- HEX_ARRAY`) still disables the rule and is
+  # reported as POLICY_DISABLE_NO_REASON.
   disable:
-    - HEX_ARRAY
-    - CHARCODE_OBFUSCATION
+    HEX_ARRAY: minified vendor bundles in this repository, reviewed 2026-08
+    CHARCODE_OBFUSCATION: same bundles, same review
   severityOverrides:
     GHA_UNPINNED_ACTION: medium
 
@@ -451,10 +502,13 @@ allowlist:
     # says who publishes the code, not that every version of it is safe.
     - my-org
 
-# Skip files matched by these path globs (** / * / ?) during the scan.
+# Skip files matched by these path globs (** / * / ?) during the scan. These
+# files are never opened, so nothing about them reaches the report except the
+# policy block below. Each glob needs a written reason; the bare list form
+# (`- vendor/**`) still skips the path and is reported as POLICY_IGNORE_NO_REASON.
 ignore:
-  - vendor/**
-  - "**/*.min.js"
+  "vendor/**": third-party code, tracked by the upstream project's own scanning
+  "**/*.min.js": build output, scanned at source instead
 
 suppress:
   - rule: RELEASE_EXE_ARTIFACT
@@ -472,6 +526,37 @@ Findings can also be suppressed inline with a comment on the line directly
 above them: `// scg-ignore-next-line RULE reason` (JS/TS) or
 `# scg-ignore-next-line RULE` (Python/YAML/shell).
 
+### Where the policy is read from, and what that means on a pull request
+
+The policy file is read **from the directory being scanned**, and from nowhere
+else. There is no flag, environment variable or Action input that points the
+scanner at a policy outside the scan target.
+
+On a `pull_request` event the checkout materialises the **head of the proposing
+branch**, so the policy that governs the scan is the one on the branch under
+review, not the one on your default branch. A change that adds
+`.supply-chain-guard.yml` alongside the code it excuses is applying its own
+policy to itself. Anyone who can push a branch can therefore narrow the scan of
+that branch.
+
+That is a property of reading policy from the tree, and it is stated here rather
+than left to be discovered. What it is **not** is silent:
+
+- Every narrowing is named in the report, in **all nine output formats**,
+  including the markdown pull request comment the Action posts by default.
+  A scan narrowed by policy can no longer be mistaken for a clean scan in any
+  format, including `ignore:`, which removes files before any rule opens them
+  and used to leave no trace anywhere.
+- A narrowing declared without a written reason is reported as a finding
+  (`POLICY_DISABLE_NO_REASON`, `POLICY_IGNORE_NO_REASON`,
+  `POLICY_SUPPRESSION_NO_REASON`), so an undocumented exclusion costs a line in
+  the report rather than nothing.
+
+If your threat model includes an untrusted proposer, the controls that actually
+hold are outside this tool: require review on `.supply-chain-guard.yml` through
+`CODEOWNERS`, or scan a base-ref checkout in a separate job. Treat a policy file
+in a pull request diff as a change to your security gate, because it is one.
+
 ## Baseline Diffing (v4.4)
 
 Only report NEW findings (ignore known baseline):
@@ -566,7 +651,7 @@ supply-chain-guard scan ./project --baseline .scg-baseline.json
 | RubyGems | `scan` | Gemfile, Gemfile.lock (malicious-gem IOCs, http/git sources) |
 | Composer/PHP | `scan` | composer.json, composer.lock (malicious-package IOCs, http repos) |
 | NuGet/.NET | `scan` | packages.lock.json, *.csproj, nuget.config (malicious-package IOCs, http feeds) |
-| Docker | `scan` | Dockerfile, docker-compose.yml, Containerfile |
+| Docker | `scan` | Dockerfile, Dockerfile.*, Containerfile. `docker-compose.yml` is read, but every Docker rule is anchored on a Dockerfile instruction keyword, so Compose `image:` values are not covered |
 | Terraform | `scan` | .tf, .hcl files (provisioners, modules, secrets) |
 | VS Code | `vscode` | .vsix files, activation events, dangerous APIs |
 | GitHub Actions | `scan` | .github/workflows/*.yml |
@@ -612,7 +697,18 @@ supply-chain-guard contributes to each of those activities:
 
 - **Component inventory:** generates a [CycloneDX 1.6](https://cyclonedx.org/)
   SBOM from the real resolved dependency tree, as a machine-readable component
-  list you can attach to technical documentation.
+  list you can attach to technical documentation. The inventory is built from
+  **npm only**, and specifically from `package-lock.json` (lockfile version 2 or
+  later) for the full transitive tree, falling back to the direct dependencies
+  declared in `package.json`. `pnpm-lock.yaml`, `yarn.lock` and `bun.lockb` are
+  **not** read, and neither is any non-npm manifest: a Python, Cargo, Go,
+  RubyGems, Composer or NuGet project produces an SBOM with no components from
+  that ecosystem. Every such file that is present is named in the document, in
+  `metadata.properties`, alongside an `inventory-coverage` value of
+  `full-transitive`, `direct-only` or `none`, so an inventory that was never
+  taken is never mistaken for a product that ships nothing. The scanner's threat
+  detection covers all the ecosystems listed at the top of this README; only the
+  SBOM inventory is npm-scoped.
 - **Dependency risk:** detects known-malicious packages and versions,
   typosquatting, dependency confusion, and compromised publisher activity, at
   scan time and at install time.
@@ -625,6 +721,68 @@ supply-chain-guard contributes to each of those activities:
 supply-chain-guard scan ./project --sbom-output sbom.json
 ```
 
+`--sbom-output <file>` and `--format sbom` produce the SAME document for the
+same scan: the same components, the same dependency graph, the same
+`vulnerabilities` entries and the same incident annotations. Only the
+`serialNumber` and the timestamps differ, because each invocation is its own
+run. The two exist so an SBOM can be written to a file while the scan report
+itself goes to stdout in another format.
+
+#### What the SBOM carries, and what it says it could not assess
+
+From `package-lock.json` (v2 or later) every component carries a stable
+`bom-ref`, a `purl`, the integrity hashes, the CycloneDX `scope`, and the
+licence the lockfile declares, expressed as an SPDX `expression` when the string
+is an expression and as `license.id` when it is a plain SPDX identifier. An
+identifier the generator cannot vouch for is kept as `license.name` rather than
+asserted as SPDX, because the CycloneDX schema constrains `license.id` to the
+SPDX enum. Relationships are emitted as a top level `dependencies` array rooted
+at the subject component and resolved the way npm resolves them, so a nested
+duplicate is linked to the dependent that actually installed it rather than to
+the hoisted copy.
+
+What could not be assessed is stated instead of left blank. A component whose
+manifest declares no licence carries a `supply-chain-guard:license` property
+saying so, so an empty licence column is never read as "no licence terms". At
+the document level, `metadata.properties` records which manifest the inventory
+came from, how many components carry a declared licence, whether the dependency
+graph was resolved, partial or not assessed, and how many declared edges resolve
+to no component in the document (uninstalled optional peer dependencies,
+normally). A declared edge whose target is not in the document is counted there
+rather than emitted as a `dependsOn` pointing at a `bom-ref` that does not
+exist.
+
+```bash
+# What this SBOM says it could and could not assess
+supply-chain-guard scan ./project --format sbom > sbom.json
+node -e "const d=require('./sbom.json');for (const p of d.metadata.properties ?? []) console.log(p.name, '=', p.value)"
+```
+
+Findings removed by a `suppress:` entry in `.supply-chain-guard.yml` are emitted
+as CycloneDX VEX statements, with the reason the policy declared carried
+verbatim in `analysis.detail`. No `analysis.justification` is emitted: that
+field is a fixed enum that a free-text reason cannot be mapped to. A suppression
+with no recorded reason produces a statement that says exactly that.
+
+Component hashes are hexadecimal digests, decoded from the base64 Subresource
+Integrity value npm writes into the lockfile, because that is the encoding the
+CycloneDX `hash-content` pattern requires. An integrity part whose algorithm is
+not one this generator maps, or whose payload does not decode to the digest
+length its algorithm requires, is dropped and reported on the component rather
+than emitted, and counted at the document level. purls are canonical: the npm
+scope is the purl namespace and the separator after it is a literal `/`.
+
+Where the inventory came from `package.json` because no lockfile was present, a
+component carries `version` and `purl` only when the manifest declares one exact
+version. A range, a dist-tag such as `latest`, a git or URL specifier and a
+`workspace:` protocol are constraints, not versions: those components carry
+neither field, a `supply-chain-guard:version` property records why, and
+`supply-chain-guard:declared-specifier` keeps the declared string verbatim.
+
+Supplier and author are not emitted. `package-lock.json` does not carry either
+field, and the SBOM generator reads only `package-lock.json` and `package.json`,
+so there is nothing to populate them from without a registry lookup.
+
 Article and paragraph citations are deliberately omitted here. Map these outputs
 to specific provisions against the final published regulation text, with your own
 legal review, rather than against this README.
@@ -637,20 +795,45 @@ chain security. The relevant capabilities are:
 - **Supply chain risk:** typosquatting, dependency confusion, compromised
   packages, and malicious GitHub Actions in CI/CD workflows.
 - **Incident evidence:** the correlation engine links individual findings into
-  named attack chains with confidence scores, and reports are exportable as
-  SARIF, JSON, and CycloneDX for retention alongside an incident record.
+  named attack chains with confidence scores calibrated to indicator match
+  completeness. The incident record itself, with its name, confidence, indicator
+  counts (matched and total), list and narrative, is carried by three
+  formats: **JSON** (`incidents` on the report), **SARIF** (the incident list on
+  `runs[0].properties`, and the incidents each result belongs to in that
+  result's property bag) and **CycloneDX** (one `annotations` entry per
+  incident, whose `subjects` are the `vulnerabilities` entries it groups). The
+  text renderer prints it as a panel. The markdown, HTML, badge, GitLab and
+  JUnit formats carry the individual findings only, not the incident record.
+  For a ready-made evidence document rather than a machine format, `scan
+  --export-incident-md` writes a markdown incident report to stdout: risk score,
+  every detected incident with its confidence, narrative and indicator list, the
+  critical findings, and the response playbooks.
 - **Configuration exposure:** IaC, Dockerfile, and `.npmrc` / `.yarnrc` scanning
   surfaces misconfiguration before deployment.
 
 ### Operating model
 
 Apache-2.0, no account required, and no telemetry: the scanner reports only to
-its own output. `scan` runs fully offline against the bundled threat feed, so it
-is suitable for air-gapped use. The commands that deliberately reach the network
-are the ones that exist to do so: `supply-chain-guard npm <pkg>` and
-`supply-chain-guard pypi <pkg>` fetch the package under inspection, and the feed
-refresh fetches updated indicators. Offline runs use the feed bundled with the
-installed version, so pin the version you intend to audit against.
+its own output.
+
+**Offline by default:**
+`scan` on a local path runs fully offline against the bundled threat feed (unless
+the opt-in `--check-registry` flag is passed), as do `guard`, `feed stats`, and
+all report formatters. These commands make zero network requests and are suitable
+for air-gapped and data-egress-restricted environments.
+
+**Networked commands and external disclosures:**
+The commands that reach the network do so deliberately for their specific functions:
+- `supply-chain-guard npm <pkg>` / `pypi <pkg>` / `vscode <ext>`: fetch and inspect remote packages and extensions from public registries (npm, PyPI, VS Code Marketplace, Open VSX).
+- `supply-chain-guard confusion <dir>`: inspects project dependency manifests and **transmits every declared dependency and devDependency package name to the public npm and PyPI registries** to determine whether private or internal packages are registered publicly.
+- `supply-chain-guard repo <url>` and `supply-chain-guard org <name>`: inspect remote GitHub repositories and organizations by invoking the `gh` CLI as a child process, using the caller's ambient GitHub credentials.
+- `supply-chain-guard monitor <wallet>`: polls public Solana RPC nodes for C2 wallet transaction activity.
+- `supply-chain-guard feed refresh`: downloads updated threat intelligence from the upstream repository into the local cache.
+- `supply-chain-guard scan <github-url>`: clones a remote repository via Git for analysis.
+- `supply-chain-guard scan . --check-registry`: opt-in flag that queries the public npm registry for the package's latest published version to detect version drift.
+
+Offline runs use the feed bundled with the installed version, so pin the version
+you intend to audit against.
 
 ## GitHub Action
 
@@ -672,7 +855,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: homeofe/supply-chain-guard@v5.28.1
+      - uses: homeofe/supply-chain-guard@v6.0.0
         with:
           fail-on: critical
           comment-on-pr: true
@@ -687,21 +870,83 @@ updates:
   - package-ecosystem: github-actions
     directory: "/"
     schedule:
-      interval: weekly
+      interval: daily
 ```
 
-### `@v5`, and what it does and does not guarantee
+**`daily`, not `weekly`, and this project's release rate is why.** Measured over
+the 155 days to 2026-08-21: 134 releases, about 1.4 a day over the last two
+months, with a median of 20 hours between releases and two thirds of the gaps
+under a day. A weekly schedule cannot track that. Each weekly run opens a correct
+bump pull request, and the next weekly run closes it as superseded and opens
+another, so an unattended pin never moves at all. Measured in one consumer of
+this Action: eight consecutive weekly bump pull requests, each alive for exactly
+seven days, each proposing a newer target than the last, while the pin itself sat
+unchanged for 49 days and fell 82 releases behind. Every scan check was green
+throughout, because a stale pin is not a failing scan.
 
-`@v5` also works and stays supported. It is a floating **branch**, fast-forwarded
+The interval is the cheap half. The half that actually decides the outcome is
+whether somebody merges the pull request, and no setting in this file supplies
+that.
+
+### `@v6`, and what it does and does not guarantee
+
+`@v6` also works and stays supported. It is a floating **branch**, fast-forwarded
 to each release by CI, and the composite action on it pins an exact npm version
-that is bumped and build-gated on every release. So `@v5` is not `latest`: every
+that is bumped and build-gated on every release. So `@v6` is not `latest`: every
 resolution still installs one exact, release-gated version.
 
-The caveat is what happens after a major. If the v5 line stops being released once
-v6 ships, `@v5` keeps resolving a frozen action that pins an old npm version, and
+The caveat is what happens after a major. If the v6 line stops being released once
+v7 ships, `@v6` keeps resolving a frozen action that pins an old npm version, and
 the IOC feed it installs stops updating. For a scanner that is a silent
 false-negative generator, and nothing in your workflow would report it. An exact
-pin turns that into a visible out-of-date dependency instead.
+pin is what turns that into a reviewable out-of-date dependency instead.
+
+**Be precise about what an exact pin does and does not buy you, because a frozen
+exact pin is the same silent false negative.** It ages exactly as quietly. This
+scanner runs offline against the IOC feed bundled with the pinned version, so a
+pin that stops moving freezes the detection rules at that date. What an exact pin
+buys is a *place* where the staleness becomes reviewable: the bump pull request.
+That is a different claim from the staleness being visible on its own, and the
+measurement above is what the difference costs. If those pull requests are opened
+and superseded without ever being merged, the pin is frozen and the rule set is
+ageing.
+
+**The scan itself now says so.** Every scan measures how old the rule set it just
+matched against actually is, and reports `THREAT_FEED_STALE` (medium) once the
+newest indicator in that rule set is more than 30 days old. The finding carries
+the measured age and the newest indicator's date, it raises the risk score off
+zero and the risk level off `clean`, and it is named in eight of the nine report
+formats and in the Action's pull request comment, which renders whichever
+`format` you set (`markdown` by default). It is derived offline from the feed
+itself, so it travels with the pin: an installation that never updates reports
+its own age without needing a network call, a registry lookup, or anything
+configured by the consumer.
+
+Where it appears, exactly, because "every format" would be one format too many:
+`text`, `json`, `markdown`, `sarif`, `sbom`, `html`, `gitlab` and `junit` all
+carry the rule id `THREAT_FEED_STALE`, and all but `junit` carry the full
+description as well. The ninth format, `badge`, does not: the Shields.io endpoint
+payload is `{schemaVersion, label, message, color}` derived from the findings
+summary counts, so it never names a rule. What you see there instead is the
+badge for an otherwise clean repository turning from `clean`/`brightgreen` into
+`1 medium`/`yellow` - the condition is visible, but not identifiable, and a
+badge is the one surface where that matters least. In `junit` the rule id is a
+passing `<testcase>` rather than a `<failure>`, because only `critical` and
+`high` become failures there.
+
+The measurement is taken over the rule set the scan *used*, not over the version
+number. A consumer running `supply-chain-guard feed refresh` before each scan
+merges the published feed for 24 hours and is correctly reported as current even
+on an old pin. `supply-chain-guard feed stats` prints both ages side by side, the
+one bundled with the installed version and the effective one at scan time, so the
+two are never confused. If a deliberately frozen rule set is the intent, exclude
+the rule by name:
+
+```yaml
+- uses: homeofe/supply-chain-guard@v6.0.0
+  with:
+    exclude-rules: THREAT_FEED_STALE
+```
 
 ### Action Inputs
 
@@ -774,13 +1019,20 @@ The bundled IOC feed ships with every release, and the same data is published as
 is ingested, not at the next release:
 
 ```bash
-supply-chain-guard feed stats     # entry counts by type and severity
+supply-chain-guard feed stats     # entry counts by type and severity, plus rule-set age
 supply-chain-guard feed refresh   # pull the latest published feed into the local cache
 supply-chain-guard feed osv       # export malicious-package IOCs as OSV records
 ```
 
 A refreshed feed is merged into every scan for the next 24 hours automatically.
 
+**Rule-set age:** `feed stats` reports two ages, the one bundled with the
+installed version and the effective one at scan time, and marks either `[STALE]`
+past 30 days. `--format json` returns the same values as `bundledFreshness` and
+`freshness` (`newestIndicator`, `ageDays`, `datedEntries`, `stale`) for a
+workflow that wants to assert on them directly. Both are computed offline, from
+the feed itself.
+
 **OSV export:** `feed osv` emits the feed's malicious-package indicators (npm,
 PyPI-adjacent, Go, RubyGems, Packagist, crates.io, NuGet) as [OSV-schema](https://ossf.github.io/osv-schema/)
 records, so the feed is consumable by `osv-scanner` and other OSV-native tooling:
@@ -796,6 +1048,16 @@ validate each entry against its type's shape and quarantine anything invalid -
 a malformed or hostile feed entry can neither crash a scan nor flood it with
 garbage matches, and a rejected refresh never overwrites the previous cache.
 
+**Acquisition bounds:** both download paths are bounded before anything is
+parsed or written. An absolute 30 second deadline covers DNS, connect, headers
+and the body read; the response is capped at 32 MiB, refused on a declared
+`Content-Length` over the cap before a byte is read and counted again while
+streaming when no length is declared; at most 5 redirects are followed and every
+hop is revalidated. An inactivity timeout would not be enough, because a peer
+that keeps trickling bytes never triggers one. Every bound fails closed and
+loudly: the download is abandoned, one line naming the bound goes to stderr, the
+command exits non-zero, and the previous cache stays in effect.
+
 ### Where the feed comes from
 
 Curated entries are hand-added from vendor write-ups. Malicious-package entries

package/action.yml

@@ -6,6 +6,20 @@ branding:
   icon: "shield"
   color: "red"
 
+# POLICY SOURCE, stated because a consumer cannot see it from the inputs below.
+#
+# The scanner reads .supply-chain-guard.yml (or .yaml / .scg.yml / .scg.yaml)
+# from the DIRECTORY IT SCANS. There is no input here that points it anywhere
+# else. On a pull_request event the checkout is the HEAD of the proposing
+# branch, so the policy applied to the scan is the proposing branch's policy: a
+# change can ship a config that narrows the scan of that same change.
+#
+# It cannot do so silently. Every rule disabled, path ignored and rule
+# suppressed by the loaded config is named in the scan report in every output
+# format, including the markdown body of the pull request comment this Action
+# posts by default, and a narrowing with no written reason is reported as a
+# finding. See the "Where the policy is read from" section of the README for
+# the controls that apply when the proposer is untrusted.
 inputs:
   path:
     description: "Path to scan (defaults to repository root)"
@@ -66,7 +80,7 @@ runs:
 
     - name: Install supply-chain-guard
       shell: bash
-      run: npm install -g supply-chain-guard@5.28.1 --ignore-scripts --no-audit --no-fund
+      run: npm install -g supply-chain-guard@6.0.0 --ignore-scripts --no-audit --no-fund
 
     - name: Run scan
       id: scan
@@ -174,7 +188,11 @@ runs:
             or . == "NPM_NO_ARTIFACT"
             or . == "INTERNAL_DENYLIST_UNAVAILABLE"
             or . == "INTERNAL_DENYLIST_INVALID_ENTRY"
-            or . == "POLICY_INVALID_INTERNAL_TERM";
+            or . == "INTERNAL_DENYLIST_REFUSED"
+            or . == "POLICY_INVALID_INTERNAL_TERM"
+            or . == "RISK_HISTORY_UNREADABLE"
+            or . == "TRIAGE_STORE_UNREADABLE"
+            or . == "SCAN_ZERO_COVERAGE";
           type == "object"
           and (.summary | type == "object")
           and (.findings | type == "array")

package/dist/cli.js

@@ -187,7 +187,7 @@ function assertDistinctOutputPaths(options) {
 program
     .name("supply-chain-guard")
     .description("Open-source supply-chain security scanner. Detects GlassWorm and similar malware campaigns in npm packages, PyPI packages, code repos, VS Code extensions, and project dependencies.")
-    .version("5.28.1");
+    .version("6.0.0");
 // ── scan command ────────────────────────────────────────────────────
 program
     .command("scan")
@@ -273,14 +273,24 @@ program
                 console.log(JSON.stringify(report.attackGraph, null, 2));
             }
         }
-        // Write SBOM to separate file if requested
+        // Write SBOM to separate file if requested.
+        //
+        // v5.30 (issue 198): this goes through the SAME renderer as
+        // `--format sbom`. It used to serialise report.sbomDocument directly
+        // unless the scan was partial, so the file carried no `vulnerabilities`
+        // key at all while stdout carried one entry per finding - two
+        // different documents from one scan, both presented by the README as
+        // the same artefact. The FILE moved, because the stdout document is the
+        // complete one and making stdout match the file would have deleted the
+        // findings from the SBOM instead of adding them to it.
         if (opts.sbomOutput && report.sbomDocument) {
             const { writeFileSync } = await import("node:fs");
-            const sbomOutput = report.partialScan
-                ? (0, reporter_js_1.formatReport)(report, "sbom")
-                : JSON.stringify(report.sbomDocument, null, 2);
-            writeFileSync(opts.sbomOutput, sbomOutput, "utf-8");
-            console.error(`SBOM written to ${opts.sbomOutput} (CycloneDX 1.6, ${report.sbomDocument.components.length} components)`);
+            const { describeInventoryCoverage } = await import("./sbom-generator.js");
+            writeFileSync(opts.sbomOutput, (0, reporter_js_1.formatReport)(report, "sbom"), "utf-8");
+            // A bare component count cannot distinguish "this project has no
+            // components" from "this ecosystem was not read" (issue 195), so the
+            // coverage sentence the document itself carries is printed with it.
+            console.error(`SBOM written to ${opts.sbomOutput} (CycloneDX 1.6, ${report.sbomDocument.components.length} components; ${describeInventoryCoverage(report.sbomDocument)})`);
         }
         // Show fix suggestions if requested
         if (opts.exportFixes && report.fixSuggestions && report.fixSuggestions.length > 0) {
@@ -684,22 +694,44 @@ const feedCmd = program
     .description("Inspect and refresh the threat-intel IOC feed");
 feedCmd
     .command("stats")
-    .description("Show IOC entry counts by type and severity (offline)")
+    .description("Show IOC entry counts, and how old the rule set is, by type and severity (offline)")
     .option("-f, --format <format>", "Output format: text, json", "text")
     .action(async (opts) => {
     try {
         const { getBundledFeed, loadThreatIntel } = await import("./threat-intel.js");
-        const { feedStats } = await import("./feed.js");
+        const { feedStats, feedFreshness, FEED_STALE_AFTER_DAYS } = await import("./feed.js");
         const bundled = getBundledFeed();
         const effective = loadThreatIntel();
         const stats = feedStats(effective);
+        // Age of what a scan would actually match against, and of the pin on its
+        // own, so the two are distinguishable: a refreshed cache can make an old
+        // pin current, and only the pair shows that.
+        const freshness = feedFreshness(effective);
+        const bundledFreshness = feedFreshness(bundled);
         if (opts.format === "json") {
-            console.log(JSON.stringify({ bundledEntries: bundled.length, ...stats }, null, 2));
+            console.log(JSON.stringify({
+                bundledEntries: bundled.length,
+                ...stats,
+                freshness,
+                bundledFreshness,
+                staleAfterDays: FEED_STALE_AFTER_DAYS,
+            }, null, 2));
             return;
         }
+        const describeAge = (f) => f.ageDays === null || f.newestIndicator === null
+            ? "unknown (no indicator carries a usable date)"
+            : `${f.ageDays} day(s), newest indicator ${f.newestIndicator}${f.stale ? "  [STALE]" : ""}`;
         console.log(`\n  Threat-intel feed statistics:\n`);
         console.log(`  Bundled entries:   ${bundled.length}`);
         console.log(`  Effective entries: ${stats.total} (bundled + fresh cache)`);
+        console.log(`\n  Rule-set age (stale after ${FEED_STALE_AFTER_DAYS} days):`);
+        console.log(`    bundled with this version  ${describeAge(bundledFreshness)}`);
+        console.log(`    effective at scan time     ${describeAge(freshness)}`);
+        if (freshness.stale) {
+            console.log(`\n  This rule set is stale. Scanning is offline, so indicators published\n` +
+                `  after that date cannot be detected. Update the package, or run\n` +
+                `  \`supply-chain-guard feed refresh\` before scanning.`);
+        }
         console.log(`\n  By type:`);
         for (const [type, count] of Object.entries(stats.byType)) {
             console.log(`    ${type.padEnd(10)} ${count}`);