@clear-capabilities/agentic-security-scanner 0.145.0 → 0.147.5

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/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

@@ -30,6 +30,7 @@ import { _remediationOf, normalizeFindings } from '../report/index.js';
 // `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
@@ -1544,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];

package/src/pipeline/scan-health.js

@@ -33,6 +33,7 @@ export const SCAN_HEALTH_SCHEMA_VERSION = 1;
  * @param {Array<{phase:string, err:string}>} input.annotatorErrors
  * @param {object} [input.engineErrors] - e.g. { cppDataflowParseErrors }
  * @param {object} [input.deepStatus] - { requested, enabled, inCi, ciOverrideAllowed, reason, failure }
+ * @param {object} [input.lineageStatus] - { requested, enabled, reason, failure } — Sub-project E, increment 5's own status, kept separate from deepStatus (IR-taint's own).
  * @param {object} [input.analyzerCoverage] - coverage-ledger.js's
  *   summarizeCoverageForScanHealth() output: {expected, completed, failed,
  *   timedOut, skippedByPolicy}. Omitted (not just empty) is treated the
@@ -41,7 +42,7 @@ export const SCAN_HEALTH_SCHEMA_VERSION = 1;
  *   never a fabricated all-zero summary.
  * @returns {object} scanHealth per PRD §10.3, additive fields only.
  */
-export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engineErrors = null, deepStatus = null, analyzerCoverage = null } = {}) {
+export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engineErrors = null, deepStatus = null, analyzerCoverage = null, lineageStatus = null } = {}) {
   const conditions = [];
   const safeAnnotatorErrors = Array.isArray(annotatorErrors) ? annotatorErrors : [];
   const filesTimedOut = Number(scanMeta?.filesTimedOut) || 0;
@@ -63,6 +64,15 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
   if (deepStatus?.requested && !deepStatus.enabled) {
     conditions.push(`deep analysis was requested but did not run: ${deepStatus.reason || 'unknown reason'}`);
   }
+  // Sub-project E, increment 5: lineage graph build status — a SEPARATE
+  // condition from deepStatus above, never folded into it. deepStatus is
+  // specifically IR-taint's own status; conflating the two would make
+  // `scanHealth.deepAnalysis.failure` ambiguous about which subsystem
+  // actually failed (the same "distinguish A from B" discipline this
+  // module already applies to analyzerCoverage vs. annotatorErrors).
+  if (lineageStatus?.failure) {
+    conditions.push(`lineage graph build threw and was skipped: ${lineageStatus.failure}`);
+  }
   // 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
@@ -96,6 +106,14 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
           failure: deepStatus.failure ?? null,
         }
       : null,
+    lineageAnalysis: lineageStatus
+      ? {
+          requested: !!lineageStatus.requested,
+          enabled: !!lineageStatus.enabled,
+          reason: lineageStatus.reason ?? null,
+          failure: lineageStatus.failure ?? null,
+        }
+      : null,
     annotatorErrorCount: safeAnnotatorErrors.length,
     freshness: null,
     conditions,

package/src/posture/CLAUDE.md

@@ -42,6 +42,23 @@ actually took — and are flagged `reliable:false` below n=10 rather than hidden
 or quoted as settled. Recording goes through `isSafeStateDir`, so it declines
 rather than creating a stray state dir outside a project.
 
+**Remediation ledger (M5 deliverable #6)** — `remediation-ledger.js`. The
+I/O half of Blast-Radius: Remediation Command Center (FR-507 + AC-31) —
+locking, JSONL append, tolerant read, and a hash chain over
+`.agentic-security/remediation/items.jsonl`/`items.lock`, matching
+`fix-metrics.js`'s own append-and-tolerant-read shape above (one
+newline-terminated record per `appendFileSync`, a torn tail dropped on
+read, never a whole-file rewrite). The pure state machine it writes
+through — `foldRemediationItem`/`foldRemediationLedger`/
+`validateTransition` — lives at `../lineage/remediation.js`, making this
+the SECOND `posture/` → `lineage/` import in the codebase
+(`auditor-walkthrough.js`'s `graph:` branch was the first — see "First
+`posture/` → `lineage/` import" below). `appendLedgerEvent` is the single
+place `validateTransition` is enforced; no CLI command computes validity
+for itself. Its `withLock` is a faithful local PORT of
+`provenance/lifecycle.js`'s own `withLock` — not an import, since that
+function is not exported.
+
 **Agentic verification** — `verifier.js`, `verifier-target.js`, `verifier-ephemeral.js`, `harness-discovery.js`, `adversary-agent.js`, `defender-agent.js`, `auditor-agent.js`, `three-agent-pipeline.js`.
 
 **Methodology additions (Agentic Methodology PRD, removed post-implementation)** — default-on annotators/artifacts that layer the agentic-hunter methodology on the deterministic engine:
@@ -83,6 +100,8 @@ Wired in `bin/agentic-security.js` after every filter and after `makeDeterminist
 
 **Rule lifecycle** — `custom-rules.js` (YAML pattern DSL), `rule-overrides.js` (`disable:` gated on signature), `rule-packs.js`, `rule-synthesis.js` (proposes suppressions from triage feedback), `ruleset-version.js`.
 
+**First `posture/` → `lineage/` import.** `auditor-walkthrough.js`'s `graph:` mapping branch (Data Flow Explorer M4 sub-project 6b) imports `evaluateGraphFlowPredicate`/`buildObligationMappingFromGraphPredicate` from `../lineage/obligation-predicates.js` — the first time any module in this directory has reached into `lineage/` (previously a one-way boundary: `lineage/` never imports `posture/`, and nothing here imported it back). It mints a real `ObligationMapping` record (see `scanner/src/lineage/CLAUDE.md`) from `scan.lineageGraph` when present, purely additively — never touching the pre-existing `anySignal`/`allCleared`/`anyCleared`/`hasUnverifiableMapping` status machinery.
+
 **NIST Privacy Framework 1.1 (`privacy-framework.js`)** — assessment + remediation
 over the bundled `compliance-frameworks/nist-privacy-1-1.json` (all 104 controls).
 Sits on top of `auditor-walkthrough.js`'s evaluator and adds the half a narrative