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

package/src/dataflow/privacy-inventory.js

@@ -0,0 +1,154 @@
+// Code-derived privacy data inventory + flow graph (assurance-hardening
+// PRD FR-406).
+//
+// Turns the raw signals privacy-taint.js already computes (piiFields,
+// findings, policyExemptions — the latter two now carrying sourceName/
+// sourceLine, added for this requirement) into per-source-flow inventory
+// records, each carrying the PRD's named fields: data class, source,
+// transformations, storage, sink/recipient, evidence locations.
+//
+// "transformations" is honestly disclosed as the literal sentinel
+// NOT_MODELED for every record — this engine has no sanitizer/
+// transformation tracking for privacy flows specifically; that is FR-403's
+// deferred scope (confirmed large this session, needing "an actual
+// dataflow-aware rewrite"). Fabricating a transformation chain this engine
+// cannot see would be exactly the vacuous-satisfaction failure mode
+// FR-405/FR-407 both guard against for their own fields — this module
+// applies the identical discipline here rather than inventing partial
+// credit.
+//
+// STORAGE_SINK_KINDS names the subset of privacy-taint.js's sink
+// categories that represent data AT REST (file writes, object storage) as
+// opposed to data IN TRANSIT (log, response, outbound HTTP, third-party
+// SDK, email) — this is what separates the PRD's "storage" field from its
+// "sink/recipient" field. It is necessarily incomplete: this engine has no
+// sink entries for a database write, a message queue, or most managed
+// storage services, so an empty storage array does NOT mean "no storage
+// exists" — the artifact says so explicitly rather than implying a
+// negative that was never checked.
+
+export const NOT_MODELED = 'not_modeled';
+export const STORAGE_SINK_KINDS = new Set(['fileWrite', 's3Upload']);
+
+function _evidenceLocations(record) {
+  const locs = [];
+  if (record.source) locs.push({ file: record.source.file, line: record.source.line, role: 'source' });
+  for (const s of record.storage) locs.push({ file: s.file, line: s.line, role: 'storage' });
+  for (const r of record.sinkRecipient) locs.push({ file: r.file, line: r.line, role: 'recipient' });
+  return locs;
+}
+
+/**
+ * Build the data inventory: one record per (data class, source variable)
+ * pair actually observed reaching at least one sink, prohibited or
+ * policy-permitted. A source with no observed sink at all (declared but
+ * never flowed anywhere the annotator's sink catalog recognizes) is NOT
+ * included — this is an inventory of REAL, observed flows, not a listing
+ * of every regulated-looking field name.
+ */
+export function buildDataInventory(piiFields, findings, policyExemptions) {
+  // Key: `${file}::${sourceName}::${classes.join(',')}` — the same source
+  // variable can carry more than one class (e.g. name+PII, ssn+PII), and a
+  // record must not merge two variables that happen to share a name across
+  // different files.
+  const byKey = new Map();
+
+  const declByFileName = new Map(); // `${file}::${name}` -> piiField (for declaredType / line fallback)
+  for (const f of piiFields || []) {
+    declByFileName.set(`${f.file}::${f.name}`, f);
+  }
+
+  function recordFor(file, name, classes, sourceLine) {
+    const key = `${file}::${name}::${classes.join(',')}`;
+    let rec = byKey.get(key);
+    if (!rec) {
+      const decl = declByFileName.get(`${file}::${name}`);
+      rec = {
+        dataClass: classes,
+        source: { file, name, line: sourceLine ?? decl?.line ?? null, declaredType: decl?.declaredType || null },
+        transformations: NOT_MODELED,
+        storage: [],
+        sinkRecipient: [],
+      };
+      byKey.set(key, rec);
+    }
+    return rec;
+  }
+
+  for (const f of findings || []) {
+    if (f.family !== 'pii-exposure' || !f.sourceName) continue;
+    const rec = recordFor(f.file, f.sourceName, f.piiClass || [], f.sourceLine);
+    const entry = { sinkKind: f.sinkKind, file: f.file, line: f.line, status: 'prohibited', severity: f.severity };
+    if (STORAGE_SINK_KINDS.has(f.sinkKind)) rec.storage.push(entry);
+    else rec.sinkRecipient.push(entry);
+  }
+  for (const e of policyExemptions || []) {
+    if (!e.name) continue;
+    const rec = recordFor(e.file, e.name, e.classes || [], e.sourceLine);
+    const reasons = (e.rules || []).map(r => r.reason).filter(Boolean);
+    const entry = { sinkKind: e.sinkKind, file: e.file, line: e.line, status: 'policy_permitted', reason: reasons[0] || null };
+    if (STORAGE_SINK_KINDS.has(e.sinkKind)) rec.storage.push(entry);
+    else rec.sinkRecipient.push(entry);
+  }
+
+  const records = [...byKey.values()];
+  for (const rec of records) rec.evidenceLocations = _evidenceLocations(rec);
+  records.sort((a, b) => (a.source.file + a.source.name).localeCompare(b.source.file + b.source.name));
+  return records;
+}
+
+/**
+ * Emit the machine-readable inventory artifact.
+ */
+export function emitDataInventoryArtifact(records) {
+  return JSON.stringify({
+    schemaNote: 'Code-derived privacy data inventory (assurance-hardening PRD FR-406). "transformations" is always "not_modeled" — this engine does not track sanitization/masking/encoding for privacy flows (see FR-403). "storage" is best-effort — only file-write and object-storage sinks are recognized; a database, queue, or managed storage service reached through an unrecognized API will not appear here.',
+    generatedAt: new Date().toISOString(),
+    records,
+  }, null, 2);
+}
+
+/**
+ * Emit a Mermaid flow-graph: one edge per source -> sink/storage
+ * relationship, decorated with the data class and whether the flow is
+ * prohibited (still an open finding) or policy-permitted.
+ */
+export function emitDataFlowGraph(records) {
+  const lines = [];
+  lines.push('# Privacy data flow graph (assurance-hardening PRD FR-406)');
+  lines.push('');
+  lines.push('Code-derived — one edge per OBSERVED source -> sink/storage flow.');
+  lines.push('A red edge is an open (prohibited) finding; a green edge is policy-permitted.');
+  lines.push('');
+  lines.push('```mermaid');
+  lines.push('graph LR');
+  const nodeIds = new Map();
+  let n = 0;
+  function idFor(label) {
+    if (!nodeIds.has(label)) nodeIds.set(label, `n${n++}`);
+    return nodeIds.get(label);
+  }
+  if (!records.length) {
+    lines.push('  EMPTY["No regulated-data flows observed"]');
+  }
+  const edgeLines = [];
+  const styleLines = [];
+  let edgeIndex = 0;
+  for (const rec of records) {
+    const srcLabel = `${rec.source.name}\\n(${rec.dataClass.join('+')})\\n${rec.source.file}:${rec.source.line ?? '?'}`;
+    const srcId = idFor(srcLabel);
+    lines.push(`  ${srcId}["${srcLabel}"]`);
+    for (const entry of [...rec.storage, ...rec.sinkRecipient]) {
+      const sinkLabel = `${entry.sinkKind}\\n${entry.file}:${entry.line}`;
+      const sinkId = idFor(sinkLabel);
+      lines.push(`  ${sinkId}[["${sinkLabel}"]]`);
+      edgeLines.push(`  ${srcId} --> ${sinkId}`);
+      const color = entry.status === 'prohibited' ? '#c0392b' : '#27ae60';
+      styleLines.push(`  linkStyle ${edgeIndex} stroke:${color}`);
+      edgeIndex++;
+    }
+  }
+  lines.push(...edgeLines, ...styleLines);
+  lines.push('```');
+  return lines.join('\n');
+}

package/src/dataflow/privacy-sink-policy.js

@@ -0,0 +1,125 @@
+// Privacy sink policy (assurance-hardening PRD FR-404).
+//
+// `annotatePrivacyTaint` treats every SINK_PATTERNS match as unconditionally
+// prohibited — any regulated-data class reaching log/response/outboundHttp/
+// etc. always produces a finding, with no way to say "PII flowing to
+// emailSend is expected here (password-reset emails), don't flag it." FR-404
+// asks specifically for a POLICY-gated version of that emission: a finding
+// still fires by default (nothing changes for a repo with no policy file —
+// this is what keeps the PRD's own worked example, "email from request
+// input to logging produces a mapped privacy finding", true unmodified), but
+// an operator can mark a specific (data class, sink) pair — or a sink
+// entirely, for every class — as policy-permitted, which suppresses the
+// finding.
+//
+// Extended for FR-408 ("repository privacy policy defining prohibited and
+// conditionally permitted flows... environment- and destination-specific
+// decisions") with two additional, OPTIONAL rule axes: `environment` (this
+// scan's deployment environment — resolved from AGENTIC_SECURITY_ENVIRONMENT,
+// never from NODE_ENV, which this codebase's own env-hygiene detector
+// already flags as "unreliable as a security boundary" for application
+// code, and the same reasoning applies to a scanner's own policy decisions)
+// and `destination` (a regex matched against the actual sink expression
+// text — "stripe.track", not just the broader "thirdPartySdk" category).
+// Both axes are ADDITIVE constraints and FAIL CLOSED: a rule naming an
+// environment or destination the caller did not supply context for does
+// NOT match — an unknown environment must never silently satisfy an
+// environment-scoped permission, which is the entire point of adding the
+// axis. A rule with neither field set behaves exactly as it did under
+// FR-404 (unconstrained by environment/destination), so every FR-404 rule
+// written before this extension keeps working unmodified.
+//
+// Suppression must be VISIBLE, not silent — same principle the root
+// CLAUDE.md states for ignore-pragma suppressions ("a suppression nobody can
+// see is indistinguishable from a finding that never fired"). A permitted
+// flow is recorded on the annotator's `policyExemptions` array (see
+// privacy-taint.js), never just dropped.
+
+import * as fs from 'node:fs';
+import { statePath } from '../posture/state-dir.js';
+
+function _policyStatePath(scanRoot) {
+  return statePath(scanRoot, 'privacy-policy.json');
+}
+
+/**
+ * Load the operator's privacy sink policy. Never throws — a missing file
+ * (ENOENT) is the common "no policy configured" case; a malformed one logs
+ * a warning and degrades to the empty policy (everything prohibited, the
+ * pre-FR-404 default). Returns { allow: [{sink, class?, reason?}] }.
+ */
+export function loadPrivacySinkPolicy(scanRoot) {
+  const EMPTY = { allow: [] };
+  if (!scanRoot) return EMPTY;
+  const fp = _policyStatePath(scanRoot);
+  let raw = null;
+  try {
+    raw = JSON.parse(fs.readFileSync(fp, 'utf8'));
+  } catch (e) {
+    if (e.code !== 'ENOENT') {
+      console.error(`agentic-security: bad JSON in privacy-policy.json — falling back to no policy (${e.message})`);
+    }
+    return EMPTY;
+  }
+  const allow = Array.isArray(raw?.allow)
+    ? raw.allow.filter(r => r && typeof r.sink === 'string' && r.sink)
+    : [];
+  return { allow };
+}
+
+// FR-408: does `ruleEnv` (unset | string | string[]) cover `currentEnv`?
+// Unset is unconstrained (matches anything, including an unknown
+// environment — preserves FR-404 rules verbatim). Set-but-unknown-current
+// fails closed: a rule scoped to an environment the caller never told us
+// about must not match by accident.
+function _matchesEnvironment(ruleEnv, currentEnv) {
+  if (ruleEnv == null) return true;
+  if (!currentEnv) return false;
+  const allowed = Array.isArray(ruleEnv) ? ruleEnv : [ruleEnv];
+  return allowed.some(e => typeof e === 'string' && e.toLowerCase() === String(currentEnv).toLowerCase());
+}
+
+// FR-408: does `rulePattern` (unset | regex source string) match `destText`
+// (the raw sink expression, e.g. "stripe.track")? Same fail-closed shape as
+// environment — an invalid operator-supplied regex never silently matches
+// everything, and an unset destText for a destination-scoped rule doesn't
+// match either.
+function _matchesDestination(rulePattern, destText) {
+  if (rulePattern == null) return true;
+  if (!destText) return false;
+  try { return new RegExp(rulePattern, 'i').test(destText); } catch { return false; }
+}
+
+function _rulesForSink(policy, sinkKind, ctx) {
+  const allow = Array.isArray(policy?.allow) ? policy.allow : [];
+  return allow.filter(r => r.sink === sinkKind
+    && _matchesEnvironment(r.environment, ctx?.environment)
+    && _matchesDestination(r.destination, ctx?.destination));
+}
+
+/**
+ * Is `sinkKind` policy-permitted for every class in `classes`, in the
+ * given context (`{environment?, destination?}`, both optional)? A rule
+ * matches a class either explicitly (`rule.class === cls`) or by covering
+ * the sink for ANY class (`rule.class` unset), AND must satisfy any
+ * environment/destination constraint the rule itself declares (FR-408).
+ * Returns true only when every matched class has a covering rule — a
+ * finding combining a permitted class with an unpermitted one (e.g.
+ * "PII+CREDENTIALS both flow to log, but only PII→log was allowed") must
+ * still fire, not be silently swept away by a partial allow rule.
+ */
+export function isSinkPermitted(classes, sinkKind, policy, ctx = {}) {
+  if (!Array.isArray(classes) || !classes.length) return false;
+  const rulesForSink = _rulesForSink(policy, sinkKind, ctx);
+  if (!rulesForSink.length) return false;
+  return classes.every(cls => rulesForSink.some(r => !r.class || r.class === cls));
+}
+
+/**
+ * The specific rule(s) that permitted a class for a sink in the given
+ * context, for exemption disclosure (reason strings, when the operator
+ * supplied one).
+ */
+export function permittingRules(classes, sinkKind, policy, ctx = {}) {
+  return _rulesForSink(policy, sinkKind, ctx).filter(r => !r.class || classes.includes(r.class));
+}

package/src/dataflow/privacy-taint.js

@@ -20,45 +20,26 @@
 // attempt content classification (Luhn-checking actual values would
 // only catch leaks that have already happened); we classify by NAME
 // + TYPE in declarations.
+//
+// The data-class taxonomy itself (PII/PHI/PCI/FIN/CREDENTIALS/GEOLOCATION/
+// DEVICE_ID, plus any organization-defined classes) is versioned and
+// customizable without editing this file — see ./privacy-taxonomy.js
+// (assurance-hardening PRD FR-402). This module keeps only the sink
+// taxonomy (where regulated data exits), which is not in FR-402's scope.
+//
+// Whether a class-reaches-sink flow actually PRODUCES a finding is
+// policy-gated (assurance-hardening PRD FR-404) — see
+// ./privacy-sink-policy.js. With no policy configured every match is
+// prohibited, unchanged from before FR-404.
 
-// PII / PHI / PCI / FIN classifiers — each is a regex against
-// field/variable/column names. Same idea as the existing classifyField
-// helpers in engine.js but enumerated for compliance reporting.
+import {
+  BUILTIN_TAXONOMY_VERSION, DEFAULT_TAXONOMY, compileTaxonomy,
+  loadPrivacyTaxonomy, classifyFieldAgainst, severityForClasses,
+} from './privacy-taxonomy.js';
+import { loadPrivacySinkPolicy, isSinkPermitted, permittingRules } from './privacy-sink-policy.js';
+import { GOVERNANCE_FIELDS, governanceRecordFor } from './privacy-governance.js';
 
-const PII_PATTERNS = {
-  PII: [
-    /\bfirst[_-]?name\b/i, /\blast[_-]?name\b/i, /\bfull[_-]?name\b/i,
-    /\bemail([_-]?address)?\b/i, /\bphone([_-]?number)?\b/i, /\bmobile\b/i,
-    /\baddress(?:_?(?:line|street|city|zip|postal))?\b/i,
-    /\bdob\b/i, /\bdate[_-]?of[_-]?birth\b/i, /\bbirthday\b/i, /\bbirthdate\b/i,
-    /\bage\b/i, /\bgender\b/i, /\bethnicity\b/i, /\brace\b/i, /\bnationality\b/i,
-    /\bssn\b/i, /\bsocial[_-]?security/i, /\bnational[_-]?id/i, /\bpassport\b/i,
-    /\bdriver[_-]?license\b/i, /\btax[_-]?id\b/i, /\bgovernment[_-]?id\b/i,
-    /\bip[_-]?address\b/i, /\bgeo[_-]?location\b/i, /\blatitude\b/i, /\blongitude\b/i,
-  ],
-  PHI: [
-    /\b(?:medical|patient|health)[_-]?record\b/i,
-    /\bdiagnosis\b/i, /\bcondition\b/i, /\bsymptom\b/i, /\btreatment\b/i,
-    /\bmedication\b/i, /\bprescription\b/i, /\bdosage\b/i,
-    /\bicd[_-]?(?:9|10|11)\b/i, /\bcpt[_-]?code\b/i, /\bmrn\b/i,
-    /\bmedical[_-]?record[_-]?number\b/i, /\bdoctor[_-]?name\b/i,
-    /\bphysician\b/i, /\binsurance[_-]?id\b/i, /\bhealth[_-]?plan\b/i,
-  ],
-  PCI: [
-    /\bcredit[_-]?card[_-]?(?:number|num|no)?\b/i,
-    /\bcard[_-]?(?:number|num|no)\b/i,
-    /\b(?:cvc|cvv)2?\b/i, /\bcvc[_-]?code\b/i,
-    /\bexp(?:iry|iration)?(?:_?date)?\b/i,
-    /\bcardholder[_-]?name\b/i, /\bpan\b/i,
-    /\biban\b/i, /\brouting[_-]?number\b/i,
-    /\baccount[_-]?number\b/i,
-  ],
-  FIN: [
-    /\bsalary\b/i, /\bincome\b/i, /\bbalance\b/i, /\btransaction[_-]?amount\b/i,
-    /\bbank[_-]?account\b/i,
-    /\bcredit[_-]?score\b/i, /\bnet[_-]?worth\b/i,
-  ],
-};
+const _BUILTIN_COMPILED = compileTaxonomy(DEFAULT_TAXONOMY);
 
 const SINK_PATTERNS = {
   log: /\b(?:log|logger|console|System\.out|System\.err|stdout|stderr|fmt\.Print|print)\b/i,
@@ -71,18 +52,15 @@ const SINK_PATTERNS = {
 };
 
 /**
- * Classify a field/variable name into PII / PHI / PCI / FIN buckets.
+ * Classify a field/variable name into the built-in taxonomy's buckets
+ * (PII / PHI / PCI / FIN / CREDENTIALS / GEOLOCATION / DEVICE_ID).
  * Returns an array of bucket labels (possibly empty, possibly multiple).
+ * `compiled` is an optional pre-compiled taxonomy (see
+ * privacy-taxonomy.js's compileTaxonomy / loadPrivacyTaxonomy) — omit it
+ * to classify against the built-in defaults only.
  */
-export function classifyField(name) {
-  if (!name) return [];
-  const out = [];
-  for (const [bucket, patterns] of Object.entries(PII_PATTERNS)) {
-    for (const p of patterns) {
-      if (p.test(name)) { out.push(bucket); break; }
-    }
-  }
-  return out;
+export function classifyField(name, compiled) {
+  return classifyFieldAgainst(name, compiled || _BUILTIN_COMPILED);
 }
 
 /**
@@ -101,19 +79,51 @@ export function classifySink(expr) {
  * a privacy-leak finding when a regulated class reaches a non-secure
  * sink (log, response, outbound HTTP, etc.).
  */
-export function annotatePrivacyTaint(perFileIR) {
-  if (!perFileIR) return { findings: [], piiFields: [] };
+export function annotatePrivacyTaint(perFileIR, opts = {}) {
+  // FR-402 (assurance-hardening PRD): the taxonomy used for classification
+  // is resolved once per call, not hardcoded — `opts.compiled` lets a
+  // caller (tests, or a future dry-run) hand in an already-compiled
+  // taxonomy directly; `opts.scanRoot` loads and compiles the effective
+  // (built-in + operator-config) taxonomy from disk. Neither is required:
+  // omitting both classifies against the built-in defaults, unchanged from
+  // before FR-402.
+  const { version, compiled } = opts.compiled
+    ? { version: opts.taxonomyVersion || BUILTIN_TAXONOMY_VERSION, compiled: opts.compiled }
+    : (opts.scanRoot ? loadPrivacyTaxonomy(opts.scanRoot) : { version: BUILTIN_TAXONOMY_VERSION, compiled: _BUILTIN_COMPILED });
+  // FR-404 (assurance-hardening PRD): whether a class-reaches-sink flow is
+  // PROHIBITED is policy-gated the same way — `opts.sinkPolicy` for a
+  // caller that already has one, `opts.scanRoot` to load
+  // .agentic-security/privacy-policy.json, or the empty policy (everything
+  // prohibited, the pre-FR-404 default) when neither is given.
+  const sinkPolicy = opts.sinkPolicy || (opts.scanRoot ? loadPrivacySinkPolicy(opts.scanRoot) : { allow: [] });
+  // FR-408: the current deployment environment, ONLY from an explicit
+  // caller-supplied opts.environment or AGENTIC_SECURITY_ENVIRONMENT — never
+  // NODE_ENV (see privacy-sink-policy.js's header for why). Unset means an
+  // environment-scoped allow rule never matches (fail closed), same as
+  // before this option existed.
+  const policyCtx = { environment: opts.environment || process.env.AGENTIC_SECURITY_ENVIRONMENT || null };
+  if (!perFileIR) return { findings: [], piiFields: [], taxonomyVersion: version, policyExemptions: [] };
   const findings = [];
   const piiFields = [];
+  // Suppression must be visible, not silent — same principle as the
+  // ignore-pragma suppression ledger (root CLAUDE.md): a policy-permitted
+  // flow is recorded here, never just dropped.
+  const policyExemptions = [];
   for (const [filePath, ir] of (perFileIR instanceof Map ? perFileIR : Object.entries(perFileIR))) {
     if (!ir || !ir._content) continue;
     const lines = ir._content.split('\n');
     // Step 1: collect PII-classified decls.
     const taintedVars = new Map(); // name → array of bucket labels
+    // FR-406: declaration line per source variable, so a finding/exemption
+    // emitted below can link back to where the regulated data ENTERED
+    // (evidence locations must cover both ends of a flow, not just the
+    // sink) without re-deriving it from piiFields by proximity guessing.
+    const declLineByName = new Map();
     for (const d of ir.decls || []) {
-      const classes = classifyField(d.name);
+      const classes = classifyFieldAgainst(d.name, compiled);
       if (classes.length) {
         taintedVars.set(d.name, classes);
+        declLineByName.set(d.name, d.line);
         piiFields.push({ file: filePath, line: d.line, name: d.name, classes, declaredType: d.type || null });
       }
     }
@@ -121,26 +131,45 @@ export function annotatePrivacyTaint(perFileIR) {
     // reaching a sink.
     for (const call of ir.calls || []) {
       const argText = (call.args || []).map(a => a.text || '').join(',');
-      const sinkLabel = classifySink(call.fullPath || call.callee || '');
+      // FR-408: the raw sink expression text, e.g. "stripe.track" — the
+      // destination-matching axis needs the actual call identity, not just
+      // its broader sink CATEGORY (sinkLabel), which "stripe.track" and
+      // "axios.post" would otherwise share.
+      const destText = call.fullPath || call.callee || '';
+      const sinkLabel = classifySink(destText);
       if (!sinkLabel) continue;
+      const ctx = { ...policyCtx, destination: destText };
       for (const [name, classes] of taintedVars) {
         if (!new RegExp(`\\b${name.replace(/[.+^${}()|\\]/g, '\\$&')}\\b`).test(argText)) continue;
+        const sourceLine = declLineByName.get(name) ?? null;
+        if (isSinkPermitted(classes, sinkLabel, sinkPolicy, ctx)) {
+          policyExemptions.push({
+            file: filePath, line: call.line, name, classes, sinkKind: sinkLabel,
+            sourceLine,
+            rules: permittingRules(classes, sinkLabel, sinkPolicy, ctx).map(r => ({ sink: r.sink, class: r.class || null, reason: r.reason || null, environment: r.environment || null, destination: r.destination || null })),
+          });
+          continue;
+        }
         findings.push({
           family: 'pii-exposure',
           subfamily: classes.join('+'),
           file: filePath, line: call.line,
-          severity: classes.includes('PCI') || classes.includes('PHI') ? 'high' : 'medium',
+          severity: severityForClasses(classes, compiled),
           cwe: 'CWE-359', // Exposure of Private Personal Information
           vuln: `Privacy — ${classes.join('+')} data flows to ${sinkLabel} sink`,
           snippet: (lines[call.line - 1] || '').trim().slice(0, 200),
           remediation: `${classes.join(' + ')} data must not flow to ${sinkLabel} unencrypted. Mask, redact, or hash the value before logging / responding / sending to third parties.`,
           piiClass: classes,
           sinkKind: sinkLabel,
+          // FR-406: evidence linkage back to the source declaration, not
+          // just the sink call site.
+          sourceName: name,
+          sourceLine,
         });
       }
     }
   }
-  return { findings, piiFields };
+  return { findings, piiFields, taxonomyVersion: version, policyExemptions };
 }
 
 /**
@@ -167,6 +196,12 @@ export function emitDpiaArtifact(piiFields, findings, opts = {}) {
   lines.push('');
   lines.push(`## Data classes identified`);
   lines.push('');
+  // FR-407: governance fields (purpose, lawful basis, subject, retention,
+  // residency, recipient, transfer, minimization, consent, access,
+  // deletion) — none inferable from code, so every one is either
+  // operator-supplied (opts.governanceConfig) or explicitly manual_required,
+  // never blank and never guessed.
+  const governanceConfig = opts.governanceConfig || null;
   for (const [cls, fields] of grouped) {
     lines.push(`### ${cls} (${fields.length} fields)`);
     lines.push('');
@@ -175,6 +210,14 @@ export function emitDpiaArtifact(piiFields, findings, opts = {}) {
     }
     if (fields.length > 20) lines.push(`- … and ${fields.length - 20} more`);
     lines.push('');
+    lines.push(`**Governance fields for ${cls}** (see the RoPA artifact for the full register):`);
+    lines.push('');
+    const record = governanceRecordFor(cls, governanceConfig);
+    for (const field of GOVERNANCE_FIELDS) {
+      const r = record[field];
+      lines.push(`- ${field}: \`${r.value}\`${r.source === 'operator_provided' ? ' (operator-provided)' : ''}`);
+    }
+    lines.push('');
   }
   lines.push(`## Privacy-related findings`);
   lines.push('');
@@ -185,6 +228,24 @@ export function emitDpiaArtifact(piiFields, findings, opts = {}) {
   }
   if (findings.length > 50) lines.push(`| … | … | … | … and ${findings.length - 50} more |`);
   lines.push('');
+  // FR-404: a policy-permitted flow must stay visible here, not vanish —
+  // same principle as the ignore-pragma suppression ledger (root
+  // CLAUDE.md). Only rendered when the policy actually exempted something.
+  const exemptions = Array.isArray(opts.policyExemptions) ? opts.policyExemptions : [];
+  if (exemptions.length) {
+    lines.push(`## Policy-permitted flows (not flagged above)`);
+    lines.push('');
+    lines.push(`These flows matched a regulated-data class reaching a sink, but were permitted by .agentic-security/privacy-policy.json and are excluded from the findings table above.`);
+    lines.push('');
+    lines.push(`| File:Line | Class → Sink | Reason |`);
+    lines.push(`|---|---|---|`);
+    for (const e of exemptions.slice(0, 50)) {
+      const reason = (e.rules || []).map(r => r.reason).filter(Boolean).join('; ') || '(no reason given)';
+      lines.push(`| ${e.file}:${e.line} | ${(e.classes || []).join('+')} → ${e.sinkKind} | ${reason} |`);
+    }
+    if (exemptions.length > 50) lines.push(`| … | … | … and ${exemptions.length - 50} more |`);
+    lines.push('');
+  }
   lines.push(`## Regulatory framework mapping`);
   lines.push('');
   lines.push(`- **GDPR Art. 35** — DPIA required when processing is likely to result in high risk to data subjects.`);
@@ -202,4 +263,4 @@ export function emitDpiaArtifact(piiFields, findings, opts = {}) {
   return lines.join('\n');
 }
 
-export const _internals = { PII_PATTERNS, SINK_PATTERNS };
+export const _internals = { DEFAULT_TAXONOMY, SINK_PATTERNS };