@clear-capabilities/agentic-security-scanner 0.169.0 → 0.171.0

package/CHANGELOG.md

@@ -9,6 +9,66 @@
 > make the history less accurate, not more.
 
 
+## 0.171.0 - documentation: surface every shipped PRD capability in the README and docs index
+
+A documentation-only release. Auditing the docs against the actual CLI surface after PRD 5 shipped found
+several real gaps — not cosmetic, actively misleading in one case — and fixed them:
+
+- **README.md said built container images are NOT scanned.** That line predated `image scan`/`image verify`
+  (PRD 5, shipped in 0.170.0) and was flatly false by the time it shipped. Corrected, with a link to the new
+  guide below.
+- **Seven of the repo's 17 slash-command dispatchers had no entry in README's own Commands list**:
+  `dataflow`, `governance`, `remediation`, `federate`, `image`, `provenance`, `runtime`. Added, grouped under
+  two new categories ("Data Flow Explorer" and "Source-to-artifact & runtime").
+- **`docs/guides/runtime-twin.md` (PRD 2's own user guide) was an orphan** — reachable from one internal
+  cross-link, linked from neither README.md nor docs/README.md. Linked from both.
+- **PRD 5 (Source-to-Artifact Security & Provenance) had no user-facing guide at all**, only the internal
+  `docs/implementation-status/` tracking doc. Added `docs/guides/artifact-provenance.md`.
+- **`docs/reference/cli.md` — "every command, flag, and exit code" — was missing `proof`, `rules`, `fleet`,
+  `runtime`, `image`, `provenance`, and `supply` entirely** from its own Commands table (the literal CLI
+  surface of PRDs 1, 3, 4, 2, and 5). Added all seven.
+- Added two new "What makes it different" bullets (runtime corroboration, source-to-artifact tracing) and a
+  `supply --vex` mode mention to README's Commands list.
+
+No code changed; `scanner/dist/agentic-security.mjs` is unchanged.
+
+## 0.170.0 - source-to-artifact security & provenance: a new `src/artifact/` package, `image`/`provenance` CLI, VEX
+
+Binds a finding to the actual **built artifact** (a container image, today) that ships it — closing the gap
+between "this dependency has a CVE" and "this specific image digest actually ships it." A new, isolated
+`scanner/src/artifact/` package reuses the existing SCA pipeline (manifest parsers, OS-package-DB parser,
+OSV/KEV/EPSS correlation) rather than building a parallel one.
+
+**OCI image scanning + inventory.** A hand-rolled, hardened tar/gzip reader (`safe-tar.js`) — hard caps on entry
+count/size/archive size, a native decompression-bomb guard, and a path-safety check that flags (never silently
+normalizes) a `..`/absolute tar entry path. Parses a `docker save`-shaped archive or an OCI-layout archive into
+digest/OS/architecture/base-image/layers/entrypoint/build-labels, with OS and application packages extracted
+through the exact same parsers every other SCA finding in this codebase uses. Never executes the image — no
+`docker run`, no daemon required for the archive path.
+
+**Layer secret analysis.** A secret added in one layer and deleted by a later overlay whiteout is still sitting
+in that earlier layer's raw tar bytes — detected and reported (value always masked/redacted, the detector is
+injected, same shape `posture/secret-history.js` already uses for the git-history analog).
+
+**Signature + attestation verification**, states exactly `verified`/`invalid`/`missing`/`unavailable` — a
+detached-signature check over the image digest, plus REAL DSSE (Pre-Authentication Encoding) verification for
+in-toto/SLSA provenance attestations, so a real cosign-keyed attestation bundle verifies here given the matching
+public key. Never treats missing material as verified.
+
+**The provenance graph** (Git Commit → Build → OCI Digest → SBOM Component → Finding → Deployment) and
+**source-vs-artifact mismatch detection** — the PRD's own "Killer Demonstration": a developer fixes a
+vulnerability in source, but production is still running the old image. `SOURCE: FIXED` / `DEPLOYED ARTIFACT:
+STILL VULNERABLE` / `PRODUCTION EXPOSURE: PRESENT`, proven end-to-end against the real built CLI. **VEX**
+statements (affected/not affected/fixed/under investigation) — `not affected` only ever from positive evidence
+(component absent, or confirmed unreachable), never from absence of information.
+
+**CLI:** `agentic-security image scan/verify`, `agentic-security provenance trace`, `agentic-security supply vex`
+— the PRD's own literal CLI shape. New slash commands `/image`, `/provenance`; `/supply` gained a `--vex` mode.
+
+**Deliberately NOT done, disclosed:** a local Docker daemon image reference and a remote OCI registry reference
+as `image scan` inputs (only local docker-archive/oci-archive tar files); keyless Rekor-transparency-log
+signature verification. See `docs/implementation-status/source-to-artifact-provenance.md`.
+
 ## 0.169.0 - runtime-corroborated security twin: 4 new telemetry adapters, honest runtime assurance, a `runtime` CLI
 
 Extends the existing Milestone 5 "Runtime-Corroborated Digital Twin" machinery (closed-world `RuntimeObservation`

package/bin/agentic-security.js

@@ -5778,6 +5778,295 @@ async function cmdRuntimeQuery(args) {
   return 0;
 }
 
+// ─── PRD 5: Source-to-Artifact Security & Provenance ───────────────────────
+// `image scan/verify`, `provenance trace`, `supply vex`. See
+// docs/implementation-status/source-to-artifact-provenance.md for the full
+// scope, naming-collision discipline (why the graph field below is
+// `artifactProvenanceGraph`, never a bare `.provenance`), and what is
+// deliberately NOT implemented (local-daemon image / remote registry
+// reference inputs; keyless Rekor signature lookup).
+
+function _readFileOrError(target) {
+  const abs = path.resolve(target);
+  if (!fs.existsSync(abs)) return { ok: false, message: `no such file: ${target}` };
+  if (!fs.statSync(abs).isFile()) return { ok: false, message: `${target} is not a file` };
+  try {
+    return { ok: true, buf: fs.readFileSync(abs) };
+  } catch (err) {
+    return { ok: false, message: `failed to read ${target}: ${err.message}` };
+  }
+}
+
+function _artifactScanDigestHex(digestOrTarget) {
+  const s = String(digestOrTarget || '');
+  const hex = s.startsWith('sha256:') ? s.slice(7) : s;
+  return /^[0-9a-f]{64}$/.test(hex) ? hex : null;
+}
+
+// Parses an archive fresh and runs inventory + vuln correlation — the one
+// real analysis path every `image scan`/`provenance trace`/`supply vex`
+// invocation that isn't reading a stored result funnels through.
+async function _scanArchiveFresh(buf) {
+  const { buildImageInventory } = await import('../src/artifact/inventory.js');
+  const { ImageArchiveError } = await import('../src/artifact/image-archive.js');
+  const { TarSafetyError } = await import('../src/artifact/safe-tar.js');
+  const { parseManifests, queryOSV } = await import('../src/sca/index.js');
+  const { correlateImageVulnerabilities } = await import('../src/artifact/vuln-correlate.js');
+  const { analyzeLayerSecrets } = await import('../src/artifact/layer-secrets.js');
+  const { scanCredentials } = await import('../src/secrets/index.js');
+
+  let built;
+  try {
+    built = buildImageInventory(buf, { manifestParser: parseManifests });
+  } catch (err) {
+    if (err instanceof ImageArchiveError || err instanceof TarSafetyError) return { ok: false, message: err.message };
+    throw err;
+  }
+  const { vulnerabilities } = await correlateImageVulnerabilities({
+    inventory: built.inventory, fileContents: built.mergedFilesystem.fileContents, queryOSVFn: queryOSV,
+  });
+  const secrets = analyzeLayerSecrets({
+    readLayersResult: built.readLayersResult, deletedPaths: built.mergedFilesystem.deletedPaths, detectFn: scanCredentials,
+  });
+  return {
+    ok: true,
+    built,
+    record: {
+      inventory: built.inventory,
+      vulnerabilities,
+      secrets: { deletedButRecoverable: secrets.deletedButRecoverable, totalFindings: secrets.findings.length },
+      scannedAt: new Date().toISOString(),
+    },
+  };
+}
+
+async function _persistArtifactScan(record) {
+  const { statePath, safeWriteState } = await import('../src/posture/state-dir.js');
+  const root = process.cwd();
+  const hex = _artifactScanDigestHex(record.inventory.digest);
+  if (!hex) return false; // defensive: digest is always well-formed sha256:<hex> from image-archive.js
+  return safeWriteState(statePath(root, 'artifact-scans', `${hex}.json`), JSON.stringify(record, null, 2), { category: 'artifact-scans' });
+}
+
+// Resolves `target` to a scan record: a digest/sha256:<hex> that matches a
+// PREVIOUSLY `image scan`-ned, persisted record is loaded from state;
+// anything else is treated as an archive file path and parsed fresh. This
+// is what lets `provenance trace <digest>` and `supply vex <digest>` work
+// after an earlier `image scan <path>` without re-reading the archive.
+async function _resolveArtifactScan(target) {
+  const hex = _artifactScanDigestHex(target);
+  if (hex) {
+    const { statePath } = await import('../src/posture/state-dir.js');
+    const storedPath = statePath(process.cwd(), 'artifact-scans', `${hex}.json`);
+    if (fs.existsSync(storedPath)) {
+      try {
+        return { ok: true, record: JSON.parse(fs.readFileSync(storedPath, 'utf8')) };
+      } catch (err) {
+        return { ok: false, message: `stored scan at ${storedPath} is corrupt: ${err.message}` };
+      }
+    }
+    return { ok: false, message: `no stored scan for digest ${target} — run "image scan" on the archive first` };
+  }
+  const read = _readFileOrError(target);
+  if (!read.ok) return read;
+  const scanned = await _scanArchiveFresh(read.buf);
+  if (!scanned.ok) return scanned;
+  return { ok: true, record: scanned.record };
+}
+
+async function cmdImageScan(args) {
+  const target = args._[2];
+  if (!target) {
+    process.stderr.write('agentic-security image scan: provide a path to a docker-archive or oci-archive tar (OCI tar / Docker tar — see commands/image.md for the two supported input shapes).\n');
+    return 2;
+  }
+  const format = args.flags.format ?? 'json';
+  if (format !== 'json' && format !== 'cli') {
+    process.stderr.write('agentic-security image scan: --format must be json|cli.\n');
+    return 2;
+  }
+  const read = _readFileOrError(target);
+  if (!read.ok) { process.stderr.write(`agentic-security image scan: ${read.message}\n`); return 1; }
+
+  const scanned = await _scanArchiveFresh(read.buf);
+  if (!scanned.ok) { process.stderr.write(`agentic-security image scan: ${scanned.message}\n`); return 1; }
+
+  await _persistArtifactScan(scanned.record);
+
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify(scanned.record, null, 2) + '\n');
+    return 0;
+  }
+  const { inventory, vulnerabilities, secrets } = scanned.record;
+  const vulnCount = vulnerabilities.filter((v) => v.type === 'vulnerable_dep').length;
+  process.stdout.write([
+    `Image digest: ${inventory.digest} (${inventory.digestKind})`,
+    `OS/architecture: ${inventory.os}/${inventory.architecture}`,
+    `OS packages: ${inventory.osPackages.length}, application packages: ${inventory.appPackages.length}`,
+    `Vulnerabilities (OSV): ${vulnCount}`,
+    `Secrets deleted-but-recoverable from an earlier layer: ${secrets.deletedButRecoverable.length}`,
+    inventory.materializationTruncated ? 'NOTE: some layer content exceeded the scan size cap and was skipped.' : '',
+  ].filter(Boolean).join('\n') + '\n');
+  return 0;
+}
+
+async function cmdImageVerify(args) {
+  const target = args._[2];
+  if (!target) {
+    process.stderr.write('agentic-security image verify: provide a path to a docker-archive or oci-archive tar, or a previously-scanned digest.\n');
+    return 2;
+  }
+  const resolved = await _resolveArtifactScan(target);
+  if (!resolved.ok) { process.stderr.write(`agentic-security image verify: ${resolved.message}\n`); return 1; }
+  const { inventory } = resolved.record;
+
+  const { verifyImageSignature, verifyProvenanceAttestation } = await import('../src/artifact/signature.js');
+
+  let signature = null;
+  let publicKeyPem = null;
+  let attestation = null;
+  if (typeof args.flags.signature === 'string') {
+    const r = _readFileOrError(args.flags.signature);
+    if (!r.ok) { process.stderr.write(`agentic-security image verify: --signature: ${r.message}\n`); return 1; }
+    signature = r.buf;
+  }
+  if (typeof args.flags['public-key'] === 'string') {
+    const r = _readFileOrError(args.flags['public-key']);
+    if (!r.ok) { process.stderr.write(`agentic-security image verify: --public-key: ${r.message}\n`); return 1; }
+    publicKeyPem = r.buf.toString('utf8');
+  }
+  if (typeof args.flags.attestation === 'string') {
+    const r = _readFileOrError(args.flags.attestation);
+    if (!r.ok) { process.stderr.write(`agentic-security image verify: --attestation: ${r.message}\n`); return 1; }
+    try { attestation = JSON.parse(r.buf.toString('utf8')); } catch (err) {
+      process.stderr.write(`agentic-security image verify: --attestation is not valid JSON: ${err.message}\n`);
+      return 1;
+    }
+  }
+
+  const signatureResult = verifyImageSignature({ digest: inventory.digest, signature, publicKeyPem });
+  const attestationResult = verifyProvenanceAttestation({ digest: inventory.digest, envelope: attestation, publicKeyPem });
+
+  const result = { digest: inventory.digest, signature: signatureResult, attestation: attestationResult };
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  // Exit non-zero only on a definite "invalid" — "missing"/"unavailable" are
+  // honest reports of absent material, not a failed check, and must not be
+  // conflated with a cryptographic failure a CI gate should actually block on.
+  return (signatureResult.state === 'invalid' || attestationResult.state === 'invalid') ? 1 : 0;
+}
+
+async function cmdProvenanceTrace(args) {
+  const target = args._[2];
+  if (!target) {
+    process.stderr.write('agentic-security provenance trace: provide a path to an image archive, or a previously-scanned digest.\n');
+    return 2;
+  }
+  const resolved = await _resolveArtifactScan(target);
+  if (!resolved.ok) { process.stderr.write(`agentic-security provenance trace: ${resolved.message}\n`); return 1; }
+  const { inventory, vulnerabilities } = resolved.record;
+
+  let deployment = null;
+  if (typeof args.flags['deployment-id'] === 'string') {
+    deployment = {
+      id: args.flags['deployment-id'],
+      environment: typeof args.flags['deployment-environment'] === 'string' ? args.flags['deployment-environment'] : null,
+      digest: typeof args.flags['deployment-digest'] === 'string' ? args.flags['deployment-digest'] : null,
+      evidence: 'operator-declared',
+    };
+  }
+
+  const { buildArtifactProvenanceGraph, traceArtifactProvenanceGraph } = await import('../src/artifact/provenance-graph.js');
+  const artifactProvenanceGraph = buildArtifactProvenanceGraph({ inventory, vulnerabilities, deployment });
+  const commitNode = artifactProvenanceGraph.nodes.find((n) => n.kind === 'gitCommit');
+  const trace = traceArtifactProvenanceGraph(artifactProvenanceGraph, commitNode.id);
+
+  let mismatch = null;
+  if (typeof args.flags.source === 'string') {
+    const sourceRoot = path.resolve(args.flags.source);
+    const lastScanPath = path.join(sourceRoot, '.agentic-security', 'last-scan.json');
+    if (!fs.existsSync(lastScanPath)) {
+      process.stderr.write(`agentic-security provenance trace: --source "${args.flags.source}" has no .agentic-security/last-scan.json — run "scan" there first.\n`);
+      return 1;
+    }
+    const sourceScan = JSON.parse(fs.readFileSync(lastScanPath, 'utf8'));
+    const { detectSourceArtifactMismatch } = await import('../src/artifact/mismatch.js');
+    mismatch = detectSourceArtifactMismatch({
+      sourceVulnerabilities: sourceScan.supplyChain || [],
+      artifactVulnerabilities: vulnerabilities,
+      artifactComponents: [...inventory.osPackages, ...inventory.appPackages],
+    });
+  }
+
+  const format = args.flags.format ?? 'json';
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify({ artifactProvenanceGraph, trace, mismatch }, null, 2) + '\n');
+    return 0;
+  }
+
+  const lines = [`Artifact digest: ${inventory.digest}`, `Source commit: ${commitNode.known ? commitNode.sha : '(not declared — no org.opencontainers.image.revision label)'}`];
+  if (mismatch) {
+    lines.push('');
+    if (mismatch.scenarioA.length > 0) {
+      lines.push('SOURCE: FIXED');
+      lines.push('DEPLOYED ARTIFACT: STILL VULNERABLE');
+      lines.push('PRODUCTION EXPOSURE: PRESENT');
+      lines.push(`  ${mismatch.scenarioA.length} vulnerabilit${mismatch.scenarioA.length === 1 ? 'y' : 'ies'} present in this artifact, already fixed in current source: ${mismatch.scenarioA.map((v) => v.osvId).join(', ')}`);
+    }
+    if (mismatch.scenarioB.length > 0) {
+      lines.push(`${mismatch.scenarioA.length > 0 ? '' : 'SOURCE: VULNERABLE\n'}BUILT ARTIFACT: AFFECTED COMPONENT ABSENT`);
+      lines.push(`  ${mismatch.scenarioB.length} vulnerabilit${mismatch.scenarioB.length === 1 ? 'y' : 'ies'} flagged in current source did not actually ship in this artifact: ${mismatch.scenarioB.map((v) => v.osvId).join(', ')}`);
+    }
+    if (!mismatch.hasMismatch) lines.push('No mismatch: current source and this deployed artifact agree.');
+  }
+  process.stdout.write(lines.join('\n') + '\n');
+  return 0;
+}
+
+async function cmdSupplyVex(args) {
+  const target = args._[2];
+  if (!target) {
+    process.stderr.write('agentic-security supply vex: provide a path to an image archive, or a previously-scanned digest.\n');
+    return 2;
+  }
+  const resolved = await _resolveArtifactScan(target);
+  if (!resolved.ok) { process.stderr.write(`agentic-security supply vex: ${resolved.message}\n`); return 1; }
+  const { inventory, vulnerabilities } = resolved.record;
+
+  let reachabilityByKey = new Map();
+  if (typeof args.flags.source === 'string') {
+    const sourceRoot = path.resolve(args.flags.source);
+    const lastScanPath = path.join(sourceRoot, '.agentic-security', 'last-scan.json');
+    if (fs.existsSync(lastScanPath)) {
+      const sourceScan = JSON.parse(fs.readFileSync(lastScanPath, 'utf8'));
+      for (const sc of (sourceScan.supplyChain || [])) {
+        if (sc.type !== 'vulnerable_dep') continue;
+        const key = sc.purl || `${sc.ecosystem}:${sc.name}`;
+        const reachable = sc.functionReachable === 'reachable' ? true : sc.functionReachable === 'unreachable' ? false : null;
+        if (reachable !== null) reachabilityByKey.set(key, { reachable, reason: sc.reachabilityTier || null });
+      }
+    }
+  }
+
+  const { deriveVexStatus } = await import('../src/artifact/vex.js');
+  const artifactComponents = [...inventory.osPackages, ...inventory.appPackages];
+  const statements = vulnerabilities.filter((v) => v.type === 'vulnerable_dep').map((v) => {
+    const key = v.purl || `${v.ecosystem}:${v.name}`;
+    const reachability = reachabilityByKey.get(key) || null;
+    const vex = deriveVexStatus({ vulnerability: v, artifactComponents, reachability });
+    return { purl: v.purl || null, name: v.name, ecosystem: v.ecosystem, osvId: v.osvId, ...vex };
+  });
+
+  const format = args.flags.format ?? 'json';
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify({ digest: inventory.digest, statements }, null, 2) + '\n');
+    return 0;
+  }
+  const lines = [`VEX for ${inventory.digest}:`];
+  for (const s of statements) lines.push(`  ${s.osvId} (${s.name}): ${s.status}${s.justification ? ` [${s.justification}]` : ''}`);
+  process.stdout.write(lines.join('\n') + '\n');
+  return 0;
+}
+
 // Mirrors posture/fix-history.js's own _writeAtomicAndSync (temp file in
 // the same directory, fsync, then rename over the target) — a crash
 // mid-write must never leave recipient-profiles.json as invalid JSON,
@@ -7524,6 +7813,48 @@ async function main() {
         }
         break;
       }
+      case 'image': {
+        // PRD 5 (Source-to-Artifact Security & Provenance) names this
+        // literal CLI shape. `scan` parses + correlates; `verify` checks
+        // signature/attestation material only (never re-runs correlation).
+        const sub = args._[1];
+        if (sub === 'scan') { process.exit(await cmdImageScan(args)); }
+        else if (sub === 'verify') { process.exit(await cmdImageVerify(args)); }
+        else {
+          process.stderr.write(`agentic-security image: unrecognized sub-command "${sub}" — must be "scan" or "verify".\n`);
+          process.exit(2);
+        }
+        break;
+      }
+      case 'provenance': {
+        // NOT `posture/provenance/`'s git-commit finding provenance, NOT
+        // `sca/sigstore-verify.js`'s package-build provenance — this is PRD
+        // 5's own artifact provenance graph (Git Commit -> Build -> OCI
+        // Digest -> SBOM Component -> Finding -> Deployment). See
+        // docs/implementation-status/source-to-artifact-provenance.md's
+        // naming-discipline section.
+        const sub = args._[1];
+        if (sub === 'trace') { process.exit(await cmdProvenanceTrace(args)); }
+        else {
+          process.stderr.write(`agentic-security provenance: unrecognized sub-command "${sub}" — must be "trace".\n`);
+          process.exit(2);
+        }
+        break;
+      }
+      case 'supply': {
+        // The `/supply` SLASH COMMAND (commands/supply.md) is a different
+        // layer entirely — Claude Code UI sugar that shells out to `scan
+        // --only sca`/`cve-watch`. This is PRD 5's own literal CLI shape,
+        // `agentic-security supply vex`, operating on an IMAGE ARTIFACT
+        // rather than a source directory.
+        const sub = args._[1];
+        if (sub === 'vex') { process.exit(await cmdSupplyVex(args)); }
+        else {
+          process.stderr.write(`agentic-security supply: unrecognized sub-command "${sub}" — must be "vex".\n`);
+          process.exit(2);
+        }
+        break;
+      }
       case 'remediation': {
         // NOT a `dataflow` subcommand — this writes operator/incident
         // state (the append-only remediation ledger), never the scanned

package/dist/2199.index.js

@@ -313,7 +313,7 @@ function saveProof(scanRoot, record) {
   const enc = (0,_encryption_provider_js__WEBPACK_IMPORTED_MODULE_3__/* .maybeEncryptForWrite */ .v2)(scanRoot, PROOFS_DIR, text);
   if (!enc.ok) return { ok: false, reason: enc.reason };
   const file = (0,_state_dir_js__WEBPACK_IMPORTED_MODULE_2__.statePath)(scanRoot, PROOFS_DIR, findingKey(record.findingId), `${safe.recordDigest}.json`);
-  if (!(0,_state_dir_js__WEBPACK_IMPORTED_MODULE_2__/* .safeWriteState */ .Ep)(file, enc.content)) return { ok: false, reason: 'state write refused' };
+  if (!(0,_state_dir_js__WEBPACK_IMPORTED_MODULE_2__.safeWriteState)(file, enc.content)) return { ok: false, reason: 'state write refused' };
   return { ok: true, file, digest: safe.recordDigest, encrypted: enc.encrypted };
 }
 

package/dist/2675.index.js

@@ -0,0 +1,174 @@
+export const id = 2675;
+export const ids = [2675];
+export const modules = {
+
+/***/ 82675:
+/***/ ((__unused_webpack___webpack_module__, __webpack_exports__, __webpack_require__) => {
+
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   verifyImageSignature: () => (/* binding */ verifyImageSignature),
+/* harmony export */   verifyProvenanceAttestation: () => (/* binding */ verifyProvenanceAttestation)
+/* harmony export */ });
+/* unused harmony export SIGNATURE_STATES */
+/* harmony import */ var node_crypto__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(77598);
+// PRD 5 P0 §5 — Signature Verification. States are exactly the PRD's own
+// four, deliberately different from `sca/sigstore-verify.js`'s own vocabulary
+// (`verified/unverified/tampered/unknown`) so the two are never confused by
+// shared words — see docs/implementation-status/source-to-artifact-provenance.md's
+// naming-discipline section:
+//
+//   verified    — a real cryptographic check ran and the signature matches.
+//   invalid     — a real cryptographic check ran and the signature does NOT match.
+//   missing     — no signature/attestation material was supplied at all.
+//   unavailable — material was supplied but could not be cryptographically
+//                 checked (no public key given, or the check itself could
+//                 not run) — the PRD's "never treat missing tooling as
+//                 verified" clause means this state, not `verified`, is what
+//                 an incomplete check must report.
+//
+// Two real, independent mechanisms are implemented:
+//   1. A plain detached signature over the image digest string, verified
+//      with an operator-supplied public key. This is this tool's OWN local
+//      convention, not cosign's "simple signing" JSON format — disclosed in
+//      the implementation-status doc, not silently passed off as cosign-
+//      compatible.
+//   2. Real DSSE (Dead Simple Signing Envelope) verification for in-toto/SLSA
+//      provenance attestations — the actual encoding cosign/Sigstore use for
+//      attestations, so a real cosign-keyed attestation bundle DOES verify
+//      here given the matching public key. `dssePae` is the exact PAE
+//      (Pre-Authentication Encoding) from the DSSE spec.
+//
+// Keyless/Rekor-transparency-log verification is NOT implemented — disclosed
+// as a gap, never faked. `sca/sigstore-verify.js`'s Rekor-query pattern is
+// the template a future increment could extend this module with.
+
+
+const SIGNATURE_STATES = Object.freeze(['verified', 'invalid', 'missing', 'unavailable']);
+
+function verifyRaw(payload, signature, publicKeyPem) {
+  let publicKey;
+  try {
+    publicKey = node_crypto__WEBPACK_IMPORTED_MODULE_0__.createPublicKey(publicKeyPem);
+  } catch (err) {
+    return { ok: false, error: `public key is not parseable: ${err.message}` };
+  }
+  const keyType = publicKey.asymmetricKeyType;
+  const algorithm = (keyType === 'ed25519' || keyType === 'ed448') ? null : 'sha256';
+  try {
+    const ok = node_crypto__WEBPACK_IMPORTED_MODULE_0__.verify(algorithm, payload, publicKey, signature);
+    return { ok, keyType };
+  } catch (err) {
+    return { ok: false, error: `signature verification failed to run: ${err.message}` };
+  }
+}
+
+/**
+ * Verifies a detached signature over an image's digest string.
+ * `signature`/`publicKeyPem` are Buffer/PEM-string; either missing means
+ * `missing` (nothing was supplied to check).
+ */
+function verifyImageSignature({ digest, signature, publicKeyPem }) {
+  if (typeof digest !== 'string' || !digest.startsWith('sha256:')) {
+    return { state: 'unavailable', reason: 'no image digest available to verify a signature against' };
+  }
+  if (!signature || !publicKeyPem) {
+    return { state: 'missing', reason: 'no detached signature and public key were supplied for this image' };
+  }
+  const { ok, error, keyType } = verifyRaw(Buffer.from(digest, 'utf8'), signature, publicKeyPem);
+  if (error) return { state: 'invalid', reason: error };
+  return ok
+    ? { state: 'verified', keyType }
+    : { state: 'invalid', reason: 'signature does not match the image digest under the supplied public key' };
+}
+
+// DSSE Pre-Authentication Encoding: "DSSEv1" SP LEN(type) SP type SP LEN(body) SP body.
+function dssePae(payloadType, payloadBytes) {
+  const typeBytes = Buffer.from(payloadType, 'utf8');
+  return Buffer.concat([
+    Buffer.from('DSSEv1 ', 'ascii'),
+    Buffer.from(String(typeBytes.length), 'ascii'),
+    Buffer.from(' ', 'ascii'),
+    typeBytes,
+    Buffer.from(' ', 'ascii'),
+    Buffer.from(String(payloadBytes.length), 'ascii'),
+    Buffer.from(' ', 'ascii'),
+    payloadBytes,
+  ]);
+}
+
+const SLSA_PREDICATE_PREFIX = 'https://slsa.dev/provenance/';
+const INTOTO_STATEMENT_TYPES = new Set(['https://in-toto.io/Statement/v0.1', 'https://in-toto.io/Statement/v1']);
+
+/**
+ * Verifies an in-toto/SLSA provenance attestation for an image.
+ * `envelope` is a DSSE envelope: `{ payloadType, payload (base64 in-toto
+ * Statement JSON), signatures: [{ sig (base64) }] }` — the real shape
+ * cosign/Sigstore attestations use. `publicKeyPem` verifies one of
+ * `signatures` against `dssePae(payloadType, payload)`.
+ *
+ * The subject-digest match is checked FIRST and independently of signature
+ * verification, so a mismatched subject is always `invalid` (never
+ * "unavailable", which would understate a real, checkable problem).
+ */
+function verifyProvenanceAttestation({ digest, envelope, publicKeyPem }) {
+  if (!envelope) return { state: 'missing', reason: 'no in-toto/SLSA provenance attestation was supplied for this image' };
+
+  let env;
+  try {
+    env = typeof envelope === 'string' ? JSON.parse(envelope) : envelope;
+  } catch (err) {
+    return { state: 'invalid', reason: `attestation envelope is not valid JSON: ${err.message}` };
+  }
+  if (typeof env.payload !== 'string' || typeof env.payloadType !== 'string' || !Array.isArray(env.signatures)) {
+    return { state: 'invalid', reason: 'not a recognized DSSE envelope (missing payload, payloadType, or signatures)' };
+  }
+
+  let payloadBytes;
+  let stmt;
+  try {
+    payloadBytes = Buffer.from(env.payload, 'base64');
+    stmt = JSON.parse(payloadBytes.toString('utf8'));
+  } catch (err) {
+    return { state: 'invalid', reason: `attestation payload is not a valid base64-encoded JSON statement: ${err.message}` };
+  }
+  if (!INTOTO_STATEMENT_TYPES.has(stmt._type)) {
+    return { state: 'invalid', reason: 'statement is missing a recognized in-toto "_type"' };
+  }
+
+  const digestHex = typeof digest === 'string' && digest.startsWith('sha256:') ? digest.slice('sha256:'.length) : digest;
+  const subjects = Array.isArray(stmt.subject) ? stmt.subject : [];
+  const subjectMatches = subjects.some((s) => s && s.digest && s.digest.sha256 === digestHex);
+  if (!subjectMatches) {
+    return { state: 'invalid', reason: 'attestation subject digest does not match this image', predicateType: stmt.predicateType || null };
+  }
+
+  const predicateType = stmt.predicateType || null;
+  const isSlsa = typeof predicateType === 'string' && predicateType.startsWith(SLSA_PREDICATE_PREFIX);
+
+  if (!publicKeyPem || env.signatures.length === 0) {
+    return {
+      state: 'unavailable',
+      reason: 'attestation subject matches this image, but no public key was supplied to verify its signature',
+      predicateType, isSlsa,
+    };
+  }
+
+  const pae = dssePae(env.payloadType, payloadBytes);
+  for (const sigEntry of env.signatures) {
+    if (!sigEntry || typeof sigEntry.sig !== 'string') continue;
+    let sigBytes;
+    try {
+      sigBytes = Buffer.from(sigEntry.sig, 'base64');
+    } catch {
+      continue;
+    }
+    const { ok } = verifyRaw(pae, sigBytes, publicKeyPem);
+    if (ok) return { state: 'verified', predicateType, isSlsa };
+  }
+  return { state: 'invalid', reason: 'no signature in the attestation envelope verifies under the supplied public key', predicateType, isSlsa };
+}
+
+
+/***/ })
+
+};

package/dist/4142.index.js

@@ -712,13 +712,13 @@ function loadLedger(scanRoot) {
 function saveLedger(scanRoot, ledger) {
   if (!(0,state_dir/* ensureStateDir */.xH)(scanRoot)) return { ok: false, reason: 'no safe state directory for this project' };
   const f = (0,state_dir.statePath)(scanRoot, DIR, 'ledger.json');
-  return { ok: (0,state_dir/* safeWriteState */.Ep)(f, JSON.stringify(ledger, null, 2)) };
+  return { ok: (0,state_dir.safeWriteState)(f, JSON.stringify(ledger, null, 2)) };
 }
 
 function saveIR(scanRoot, ir) {
   if (!(0,state_dir/* ensureStateDir */.xH)(scanRoot)) return { ok: false, reason: 'no safe state directory for this project' };
   const f = external_node_path_.join(ruleDir(scanRoot, ir.id), 'ir.json');
-  return { ok: (0,state_dir/* safeWriteState */.Ep)(f, JSON.stringify(ir, null, 2)), file: f };
+  return { ok: (0,state_dir.safeWriteState)(f, JSON.stringify(ir, null, 2)), file: f };
 }
 
 function loadIR(scanRoot, id) {
@@ -729,7 +729,7 @@ function loadIR(scanRoot, id) {
 function saveEvaluation(scanRoot, id, evaluation) {
   if (!(0,state_dir/* ensureStateDir */.xH)(scanRoot)) return { ok: false, reason: 'no safe state directory for this project' };
   const f = external_node_path_.join(ruleDir(scanRoot, id), 'evaluation.json');
-  return { ok: (0,state_dir/* safeWriteState */.Ep)(f, JSON.stringify(evaluation, null, 2)) };
+  return { ok: (0,state_dir.safeWriteState)(f, JSON.stringify(evaluation, null, 2)) };
 }
 
 /** Write the regression fixtures a promoted rule needs: the SAME vulnerable/clean convention `runRuleTests`
@@ -741,11 +741,11 @@ function writeFixtures(scanRoot, ir, corpus) {
   const written = [];
   for (const p of corpus.positives) {
     const f = external_node_path_.join(base, 'vulnerable', `${p.label.replace(/[^a-z0-9_-]/gi, '_')}.${ext}`);
-    if ((0,state_dir/* safeWriteState */.Ep)(f, p.code)) written.push(f);
+    if ((0,state_dir.safeWriteState)(f, p.code)) written.push(f);
   }
   for (const n of corpus.negatives) {
     const f = external_node_path_.join(base, 'clean', `${n.label.replace(/[^a-z0-9_-]/gi, '_')}.${ext}`);
-    if ((0,state_dir/* safeWriteState */.Ep)(f, n.code)) written.push(f);
+    if ((0,state_dir.safeWriteState)(f, n.code)) written.push(f);
   }
   return { ok: true, written, glob: external_node_path_.join(base, '**', '*') };
 }
@@ -772,7 +772,7 @@ function publishCustomRule(scanRoot, ir) {
     `  message: ${JSON.stringify(doc.message)}`,
     '',
   ].join('\n');
-  return { ok: (0,state_dir/* safeWriteState */.Ep)(f, yamlText), file: f };
+  return { ok: (0,state_dir.safeWriteState)(f, yamlText), file: f };
 }
 
 function unpublishCustomRule(scanRoot, id) {

package/dist/5014.index.js

@@ -136,7 +136,7 @@ function addLegalHold(scanRoot, { artifact, owner, reason, expires_at } = {}) {
   const holds = _loadRaw(scanRoot);
   holds.push(hold);
   const fp = (0,_state_dir_js__WEBPACK_IMPORTED_MODULE_1__.statePath)(scanRoot, LEGAL_HOLD_FILE);
-  if (!(0,_state_dir_js__WEBPACK_IMPORTED_MODULE_1__/* .safeWriteState */ .Ep)(fp, JSON.stringify(holds, null, 2) + '\n')) {
+  if (!(0,_state_dir_js__WEBPACK_IMPORTED_MODULE_1__.safeWriteState)(fp, JSON.stringify(holds, null, 2) + '\n')) {
     return { ok: false, reason: 'state writes are disabled (--no-state) or this is not a safe state directory' };
   }
   return { ok: true, hold };
@@ -152,7 +152,7 @@ function removeLegalHold(scanRoot, artifact) {
   const removedCount = holds.length - remaining.length;
   if (removedCount > 0) {
     const fp = (0,_state_dir_js__WEBPACK_IMPORTED_MODULE_1__.statePath)(scanRoot, LEGAL_HOLD_FILE);
-    (0,_state_dir_js__WEBPACK_IMPORTED_MODULE_1__/* .safeWriteState */ .Ep)(fp, JSON.stringify(remaining, null, 2) + '\n');
+    (0,_state_dir_js__WEBPACK_IMPORTED_MODULE_1__.safeWriteState)(fp, JSON.stringify(remaining, null, 2) + '\n');
   }
   return removedCount;
 }