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

package/src/lineage/validate.js

@@ -0,0 +1,285 @@
+//
+// Structural validator for DataFlowGraph v1 (PRD section 10). Hand-rolled
+// rather than a generic JSON-Schema interpreter + a new `ajv`-style
+// dependency, matching this codebase's existing preference for
+// hand-rolled implementations over new runtime deps (see every parser in
+// scanner/src/ir/). scanner/src/lineage/dataflow-graph.schema.json (Task
+// 6) is the authoritative JSON Schema document for external interop /
+// documentation; this file is what the engine actually calls at graph-
+// build phase 12 (PRD 18.3: "Validate the graph contract and freeze it
+// before rendering").
+//
+// Never throws. A malformed top-level input produces one error and
+// returns early; a malformed nested entity is skipped for further
+// structural checks on ITSELF but does not stop validation of siblings.
+
+import {
+  SCHEMA_VERSION, NODE_KINDS, MAPPING_TYPES, COVERAGE_STATUS_VALUES, EXTERNALITY_VALUES,
+  TRANSFORM_KINDS, REVERSIBILITY_VALUES, DESTINATION_RESOLUTION_VALUES, EDGE_PROVENANCE_VALUES, POLICY_STATES,
+  FLOW_SUMMARY_VALUES, EVIDENCE_TYPES, GRAPH_SCOPE_SOURCES, HANDLING_VALUES, STORE_OPERATION_VALUES,
+  QUEUE_OPERATION_VALUES,
+} from './schema.js';
+import { isValidProtectionDimension, PROTECTION_DIMENSIONS } from './protection.js';
+import { LINEAGE_DATA_CLASSES, isAiContext } from './classification.js';
+
+function _err(errors, path, message) {
+  errors.push({ path, message });
+}
+
+function _requireArray(graph, key, errors) {
+  if (!Array.isArray(graph[key])) _err(errors, `$.${key}`, `${key} must be an array`);
+}
+
+function _requireObject(graph, key, errors) {
+  if (typeof graph[key] !== 'object' || graph[key] === null || Array.isArray(graph[key])) {
+    _err(errors, `$.${key}`, `${key} must be an object`);
+  }
+}
+
+const ID_PREFIXES = {
+  node: /^node:/,
+  edge: /^edge:/,
+  data: /^data:/,
+  flow: /^flow:/,
+  transform: /^transform:/,
+  evidence: /^evidence:/,
+};
+
+function _validateNode(node, idx, errors, seenIds) {
+  const path = (suffix) => `$.nodes[${idx}]${suffix}`;
+  if (!node || typeof node !== 'object') { _err(errors, path(''), 'node must be an object'); return; }
+  if (typeof node.id !== 'string' || !node.id) _err(errors, path('.id'), 'node.id is required');
+  else {
+    if (!ID_PREFIXES.node.test(node.id)) _err(errors, path('.id'), `node.id must start with "node:"`);
+    seenIds.add(node.id);
+  }
+  if (!NODE_KINDS.includes(node.kind)) _err(errors, path('.kind'), `unrecognized node kind "${node.kind}"`);
+  // node.subtype is optional and may be `null` — an `unsupported`-coverage
+  // node (e.g. a sink registry decision with `category: null`, PRD 6.4/
+  // DESIGN_REGISTRIES.md §9.0) legitimately carries no subtype at all,
+  // either as an absent field or an explicit `null`; only a present,
+  // non-null, non-string value (a number, object, array, etc.) is invalid.
+  if (Object.prototype.hasOwnProperty.call(node, 'subtype') && node.subtype !== null && typeof node.subtype !== 'string') {
+    _err(errors, path('.subtype'), 'node.subtype must be a string or null');
+  }
+  if (typeof node.label !== 'string' || !node.label) _err(errors, path('.label'), 'node.label is required');
+  if (!Array.isArray(node.aliases)) _err(errors, path('.aliases'), 'node.aliases must be an array');
+  if (!Array.isArray(node.dataElementIds)) _err(errors, path('.dataElementIds'), 'node.dataElementIds must be an array');
+  if (!Array.isArray(node.evidenceRefs)) _err(errors, path('.evidenceRefs'), 'node.evidenceRefs must be an array');
+  if (!COVERAGE_STATUS_VALUES.includes(node.coverageStatus)) _err(errors, path('.coverageStatus'), `unrecognized coverageStatus "${node.coverageStatus}"`);
+  if (node.externality && !EXTERNALITY_VALUES.includes(node.externality.value)) {
+    _err(errors, path('.externality.value'), `unrecognized externality "${node.externality.value}"`);
+  }
+  // Milestone 2, Sub-project A, increment 1: `node.destination` is `null`
+  // on every node this increment doesn't resolve — only checked when
+  // non-null, mirroring `_validateEdge`'s own `edge.protocol` pattern below.
+  if (node.destination && typeof node.destination === 'object') {
+    if (!DESTINATION_RESOLUTION_VALUES.includes(node.destination.resolutionStatus)) {
+      _err(errors, path('.destination.resolutionStatus'), `unrecognized destination.resolutionStatus "${node.destination.resolutionStatus}"`);
+    }
+    if (node.destination.resolutionStatus !== 'literal' && node.destination.literalValue !== null) {
+      _err(errors, path('.destination.literalValue'), 'destination.literalValue must be null unless resolutionStatus is "literal"');
+    }
+  }
+  // Milestone 2, Sub-project E, increment 2: `node.storeDetail` is `null`
+  // on every node this increment doesn't populate — only checked when
+  // non-null, mirroring `node.destination`'s own "only checked when the
+  // parent object is present" shape immediately above.
+  if (node.storeDetail && typeof node.storeDetail === 'object') {
+    if (node.storeDetail.operation !== null && !STORE_OPERATION_VALUES.includes(node.storeDetail.operation)) {
+      _err(errors, path('.storeDetail.operation'), `unrecognized storeDetail.operation "${node.storeDetail.operation}"`);
+    }
+    if (Object.prototype.hasOwnProperty.call(node.storeDetail, 'columns') && !Array.isArray(node.storeDetail.columns)) {
+      _err(errors, path('.storeDetail.columns'), 'storeDetail.columns must be an array');
+    } else if (Array.isArray(node.storeDetail.columns)) {
+      node.storeDetail.columns.forEach((c, i) => {
+        if (typeof c !== 'string') _err(errors, path(`.storeDetail.columns[${i}]`), 'storeDetail.columns entries must be strings');
+      });
+    }
+  }
+  // Milestone 2, Sub-project E, increment 3: `node.queueDetail` is `null`
+  // on every node this increment doesn't populate — only checked when
+  // non-null, mirroring `node.storeDetail`'s own "only checked when the
+  // parent object is present" shape immediately above.
+  if (node.queueDetail && typeof node.queueDetail === 'object') {
+    if (node.queueDetail.operation !== null && !QUEUE_OPERATION_VALUES.includes(node.queueDetail.operation)) {
+      _err(errors, path('.queueDetail.operation'), `unrecognized queueDetail.operation "${node.queueDetail.operation}"`);
+    }
+    if (node.queueDetail.topic !== null && typeof node.queueDetail.topic !== 'string') {
+      _err(errors, path('.queueDetail.topic'), 'queueDetail.topic must be a string or null');
+    }
+  }
+}
+
+function _validateDataElement(de, idx, errors, seenIds) {
+  const path = (suffix) => `$.dataElements[${idx}]${suffix}`;
+  if (!de || typeof de !== 'object') { _err(errors, path(''), 'dataElement must be an object'); return; }
+  if (typeof de.id !== 'string' || !de.id) _err(errors, path('.id'), 'dataElement.id is required');
+  else {
+    if (!ID_PREFIXES.data.test(de.id)) _err(errors, path('.id'), `dataElement.id must start with "data:"`);
+    seenIds.add(de.id);
+  }
+  if (typeof de.name !== 'string' || !de.name) _err(errors, path('.name'), 'dataElement.name is required');
+  if (!Array.isArray(de.dataClasses)) _err(errors, path('.dataClasses'), 'dataElement.dataClasses must be an array');
+  else {
+    for (let i = 0; i < de.dataClasses.length; i++) {
+      const cls = de.dataClasses[i];
+      if (!LINEAGE_DATA_CLASSES.includes(cls)) {
+        _err(errors, path(`.dataClasses[${i}]`), `unrecognized data class "${cls}"`);
+      }
+    }
+  }
+  if (!Array.isArray(de.aiContexts)) _err(errors, path('.aiContexts'), 'dataElement.aiContexts must be an array');
+  else {
+    for (let i = 0; i < de.aiContexts.length; i++) {
+      const ctx = de.aiContexts[i];
+      if (!isAiContext(ctx)) {
+        _err(errors, path(`.aiContexts[${i}]`), `unrecognized AI processing context "${ctx}"`);
+      }
+    }
+  }
+}
+
+function _validateEdge(edge, idx, errors, nodeIds, dataElementIds) {
+  const path = (suffix) => `$.edges[${idx}]${suffix}`;
+  if (!edge || typeof edge !== 'object') { _err(errors, path(''), 'edge must be an object'); return; }
+  if (typeof edge.id !== 'string' || !edge.id) _err(errors, path('.id'), 'edge.id is required');
+  else if (!ID_PREFIXES.edge.test(edge.id)) _err(errors, path('.id'), `edge.id must start with "edge:"`);
+  if (!nodeIds.has(edge.from)) _err(errors, path('.from'), `unknown node id "${edge.from}"`);
+  if (!nodeIds.has(edge.to)) _err(errors, path('.to'), `unknown node id "${edge.to}"`);
+  if (edge.relationship !== 'data_flow') _err(errors, path('.relationship'), `unrecognized relationship "${edge.relationship}"`);
+  if (!Array.isArray(edge.fieldMappings)) _err(errors, path('.fieldMappings'), 'edge.fieldMappings must be an array');
+  else {
+    edge.fieldMappings.forEach((fm, i) => {
+      if (!MAPPING_TYPES.includes(fm?.mappingType)) _err(errors, path(`.fieldMappings[${i}].mappingType`), `unrecognized mappingType "${fm?.mappingType}"`);
+      for (const deId of fm?.dataElementIds || []) {
+        if (!dataElementIds.has(deId)) _err(errors, path(`.fieldMappings[${i}].dataElementIds`), `unknown dataElement id "${deId}"`);
+      }
+    });
+  }
+  if (!edge.protection || typeof edge.protection !== 'object') {
+    _err(errors, path('.protection'), 'edge.protection is required');
+  } else {
+    for (const dim of PROTECTION_DIMENSIONS) {
+      if (!isValidProtectionDimension(edge.protection[dim])) _err(errors, path(`.protection.${dim}`), `invalid protection dimension`);
+    }
+  }
+  if (edge.protocol && typeof edge.protocol === 'object') {
+    if (!DESTINATION_RESOLUTION_VALUES.includes(edge.protocol.destinationResolution)) {
+      _err(errors, path('.protocol.destinationResolution'), `unrecognized destinationResolution "${edge.protocol.destinationResolution}"`);
+    }
+  }
+  if (!EDGE_PROVENANCE_VALUES.includes(edge.provenance)) {
+    _err(errors, path('.provenance'), `unrecognized provenance "${edge.provenance}"`);
+  }
+}
+
+function _validateFlow(flow, idx, errors, nodeIds, dataElementIds, edgeIds) {
+  const path = (suffix) => `$.flows[${idx}]${suffix}`;
+  if (!flow || typeof flow !== 'object') { _err(errors, path(''), 'flow must be an object'); return; }
+  if (typeof flow.id !== 'string' || !flow.id) _err(errors, path('.id'), 'flow.id is required');
+  else if (!ID_PREFIXES.flow.test(flow.id)) _err(errors, path('.id'), `flow.id must start with "flow:"`);
+  if (!nodeIds.has(flow.source)) _err(errors, path('.source'), `unknown node id "${flow.source}"`);
+  if (!nodeIds.has(flow.sink)) _err(errors, path('.sink'), `unknown node id "${flow.sink}"`);
+  for (const deId of flow.dataElementIds || []) {
+    if (!dataElementIds.has(deId)) _err(errors, path('.dataElementIds'), `unknown dataElement id "${deId}"`);
+  }
+  for (const eId of flow.edgeIds || []) {
+    if (!edgeIds.has(eId)) _err(errors, path('.edgeIds'), `unknown edge id "${eId}"`);
+  }
+  if (!POLICY_STATES.includes(flow.policyVerdict)) _err(errors, path('.policyVerdict'), `unrecognized policyVerdict "${flow.policyVerdict}"`);
+  if (!FLOW_SUMMARY_VALUES.includes(flow.protectionSummary)) _err(errors, path('.protectionSummary'), `unrecognized protectionSummary "${flow.protectionSummary}"`);
+  // Milestone 2, Sub-project D, increment 1: `flow.handling` is `null` on
+  // every flow this increment's own caller chose not to populate — only
+  // checked when non-null, mirroring `_validateNode`'s own `node.destination`
+  // pattern above.
+  if (flow.handling != null && !HANDLING_VALUES.includes(flow.handling)) {
+    _err(errors, path('.handling'), `unrecognized handling "${flow.handling}"`);
+  }
+}
+
+function _validateTransformation(t, idx, errors) {
+  const path = (suffix) => `$.transformations[${idx}]${suffix}`;
+  if (!t || typeof t !== 'object') { _err(errors, path(''), 'transformation must be an object'); return; }
+  if (typeof t.id !== 'string' || !t.id) _err(errors, path('.id'), 'transformation.id is required');
+  else if (!ID_PREFIXES.transform.test(t.id)) _err(errors, path('.id'), `transformation.id must start with "transform:"`);
+  if (!TRANSFORM_KINDS.includes(t.kind)) _err(errors, path('.kind'), `unrecognized transformation kind "${t.kind}"`);
+  if (!REVERSIBILITY_VALUES.includes(t.reversibility)) _err(errors, path('.reversibility'), `unrecognized reversibility "${t.reversibility}"`);
+}
+
+function _validateEvidence(e, idx, errors) {
+  const path = (suffix) => `$.evidence[${idx}]${suffix}`;
+  if (!e || typeof e !== 'object') { _err(errors, path(''), 'evidence must be an object'); return; }
+  if (typeof e.id !== 'string' || !e.id) _err(errors, path('.id'), 'evidence.id is required');
+  else if (!ID_PREFIXES.evidence.test(e.id)) _err(errors, path('.id'), `evidence.id must start with "evidence:"`);
+  if (!EVIDENCE_TYPES.includes(e.evidenceType)) _err(errors, path('.evidenceType'), `unrecognized evidenceType "${e.evidenceType}"`);
+}
+
+/**
+ * Report a validation error for every duplicate id beyond the first
+ * occurrence in a top-level entity array. Entities with a missing/invalid
+ * id are skipped here — that is already reported by the per-entity
+ * structural check, and treating `undefined` as a colliding "id" would be
+ * noise, not signal.
+ */
+function _checkDuplicateIds(items, key, errors) {
+  const seenAt = new Map();
+  items.forEach((item, idx) => {
+    if (!item || typeof item.id !== 'string' || !item.id) return;
+    if (seenAt.has(item.id)) {
+      _err(errors, `$.${key}[${idx}].id`, `duplicate id "${item.id}" (also used at $.${key}[${seenAt.get(item.id)}])`);
+    } else {
+      seenAt.set(item.id, idx);
+    }
+  });
+}
+
+/**
+ * Structurally validate a DataFlowGraph v1 envelope. Returns
+ * `{valid, errors}` and never throws.
+ */
+export function validateGraph(graph) {
+  const errors = [];
+  if (!graph || typeof graph !== 'object' || Array.isArray(graph)) {
+    return { valid: false, errors: [{ path: '$', message: 'graph must be an object' }] };
+  }
+
+  if (graph.schemaVersion !== SCHEMA_VERSION) {
+    _err(errors, '$.schemaVersion', `expected "${SCHEMA_VERSION}", got "${graph.schemaVersion}"`);
+  }
+  if (typeof graph.graphId !== 'string' || !graph.graphId.startsWith('dfg:')) {
+    _err(errors, '$.graphId', 'graphId must be a string starting with "dfg:"');
+  }
+  for (const key of ['nodes', 'edges', 'dataElements', 'transformations', 'flows', 'controls', 'policies', 'evidence', 'limitations']) {
+    _requireArray(graph, key, errors);
+  }
+  for (const key of ['scope', 'scanHealth', 'taxonomy', 'coverage', 'extensions']) {
+    _requireObject(graph, key, errors);
+  }
+  if (graph.scope && typeof graph.scope === 'object' && !Array.isArray(graph.scope)) {
+    if (!GRAPH_SCOPE_SOURCES.includes(graph.scope.source)) {
+      _err(errors, '$.scope.source', `unrecognized scope.source "${graph.scope.source}"`);
+    }
+  }
+
+  const nodeIds = new Set();
+  const dataElementIds = new Set();
+  const edgeIds = new Set();
+
+  (Array.isArray(graph.nodes) ? graph.nodes : []).forEach((n, i) => _validateNode(n, i, errors, nodeIds));
+  (Array.isArray(graph.dataElements) ? graph.dataElements : []).forEach((d, i) => _validateDataElement(d, i, errors, dataElementIds));
+  (Array.isArray(graph.edges) ? graph.edges : []).forEach((e, i) => {
+    _validateEdge(e, i, errors, nodeIds, dataElementIds);
+    if (e && typeof e.id === 'string') edgeIds.add(e.id);
+  });
+  (Array.isArray(graph.flows) ? graph.flows : []).forEach((f, i) => _validateFlow(f, i, errors, nodeIds, dataElementIds, edgeIds));
+  (Array.isArray(graph.transformations) ? graph.transformations : []).forEach((t, i) => _validateTransformation(t, i, errors));
+  (Array.isArray(graph.evidence) ? graph.evidence : []).forEach((e, i) => _validateEvidence(e, i, errors));
+
+  _checkDuplicateIds(Array.isArray(graph.nodes) ? graph.nodes : [], 'nodes', errors);
+  _checkDuplicateIds(Array.isArray(graph.edges) ? graph.edges : [], 'edges', errors);
+  _checkDuplicateIds(Array.isArray(graph.dataElements) ? graph.dataElements : [], 'dataElements', errors);
+  _checkDuplicateIds(Array.isArray(graph.flows) ? graph.flows : [], 'flows', errors);
+
+  return { valid: errors.length === 0, errors };
+}

package/src/lsp/server.js

@@ -18,6 +18,7 @@ import * as path from 'node:path';
 import * as readline from 'node:readline';
 import { runScan } from '../runScan.js';
 import { resetCustomRulesBudget } from '../posture/custom-rules.js';
+import { withStateWritesDisabled } from '../posture/state-dir.js';
 import { redactFinding } from '../mcp/redact.js';
 import { _remediationOf } from '../report/index.js';
 
@@ -156,7 +157,34 @@ async function scanFile(uri) {
     // whose source and sink are connected only through a call. Scoped to
     // exactly the saved file (fileContents has one entry), so this does not
     // turn every keystroke's save into a full-project deep scan.
-    const { scan } = await runScan(_rootDir, { fileContents, depFileContents, deep: true, deepInCi: true });
+    // withStateWritesDisabled, for the same reason mcp/tools.js's scan_diff
+    // wraps its own partial-set scan (FR-704). This is a DIAGNOSTIC surface: it
+    // runs on every file save, against the user's real project root, with a
+    // fileContents map holding exactly one file. Without the wrapper,
+    // runFullScan's state writers fire on every keystroke-save — dpia.md,
+    // ropa.md, privacy-framework.json, threat-model.json and the rest, written
+    // into the user's tree by an editor plugin they never asked to mutate
+    // anything.
+    //
+    // The provenance lifecycle store makes that actively destructive rather
+    // than merely noisy: updateLifecycle marks every open stableId ABSENT from
+    // the finding set it is handed as `remediated`, and this set is one file's
+    // worth of findings. Every save would remediate the whole project, and the
+    // next real scan would reintroduce it.
+    //
+    // Chosen over forwarding `provenance:false` through runScan because that
+    // would fix only the lifecycle half and leave the other state writers
+    // firing. The flag is process-global (see its KNOWN LIMITATION), which is
+    // harmless here: this server is a read-only surface whose every scan wants
+    // writes off, so overlapping saves can only ever agree, and the `finally`
+    // restores the prior value either way. exceptCategories:['provenance-cache']
+    // (M2 §2.4) is the one deliberate exception — every OTHER write this scan
+    // would make stays suppressed, but the provenance disk cache stays live so
+    // repeated saves of the same file are not each paying the full uncached
+    // resolution cost.
+    const { scan } = await withStateWritesDisabled(() =>
+      runScan(_rootDir, { fileContents, depFileContents, deep: true, deepInCi: true }),
+      { exceptCategories: ['provenance-cache'] });
     // Stage 6 correctness audit: this only ever read scan.findings (the SAST
     // channel). scan.secrets and scan.logicVulns are separate arrays on the
     // raw runScan() result — normalizeFindings is what merges all four
@@ -298,7 +326,26 @@ export function startLspServer() {
 }
 
 // Allow direct invocation as a bin entry: `node lsp/server.js`.
-if (import.meta.url === `file://${process.argv[1]}`) {
+//
+// `import.meta.url === file://${process.argv[1]}` looks equivalent but is
+// NOT: when this script is invoked through a symlink (exactly what
+// `npm install -g`, `npx`, and `node_modules/.bin/<name>` all do for a
+// package's `bin` entries — and `agentic-security-lsp` IS one of this
+// package's bin entries), Node resolves `import.meta.url` to the symlink's
+// realpath while `process.argv[1]` stays the symlink path as invoked, so the
+// two never match, the guard is always false, and the server silently exits
+// with no output — an editor would see the language server start and
+// immediately die with nothing on stderr to explain it. `import.meta.main` is
+// resolved correctly through a symlink. It was added in Node v24.2.0
+// (backported to v22.18.0) and is currently Stability 1.0 (early development)
+// per Node's own docs — NOT stable, and NOT available on v20.11. Concretely:
+// it is `undefined` on Node 24.0.0/24.1.x, which satisfy this repo's declared
+// `engines.node: ">=24.0.0"` floor, so `import.meta.main` alone would
+// reproduce this exact bug on a plain non-symlinked invocation under those two
+// point releases. The `??` fallback covers that gap without bumping the
+// engines floor. Identical to bin/agentic-security.js's guard, deliberately —
+// see the long-form note there.
+if (import.meta.main ?? (import.meta.url === `file://${process.argv[1]}`)) {
   startLspServer();
 }
 

package/src/mcp/CLAUDE.md

@@ -23,8 +23,14 @@ MCP server. JSON-RPC 2.0 over NDJSON on stdin/stdout. Bin entry `../../bin/agent
 | `query_triage_memory` | ✓ | reads past triage decisions (wont-fix/false-positive) by natural-language query |
 | `query_findings_memory` | ✓ | reads accumulated scan memory (findings + triage history + AGENTS.md) by natural-language query |
 | `query_cache_telemetry` | ✓ | reads prompt-cache economics from the current session transcript; no network |
+| `dataflow_get_graph` | ✓ | reads the signed `lineage-graph.json` (via `server/graph-loader.js`, reused unmodified); returns the DataFlowGraph v1 artifact. Milestone 5: an optional `filter: {nodeIds, edgeIds}` input narrows the returned nodes/edges/flows/dataElements via the exact same `validateFilterShape`/`_filterGraph` pair the CLI's `--filter` and the `explore` server's `POST /api/v1/query` endpoint use — closes the large-graph gap FOR A CALLER THAT SUPPLIES A FILTER. **Known gap, still real**: an OMITTED filter still returns the whole graph inline with no pagination/offload — a very large, unfiltered graph can still exceed the stdio transport line cap — see `dataflow-tools.js`'s own header comment |
+| `dataflow_get_node` | ✓ | as above, ID-scoped node lookup (via `server/routes.js`'s `handleNode`, reused unmodified) |
+| `dataflow_get_edge` | ✓ | as above, ID-scoped edge lookup (`handleEdge`) |
+| `dataflow_get_flow` | ✓ | as above, ID-scoped flow lookup (`handleFlow`), includes contributing node/edge canonical ids |
 
-**17 tools, not 12** — this table previously stopped at 12 and the count quoted elsewhere (root `CLAUDE.md`, the non-Claude plugin manifests) said "Six." Re-derive with `grep -c "name: '" scanner/src/mcp/tools.js` rather than trusting a hardcoded number here again.
+**Dataflow-tools redaction scope (found by a post-Task-2 whole-branch security review, fixed same day):** the initial cut only redacted `evidence[].location.note`, which turned out to be fixture-only — the real graph-builder emitter never populates `.note` (it uses `{file,line}`). The real source-derived surfaces are `node.destination.raw`/`.literalValue` (lifted verbatim from a scanned call-site argument by `lineage/resolve-destination.js`) and `evidence[].claim`/`.snippet`. `dataflow-tools.js`'s `_redactNode`/`_redactEvidence`/`_redactGraph` now cover all of them, applied on `dataflow_get_graph` (full graph) and `dataflow_get_node` (single node); edges and flows carry only `evidenceRefs` (id strings), never embedded evidence or destination-shaped fields, so they need no redaction pass. `dataflow-tools.js` was also missing from `server.js`'s `CODE_FINGERPRINT` file list (OWASP MCP04/MCP09) — added.
+
+**21 tools, not 12** — this table previously stopped at 12 and the count quoted elsewhere (root `CLAUDE.md`, the non-Claude plugin manifests) said "Six." Re-derive with `grep -c "name: '" scanner/src/mcp/tools.js scanner/src/mcp/dataflow-tools.js | awk -F: '{s+=$2} END{print s}'` — **not** `tools.js` alone, which now undercounts by 4: the 4 `dataflow_*` tools are defined in `dataflow-tools.js` and only imported into `tools.js`'s `ALL_TOOLS`. If a future tool file follows this same reused-adapter-module pattern, extend the file list rather than trusting a single-file grep again.
 
 **Two write tools, not one.** `apply_fix` and `apply_sca_upgrade` both write; `verify_fix` also writes (see its row above) though not to the target project's own files. `apply_fix` additionally requires `confirm:true` AND the last-scan HMAC to verify AND the target path not on the reserved-write list; `apply_sca_upgrade` requires `confirm:true` and gates on its own test-restore cycle.
 

package/src/mcp/dataflow-tools.js

@@ -0,0 +1,160 @@
+// dataflow-tools.js — Milestone 4, sub-project MCP tools.
+//
+// Thin, read-only MCP adapter over the DataFlowGraph v1 artifact. Every
+// piece of actual graph-loading and graph-query logic here is REUSED,
+// unmodified, from scanner/src/server/ (built for the `explore` HTTP
+// server, Milestone 3): loadSignedGraph does the signed-artifact
+// load+verify, the four handleX functions do the lookups. This module
+// adds nothing but MCP tool shape (name/description/inputSchema/handler)
+// and MCP-appropriate error handling — no new graph-query logic is
+// written here, on purpose (see this sub-project's own scoping doc).
+
+import { loadSignedGraph } from '../server/graph-loader.js';
+import { handleGraph, handleNode, handleEdge, handleFlow } from '../server/routes.js';
+import { _redactNode, _redactEvidence, _redactGraph } from '../lineage/redact-graph.js';
+import { _filterGraph, validateFilterShape } from '../lineage/export-json.js';
+
+const META = { source: 'agentic-security-mcp', untrusted_excerpts: true };
+
+function _loadOrFailure(sessionRoot) {
+  const loaded = loadSignedGraph(sessionRoot);
+  if (loaded.ok) return { graph: loaded.graph };
+  return {
+    failure: {
+      _meta: META,
+      hasResult: false,
+      reason: loaded.reason,
+      message: loaded.message,
+    },
+  };
+}
+
+// Milestone 5, large-graph pagination: an optional `filter` input narrows the
+// returned graph via the exact same `validateFilterShape`/`_filterGraph`
+// pair the CLI's own `--filter` and the `explore` server's new
+// `POST /api/v1/query` endpoint both already use — one real, shared
+// primitive, not a third drifting copy. KNOWN, DISCLOSED GAP (still open):
+// an OMITTED filter still returns the whole graph inline, with the same
+// stdio.js MAX_LINE_BYTES (4MB) risk on a very large, unfiltered scan as
+// before this change — this increment adds an opt-in capability for a
+// caller that supplies a filter, it does not add a forced fallback/offload
+// for a caller that doesn't. That remains a follow-up increment.
+// Final whole-branch review finding: `filter: {}` is NOT the same as
+// omitting `filter` — `_filterGraph` treats an empty (but well-formed)
+// filter object as "narrow to nothing" (empty nodeIds/edgeIds Sets), so
+// `filter: {}` returns an EMPTY graph (zero nodes/edges/flows), not the
+// whole one. Called out explicitly in this tool's own `description` below
+// so an agent reaching for "no restriction" reaches for OMITTING the
+// argument, never for `{}`.
+export const dataflow_get_graph = {
+  name: 'dataflow_get_graph',
+  description: 'Return the DataFlowGraph v1 artifact from the last signed, verified deep-mode scan: nodes, edges, flows, scope, coverage, and limitations. Requires a prior `AGENTIC_SECURITY_LINEAGE_DEEP=1 agentic-security scan`. Optional `filter: {nodeIds, edgeIds}` narrows the returned nodes/edges/flows/dataElements (same primitive as the CLI\'s `--filter` and the `explore` server\'s `POST /api/v1/query`). IMPORTANT: omit `filter` entirely for the whole graph — passing `filter: {}` returns an EMPTY graph (zero nodes/edges/flows), not the whole one, since an empty filter narrows to nothing rather than meaning "no restriction". KNOWN GAP: an OMITTED filter still returns the whole graph inline with no pagination/offload — may exceed the stdio transport line cap on a very large, unfiltered graph; supply a real, non-empty filter to narrow the response.',
+  inputSchema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      filter: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          nodeIds: { type: 'array', items: { type: 'string' } },
+          edgeIds: { type: 'array', items: { type: 'string' } },
+        },
+      },
+    },
+  },
+  async handler(args, ctx) {
+    const { graph, failure } = _loadOrFailure(ctx.sessionRoot);
+    if (failure) return failure;
+    // Milestone 5, large-graph pagination: reuses the exact same
+    // validateFilterShape/_filterGraph pair the new POST /api/v1/query
+    // server endpoint and the CLI's own --filter both use — one real,
+    // shared primitive, not a third drifting copy.
+    const filterCheck = validateFilterShape(args?.filter);
+    if (!filterCheck.valid) {
+      return { _meta: META, hasResult: false, reason: 'invalid-filter', message: filterCheck.error };
+    }
+    const { status, body } = handleGraph(graph);
+    return {
+      _meta: META,
+      hasResult: true,
+      status,
+      data: _redactGraph(args?.filter ? _filterGraph(body.data, args.filter) : body.data),
+      digest: body.digest,
+      schemaVersion: body.schemaVersion,
+      extensions: body.extensions,
+      scope: body.scope,
+      coverage: body.coverage,
+      limitations: body.limitations,
+    };
+  },
+};
+
+export const dataflow_get_node = {
+  name: 'dataflow_get_node',
+  description: 'Look up one node by canonical id in the DataFlowGraph v1 artifact.',
+  inputSchema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: { id: { type: 'string', minLength: 1, maxLength: 512 } },
+    required: ['id'],
+  },
+  async handler({ id }, ctx) {
+    const { graph, failure } = _loadOrFailure(ctx.sessionRoot);
+    if (failure) return failure;
+    const { status, body } = handleNode(graph, id);
+    return {
+      _meta: META,
+      hasResult: true,
+      notFound: status === 404,
+      data: _redactNode(body.data),
+      canonicalIds: body.canonicalIds,
+    };
+  },
+};
+
+export const dataflow_get_edge = {
+  name: 'dataflow_get_edge',
+  description: 'Look up one edge by canonical id in the DataFlowGraph v1 artifact.',
+  inputSchema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: { id: { type: 'string', minLength: 1, maxLength: 512 } },
+    required: ['id'],
+  },
+  async handler({ id }, ctx) {
+    const { graph, failure } = _loadOrFailure(ctx.sessionRoot);
+    if (failure) return failure;
+    const { status, body } = handleEdge(graph, id);
+    return {
+      _meta: META,
+      hasResult: true,
+      notFound: status === 404,
+      data: body.data,
+      canonicalIds: body.canonicalIds,
+    };
+  },
+};
+
+export const dataflow_get_flow = {
+  name: 'dataflow_get_flow',
+  description: 'Look up one flow by canonical id in the DataFlowGraph v1 artifact, including its contributing node/edge canonical ids.',
+  inputSchema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: { id: { type: 'string', minLength: 1, maxLength: 512 } },
+    required: ['id'],
+  },
+  async handler({ id }, ctx) {
+    const { graph, failure } = _loadOrFailure(ctx.sessionRoot);
+    if (failure) return failure;
+    const { status, body } = handleFlow(graph, id);
+    return {
+      _meta: META,
+      hasResult: true,
+      notFound: status === 404,
+      data: body.data,
+      canonicalIds: body.canonicalIds,
+    };
+  },
+};

package/src/mcp/server.js

@@ -43,7 +43,7 @@ const TOOLS_BY_NAME = Object.fromEntries(ALL_TOOLS.map(t => [t.name, t]));
 function _codeFingerprint() {
   try {
     const here = path.dirname(fileURLToPath(import.meta.url));
-    const files = ['server.js', 'tools.js', 'stdio.js', 'audit.js', 'validate.js', 'redact.js'];
+    const files = ['server.js', 'tools.js', 'dataflow-tools.js', 'stdio.js', 'audit.js', 'validate.js', 'redact.js'];
     const h = crypto.createHash('sha256');
     for (const f of files) {
       try { h.update(f); h.update(fs.readFileSync(path.join(here, f))); } catch {}

package/src/mcp/tools.js

@@ -26,6 +26,11 @@ import { withStateWritesDisabled } from '../posture/state-dir.js';
 import { analyzeTranscript, formatCacheReport, renderCacheStatusLine } from '../posture/cache-economics.js';
 import { redactString, redactFinding } from './redact.js';
 import { _remediationOf, normalizeFindings } from '../report/index.js';
+// Git-origin provenance (Finding Provenance M0/M1). Distinct from
+// `finding.provenance` (AI-authorship) and from an SCA entry's `provenance`
+// (Sigstore/SLSA attestation) — see report/index.js's import comment.
+import { redactFindingProvenance } from '../posture/provenance/schema.js';
+import { dataflow_get_graph, dataflow_get_node, dataflow_get_edge, dataflow_get_flow } from './dataflow-tools.js';
 
 // Lazy-loaded: these transitively pull in npm packages (@babel/core and
 // friends) that aren't available in the plugin-cache install path
@@ -571,6 +576,21 @@ export const explain_finding = {
       epssScore: typeof f.epssScore === 'number' ? f.epssScore : null,
       epssPercentile: typeof f.epssPercentile === 'number' ? f.epssPercentile : null,
       exploitedNow: !!f.exploitedNow,
+      // Which commit introduced this finding. `includeEmail` stays at its
+      // DEFAULT (false) unconditionally — unlike the JSON report there is no
+      // operator-set env escape for it here, because the consumer is an
+      // agent that has no business receiving a committer's email address.
+      // `pseudonymize`, by contrast, IS read back from the same env var
+      // report/index.js's `_normalizedProvenance` reads
+      // (AGENTIC_SECURITY_PSEUDONYMIZE_AUTHORS=1 / --pseudonymize-authors) —
+      // fix-round item 4: an operator who set that policy was still getting
+      // raw committer names (and, via providerEnrichment, raw reviewer
+      // logins/CODEOWNERS lines) through this MCP surface because this call
+      // passed no options object at all, silently defeating their policy at
+      // this one output boundary while report/index.js honoured it.
+      findingProvenance: f.findingProvenance ? redactFindingProvenance(f.findingProvenance, {
+        pseudonymize: process.env.AGENTIC_SECURITY_PSEUDONYMIZE_AUTHORS === '1',
+      }) : null,
     };
   },
 };
@@ -775,6 +795,7 @@ export const apply_fix = {
           const entry = await applyFixHistory({
             scanRoot: ctx.sessionRoot, file: rel, originalContent, newContent: v.content, fileExisted,
             findingId: f.id, stableId: f.stableId, ruleId: f.ruleId || f.cwe || f.family || null, vuln: f.vuln || f.title || null,
+            findingProvenance: f.findingProvenance || null,
           });
           written.push({ file: rel, historyId: entry.id, backupPath: entry.backupPath });
         }
@@ -1524,4 +1545,4 @@ export const apply_sca_upgrade = {
   },
 };
 
-export const ALL_TOOLS = [scan_diff, query_taint, explain_finding, apply_fix, verify_fix, synthesize_fix, find_rule_module, append_scratchpad, read_scratchpad, append_agents_memory, read_agents_memory, lookup_cve, synthesize_sca_upgrade, apply_sca_upgrade, query_triage_memory, query_findings_memory, query_cache_telemetry];
+export const ALL_TOOLS = [scan_diff, query_taint, explain_finding, apply_fix, verify_fix, synthesize_fix, find_rule_module, append_scratchpad, read_scratchpad, append_agents_memory, read_agents_memory, lookup_cve, synthesize_sca_upgrade, apply_sca_upgrade, query_triage_memory, query_findings_memory, query_cache_telemetry, dataflow_get_graph, dataflow_get_node, dataflow_get_edge, dataflow_get_flow];