@clear-capabilities/agentic-security-scanner 0.183.1 → 0.185.0

package/src/lineage/witness-selection.js

@@ -0,0 +1,95 @@
+// witness-selection.js: which paths to DISPLAY, and what may be claimed from
+// them (DAG-07 R07.8).
+//
+// Two jobs that must never be confused:
+//   1. rankWitnesses: choose a small, diverse sample of the enumerated paths
+//      to show. Diversity is over source, sink, data class, trust boundary,
+//      control state and ambiguity. This is presentation only.
+//   2. assessAllPathsProtected: decide whether "every path is protected" may
+//      be said. It looks at EVERY enumerated path, displayed or not, and it
+//      refuses outright when the enumeration itself was truncated, so a
+//      sample that happens to contain only protected paths can never produce
+//      the claim. A hidden unprotected path refutes the claim.
+//
+// Pure: no store access, no engine imports.
+
+export const DIVERSITY_DIMENSIONS = Object.freeze(['source', 'sink', 'dataClass', 'trustBoundary', 'controlState', 'ambiguity']);
+
+/**
+ * Attribute values for one path. `attrsOf(path)` may supply `dataClass` and
+ * `controlState` ('protected' | 'unprotected' | 'unknown'); source, sink,
+ * boundary and ambiguity come from the path itself.
+ */
+export function witnessAttributes(path, attrsOf) {
+  const extra = typeof attrsOf === 'function' ? (attrsOf(path) ?? {}) : {};
+  return {
+    source: path.sourceNodeId ?? null,
+    sink: path.sinkNodeId ?? null,
+    dataClass: extra.dataClass ?? path.dataElementId ?? 'unknown',
+    trustBoundary: (path.crossScopeCount ?? 0) > 0 ? 'crosses' : 'local',
+    controlState: extra.controlState ?? 'unknown',
+    ambiguity: (path.ambiguousHopCount ?? 0) > 0 ? 'ambiguous' : 'correlated',
+  };
+}
+
+/**
+ * Greedy diversity ranking. Each step picks the path adding the most
+ * not-yet-shown values across the six dimensions; ties go to the path id so
+ * the order is deterministic. Never drops or alters a path: `ranked` is a
+ * permutation of the input and `displayed` is its prefix.
+ */
+export function rankWitnesses(paths, { limit = 10, attrsOf } = {}) {
+  const list = Array.isArray(paths) ? paths : [];
+  const cap = Number.isInteger(limit) && limit >= 0 ? limit : 10;
+  const seen = Object.fromEntries(DIVERSITY_DIMENSIONS.map((d) => [d, new Set()]));
+  const pool = list.map((p) => ({ p, a: witnessAttributes(p, attrsOf) }));
+  const ranked = [];
+  while (pool.length) {
+    let best = -1;
+    let bestGain = -1;
+    for (let i = 0; i < pool.length; i++) {
+      let gain = 0;
+      for (const d of DIVERSITY_DIMENSIONS) if (!seen[d].has(pool[i].a[d])) gain += 1;
+      if (gain > bestGain || (gain === bestGain && String(pool[i].p.id) < String(pool[best].p.id))) { best = i; bestGain = gain; }
+    }
+    const [chosen] = pool.splice(best, 1);
+    for (const d of DIVERSITY_DIMENSIONS) seen[d].add(chosen.a[d]);
+    ranked.push(chosen.p);
+  }
+  const displayed = ranked.slice(0, cap);
+  const coverage = Object.fromEntries(DIVERSITY_DIMENSIONS.map((d) => [d, new Set(displayed.map((p) => witnessAttributes(p, attrsOf)[d])).size]));
+  return { ranked, displayed, hiddenCount: ranked.length - displayed.length, coverage };
+}
+
+/**
+ * May "all paths are protected" be asserted?
+ *
+ * `enumerated` is every path the query produced (before any display cap);
+ * `result` is the reconstructPaths result they came from. The claim is
+ * allowed only when the query was exhaustive (status complete, nothing
+ * dropped or truncated, at least one path) and every path is protected.
+ * `holds` is false when ANY enumerated path, hidden or not, is unprotected
+ * (a refutation needs no exhaustiveness), and null when it is merely not
+ * established.
+ */
+export function assessAllPathsProtected({ result, enumerated, attrsOf }) {
+  const paths = Array.isArray(enumerated) ? enumerated : [];
+  const stateOf = (p) => (typeof attrsOf === 'function' ? (attrsOf(p)?.controlState ?? 'unknown') : 'unknown');
+  const unprotected = paths.filter((p) => stateOf(p) === 'unprotected');
+  const unknown = paths.filter((p) => stateOf(p) !== 'protected' && stateOf(p) !== 'unprotected');
+  const reasons = [];
+  if (!result || result.status !== 'complete') reasons.push('query-not-complete');
+  if (result && (result.truncated || result.droppedPathCount > 0 || result.analysisTruncated)) reasons.push('truncated-sample');
+  if (result && result.resumed) reasons.push('resumed-page');
+  if (paths.length === 0) reasons.push('no-paths');
+  if (unknown.length) reasons.push('control-state-unknown');
+  if (unprotected.length) {
+    return {
+      claim: 'all-paths-protected', allowed: false, holds: false,
+      reasons: ['refuted-by-unprotected-path'],
+      refutingPathId: unprotected[0].id ?? null, unprotectedCount: unprotected.length,
+    };
+  }
+  const allowed = reasons.length === 0;
+  return { claim: 'all-paths-protected', allowed, holds: allowed ? true : null, reasons, unprotectedCount: 0 };
+}

package/src/pipeline/scan-health.js

@@ -84,6 +84,19 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
   if (lineageStatus?.failure) {
     conditions.push(`lineage graph build threw and was skipped: ${lineageStatus.failure}`);
   }
+  if (Array.isArray(lineageStatus?.incomplete) && lineageStatus.incomplete.length) {
+    conditions.push(`lineage field analysis stopped early in ${lineageStatus.incomplete.length} function(s) (iteration budget); a missing flow from those functions is not evidence of safety`);
+  }
+  if (lineageStatus?.completion && lineageStatus.completion.status !== 'complete') {
+    // DAG-07 R07.2: construction limits, cancellation, seeding limits and a
+    // zero-flow result from incomplete analysis all land here, in terms of
+    // the shared envelope, so none of them can be silent.
+    const c = lineageStatus.completion;
+    conditions.push(`lineage analysis is ${c.status} (${(c.reasons || []).join(', ') || 'no reason recorded'}); absence of a flow is not evidence that none exists`);
+  }
+  if (Array.isArray(lineageStatus?.degraded) && lineageStatus.degraded.length) {
+    conditions.push(`lineage analysis used a coarser summary for ${lineageStatus.degraded.length} call context(s) (context cap or unconverged recursion)`);
+  }
   // FR-203: a detector that threw on at least one file (captured via
   // FR-201's runDetector isolation) is a real analysis gap distinct from
   // an ANNOTATOR error above — annotators run post-detection over the
@@ -136,6 +149,8 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
           reason: deepStatus.reason ?? null,
           failure: deepStatus.failure ?? null,
           ...(Array.isArray(deepStatus.incomplete) && deepStatus.incomplete.length ? { incomplete: deepStatus.incomplete } : {}),
+          // DAG-05 R05.7: present only when the cross-scan cache was requested; says what was reused, what was recomputed, and why a run was cold.
+          ...(deepStatus.incremental ? { incremental: deepStatus.incremental } : {}),
         }
       : null,
     lineageAnalysis: lineageStatus
@@ -144,6 +159,9 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
           enabled: !!lineageStatus.enabled,
           reason: lineageStatus.reason ?? null,
           failure: lineageStatus.failure ?? null,
+          ...(lineageStatus.completion ? { completion: lineageStatus.completion } : {}),
+          ...(Array.isArray(lineageStatus.incomplete) && lineageStatus.incomplete.length ? { incomplete: lineageStatus.incomplete } : {}),
+          ...(Array.isArray(lineageStatus.degraded) && lineageStatus.degraded.length ? { degraded: lineageStatus.degraded } : {}),
         }
       : null,
     annotatorErrorCount: safeAnnotatorErrors.length,
@@ -172,6 +190,7 @@ const FRESHNESS_CONDITION_BUILDERS = {
   epss: (f) => (f?.stale === true) ? `EPSS exploit-probability data is stale (${f.ageDays} day(s) old)` : null,
   calibration: (f) => (f?.stale === true) ? `calibration data is stale (${f.ageDays} day(s) old${f.generatedAt ? `, last generated ${f.generatedAt}` : ''})` : null,
   customRules: (f) => (f?.stale === true) ? `${f.staleFiles.length} custom rule file(s) exceed their configured review interval` : null,
+  advisories: (f) => (Number(f?.unanswered) > 0) ? `${f.unanswered} of ${f.componentsChecked} dependencies were not checked against advisory data (${f.source}) — the absence of a vulnerable dependency finding is not evidence that the dependency is safe` : null,
   compliance: (f) => (Number(f?.stale) > 0) ? `${f.stale} compliance control(s) have stale evidence` : null,
 };
 

package/src/posture/CLAUDE.md

@@ -1019,6 +1019,19 @@ Measures a deterministic baseline and model arms, and routes tasks from the meas
 * **The router is the policy layer, `routing/decide.js` is the calibrated one.** `policy-router.js` selects from measured scoreboard entries (quality, median cost, median latency, run count) under four policies; `decide.js` keeps quality LOWER bounds on held-out outcomes per stratum. They do not call each other. The router refuses to guess: too few runs, unknown cost under a cost policy, an egress denial or a dataset mismatch excludes a model with the reason, and `threat-model` is blocked because it has no evaluation task.
 * **Digest-checked state.** Runs and the scoreboard live under `.agentic-security/eval-lab/` (registered in `artifact-registry.js`); a record that no longer matches its digest is reported and never used for routing.
 
+## Replayable path witnesses and scoped runtime support: `witness-bundle.js`, `witness-runtime.js` (DAG-10)
+
+A sibling of `evidence-bundle.js` for one source-to-sink PATH rather than one finding. Same Ed25519 key, same self-issued trust basis (`buildLocalIssuance`, newly exported, is the only edit to `evidence-bundle.js`). Pure of the scan path: nothing here is wired into `engine.js`; the one production caller is `verify-attestation` in `bin/agentic-security.js`. Suite: `test/witness-bundle.test.js` (in `test:posture`).
+
+- **Artifacts, not trust.** `exportProvenanceArtifact({hops, incomplete})` is the provenance store export: the normalized 14-field hop stream plus the truncation marks that never travel as hops (`analysisCompletion.incomplete`). `buildWitnessBundle` records graph digest (`computeGraphDigest`), provenance digest, source blob sha256s, the analysis configuration digest, transfer-model fingerprints, ordered edges (full derivation fields plus call/return binding), sink/source/field/context references and completion records. `replayWitness(bundle, {graph, provenance, sources, config})` is offline and bounded (`WITNESS_BOUNDS`): it rebuilds a `PathStore` from the hop stream and requires every recorded edge to be the edge the store derives, the edges to chain, each call/return binding to match both the store and a carrying hop, the terminal reason and truncation state to re-derive, and every digest to match.
+- **A valid signature proves integrity only.** The bundle carries `proves`/`doesNotProve` inside the signed bytes and the verifier rejects a bundle that drops or edits them. Transfer-model fingerprints are computed by RUNNING the half-edge classifiers on fixed probe hops (a minified bundle and the source tree agree); replay under a different fingerprint fails rather than pretending the old model still holds. Replay does not validate the model.
+- **Four statuses, never merged** (`witness-runtime.js`): `modeledPath`, `feasibility` (the nullable DAG-04 `controlEvidence` slot; `not_assessed` until it exists), `runtimeSupport`, `exploitProof`. `evidence` holds exactly these four keys, each `{status}`; any other key (a score, a confidence) fails replay.
+- **Runtime support rules.** `path_supported` needs ONE causal group covering every path edge with compatible environment, deployment, time window, identity scope, order and unambiguous mappings; edges seen in unrelated traces are `edge_partial`. Low-confidence mappings stay `candidate_only`; `no_observation_in_window` and `not_consulted` are different and neither is evidence of safety; a denied observation is `blocked_attempt` and proves only that attempt. The closed-world `RuntimeObservation` contract has no trace or session field, so causal groups are caller-supplied: from the observation store alone the strongest answer is `edge_partial`.
+- **Proof binding.** An external proof reference must name this bundle's sink node, data element, graph digest and configuration digest; a stale or mismatched one is listed under `exploit.rejected` with reasons and is never re-attached.
+- **Partial stays partial.** Completion fields are required (a missing one is invalid, never "complete"), the bundle is JSON-normalized at build so serialization cannot change it, and replay re-derives the path terminal, the truncation marks and `overall`.
+- **Redaction.** Identities become `idt_` tokens (`lineage/identity-token.js`), trace/session ids become `sref_` references, free text goes through `mcp/redact.js`, unknown input fields are dropped and only counted.
+- **Limits.** Building needs the hop stream, which a scan does not persist; there is no `attest --witness` yet. Source files are bound only when the caller supplies their text (the rest are listed `unboundSourceFiles` and replay warns). The graph-edge to provenance-edge relation is the flow binding (`graphBinding.flowId`), checked for existence, not re-derived. Cross-service replay depends on DAG-08.
+
 ## Gotchas
 
 - The seed `calibration-seed.json` is small (n < 30 for several families). Don't treat it as a held-out set — that's `holdout-eval.js`'s job, against an externally-supplied JSONL.

package/src/posture/evidence-bundle.js

@@ -77,7 +77,7 @@ export function keyFingerprint(publicKeyPem) {
 }
 
 /** Issuance block for a locally generated key. */
-function buildLocalIssuance(publicKeyPem) {
+export function buildLocalIssuance(publicKeyPem) {
   const fp = keyFingerprint(publicKeyPem);
   return {
     issuer: { id: `local-install:${fp.slice(0, 16)}`, kind: 'local-install', keyFingerprint: fp },