@clear-capabilities/agentic-security-scanner 0.161.0 → 0.162.0

package/src/posture/assurance/identity.js

@@ -0,0 +1,62 @@
+// Deterministic identities for the assurance evidence contracts (CORE-002).
+//
+// Reuses, does not duplicate:
+//   - canonicalJson (posture/evidence-bundle.js): sorted keys at every depth, so
+//     two records that differ only in key order serialize to the same bytes.
+//   - computeStableId (posture/stable-id.js): the refactor-stable finding id.
+//     A hypothesis id is that same id; this module never invents a second way to
+//     identify a finding.
+//
+// An identity is a hash over an ALLOWLIST of semantic fields, never over the
+// whole record. That is what keeps clocks, nonces and migration bookkeeping out
+// of an id: a field that is not named in the allowlist cannot reach the hash,
+// however it is added later. The lineage package (scanner/src/lineage) has its
+// own id namespace for graph entities; vulnerability evidence ids use distinct
+// prefixes (vrec/obind/capd/rlab/rev) so the two can never be confused, and this
+// module imports nothing from lineage.
+
+import * as crypto from 'node:crypto';
+import { canonicalJson } from '../evidence-bundle.js';
+import { computeStableId } from '../stable-id.js';
+
+export const ID_HEX_LEN = 16;
+
+export const ID_PREFIXES = Object.freeze({
+  verification: 'vrec',
+  observationBinding: 'obind',
+  capabilityDecision: 'capd',
+  routingLabel: 'rlab',
+  releaseEvidence: 'rev',
+});
+
+/** Canonical bytes of a value: key-order independent, no clock, no randomness. */
+export function canonicalize(value) {
+  return canonicalJson(value);
+}
+
+/** `sha256:<64 hex>` digest of the canonical form of a value. */
+export function digestOf(value) {
+  return `sha256:${crypto.createHash('sha256').update(canonicalJson(value)).digest('hex')}`;
+}
+
+export function digestOfBytes(bytes) {
+  return `sha256:${crypto.createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+/**
+ * Prefixed id over an allowlisted projection of a record.
+ * `fields` is the allowlist; a missing field projects to null so an absent field
+ * and an explicit null produce the same id (canonicalJson already treats them so).
+ */
+export function semanticId(prefix, record, fields) {
+  const material = {};
+  for (const f of fields) material[f] = record?.[f] === undefined ? null : record[f];
+  const hex = crypto.createHash('sha256').update(canonicalJson({ kind: prefix, material })).digest('hex');
+  return `${prefix}:${hex.slice(0, ID_HEX_LEN)}`;
+}
+
+/** The hypothesis id of a finding: its refactor-stable id, reused unchanged. */
+export function hypothesisIdFromFinding(finding) {
+  if (!finding || typeof finding !== 'object') return null;
+  return finding.stableId || computeStableId(finding);
+}

package/src/posture/assurance/migrations.js

@@ -0,0 +1,259 @@
+// Explicit version-1 migration adapters (CORE-002).
+//
+// Two directions, both conservative:
+//   - FROM legacy shapes the repository already produces (a proof tier, a
+//     boolean "verified", an egress decision, a legacy attestation) INTO version-1
+//     records.
+//   - FROM a version-1 record INTO a legacy view for consumers that still expect a
+//     status string or a boolean.
+//
+// The rule that governs every mapping: evidence can be lost in translation but
+// never invented. Unknown, skipped, unconfirmed, failed-to-run and incomplete
+// inputs land on the matching non-positive state. A legacy "true" with no oracle
+// evidence is `inconclusive`, never `confirmed`; a legacy "proof-failed" is
+// `inconclusive`, never `refuted` (the old tier's own comment says absence of
+// proof is not proof of absence). The only path to `confirmed` from a legacy
+// shape is an explicit `trustedRunner` assertion by the caller, which supplies
+// the trusted-runtime-proof evidence the new contract requires.
+//
+// What the adapter cannot recover is recorded in `migration` rather than
+// dropped: the legacy value and the shape it came from stay on the record.
+
+import {
+  SCHEMA_VERSION, isPlainObject, isDigest,
+} from './schema-kit.js';
+import {
+  VERIFICATION_SCHEMA, VERIFICATION_OUTCOMES, buildVerificationRecord, validateVerificationRecord,
+} from './verification-record.js';
+import {
+  OBSERVATION_BINDING_SCHEMA, CAPABILITY_DECISION_SCHEMA, ROUTING_LABEL_SCHEMA, RELEASE_EVIDENCE_SCHEMA,
+  observationBindingId, capabilityDecisionId, routingLabelId, releaseEvidenceId, deriveReleaseComplete,
+  validateObservationBinding, validateCapabilityDecision, validateRoutingLabel, validateReleaseEvidence,
+} from './contracts.js';
+import { digestOf } from './identity.js';
+
+const SCHEMAS = Object.freeze({
+  verification: [VERIFICATION_SCHEMA, validateVerificationRecord],
+  observationBinding: [OBSERVATION_BINDING_SCHEMA, validateObservationBinding],
+  capabilityDecision: [CAPABILITY_DECISION_SCHEMA, validateCapabilityDecision],
+  routingLabel: [ROUTING_LABEL_SCHEMA, validateRoutingLabel],
+  releaseEvidence: [RELEASE_EVIDENCE_SCHEMA, validateReleaseEvidence],
+});
+
+function fail(code, message) { return { ok: false, record: null, errors: [{ code, path: '', message }] }; }
+
+/**
+ * Entry point. A record carrying a `schema` marker is a current-format record: its
+ * major version must be supported, and it is validated, never rewritten. A record
+ * without one is treated as legacy and routed to the matching adapter.
+ *
+ * @param {'verification'|'observationBinding'|'capabilityDecision'|'routingLabel'|'releaseEvidence'} kind
+ * @param {object} input
+ * @param {object} [ctx] adapter context for legacy input (see each adapter)
+ */
+export function migrateRecord(kind, input, ctx = {}) {
+  const entry = SCHEMAS[kind];
+  if (!entry) return fail('UNKNOWN_ENUM', `unknown record kind '${kind}'`);
+  if (!isPlainObject(input)) return fail('NOT_AN_OBJECT', 'input must be an object');
+  const [schemaName, validate] = entry;
+  if (input.schema !== undefined) {
+    const v = validate(input);
+    return { ok: v.ok, record: v.ok ? input : null, errors: v.errors };
+  }
+  const adapter = ADAPTERS[kind];
+  const out = adapter(input, ctx);
+  if (!out.ok) return out;
+  const v = validate(out.record);
+  return v.ok ? out : { ok: false, record: null, errors: v.errors };
+}
+
+// ---------------------------------------------------------------- verification
+
+
+/**
+ * Map a legacy status to a version-1 outcome. Returns `{ outcome, reason }`.
+ * Understands: the execution-proof evidence object ({tier, ran, witnessStatus,
+ * timedOut, reason}), a boolean `verified`, and a status string.
+ */
+export function legacyVerificationOutcome(legacy, { trustedRunner = false } = {}) {
+  const pe = isPlainObject(legacy.proofEvidence) ? legacy.proofEvidence : (legacy.tier !== undefined ? legacy : null);
+  if (pe) {
+    const ran = pe.ran === true;
+    if (!ran) {
+      const reason = pe.reason || 'the proof-of-concept did not execute';
+      if (/unsupported|no confinement primitive/i.test(String(pe.reason || ''))) return { outcome: 'unsupported', reason };
+      if (pe.witnessStatus === 'error' || /could not start/i.test(String(pe.reason || ''))) return { outcome: 'error', reason };
+      if (pe.timedOut) return { outcome: 'inconclusive', reason: pe.reason || 'the proof-of-concept timed out' };
+      return { outcome: 'not-run', reason };
+    }
+    if (pe.tier === 'execution-proven') {
+      return trustedRunner
+        ? { outcome: 'confirmed', reason: pe.observed || 'legacy execution proof, asserted by a trusted runner' }
+        : { outcome: 'inconclusive', reason: 'legacy execution proof predates trusted-runtime-proof classification; re-verify under the trusted verifier to confirm' };
+    }
+    if (pe.tier === 'proof-failed') return { outcome: 'inconclusive', reason: 'the proof-of-concept ran but did not demonstrate the effect; absence of proof is not refutation' };
+    return { outcome: 'inconclusive', reason: `legacy proof tier '${pe.tier}' carries no execution evidence` };
+  }
+  const raw = legacy.status !== undefined ? legacy.status : legacy.verified;
+  if (raw === true) return { outcome: 'inconclusive', reason: 'legacy boolean true carries no oracle evidence' };
+  if (raw === false) return { outcome: 'inconclusive', reason: 'legacy boolean false is not a refutation: no applicable oracle or preconditions are recorded' };
+  if (raw === null || raw === undefined) return { outcome: 'not-run', reason: 'legacy record has no verification status' };
+  if (typeof raw === 'string') {
+    const s = raw.toLowerCase();
+    if (VERIFICATION_OUTCOMES.includes(s)) {
+      if (s === 'confirmed' || s === 'refuted') {
+        return { outcome: 'inconclusive', reason: `legacy status '${s}' carries no evidence references, so it is not carried forward as '${s}'` };
+      }
+      return { outcome: s, reason: `legacy status '${s}'` };
+    }
+    if (['skipped', 'pending', 'queued', 'disabled'].includes(s)) return { outcome: 'not-run', reason: `legacy status '${s}'` };
+    if (['timeout', 'timed-out', 'unconfirmed', 'partial', 'incomplete', 'unknown'].includes(s)) return { outcome: 'inconclusive', reason: `legacy status '${s}'` };
+    if (['failed', 'failure', 'errored', 'crash'].includes(s)) return { outcome: 'error', reason: `legacy status '${s}'` };
+  }
+  return { outcome: 'inconclusive', reason: `unrecognized legacy status ${JSON.stringify(raw)}` };
+}
+
+/**
+ * Legacy verification result -> version-1 verification record.
+ * ctx: { hypothesisId, commit, detectorOrigin, scope, trustedRunner?, oracle? }.
+ * Missing context is not invented: without a hypothesisId the adapter refuses.
+ */
+export function fromLegacyVerification(legacy, ctx = {}) {
+  if (!ctx.hypothesisId) return fail('MISSING_FIELD', 'a legacy verification needs a hypothesisId from the caller; it is not guessed');
+  const { outcome, reason } = legacyVerificationOutcome(legacy, { trustedRunner: ctx.trustedRunner === true });
+  const evidence = [];
+  if (outcome === 'confirmed') {
+    evidence.push({
+      id: 'legacy-runtime-proof', kind: 'trusted-runtime-proof', producer: 'trusted-runner',
+      digest: digestOf(legacy.proofEvidence || legacy), source: 'legacy-execution-proof',
+    });
+  }
+  const pe = isPlainObject(legacy.proofEvidence) ? legacy.proofEvidence : legacy;
+  const rec = buildVerificationRecord({
+    hypothesisId: ctx.hypothesisId,
+    commit: ctx.commit ?? null,
+    detectorOrigin: ctx.detectorOrigin || { detector: 'legacy-unknown' },
+    oracle: outcome === 'confirmed' ? (ctx.oracle || { id: 'legacy-execution-proof', kind: 'runtime-replay' }) : (ctx.oracle ?? null),
+    attempt: ['not-run', 'unsupported'].includes(outcome) ? 0 : 1,
+    outcome, reason,
+    evidence,
+    scope: ctx.scope || { description: 'unspecified legacy scope', platform: pe.backend ? String(pe.backend) : 'unknown' },
+    migration: { from: 'legacy-verification', legacyValue: JSON.stringify(legacy.status ?? legacy.verified ?? pe.tier ?? null) },
+  });
+  return { ok: true, record: rec, errors: [] };
+}
+
+/**
+ * Version-1 record -> view for a legacy consumer. `verified` is true ONLY for a
+ * confirmed record and false ONLY for a refuted one; every other state is null, so
+ * a consumer that tests `=== true` cannot be told a skipped check passed, and one
+ * that tests `=== false` cannot be told an unrun check failed.
+ */
+export function toLegacyVerificationView(record) {
+  return {
+    status: record.outcome,
+    verified: record.outcome === 'confirmed' ? true : record.outcome === 'refuted' ? false : null,
+    confirmationLevel: record.confirmationLevel,
+    repairStatus: record.repair?.status ?? 'none',
+    reason: record.reason,
+  };
+}
+
+// ---------------------------------------------------------------- other kinds
+
+function fromEgressDecision(legacy) {
+  // posture/egress evaluateEgress(): { allowed, decision, reason, provider, policySource, purpose }.
+  // It is an in-process policy check before a call: it explains a decision and is
+  // not OS-level isolation, so it can never be recorded as enforced.
+  const decision = legacy.decision === 'allow' ? 'allow' : legacy.decision === 'deny' ? 'deny' : 'unsupported';
+  const rec = {
+    schema: CAPABILITY_DECISION_SCHEMA, schemaVersion: SCHEMA_VERSION,
+    taskId: String(legacy.purpose || 'unknown'),
+    capability: 'network',
+    subject: String(legacy.provider || 'unknown'),
+    decision,
+    mediation: 'in-process-policy',
+    enforced: false,
+    backend: null,
+    reason: String(legacy.reason || (decision === 'allow' ? 'egress policy allowed the call' : 'no reason recorded')),
+    migration: { from: 'egress-decision', legacyValue: JSON.stringify(legacy.decision ?? null) },
+  };
+  rec.id = capabilityDecisionId(rec);
+  return { ok: true, record: rec, errors: [] };
+}
+
+function fromLegacyRoutingLabel(legacy) {
+  if (!legacy.taskId || !legacy.model) return fail('MISSING_FIELD', 'a legacy routing label needs taskId and model');
+  const decided = legacy.correct === true || legacy.correct === false;
+  const source = ['adjudication', 'trusted-execution'].includes(legacy.labelSource) ? legacy.labelSource : 'none';
+  // A boolean without a named source is not an adjudicated label.
+  const outcome = decided && source !== 'none' ? (legacy.correct ? 'correct' : 'incorrect') : (legacy.delayed ? 'delayed' : 'unknown');
+  const rec = {
+    schema: ROUTING_LABEL_SCHEMA, schemaVersion: SCHEMA_VERSION,
+    taskId: String(legacy.taskId),
+    taskKind: legacy.taskKind || 'triage',
+    stratum: String(legacy.stratum || 'unstratified'),
+    model: String(legacy.model),
+    outcome,
+    labelSource: outcome === 'correct' || outcome === 'incorrect' ? source : 'none',
+    migration: { from: 'legacy-routing-label', legacyValue: JSON.stringify(legacy.correct ?? null) },
+  };
+  rec.id = routingLabelId(rec);
+  return { ok: true, record: rec, errors: [] };
+}
+
+function fromLegacyRelease(legacy) {
+  const claims = (Array.isArray(legacy.checks) ? legacy.checks : []).map((c, i) => {
+    const refs = (Array.isArray(c.evidence) ? c.evidence : (c.evidence ? [c.evidence] : [])).filter(r => typeof r === 'string' && (r.startsWith('vrec:') || isDigest(r)));
+    const s = String(c.status || '').toLowerCase();
+    let status; let gaps = [];
+    if (['pass', 'passed', 'ok'].includes(s) && refs.length) status = 'verified';
+    else if (['pass', 'passed', 'ok'].includes(s)) { status = 'unverified'; gaps = ['legacy check reported a pass but cites no evidence']; }
+    else if (['fail', 'failed'].includes(s)) { status = 'failed'; gaps = [`legacy check '${c.id ?? i}' failed`]; }
+    else if (['skip', 'skipped'].includes(s)) { status = 'skipped'; gaps = [`legacy check '${c.id ?? i}' was skipped`]; }
+    else { status = 'incomplete'; gaps = [`legacy check '${c.id ?? i}' has status ${JSON.stringify(c.status ?? null)}`]; }
+    return { id: String(c.id ?? `check-${i}`), statement: String(c.statement || c.id || `check ${i}`), status, evidenceRefs: refs, gaps };
+  });
+  const rec = {
+    schema: RELEASE_EVIDENCE_SCHEMA, schemaVersion: SCHEMA_VERSION,
+    subject: { commit: legacy.commit ?? null, bundleDigest: isDigest(legacy.bundleDigest) ? legacy.bundleDigest : null },
+    claims,
+    complete: false,
+    migration: { from: 'legacy-attestation', legacyValue: JSON.stringify(legacy.verified ?? null) },
+  };
+  rec.complete = deriveReleaseComplete(rec);
+  rec.id = releaseEvidenceId(rec);
+  return { ok: true, record: rec, errors: [] };
+}
+
+function fromLineageObservation(legacy, ctx) {
+  // A lineage RuntimeObservation (id, adapter, windowStart/End, matched*Ids). The
+  // observation stays in lineage; only its id is referenced.
+  if (!ctx.hypothesisId) return fail('MISSING_FIELD', 'an observation binding needs a hypothesisId from the caller');
+  if (!legacy.id) return fail('MISSING_FIELD', 'legacy observation has no id');
+  const matched = ['matchedNodeIds', 'matchedEdgeIds', 'matchedFlowIds'].some(k => Array.isArray(legacy[k]) && legacy[k].length > 0);
+  const rec = {
+    schema: OBSERVATION_BINDING_SCHEMA, schemaVersion: SCHEMA_VERSION,
+    hypothesisId: ctx.hypothesisId,
+    observationRef: { observationId: String(legacy.id), ...(legacy.adapter ? { adapter: String(legacy.adapter) } : {}) },
+    provenance: 'runtime-observation',
+    // Matching an observation never shows the sample was complete.
+    pathState: matched ? 'runtime-supported' : 'unresolved',
+    completeness: 'unknown',
+    window: legacy.windowStart && legacy.windowEnd ? { start: String(legacy.windowStart), end: String(legacy.windowEnd) } : undefined,
+    migration: { from: 'lineage-runtime-observation', legacyValue: JSON.stringify(legacy.matchMethod ?? null) },
+  };
+  if (rec.window === undefined) delete rec.window;
+  rec.id = observationBindingId(rec);
+  return { ok: true, record: rec, errors: [] };
+}
+
+const ADAPTERS = Object.freeze({
+  verification: (legacy, ctx) => fromLegacyVerification(legacy, ctx),
+  observationBinding: fromLineageObservation,
+  capabilityDecision: (legacy) => fromEgressDecision(legacy),
+  routingLabel: (legacy) => fromLegacyRoutingLabel(legacy),
+  releaseEvidence: (legacy) => fromLegacyRelease(legacy),
+});
+
+export { fromEgressDecision, fromLegacyRoutingLabel, fromLegacyRelease, fromLineageObservation };

package/src/posture/assurance/schema-kit.js

@@ -0,0 +1,111 @@
+// Small validation primitives shared by the assurance evidence contracts
+// (CORE-002). Pure: no fs, no clock, no network. Every validator returns
+// `{ ok, errors }` where each error is `{ code, path, message }`; nothing throws
+// on bad input, because a validator that throws on hostile input is a denial of
+// service on whatever called it.
+
+export const ERROR_CODES = Object.freeze([
+  'NOT_AN_OBJECT', 'SCHEMA_MISMATCH', 'UNSUPPORTED_MAJOR', 'BAD_VERSION', 'MISSING_FIELD', 'UNKNOWN_FIELD',
+  'BAD_TYPE', 'UNKNOWN_ENUM', 'BAD_DIGEST', 'BAD_ID', 'ID_MISMATCH', 'DUPLICATE_ID', 'DANGLING_REF', 'RULE_VIOLATION',
+]);
+
+export const SUPPORTED_MAJOR = 1;
+export const SCHEMA_VERSION = '1.0.0';
+
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const COMMIT = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
+export function makeCtx() {
+  const errors = [];
+  return {
+    errors,
+    err(code, path, message) { errors.push({ code, path, message }); },
+  };
+}
+
+export function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+export function isDigest(v) { return typeof v === 'string' && DIGEST.test(v); }
+export function isCommit(v) { return typeof v === 'string' && COMMIT.test(v); }
+export function isNonEmptyString(v) { return typeof v === 'string' && v.trim().length > 0; }
+
+/** Header check: `schema` must match and the major version must be supported. */
+export function checkHeader(ctx, rec, schemaName) {
+  if (rec.schema !== schemaName) {
+    ctx.err('SCHEMA_MISMATCH', 'schema', `expected schema '${schemaName}', got ${JSON.stringify(rec.schema)}`);
+    return false;
+  }
+  const m = typeof rec.schemaVersion === 'string' ? SEMVER.exec(rec.schemaVersion) : null;
+  if (!m) {
+    ctx.err('BAD_VERSION', 'schemaVersion', `schemaVersion must be a semantic version, got ${JSON.stringify(rec.schemaVersion)}`);
+    return false;
+  }
+  if (Number(m[1]) !== SUPPORTED_MAJOR) {
+    ctx.err('UNSUPPORTED_MAJOR', 'schemaVersion', `major version ${m[1]} is not supported (supported: ${SUPPORTED_MAJOR})`);
+    return false;
+  }
+  return true;
+}
+
+/** Closed world: any field outside `allowed` is rejected, never silently carried. */
+export function checkFields(ctx, rec, allowed, required) {
+  for (const k of Object.keys(rec)) {
+    if (!allowed.includes(k)) ctx.err('UNKNOWN_FIELD', k, `field '${k}' is not part of this schema`);
+  }
+  for (const k of required) {
+    if (rec[k] === undefined) ctx.err('MISSING_FIELD', k, `required field '${k}' is missing`);
+  }
+  // `createdAt` is informational and never enters an id; it must still be a string.
+  if (rec.createdAt !== undefined && typeof rec.createdAt !== 'string') ctx.err('BAD_TYPE', 'createdAt', 'must be a string');
+}
+
+export function checkEnum(ctx, path, value, allowed) {
+  if (typeof value !== 'string' || !allowed.includes(value)) {
+    ctx.err('UNKNOWN_ENUM', path, `${JSON.stringify(value)} is not one of: ${allowed.join(', ')}`);
+    return false;
+  }
+  return true;
+}
+
+export function checkDigest(ctx, path, value, { nullable = false } = {}) {
+  if (value === null && nullable) return true;
+  if (!isDigest(value)) { ctx.err('BAD_DIGEST', path, `must be 'sha256:' followed by 64 lowercase hex characters`); return false; }
+  return true;
+}
+
+export function checkCommit(ctx, path, value, { nullable = true } = {}) {
+  if (value === null && nullable) return true;
+  if (!isCommit(value)) { ctx.err('BAD_TYPE', path, 'must be a 40 or 64 character lowercase hex commit id'); return false; }
+  return true;
+}
+
+export function checkString(ctx, path, value) {
+  if (!isNonEmptyString(value)) { ctx.err('BAD_TYPE', path, 'must be a non-empty string'); return false; }
+  return true;
+}
+
+export function checkId(ctx, rec, expectedId) {
+  const prefix = expectedId.split(':')[0];
+  if (typeof rec.id !== 'string' || !rec.id.startsWith(`${prefix}:`)) {
+    ctx.err('BAD_ID', 'id', `id must start with '${prefix}:'`);
+  } else if (rec.id !== expectedId) {
+    ctx.err('ID_MISMATCH', 'id', `id does not match the record's semantic content (expected ${expectedId})`);
+  }
+}
+
+export function result(ctx) {
+  return { ok: ctx.errors.length === 0, errors: ctx.errors };
+}
+
+/** Reject non-object input with one typed error instead of throwing downstream. */
+export function guardObject(rec) {
+  const ctx = makeCtx();
+  if (!isPlainObject(rec)) {
+    ctx.err('NOT_AN_OBJECT', '', 'record must be a plain object');
+    return { ctx, ok: false };
+  }
+  return { ctx, ok: true };
+}