@clear-capabilities/agentic-security-scanner 0.143.0 → 0.144.0

package/src/posture/compliance-evidence-signing.js

@@ -0,0 +1,131 @@
+// Sign compliance evidence manifests (assurance-hardening PRD FR-505).
+//
+// "Sign evidence manifests when signing is configured | Signature
+// verification detects altered findings, scope, policy, or evidence
+// references."
+//
+// SAME TRUST DOMAIN AS evidence-bundle.js, DELIBERATELY REUSING ITS KEY
+// --------------------------------------------------------------------------
+// A compliance evidence manifest and a finding evidence bundle make the
+// SAME kind of claim: "this artifact is exactly what MY install produced,
+// unaltered since." Both are self-attestation by the running install, not
+// a claim authored by a third party and distributed for others to verify
+// (that is policy-bundle.js's job, and why IT needed a separate key — see
+// D-0026). Reusing evidence-bundle.js's `ensureKeyPair()` directly means an
+// operator who already generated a key for finding attestations does not
+// need a second one for compliance evidence; the two artifact types are
+// simply two things the SAME key can honestly attest to.
+//
+// EA-03 DISCIPLINE, APPLIED FROM THE FIRST WRITE (see D-0026)
+// --------------------------------------------------------------------------
+// canonicalComplianceEvidenceBytes signs an explicit ALLOWLIST — every key
+// emitEvidenceJsonLd() can actually produce, no more, no less — and
+// verifyComplianceEvidence REJECTS any top-level key outside
+// {that allowlist, signature}. A field stapled on after signing (a status
+// silently edited, a control removed, a narrative_evidence line added) must
+// fail verification, not verify successfully with the addition unnoticed.
+//
+// WHY THE FULL DOCUMENT, NOT JUST evidenceDigest (FR-504)
+// --------------------------------------------------------------------------
+// computeEvidenceDigest (FR-504) binds `controls` down to {id, status} only
+// — enough to prove "the CONCLUSION did not change," but not enough to
+// catch an edited check reason or narrative evidence bullet without
+// touching the top-line status. FR-505's acceptance criterion is broader
+// ("altered ... evidence references"), so the signature here covers the
+// full per-control shape (checks[], narrative_evidence[]) that
+// emitEvidenceJsonLd actually renders, not just the FR-504 digest.
+
+import * as fs from 'node:fs';
+import * as crypto from 'node:crypto';
+import { keyPaths } from './evidence-bundle.js';
+
+export const COMPLIANCE_EVIDENCE_SCHEMA = 'agentic-security/compliance-evidence@1';
+
+/**
+ * "Sign evidence manifests WHEN SIGNING IS CONFIGURED" — this is the opt-in
+ * check. Unlike `agentic-security attest` (an explicit command an operator
+ * runs specifically to sign something, where generating a key on first use
+ * is the right default), compliance evidence is emitted automatically on
+ * every ordinary scan — auto-generating a signing key as a side effect of a
+ * routine scan would be surprising, unrequested behavior. "Configured"
+ * therefore means an operator has ALREADY set up the shared key (by running
+ * `attest` once, or by any other means) — this function only ever READS,
+ * never generates. Read-first-in-try/catch (D-0012) — no
+ * existsSync-then-readFileSync.
+ *
+ * @returns {{privateKeyPem: string, publicKeyPem: string}|null}
+ */
+export function loadSigningKeyIfConfigured() {
+  const p = keyPaths();
+  let privateKeyPem, publicKeyPem;
+  try { privateKeyPem = fs.readFileSync(p.privateKey, 'utf8'); } catch { return null; }
+  try { publicKeyPem = fs.readFileSync(p.publicKey, 'utf8'); } catch { return null; }
+  return { privateKeyPem, publicKeyPem };
+}
+
+// The complete set of top-level keys a real emitEvidenceJsonLd() output can
+// carry, BEFORE signing. Must be kept in sync with that function — the
+// signed allowlist and the "known keys" allowlist for unsigned-field
+// rejection are the SAME set, exactly as evidence-bundle.js/policy-bundle.js
+// both already establish.
+const EVIDENCE_FIELDS = [
+  '@context', '@type', 'schemaVersion', 'statusSemantics', 'policySource',
+  'framework', 'version', 'generatedAt',
+  'disclaimer', 'provenance', 'evidenceDigest', 'summary', 'controls',
+];
+const EVIDENCE_TOP_LEVEL_KEYS = new Set([...EVIDENCE_FIELDS, 'signature']);
+
+// Deterministic JSON, keys sorted at every level — same algorithm as
+// evidence-bundle.js's canonicalJson and policy-bundle.js's canonicalJson
+// (each duplicated locally rather than imported, per those modules' own
+// stated reasoning: a pure, three-line function not worth coupling three
+// signing modules' formats together for).
+function _canonicalJson(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value ?? null);
+  if (Array.isArray(value)) return `[${value.map(_canonicalJson).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map(k => `${JSON.stringify(k)}:${_canonicalJson(value[k])}`).join(',')}}`;
+}
+
+export function canonicalComplianceEvidenceBytes(jsonld) {
+  const signed = {};
+  for (const k of EVIDENCE_FIELDS) signed[k] = jsonld[k] ?? null;
+  return Buffer.from(_canonicalJson(signed), 'utf8');
+}
+
+/** Sign a compliance evidence document. Returns a new object; the input is not mutated. */
+export function signComplianceEvidence(jsonld, privateKeyPem) {
+  const sig = crypto.sign(null, canonicalComplianceEvidenceBytes(jsonld), privateKeyPem);
+  return {
+    ...jsonld,
+    signature: { algorithm: 'ed25519', canonicalisation: COMPLIANCE_EVIDENCE_SCHEMA, value: sig.toString('base64') },
+  };
+}
+
+/**
+ * Verify a signed compliance evidence document with a PUBLIC key. Never
+ * throws — a malformed or tampered document from an untrusted source (an
+ * auditor or GRC tool checking what they were handed) is an expected input.
+ *
+ * @returns {{ok: boolean, reason: string|null}}
+ */
+export function verifyComplianceEvidence(jsonld, publicKeyPem) {
+  if (!jsonld || typeof jsonld !== 'object') return { ok: false, reason: 'document is not an object' };
+  const unknownKeys = Object.keys(jsonld).filter(k => !EVIDENCE_TOP_LEVEL_KEYS.has(k));
+  if (unknownKeys.length) {
+    return { ok: false, reason: `unrecognised top-level key(s) not covered by the signature: ${unknownKeys.join(', ')}` };
+  }
+  const sig = jsonld.signature;
+  if (!sig?.value) return { ok: false, reason: 'document is unsigned' };
+  if (sig.algorithm !== 'ed25519') return { ok: false, reason: `unsupported algorithm: ${sig.algorithm}` };
+  if (!publicKeyPem) return { ok: false, reason: 'no public key supplied' };
+  let sigOk = false;
+  try {
+    sigOk = crypto.verify(null, canonicalComplianceEvidenceBytes(jsonld), publicKeyPem, Buffer.from(sig.value, 'base64'));
+  } catch (e) {
+    return { ok: false, reason: `verification error: ${e.message}` };
+  }
+  return sigOk
+    ? { ok: true, reason: null }
+    : { ok: false, reason: 'signature does not match the document contents — it was modified after signing' };
+}

package/src/posture/compliance-policy.js

@@ -29,9 +29,33 @@
 //   finding-family: <name>     must-be: zero | min: <n> | max: <n>
 //   file-exists: <relative-path>
 //   documented: <relative-path>  (alias for file-exists)
+//   file-contains: <relative-path>   pattern: <regex>
+//     FR-503: for a control that demands the file's CONTENT prove something,
+//     not just its existence — "mere artifact existence... is insufficient
+//     unless the mapping explicitly defines it." file-exists remains valid
+//     for controls that genuinely only need a document to exist.
 //   env-var-set: <name>
 //   sca-policy-has-entry: <type>  (e.g. accept-risk, sla)
 //
+// FR-504/FR-506 (assurance-hardening PRD) — optional, per-control fields,
+// all additive (a control naming none of these is unaffected):
+//   owner: <string>                 — who is accountable for this control
+//   reviewer: <string>               — who last reviewed the evidence
+//   reviewed-at: <ISO date>          — when it was last reviewed
+//   review-interval-days: <number>   — opts into staleness: once
+//                                      reviewed-at + this interval has
+//                                      passed, status becomes `stale`
+//   not-applicable: true             — legacy bare exception, never expires
+//   not-applicable:                  — structured exception; an EXPIRED one
+//     reason: "..."                    reopens the control as status `gap`
+//     owner: "..."                     rather than silently staying
+//     expires-at: <ISO date>           not-applicable
+//
+// Every verification also computes `evidenceDigest` (FR-504) — a sha256 of
+// {repository, commit, scope, engine, ruleset, analyzerHealth,
+// mappingVersion, controls[{id,status}]} — so changing any bound input is a
+// checkable property, not an assertion.
+//
 // Output:
 //   .agentic-security/compliance-evidence.json — JSON-LD compliant
 //     structured artifact
@@ -39,12 +63,41 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { execSync } from 'node:child_process';
 import * as yaml from '../util/yaml.js';
-import { statePath, safeWriteState } from './state-dir.js';
+import { statePath, safeWriteState, STATE_DIR_NAME } from './state-dir.js';
 import { SCANNER_VERSION } from './version.js';
+import { EVIDENCE_GRADE_DISCLAIMER, EVIDENCE_GRADE_DISCLAIMER_SHORT } from './evidence-grade-wording.js';
+import { loadSigningKeyIfConfigured, signComplianceEvidence } from './compliance-evidence-signing.js';
+import { maybeEncryptForWrite } from './encryption-provider.js';
 
 const POLICY_FILE = 'compliance.policy.yml';
 
+// FR-508: "export evidence in a stable API suitable for external GRC
+// ingestion | exported records retain source references, status
+// semantics, and schema version." The JSON-LD shape itself has been
+// additive-only since it was introduced (every field this session has
+// added — evidenceDigest, owner/reviewer/staleReason/gapReason, signature —
+// was optional and backward-compatible), which IS the stability guarantee;
+// this constant is what lets a consumer verify that claim programmatically
+// instead of taking it on faith. Bump when — and only when — an existing
+// field's MEANING changes incompatibly (a genuinely additive field does
+// not require a bump, matching every semver-adjacent convention in this
+// codebase: new optional fields are not breaking changes).
+export const EVIDENCE_SCHEMA_VERSION = 1;
+
+// FR-508: "status semantics" — a GRC tool ingesting this artifact should
+// not have to reverse-engineer what each status string means from this
+// codebase's own source; the definitions travel WITH the document.
+export const STATUS_SEMANTICS = {
+  compliant: 'Every check for this control passed against the current scan.',
+  'non-compliant': 'At least one check for this control failed against the current scan.',
+  'not-applicable': 'The control is explicitly excepted by the policy mapping (not-applicable) and was not evaluated.',
+  stale: 'The control passed its checks, but its evidence exceeded an operator-configured review interval (FR-506) and has not been re-reviewed.',
+  gap: 'A previously-recorded not-applicable exception has expired (FR-506); the control has neither a fresh exception nor a fresh evaluation.',
+};
+
 export function loadPolicy(scanRoot) {
   const fp = statePath(scanRoot, POLICY_FILE);
   if (!fs.existsSync(fp)) return null;
@@ -57,6 +110,27 @@ export function loadPolicy(scanRoot) {
   }
 }
 
+// FR-506: `not-applicable` accepts either the legacy bare `true` (kept
+// working forever — many existing compliance policy YAMLs use this shape,
+// and a bare exception with no expiry is a valid, if less accountable,
+// choice) or a structured exception object `{reason, owner, expires_at}`.
+// Only the structured shape can expire; a bare `true` never does, matching
+// this session's own "no expiry configured = never expires" convention
+// (D-0025's suppression exceptions, the waiver-file pattern).
+function _normalizeNotApplicable(raw) {
+  if (!raw) return null;
+  if (raw === true) return { legacy: true };
+  if (typeof raw === 'object') {
+    return {
+      legacy: false,
+      reason: raw.reason || null,
+      owner: raw.owner || null,
+      expires_at: raw['expires-at'] || raw.expires_at || null,
+    };
+  }
+  return null;
+}
+
 function _normalize(doc) {
   if (!doc) return null;
   return {
@@ -67,11 +141,55 @@ function _normalize(doc) {
       title: c.title || id,
       requires: Array.isArray(c.requires) ? c.requires : [],
       evidence: Array.isArray(c.evidence) ? c.evidence : [],
-      not_applicable: !!c['not-applicable'],
+      not_applicable: _normalizeNotApplicable(c['not-applicable']),
+      // FR-506: freshness + accountability metadata. All optional and
+      // additive — a control naming neither owner/reviewer nor a review
+      // interval is completely unaffected (no-op, matching every other
+      // gate this session has built).
+      owner: c.owner || null,
+      reviewer: c.reviewer || null,
+      reviewed_at: c['reviewed-at'] || c.reviewed_at || null,
+      review_interval_days: typeof c['review-interval-days'] === 'number' ? c['review-interval-days']
+        : (typeof c.review_interval_days === 'number' ? c.review_interval_days : null),
     })),
   };
 }
 
+/**
+ * FR-506: is this control's evidence stale? Only meaningful when the
+ * mapping author opted in via `review-interval-days` — a control with none
+ * set is never stale, by construction (there is no baseline to be stale
+ * relative to). `reviewed_at` missing while an interval IS set counts as
+ * "never reviewed," which is at least as stale as a review that happened
+ * on day zero — not a free pass.
+ */
+function _staleness(control, now) {
+  if (!Number.isFinite(control.review_interval_days)) return { stale: false };
+  const reviewedAt = control.reviewed_at ? Date.parse(control.reviewed_at) : NaN;
+  const baseline = Number.isFinite(reviewedAt) ? reviewedAt : 0; // never-reviewed => already maximally stale
+  const ageMs = now - baseline;
+  const staleAfterMs = control.review_interval_days * 24 * 3600 * 1000;
+  if (ageMs > staleAfterMs) {
+    return { stale: true, reason: control.reviewed_at ? `last reviewed ${control.reviewed_at}, exceeds ${control.review_interval_days}-day interval` : `never reviewed (review-interval-days: ${control.review_interval_days} requires an initial reviewed-at)` };
+  }
+  return { stale: false };
+}
+
+/**
+ * FR-506: has this control's not-applicable EXCEPTION expired? A bare-`true`
+ * exception (legacy shape) never expires. An expired structured exception
+ * reopens the control as a GAP (unevidenced), not silently back to
+ * whatever `requires` would have said — an operator who marked something
+ * not-applicable never ran the underlying checks, so there is no fresh
+ * compliant/non-compliant verdict to fall back to.
+ */
+function _exceptionExpired(notApplicable, now) {
+  if (!notApplicable || notApplicable.legacy) return false;
+  if (!notApplicable.expires_at) return false;
+  const exp = Date.parse(notApplicable.expires_at);
+  return Number.isFinite(exp) && exp < now;
+}
+
 /**
  * Run a single primitive check against the scanner state.
  *   { passed, reason }
@@ -100,6 +218,29 @@ function _runCheck(check, ctx) {
     if (fs.existsSync(fp)) return { passed: true, reason: `${rel} exists` };
     return { passed: false, reason: `${rel} not found` };
   }
+  // FR-503: "mere artifact existence... is insufficient UNLESS the mapping
+  // explicitly defines it." `file-exists` remains legitimate for controls
+  // that genuinely only need "is there a policy document" — this is a NEW,
+  // separate primitive a mapping author opts into for a control that
+  // demands the file's CONTENT prove something (e.g. a workflow file that
+  // must actually configure dependency automation, not merely exist under
+  // that name with an empty body). Read-first-in-try/catch (D-0012) — no
+  // existsSync-then-readFileSync, unlike the sibling file-exists check
+  // above (pre-existing code, not touched here).
+  if (check['file-contains']) {
+    const rel = check['file-contains'];
+    const fp = path.join(ctx.scanRoot, rel);
+    let content;
+    try { content = fs.readFileSync(fp, 'utf8'); }
+    catch { return { passed: false, reason: `${rel} not found` }; }
+    const patternStr = check.pattern;
+    if (!patternStr) return { passed: false, reason: 'file-contains check has no pattern' };
+    let re;
+    try { re = new RegExp(patternStr, 'i'); }
+    catch (e) { return { passed: false, reason: `file-contains pattern is not a valid regex: ${e.message}` }; }
+    if (re.test(content)) return { passed: true, reason: `${rel} exists and matches required pattern` };
+    return { passed: false, reason: `${rel} exists but does not match required pattern (mere existence is not enough for this control)` };
+  }
   if (check['env-var-set']) {
     const name = check['env-var-set'];
     if (process.env[name]) return { passed: true, reason: `$${name} set` };
@@ -108,9 +249,16 @@ function _runCheck(check, ctx) {
   if (check['sca-policy-has-entry']) {
     const type = check['sca-policy-has-entry'];
     const policyPath = statePath(ctx.scanRoot, 'sca-policy.yml');
-    if (!fs.existsSync(policyPath)) return { passed: false, reason: 'sca-policy.yml not found' };
+    // FR-503 self-scan finding, fixed in passing: this was an
+    // existsSync-then-readFileSync TOCTOU (D-0012's own named
+    // anti-pattern) — read first, treat ENOENT as "not found" inside the
+    // same catch that already handles a parse error, rather than a
+    // separate pre-check with a window between it and the read.
+    let raw;
+    try { raw = fs.readFileSync(policyPath, 'utf8'); }
+    catch { return { passed: false, reason: 'sca-policy.yml not found' }; }
     try {
-      const policy = yaml.load(fs.readFileSync(policyPath, 'utf8'));
+      const policy = yaml.load(raw);
       if (type === 'accept-risk' && Array.isArray(policy['accept-risk']) && policy['accept-risk'].length) {
         return { passed: true, reason: `${policy['accept-risk'].length} accept-risk entries` };
       }
@@ -152,17 +300,34 @@ export function verifyPolicy(policy, ctx) {
       ...(ctx.supplyChain || []).map(sc => ({ ...sc, family: sc.family || 'vulnerable-dep' })),
     ],
   };
+  const now = Date.now();
   const results = [];
   for (const control of policy.controls) {
     if (control.not_applicable) {
+      // FR-506: an EXPIRED structured exception reopens the control as a
+      // gap — nobody re-affirmed the exception, and the underlying checks
+      // were never run, so there is no fresher verdict to report instead.
+      if (_exceptionExpired(control.not_applicable, now)) {
+        results.push({
+          ...control, status: 'gap', checks: [],
+          gapReason: `not-applicable exception expired on ${control.not_applicable.expires_at} — re-affirm or re-evaluate this control`,
+        });
+        continue;
+      }
       results.push({ ...control, status: 'not-applicable', checks: [] });
       continue;
     }
     const checkResults = control.requires.map(c => ({ check: c, result: _runCheck(c, ctx) }));
     const allPassed = checkResults.every(r => r.result.passed);
+    // FR-506: staleness is checked AFTER the real verdict, and can only ever
+    // downgrade a `compliant` reading — a control already reporting
+    // non-compliant findings does not need a second, redundant caveat that
+    // its (already-failing) evidence is also old.
+    const staleness = allPassed ? _staleness(control, now) : { stale: false };
     results.push({
       ...control,
-      status: allPassed ? 'compliant' : 'non-compliant',
+      status: staleness.stale ? 'stale' : (allPassed ? 'compliant' : 'non-compliant'),
+      ...(staleness.stale ? { staleReason: staleness.reason } : {}),
       checks: checkResults,
     });
   }
@@ -171,8 +336,74 @@ export function verifyPolicy(policy, ctx) {
     compliant: results.filter(r => r.status === 'compliant').length,
     nonCompliant: results.filter(r => r.status === 'non-compliant').length,
     notApplicable: results.filter(r => r.status === 'not-applicable').length,
+    // FR-506: reported at the top level, not buried inside individual
+    // controls — a summary that only says "compliant: 40" while 5 of those
+    // are actually stale evidence, or 3 gaps hide behind expired
+    // exceptions, is exactly the false-assurance shape this PRD exists to
+    // close.
+    stale: results.filter(r => r.status === 'stale').length,
+    gap: results.filter(r => r.status === 'gap').length,
+  };
+  // FR-504: bind this conclusion to the inputs that could change it —
+  // repository, commit, scope (framework+version), engine, ruleset,
+  // analyzer health, and mapping version — so "changing any bound input
+  // produces a new evidence digest" is a real, checkable property rather
+  // than an assertion. Deliberately mirrors attestation.js's own
+  // allowlist-then-sorted-JSON-then-sha256 shape rather than inventing a
+  // fourth canonicalisation scheme in this codebase (see D-0026's lesson,
+  // applied here even though this isn't a SIGNED bundle — the same
+  // "unambiguous, reproducible digest of a defined field set" discipline
+  // still applies).
+  const evidenceDigest = computeEvidenceDigest({
+    repository: ctx.repository ?? null,
+    commit: ctx.commit ?? _currentCommit(ctx.scanRoot),
+    scope: `${policy.framework}@${policy.version}`,
+    engine: SCANNER_VERSION,
+    ruleset: ctx.rulesetVersion ?? null,
+    analyzerHealth: ctx.scanHealth?.status ?? null,
+    mappingVersion: policy.version,
+    controls: results.map(r => ({ id: r.id, status: r.status })),
+  });
+  return { framework: policy.framework, version: policy.version, controls: results, summary, evidenceDigest };
+}
+
+function _currentCommit(scanRoot) {
+  if (!scanRoot) return null;
+  try {
+    return execSync('git rev-parse HEAD', { cwd: scanRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch { return null; } // not a git repo, or git unavailable — not an error condition
+}
+
+/**
+ * FR-504: the signed field set — an allowlist, exactly as attestation.js
+ * and evidence-bundle.js canonicalise. A field not named here is not bound,
+ * so a future addition to the evidence report cannot silently join or
+ * leave the digest's scope.
+ */
+export function computeEvidenceDigest(fields) {
+  const bound = {
+    repository: fields.repository ?? null,
+    commit: fields.commit ?? null,
+    scope: fields.scope ?? null,
+    engine: fields.engine ?? null,
+    ruleset: fields.ruleset ?? null,
+    analyzerHealth: fields.analyzerHealth ?? null,
+    mappingVersion: fields.mappingVersion ?? null,
+    controls: [...(fields.controls || [])].sort((a, b) => String(a.id).localeCompare(String(b.id))),
   };
-  return { framework: policy.framework, version: policy.version, controls: results, summary };
+  return crypto.createHash('sha256').update(_canonicalJson(bound), 'utf8').digest('hex');
+}
+
+// Deterministic JSON — keys sorted at every level, arrays order-preserving.
+// Same algorithm as evidence-bundle.js's canonicalJson (duplicated rather
+// than imported for the same reason policy-bundle.js gave: a pure,
+// three-line function, and importing it would couple this module's digest
+// format to a sibling module's internals for no real benefit).
+function _canonicalJson(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value ?? null);
+  if (Array.isArray(value)) return `[${value.map(_canonicalJson).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map(k => `${JSON.stringify(k)}:${_canonicalJson(value[k])}`).join(',')}}`;
 }
 
 /**
@@ -186,20 +417,44 @@ export function emitEvidenceJsonLd(report, scanRoot) {
       'schema': 'https://schema.org/',
     },
     '@type': 'ComplianceEvidence',
+    // FR-508: schema version and status semantics travel WITH the
+    // document — a consumer does not need to know this codebase's own
+    // source to interpret either. policySource names exactly which
+    // mapping file produced this export (the one per-export "source
+    // reference" that is not already implicit in each control's own
+    // `checks[].rule`, which already carries the raw check definition).
+    schemaVersion: EVIDENCE_SCHEMA_VERSION,
+    statusSemantics: STATUS_SEMANTICS,
+    policySource: `${STATE_DIR_NAME}/${POLICY_FILE}`,
     framework: report.framework,
     version: report.version,
     generatedAt: new Date().toISOString(),
-    // CMP-5: this artifact is fed to GRC tooling (Vanta/Drata/SecureFrame) and
-    // auditors largely unread by a human — the same reason
+    // CMP-5 / FR-507: this artifact is fed to GRC tooling (Vanta/Drata/
+    // SecureFrame) and auditors largely unread by a human — the same reason
     // auditor-walkthrough.js's narrative carries this disclaimer verbatim.
     // Without it here, a machine-consumed "ComplianceEvidence" document reads
-    // as an attestation, not a scanner's automated observation.
-    disclaimer: 'This artifact organizes automated scanner evidence into a structured report. It does not certify compliance. A licensed assessor (CPA / auditor / DPO) is responsible for the final attestation.',
+    // as an attestation, not a scanner's automated observation. Sourced from
+    // evidence-grade-wording.js — see that module's header for why this text
+    // names all three assurance tiers explicitly, not just "not certified."
+    disclaimer: EVIDENCE_GRADE_DISCLAIMER,
     provenance: { engineVersion: SCANNER_VERSION },
+    // FR-504: "changing any bound input produces a new evidence digest."
+    // Present only when verifyPolicy actually computed one (every real
+    // caller does; a hand-built report in a test predating this field
+    // simply omits it, rather than this function fabricating one from
+    // partial information).
+    ...(report.evidenceDigest ? { evidenceDigest: report.evidenceDigest } : {}),
     summary: report.summary,
     controls: report.controls.map(c => ({
       '@type': 'Control',
       id: c.id, title: c.title, status: c.status,
+      // FR-506: present only when set — an owner-less, reviewer-less
+      // control (the overwhelming majority, for any policy predating this
+      // field) does not gain fabricated accountability metadata.
+      ...(c.owner ? { owner: c.owner } : {}),
+      ...(c.reviewer ? { reviewer: c.reviewer } : {}),
+      ...(c.staleReason ? { staleReason: c.staleReason } : {}),
+      ...(c.gapReason ? { gapReason: c.gapReason } : {}),
       checks: c.checks.map(ck => ({
         '@type': 'Check',
         rule: ck.check,
@@ -209,10 +464,36 @@ export function emitEvidenceJsonLd(report, scanRoot) {
       narrative_evidence: c.evidence || [],
     })),
   };
+  // FR-505: "sign evidence manifests WHEN SIGNING IS CONFIGURED" — a no-op
+  // when the operator has not already set up a signing key (the common
+  // case), so an ordinary scan's behavior is unchanged unless an operator
+  // opted in. loadSigningKeyIfConfigured only ever READS an existing key,
+  // never generates one — see that function's own header for why emitting
+  // compliance evidence (an automatic, routine side effect of every scan)
+  // must not silently create key material the way an explicit `attest`
+  // command legitimately does.
+  let signed = jsonld;
+  const signingKey = loadSigningKeyIfConfigured();
+  if (signingKey) signed = signComplianceEvidence(jsonld, signingKey.privateKeyPem);
   // Through the seam — see the note in pqc-migration-plan.js. The report is
   // still returned when writing is off; only the artifact is withheld.
-  safeWriteState(statePath(scanRoot, 'compliance-evidence.json'), JSON.stringify(jsonld, null, 2));
-  return jsonld;
+  // FR-705: this artifact is marked confidential in artifact-registry.js.
+  // maybeEncryptForWrite is a safe no-op when encryption isn't configured
+  // (the overwhelming default case) and encrypts the JSON body when it is.
+  // The fail-closed half of FR-705's acceptance criterion lives HERE: when
+  // encryption is required but unavailable, the write is skipped entirely
+  // — never a plaintext fallback — and an operator is told why, rather
+  // than silently persisting unencrypted sensitive compliance evidence.
+  const gated = maybeEncryptForWrite(scanRoot, 'compliance-evidence.json', JSON.stringify(signed, null, 2));
+  if (!gated.ok) {
+    // Always visible, not debug-gated: a required control silently not
+    // being met is exactly the kind of thing FR-705 exists to surface,
+    // not hide behind an opt-in verbosity flag.
+    process.stderr.write(`[agentic-security] compliance-evidence.json NOT written: ${gated.reason}\n`);
+  } else {
+    safeWriteState(statePath(scanRoot, 'compliance-evidence.json'), gated.content);
+  }
+  return signed;
 }
 
 /**
@@ -224,12 +505,21 @@ export function emitEvidenceMarkdown(report, scanRoot) {
   lines.push('');
   lines.push(`Generated by agentic-security (engine ${SCANNER_VERSION}) on ${new Date().toISOString().slice(0,10)}.`);
   lines.push('');
-  lines.push('> This document organizes automated scanner evidence into a structured report. It does not certify compliance. A licensed assessor (CPA / auditor / DPO) is responsible for the final attestation.');
+  lines.push(`> ${EVIDENCE_GRADE_DISCLAIMER_SHORT}`);
   lines.push('');
-  lines.push(`Compliant: **${report.summary.compliant}** / Non-compliant: **${report.summary.nonCompliant}** / Not applicable: **${report.summary.notApplicable}** of ${report.summary.total} controls.`);
+  if (report.evidenceDigest) {
+    lines.push(`Evidence digest (FR-504 — repository, commit, scope, engine, ruleset, analyzer health, and mapping version bound): \`${report.evidenceDigest}\``);
+    lines.push('');
+  }
+  lines.push(`Compliant: **${report.summary.compliant}** / Non-compliant: **${report.summary.nonCompliant}** / Not applicable: **${report.summary.notApplicable}**` +
+    `${report.summary.stale ? ` / Stale: **${report.summary.stale}**` : ''}${report.summary.gap ? ` / Gap: **${report.summary.gap}**` : ''} of ${report.summary.total} controls.`);
   lines.push('');
   for (const c of report.controls) {
     lines.push(`## ${c.id} — ${c.title}  (${c.status})`);
+    if (c.owner) lines.push(`- owner: ${c.owner}`);
+    if (c.reviewer) lines.push(`- reviewer: ${c.reviewer}`);
+    if (c.staleReason) lines.push(`- ⚠ stale: ${c.staleReason}`);
+    if (c.gapReason) lines.push(`- ⚠ gap: ${c.gapReason}`);
     for (const ck of c.checks) {
       const mark = ck.result.passed ? '✓' : '✗';
       lines.push(`- ${mark} \`${JSON.stringify(ck.check)}\` — ${ck.result.reason}`);
@@ -241,8 +531,15 @@ export function emitEvidenceMarkdown(report, scanRoot) {
     }
     lines.push('');
   }
-  safeWriteState(statePath(scanRoot, 'compliance-evidence.md'), lines.join('\n'));
-  return lines.join('\n');
+  // FR-705: same fail-closed gate as emitEvidenceJsonLd above.
+  const rendered = lines.join('\n');
+  const gated = maybeEncryptForWrite(scanRoot, 'compliance-evidence.md', rendered);
+  if (!gated.ok) {
+    process.stderr.write(`[agentic-security] compliance-evidence.md NOT written: ${gated.reason}\n`);
+  } else {
+    safeWriteState(statePath(scanRoot, 'compliance-evidence.md'), gated.content);
+  }
+  return rendered;
 }
 
-export const _internals = { _normalize, _runCheck };
+export const _internals = { _normalize, _runCheck, _staleness, _exceptionExpired, _currentCommit };

package/src/posture/custom-rules.js

@@ -52,6 +52,42 @@ function rulesDir(scanRoot) {
   return statePath(scanRoot, 'rules');
 }
 
+// FR-207: freshness of the operator's own custom rule packs. Reuses
+// compliance-policy.js's exact opt-in idiom (review-interval-days +
+// reviewed-at at the document's top level, sibling to `rules:`;
+// baseline-zero-if-never-reviewed) rather than the file's mtime — a git
+// checkout or CI clone resets mtimes to checkout time, which would make an
+// mtime-based check silently blind in CI, the one place a strict-mode
+// failure matters most. A rule pack that never opts in (no
+// review-interval-days) is never reported stale, matching every other
+// freshness check in this codebase — no claim, no staleness.
+export function customRulesFreshness(scanRoot, { now = Date.now() } = {}) {
+  const dir = rulesDir(scanRoot);
+  const result = { checked: 0, stale: false, staleFiles: [] };
+  if (!fs.existsSync(dir)) return result;
+  let files = [];
+  try {
+    files = fs.readdirSync(dir).filter(f => /\.(ya?ml)$/i.test(f)).map(f => path.join(dir, f));
+  } catch { return result; }
+  for (const fp of files) {
+    let raw;
+    try { raw = yaml.load(fs.readFileSync(fp, 'utf8')); } catch { continue; }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) continue; // bare rule list can't carry document-level metadata
+    const intervalDays = typeof raw['review-interval-days'] === 'number' ? raw['review-interval-days']
+      : (typeof raw.review_interval_days === 'number' ? raw.review_interval_days : null);
+    if (!Number.isFinite(intervalDays)) continue; // no opt-in => never stale
+    result.checked++;
+    const reviewedAt = raw['reviewed-at'] || raw.reviewed_at || null;
+    const reviewedTs = reviewedAt ? Date.parse(reviewedAt) : NaN;
+    const baseline = Number.isFinite(reviewedTs) ? reviewedTs : 0;
+    if (now - baseline > intervalDays * 86400000) {
+      result.stale = true;
+      result.staleFiles.push({ file: path.basename(fp), reviewedAt, intervalDays });
+    }
+  }
+  return result;
+}
+
 export function loadCustomRules(scanRoot) {
   const dir = rulesDir(scanRoot);
   const out = [];

package/src/posture/deterministic.js

@@ -83,8 +83,15 @@ function sortFn(a, b) {
 }
 
 export function makeDeterministic(scan, meta) {
+  // Assurance-hardening PRD FR-104: scan.findings is now frozen by
+  // engine.js after finalization (no producer may append past that point).
+  // Object.prototype.sort() mutates in place and throws a TypeError on a
+  // frozen array — replace with a new sorted array and reassign rather than
+  // sorting the existing one. `scan` itself (the object holding the
+  // reference) is not frozen, only the array was, so this reassignment is
+  // legal and produces byte-identical output to the old in-place sort.
   for (const k of ['findings', 'secrets', 'logicVulns', 'supplyChain']) {
-    if (Array.isArray(scan[k])) scan[k].sort(sortFn);
+    if (Array.isArray(scan[k])) scan[k] = [...scan[k]].sort(sortFn);
   }
   if (meta) {
     meta.scanId = 'deterministic';