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

package/src/lineage/CLAUDE.md

@@ -1182,6 +1182,37 @@ established operator-config trust model this whole package uses
 everywhere else (a hand-edited config file is trusted as declared, the
 way `recipient-profiles.json`/`privacy-policy.json` already are).
 
+## Deployment boundary graph (differentiation PRD, X-301 to X-308)
+
+`deployment/` is a SEPARATE graph from `DataFlowGraph v1`: it answers "what can reach what, as deployed" (repositories,
+services, routes, identities, tenants, resources, environments), not "where does a data element flow". It shares no mutable
+state with the taint or vulnerability engines. It imports only pure helpers (the assurance schema kit, canonical
+serialization and content hashing from `posture/assurance/`) and three assurance enums (provenance, path state,
+observation completeness), so the verification layer and this graph speak one vocabulary. It is gated by the
+`deployment-boundaries` feature (off by default); only the two file-reading entry points are gated, everything else is a
+pure function of text. Suite: `npm run test:deployment`, with fixtures under `test/deployment/fixtures/`.
+
+| Module | Responsibility |
+|---|---|
+| `deployment/boundary-graph.js` | X-301. The versioned, closed-world contract. Seven node kinds, a relation table giving each relation its legal endpoint kinds, the trust boundary it crosses and its meaning (`RELATION_SEMANTICS`), and `validateBoundaryGraph` (ids are recomputed, a tampered digest or id is refused). **Three provenance types are separate**: `static-config`, `runtime-observation`, `inferred` (part of an edge's id, so a configured and an observed edge between the same nodes are two edges). A path is `possible`, `blocked`, `unresolved` or `runtime-supported`; `blocked` requires an explicit deny and a deny is always blocked; absence never blocks. The edge completeness enum has no `complete` value, so no producer can assert complete traffic coverage. Node ids hash (kind, name, environment, tenant), so two environments or tenants are two nodes; the owning repository is NOT in the id, so a reference and its declaration coincide and two repositories claiming one identity collide detectably. `buildBoundaryGraph` normalizes, merges identical declarations, records conflicts as gaps (conflicting allow becomes `unresolved`, deny kept) and never throws; `exportBoundaryGraph`/`importBoundaryGraph` round-trip byte-identically; `findPath` is a bounded, cycle-safe shortest path (shared with the correlation and cross-repository code, and the base for X-305). |
+| `deployment/adapter-kit.js` | Shared adapter context. Every static edge carries `{file, digest, parser, parserVersion}` and the revision; every declared node carries `declaredBy` file references; an unresolved reference becomes an unresolved node plus a typed gap. YAML is read with the scanner's safe loader (unknown tags refused), more than 100 aliases is refused, JSON with `JSON.parse`; nothing is evaluated. |
+| `deployment/adapter-kubernetes.js`, `adapter-compose.js`, `adapter-cloud.js` | X-302 adapters: Kubernetes (workloads, Service, Ingress, Gateway API HTTPRoute, ServiceAccount, Role/ClusterRole bindings, NetworkPolicy), compose files, Terraform plan JSON (`terraform show -json`, with `configuration` references used to join resources and `after_unknown` honoured) and standalone IAM policy documents. Secrets, ConfigMaps, environment values, env files and images are never read. A selector that matches nothing, a missing ServiceAccount/Role/Service, a value known only after apply, `NotAction`/`NotResource`, a YAML merge key and unknown resource types are typed gaps, never edges. A `<<` merge key is reported, not expanded. |
+| `deployment/ingest.js` | `ingestDeploymentConfig` (pure: text in, graph out; an adapter that throws is contained to that file), `ingestDeploymentFiles` (reads named files under one root, refusing traversal, absolute paths, symlinks and oversize files; feature gated), `detectFormat` (HCL, proxy configuration and TOML/XML are typed unsupported syntax) and `invalidateChangedSources` (drops the relations a changed or removed file supported, using the recorded digests; a node only that file declared stops being resolved or is dropped). |
+| `deployment/trace-correlation.js` | X-303. `importTraceLines` keeps an allowlist of topology metadata and removes every other field WITHOUT storing it, even its name (only counts, split credential-shaped, payload-shaped and other); strips query strings; turns opaque path segments into `:id`; rejects a record whose kept value is not identifier-shaped; refuses other-environment records instead of relabelling them; merges duplicates; and is bounded (bytes, line length, lines, distinct observations with oldest-first eviction reported). `correlateObservations` matches with numbered rules R1 to R4 (exact service pair, route chain, identity, naming convention); R4 yields an `inferred` edge, R1 to R3 a `runtime-observation` edge, and static edges are never edited. `coverage.trafficCoverage` is always `not-established`; observed, sampled, stale and missing are separate lists; a static edge with no observation stays `possible`. `applyCorrelation` folds the result into a new validated graph. It does NOT persist anything: callers store `exportObservationSet` output and read it back with `parseObservationSet` (closed world, bounded, digest-checked). This sits beside, not on top of, the existing data-flow `runtime-observation.js` records, whose graph-id oriented contract is unchanged; only `EVENT_COUNT_BANDS` is shared. |
+| `deployment/cross-repo.js` | X-304. `resolveCrossRepoBoundaries` takes graph exports the operator supplies, declared dependencies (each binding an exact 40/64 hex revision for both ends) and an access scope; it has no network or file access (a test pins its import list). A link resolves only when both repositories are in scope and supplied, each graph validates and names the repository it was supplied as, the graph revision equals the bound revision, the declared service exists resolved in its repository and in no other supplied repository, and a declared entry route reaches it. Every failure is a typed gap (`access-denied`, `repository-unavailable`, `version-mismatch`, `revision-unknown`, `identity-collision`, `unresolved-identity`, `graph-integrity`, `malformed-input`) and the dependency is kept as an unresolved edge to an unresolved callee. A resolved link carries evidence (declaration file and digest, both graph digests, the declaring files on each side, the route chain) and transitions (entry route, caller identities, callee identity and its grants, boundary crossings). It extends the idea of `cross-repo-link.js` to this graph; that module and `federation-loader.js` are unchanged. |
+| `deployment/attack-paths.js` | X-305. `computeAttackPaths` walks bounded, cycle-safe simple paths from entry points (resolved public routes and services) to targets (resources an identity is granted, or in the privileged zone) over `routes-to`, `calls`, `depends-on`, `network-allows`, `assumes` and `grants`. A hop is `blocked` only when an explicit deny edge sits between its endpoints; a path is `blocked` if any hop is, `unresolved` if a hop or endpoint is unresolved or a tenant transition makes it CONDITIONAL (a hop whose endpoints carry different tenants, listed as a `tenant-binding` condition), `runtime-supported` only if every network hop was observed (identity hops stay configuration), else `possible`. Each path lists supporting edges (with source file, digest, revision), assumptions, blockers, environments, boundary crossings and a coverage block (observed, sampled, stale, unobserved hops; `trafficCoverage` is always `not-established`; staleness is judged only when the caller passes `now`). Path ids hash the edge ids along the path, not the state, so they survive reordering and state changes. `bindFindingToService` ties a finding to a service ONLY through an explicit path-prefix binding (longest prefix wins; a tie, an absent service or no binding is a typed non-bound status and nothing is guessed). `analyzeFindingBoundaries` builds the per-finding `boundary-context` (exposure paths to the bound service, impact paths onward, verification assessments, uncovered boundaries, warnings). **Exploitability is never derived from reachability**: `assessVerification` accepts a record only if it validates, its outcome is `confirmed`, its confirmation level RECOMPUTED from evidence is `runtime-confirmed`, and its oracle is the one the finding's non-taint class names (an unsupported class has none); the label is `exploitable-confirmed` only then, and a blocked or unresolved path keeps that fact in an `oracle-confirmed-path-*` label. `exposureReach` is the path-free reachability the drift diff compares. |
+| `deployment/drift.js` | X-306. `diffBoundaryGraphs` compares two validated graphs of one repository at stable ids: new exposure (newly reachable from an entry, by reachability not by edge), changed privilege (new or changed grant, new identity assumption), tenant weakening (a dropped tenant binding, found by (kind, name, environment) because the tenant is part of the node id, or a new cross-tenant edge) and removed controls (a removed deny) are `material`; other relation changes are reported but not material. It also diffs the SOURCES and names the edges each moved file supported. `planRescan` maps changes to hypotheses through the bound service: a hypothesis is affected when its service is a seed of a change or can reach or be reached from one (union of both revisions, bounded closure); everything else is `skipped` with a reason and NOT rescanned. A hypothesis that cannot be tied to a service cannot be proven independent, so it makes the plan `incomplete` (only when something changed), as does a graph gap that stands for a missing dependency (`DEPENDENCY_GAP_CODES`). `incrementalAnnotate` recomputes only the planned hypotheses; `compareScoped` checks the result against a complete recomputation on `scopedSignature` (which leaves out graph-wide metadata) and never reports an incomplete result as equivalent. `invalidatePathsForSources` reuses `invalidateChangedSources` and drops exactly the paths whose supporting edges or node declarations cite a changed file. |
+| `deployment/projection.js` | X-307. The ONE projection of a boundary context, modelled on `posture/verification/projection.js`: `projectBoundaryContext` (closed-world validation first: an unknown field, a credential-shaped or payload-shaped string, a control character or an over-long string refuses the whole context), `filterBoundaryView` (service, repository, environment, tenant; keeps scope, uncovered boundaries and every earlier warning and adds a warning saying how many paths it hid), `boundaryFields` (the additive report fields; the context itself is echoed only when it validated), `boundaryCoverage` (run accounting) and `attachBoundaryContext`, the ONLY producer, gated by the `deployment-boundaries` feature (off returns the same findings array untouched). The text states what was and was not established, never says safe, protected or unreachable (a lint-style test sweeps every state), and a context with no path says "not shown to exist". Consumed by `report/index.js` (`normalizeFindings` adds `boundaryContext` and `boundaryView` only when a finding carries a context, a top-level `boundaryCoverage`, a Markdown and a terminal block) and by MCP `explain_finding`. Previous output schemas are pinned in `test/fixtures/boundary-compat/` (captured before the wiring). |
+| `deployment/boundaries-run.js` | X-308 wiring. The one operator entry point: `agentic-security boundaries --from <dir> [--findings <last-scan.json>] [--environment] [--repository] [--revision] [--root] [--out] [--json] [--now]`. `runBoundaries` (gated by `deployment-boundaries`, off by default; off returns a typed `disabled` BEFORE any file is opened) lists configuration files under the directory (bounded walk, symlinks never followed or listed), reads the reserved inputs `service-bindings.json`, `identities.json` and `traces.jsonl`/`traces.ndjson` (never ingested as configuration), ingests through `ingestDeploymentFiles`, correlates sanitized traces, reads findings from a scan result (a sibling `.sig` that exists must verify, else exit 1; an absent one is read and labelled unsigned) or from memory, and attaches contexts with `attachBoundaryContext`. Local files only, no scan, no execution; the only write is `--out`, refused when the target is a symbolic link. Exit codes: 0 report, 1 failed, 2 usage, 3 feature off, blocked or unsupported. `renderBoundariesText` reuses each context's own projected text. Suite: `test/deployment/boundaries-cli.test.js`. |
+
+**Disclosed limits.** Kubernetes `matchExpressions`, namespace-only selectors and ExternalName targets are not evaluated
+(reported as gaps). Terraform modules other than the root are joined only through the plan's flat `resource_changes`.
+IAM conditions are not interpreted (a conditioned statement is recorded at low confidence with `conditioned: true`).
+The digest of an ingested file is over the UTF-8 text that was parsed. Observation persistence is not wired. The presentation (X-307) is consumed by the report and MCP `explain_finding` only when a finding carries a
+`boundaryContext`; nothing in the default scan produces one. `attachBoundaryContext` is a feature-gated helper; its one operator entry point is
+`agentic-security boundaries` (`boundaries-run.js`, explicit, read-only, off by default), so default output is unchanged. The boundary graph attribute grammar admits credential-shaped values such as `password=x` (it only
+restricts characters); the projection refuses them, but the graph contract itself does not.
+
 ## Conventions
 
 - Every enum here is a single source of truth for its concept. If you add

package/src/lineage/deployment/adapter-cloud.js

@@ -0,0 +1,202 @@
+// adapter-cloud.js: Terraform plan JSON and IAM policy documents into
+// deployment boundary nodes and edges (X-302).
+//
+// Input is a plan that someone already produced (`terraform show -json`); this
+// adapter never runs terraform, never evaluates HCL and never contacts a
+// provider. Values the plan itself marks as unknown after apply are not
+// guessed: the relation becomes an unresolved node plus a gap. Policy
+// documents are read with JSON.parse; `NotAction` / `NotResource` statements
+// and conditions it cannot interpret are reported, not approximated.
+
+import { adapterContext, isObject, asArray, str } from './adapter-kit.js';
+
+export const TERRAFORM_PARSER = 'terraform-plan-json';
+export const TERRAFORM_PARSER_VERSION = '1';
+export const IAM_PARSER = 'iam-policy-json';
+export const IAM_PARSER_VERSION = '1';
+
+const MAX_STATEMENTS = 200;
+const MAX_RESOURCES_PER_STATEMENT = 50;
+
+function toList(v) { return typeof v === 'string' ? [v] : Array.isArray(v) ? v.filter(x => typeof x === 'string') : []; }
+
+/** Emit grants edges for every statement of a policy document. Returns the number of statements read. */
+function applyPolicy(kit, identity, policy, subject) {
+  const statements = Array.isArray(policy?.Statement) ? policy.Statement : isObject(policy?.Statement) ? [policy.Statement] : null;
+  if (!statements) { kit.gap('malformed-input', subject, 'policy document has no Statement'); return 0; }
+  let read = 0;
+  for (const st of statements.slice(0, MAX_STATEMENTS)) {
+    if (!isObject(st)) { kit.gap('malformed-input', subject, 'a policy statement that is not an object is skipped'); continue; }
+    if (st.NotAction !== undefined || st.NotResource !== undefined || st.NotPrincipal !== undefined) {
+      kit.gap('unsupported-syntax', subject, 'NotAction, NotResource and NotPrincipal statements are not interpreted; the statement is skipped');
+      continue;
+    }
+    const effect = st.Effect === 'Allow' ? 'allow' : st.Effect === 'Deny' ? 'deny' : null;
+    if (!effect) { kit.gap('malformed-input', subject, `statement Effect must be Allow or Deny, got ${JSON.stringify(st.Effect)}`); continue; }
+    const actions = toList(st.Action).sort();
+    const resources = toList(st.Resource);
+    if (actions.length === 0 || resources.length === 0) { kit.gap('malformed-input', subject, 'a statement without Action and Resource is skipped'); continue; }
+    const conditioned = isObject(st.Condition) && Object.keys(st.Condition).length > 0;
+    read += 1;
+    if (resources.length > MAX_RESOURCES_PER_STATEMENT) kit.gap('limit-exceeded', subject, `a statement lists ${resources.length} resources; only the first ${MAX_RESOURCES_PER_STATEMENT} are read`);
+    for (const r of resources.slice(0, MAX_RESOURCES_PER_STATEMENT)) {
+      const target = kit.node('resource', `aws/${r}`, { trustZone: 'internal', attrs: r === '*' ? { wildcard: true } : {} });
+      const attrs = { actions: actions.join(',').slice(0, 250) };
+      if (conditioned) attrs.conditioned = true;
+      kit.edge('grants', identity, target, {
+        effect, confidence: conditioned ? 'low' : 'high', discriminator: `${actions.join(',')}${conditioned ? ';cond' : ''}`.slice(0, 250), attrs,
+      });
+    }
+  }
+  if (statements.length > MAX_STATEMENTS) kit.gap('limit-exceeded', subject, `policy has ${statements.length} statements; only the first ${MAX_STATEMENTS} are read`);
+  return read;
+}
+
+export function parseIamPolicy(text, fileCtx) {
+  const kit = adapterContext({ ...fileCtx, parser: IAM_PARSER, parserVersion: IAM_PARSER_VERSION });
+  let doc;
+  try { doc = JSON.parse(text); } catch (e) {
+    kit.gap('malformed-input', fileCtx.file, `not valid JSON (${String(e.message).split('\n')[0]})`);
+    return kit.result();
+  }
+  const identityName = str(fileCtx.identity);
+  let identity;
+  if (identityName) identity = kit.node('identity', `iam/${identityName}`, { trustZone: 'internal' });
+  else {
+    identity = kit.unresolved('identity', `iam/policy:${fileCtx.file}`, 'the policy document is not attached to a named identity', { trustZone: 'unknown' });
+    kit.gap('unresolved-identity', fileCtx.file, 'the policy document is not attached to a named identity; supply the identity it belongs to');
+  }
+  applyPolicy(kit, identity, doc, fileCtx.file);
+  return kit.result();
+}
+
+function roleNameFromArn(arn) {
+  const m = /^arn:[^:]*:iam::[^:]*:role\/(?:.*\/)?([^/]+)$/.exec(arn ?? '');
+  return m ? m[1] : null;
+}
+
+export function parseTerraformPlan(text, fileCtx) {
+  const kit = adapterContext({ ...fileCtx, parser: TERRAFORM_PARSER, parserVersion: TERRAFORM_PARSER_VERSION });
+  let plan;
+  try { plan = JSON.parse(text); } catch (e) {
+    kit.gap('malformed-input', fileCtx.file, `not valid JSON (${String(e.message).split('\n')[0]})`);
+    return kit.result();
+  }
+  if (!isObject(plan) || !str(plan.format_version) || !Array.isArray(plan.resource_changes)) {
+    kit.gap('unsupported-format', fileCtx.file, 'not a terraform plan in JSON form (needs format_version and resource_changes)');
+    return kit.result();
+  }
+  const resources = new Map();
+  for (const rc of plan.resource_changes) {
+    if (!isObject(rc) || !str(rc.address) || !isObject(rc.change)) continue;
+    const actions = asArray(rc.change.actions);
+    if (actions.includes('delete') && !actions.includes('create')) continue;
+    resources.set(rc.address, { type: rc.type, name: rc.name, after: isObject(rc.change.after) ? rc.change.after : {}, unknown: isObject(rc.change.after_unknown) ? rc.change.after_unknown : {} });
+  }
+  const config = new Map();
+  for (const r of asArray(plan.configuration?.root_module?.resources)) {
+    if (isObject(r) && str(r.address)) config.set(r.address, isObject(r.expressions) ? r.expressions : {});
+  }
+  const refTarget = (address, field, wantType) => {
+    const refs = asArray(config.get(address)?.[field]?.references);
+    for (const ref of refs) {
+      const m = /^([a-z0-9_]+\.[A-Za-z0-9_-]+)(?:\.|$)/.exec(ref);
+      if (m && resources.get(m[1])?.type === wantType) return m[1];
+    }
+    return null;
+  };
+
+  const identityNodes = new Map();
+  const roleNode = (address) => {
+    if (identityNodes.has(address)) return identityNodes.get(address);
+    const r = resources.get(address);
+    const name = str(r?.after?.name);
+    let node;
+    if (name && r.unknown.name !== true) node = kit.node('identity', `iam-role/${name}`, { trustZone: 'internal' });
+    else {
+      node = kit.unresolved('identity', `iam-role/${address}`, 'the role name is only known after apply', { trustZone: 'unknown' });
+      kit.gap('unresolved-identity', address, 'the role name is only known after apply');
+    }
+    identityNodes.set(address, node);
+    return node;
+  };
+  const roleByArn = (arn, subject) => {
+    const n = roleNameFromArn(arn);
+    if (!n) { kit.gap('unresolved-identity', subject, 'the role reference is not a literal role ARN and has no resolvable reference'); return kit.unresolved('identity', `iam-role/${subject}`, 'unresolved role reference', { trustZone: 'unknown' }); }
+    return kit.unresolved('identity', `iam-role/${n}`, 'the role is not defined in this plan', { trustZone: 'unknown' });
+  };
+
+  const handled = new Set(['aws_iam_role', 'aws_iam_policy', 'aws_iam_role_policy', 'aws_iam_role_policy_attachment', 'aws_lambda_function', 'aws_s3_bucket', 'aws_security_group']);
+  const unsupportedTypes = new Set();
+  const policies = new Map();
+  for (const [address, r] of resources) {
+    if (r.type === 'aws_iam_policy' || r.type === 'aws_iam_role_policy') {
+      let doc = null;
+      if (typeof r.after.policy === 'string' && r.unknown.policy !== true) { try { doc = JSON.parse(r.after.policy); } catch { doc = null; } }
+      policies.set(address, doc);
+    }
+    if (!handled.has(r.type)) unsupportedTypes.add(r.type);
+  }
+
+  for (const [address, r] of resources) {
+    switch (r.type) {
+      case 'aws_iam_role': roleNode(address); break;
+      case 'aws_iam_role_policy': {
+        const roleAddr = refTarget(address, 'role', 'aws_iam_role');
+        const ident = roleAddr ? roleNode(roleAddr) : (str(r.after.role) && r.unknown.role !== true ? kit.node('identity', `iam-role/${r.after.role}`, { trustZone: 'internal' }) : kit.unresolved('identity', `iam-role/${address}`, 'the role is only known after apply', { trustZone: 'unknown' }));
+        const doc = policies.get(address);
+        if (!doc) kit.gap('unresolved-identity', address, 'the policy document is only known after apply or is not valid JSON; its grants are unknown');
+        else applyPolicy(kit, ident, doc, address);
+        break;
+      }
+      case 'aws_iam_role_policy_attachment': {
+        const roleAddr = refTarget(address, 'role', 'aws_iam_role');
+        const polAddr = refTarget(address, 'policy_arn', 'aws_iam_policy');
+        const ident = roleAddr ? roleNode(roleAddr) : (str(r.after.role) && r.unknown.role !== true ? kit.node('identity', `iam-role/${r.after.role}`, { trustZone: 'internal' }) : kit.unresolved('identity', `iam-role/${address}`, 'the role is only known after apply', { trustZone: 'unknown' }));
+        if (!polAddr) {
+          kit.gap('unresolved-identity', address, `attached policy ${typeof r.after.policy_arn === 'string' ? r.after.policy_arn : '(known after apply)'} is not defined in this plan, so what it grants is unknown`);
+          const target = kit.unresolved('resource', `aws/policy:${typeof r.after.policy_arn === 'string' ? r.after.policy_arn : address}`, 'the attached policy is not defined in this plan', { trustZone: 'unknown' });
+          kit.edge('grants', ident, target, { effect: 'allow', confidence: 'low', discriminator: 'attached-policy' });
+        } else if (!policies.get(polAddr)) {
+          kit.gap('unresolved-identity', polAddr, 'the policy document is only known after apply or is not valid JSON; its grants are unknown');
+        } else applyPolicy(kit, ident, policies.get(polAddr), address);
+        break;
+      }
+      case 'aws_lambda_function': {
+        const name = str(r.after.function_name);
+        const node = name && r.unknown.function_name !== true
+          ? kit.node('service', `lambda/${name}`, { trustZone: 'internal' })
+          : kit.unresolved('service', `lambda/${address}`, 'the function name is only known after apply', { trustZone: 'unknown' });
+        const roleAddr = refTarget(address, 'role', 'aws_iam_role');
+        const ident = roleAddr ? roleNode(roleAddr) : (typeof r.after.role === 'string' ? roleByArn(r.after.role, address) : roleByArn(null, address));
+        kit.edge('assumes', node, ident, { confidence: roleAddr ? 'high' : 'low' });
+        break;
+      }
+      case 'aws_s3_bucket': {
+        const b = str(r.after.bucket);
+        if (b && r.unknown.bucket !== true) kit.node('resource', `s3/${b}`, { trustZone: r.after.acl === 'public-read' || r.after.acl === 'public-read-write' ? 'public' : 'internal', attrs: { acl: typeof r.after.acl === 'string' ? r.after.acl : 'unspecified' } });
+        else kit.unresolved('resource', `s3/${address}`, 'the bucket name is only known after apply', { trustZone: 'unknown' });
+        break;
+      }
+      case 'aws_security_group': {
+        const name = str(r.after.name) ?? address;
+        const sg = kit.node('resource', `sg/${name}`, { trustZone: 'internal' });
+        for (const rule of asArray(r.after.ingress)) {
+          const cidrs = asArray(rule?.cidr_blocks).filter(c => typeof c === 'string');
+          const ports = `${rule?.protocol ?? '-1'}:${rule?.from_port ?? 0}-${rule?.to_port ?? 0}`;
+          for (const cidr of cidrs) {
+            const src = kit.node('route', `cidr/${cidr}`, { trustZone: cidr === '0.0.0.0/0' ? 'public' : 'edge', attrs: { cidr } });
+            kit.edge('network-allows', src, sg, { confidence: 'high', discriminator: ports, attrs: { ports } });
+          }
+        }
+        break;
+      }
+      default: break;
+    }
+  }
+  if (unsupportedTypes.size) {
+    const list = [...unsupportedTypes].sort();
+    kit.gap('unsupported-format', fileCtx.file, `resource types not interpreted by this adapter: ${list.slice(0, 10).join(', ')}${list.length > 10 ? `, and ${list.length - 10} more` : ''}`);
+  }
+  return kit.result();
+}

package/src/lineage/deployment/adapter-compose.js

@@ -0,0 +1,90 @@
+// adapter-compose.js: container composition files into deployment boundary
+// nodes and edges (X-302).
+//
+// A service is a node. A published port is an entry route into it, public
+// unless it is bound to loopback. `depends_on` and `links` are declared
+// dependencies: they are recorded as `depends-on`, never as `calls`, because a
+// dependency is a startup ordering or a reachability hint and says nothing
+// about a call actually being made. Environment variables, env files, secrets
+// and build arguments are never read, so a credential in a compose file cannot
+// reach the graph.
+
+import { adapterContext, parseYamlDocuments, isObject, asArray, str } from './adapter-kit.js';
+
+export const COMPOSE_PARSER = 'compose-file';
+export const COMPOSE_PARSER_VERSION = '1';
+
+function parsePort(p) {
+  if (typeof p === 'number') return { published: String(p), target: String(p), hostIp: null };
+  if (typeof p === 'string') {
+    let t = p.trim().replace(/\/(tcp|udp|sctp)$/i, '');
+    let hostIp = null;
+    const v6 = /^\[([^\]]+)\]:(.*)$/.exec(t);
+    if (v6) { hostIp = `[${v6[1]}]`; t = v6[2]; }
+    const parts = t.split(':');
+    const port = /^\d+(-\d+)?$/;
+    if (parts.some(x => !port.test(x) && !(parts.length === 3 && x === parts[0] && /^[0-9.]+$/.test(x)))) return null;
+    if (parts.length === 1) return { published: null, target: parts[0], hostIp };
+    if (parts.length === 2) return { published: parts[0], target: parts[1], hostIp };
+    if (parts.length === 3 && !hostIp) return { published: parts[1], target: parts[2], hostIp: parts[0] };
+    return null;
+  }
+  if (isObject(p)) {
+    const target = p.target != null ? String(p.target) : null;
+    if (!target) return null;
+    return { published: p.published != null ? String(p.published) : null, target, hostIp: str(p.host_ip) };
+  }
+  return null;
+}
+
+export function parseCompose(text, fileCtx) {
+  const kit = adapterContext({ ...fileCtx, parser: COMPOSE_PARSER, parserVersion: COMPOSE_PARSER_VERSION });
+  const parsed = parseYamlDocuments(text, fileCtx.file);
+  if (parsed.gap) { kit.gaps.push(parsed.gap); return kit.result(); }
+  const doc = parsed.docs[0];
+  if (!isObject(doc) || !isObject(doc.services)) {
+    kit.gap('unsupported-format', fileCtx.file, 'no top-level services mapping; not a compose file');
+    return kit.result();
+  }
+  const declared = new Set(Object.keys(doc.services));
+  const nodes = new Map();
+  const nodeFor = (name) => nodes.get(name);
+  const networks = isObject(doc.networks) ? doc.networks : {};
+
+  for (const [name, svc] of Object.entries(doc.services)) {
+    if (!isObject(svc)) { kit.gap('malformed-input', name, 'a service that is not a mapping is skipped'); continue; }
+    if (Object.hasOwn(svc, '<<')) kit.gap('unsupported-syntax', name, "YAML merge key '<<' is not expanded; fields inherited through it are not read");
+    const tenant = isObject(svc.labels) && typeof svc.labels.tenant === 'string' && /^[A-Za-z0-9._-]{1,64}$/.test(svc.labels.tenant) ? svc.labels.tenant : null;
+    const attrs = {};
+    const nets = (Array.isArray(svc.networks) ? svc.networks : isObject(svc.networks) ? Object.keys(svc.networks) : []).filter(n => typeof n === 'string').sort();
+    if (nets.length) attrs.networks = nets.join(',');
+    if (nets.length && nets.every(n => isObject(networks[n]) && networks[n].internal === true)) attrs.networkInternal = true;
+    if (svc.network_mode === 'host') attrs.networkMode = 'host';
+    nodes.set(name, kit.node('service', name, { tenant, trustZone: 'internal', attrs }));
+  }
+
+  for (const [name, svc] of Object.entries(doc.services)) {
+    const node = nodeFor(name);
+    if (!node) continue;
+    for (const raw of asArray(svc.ports)) {
+      const port = parsePort(raw);
+      if (!port) { kit.gap('malformed-input', name, 'a port mapping that cannot be read is skipped'); continue; }
+      if (port.published === null) continue; // container port only, not published to the host
+      const loop = port.hostIp !== null && (/^127\./.test(port.hostIp) || port.hostIp === '[::1]');
+      const route = kit.node('route', `port/${name}:${port.published}`, { tenant: node.tenant, trustZone: loop ? 'internal' : 'public', attrs: { published: port.published, target: port.target, bind: port.hostIp ?? 'all-interfaces' } });
+      kit.edge('routes-to', route, node, { confidence: 'high' });
+    }
+    const deps = Array.isArray(svc.depends_on) ? svc.depends_on : isObject(svc.depends_on) ? Object.keys(svc.depends_on) : [];
+    const links = [...asArray(svc.links), ...asArray(svc.external_links)].map(l => (typeof l === 'string' ? l.split(':')[0] : null));
+    for (const d of [...deps, ...links]) {
+      if (typeof d !== 'string' || !d) continue;
+      if (declared.has(d) && nodeFor(d)) kit.edge('depends-on', node, nodeFor(d), { confidence: 'medium' });
+      else {
+        const miss = kit.unresolved('service', d, 'the dependency is not defined in this compose file', { trustZone: 'unknown' });
+        kit.edge('depends-on', node, miss, { confidence: 'low' });
+        kit.gap('unresolved-identity', name, `depends on '${d}', which this compose file does not define`);
+      }
+    }
+  }
+  return kit.result();
+}

package/src/lineage/deployment/adapter-kit.js

@@ -0,0 +1,142 @@
+// adapter-kit.js: shared plumbing for the deployment configuration adapters
+// (X-302). Every adapter is a pure function from text to `{ nodes, edges, gaps }`
+// built through one context, so that three things hold for every adapter
+// without each one remembering them:
+//
+//  - every edge a static adapter emits is `static-config` provenance and
+//    carries the exact file reference, digest, parser name and parser version
+//    it came from (X-302.AC03);
+//  - environment, tenant and owning repository are stamped uniformly, so two
+//    environments never share a node;
+//  - a reference that cannot be resolved becomes an unresolved node plus a gap,
+//    never a guessed edge to a resolved one.
+//
+// Nothing here evaluates configuration. YAML is read with the scanner's safe
+// loader (unknown tags are refused), JSON with JSON.parse, and policy strings
+// are JSON.parse'd, never evaluated.
+
+import { load as loadYaml } from '../../util/yaml.js';
+import { nodeIdOf } from './boundary-graph.js';
+
+const ANCHOR_LIMIT = 100;
+
+/**
+ * Parse one YAML document, or several separated by `---`. Never throws.
+ * Returns `{ docs }` or `{ gap }` where the gap is a typed unsupported or
+ * malformed result. YAML merge keys are not expanded by the loader, so a
+ * document that uses `<<` is reported by the adapter that needs the key.
+ */
+export function parseYamlDocuments(text, file) {
+  const aliasCount = (text.match(/(^|[\s\[{,:-])\*[A-Za-z0-9_-]+/g) || []).length;
+  if (aliasCount > ANCHOR_LIMIT) {
+    return { gap: { code: 'unsupported-syntax', subject: file, file, message: `YAML uses ${aliasCount} aliases, over the limit of ${ANCHOR_LIMIT}; the file is not read` } };
+  }
+  const chunks = text.split(/^---[ \t]*$/m);
+  const docs = [];
+  for (const chunk of chunks) {
+    let doc;
+    try { doc = loadYaml(chunk); } catch (e) {
+      return { gap: { code: 'malformed-input', subject: file, file, message: `not valid YAML (${String(e.message).split('\n')[0]})` } };
+    }
+    if (doc !== undefined && doc !== null) docs.push(doc);
+  }
+  return { docs };
+}
+
+export function isObject(v) { return v !== null && typeof v === 'object' && !Array.isArray(v); }
+export function asArray(v) { return Array.isArray(v) ? v : []; }
+export function str(v) { return typeof v === 'string' && v.length > 0 ? v : null; }
+
+/** True when every entry of `selector` is present with the same value in `labels`. An empty selector selects nothing. */
+export function selectorMatches(selector, labels) {
+  if (!isObject(selector) || !isObject(labels)) return false;
+  const entries = Object.entries(selector);
+  if (entries.length === 0) return false;
+  return entries.every(([k, v]) => Object.hasOwn(labels, k) && String(labels[k]) === String(v));
+}
+
+/**
+ * @param {object} p
+ * @param {string} p.file         path as supplied, relative to the ingest root
+ * @param {string} p.digest       sha256 of the text that was parsed
+ * @param {string} p.environment  deployment environment these files describe
+ * @param {string|null} p.repository
+ * @param {string|null} p.revision exact commit, when known
+ * @param {string} p.parser
+ * @param {string} p.parserVersion
+ */
+export function adapterContext({ file, digest, environment, repository, revision, parser, parserVersion }) {
+  const nodes = [];
+  const edges = [];
+  const gaps = [];
+  const ref = { file, digest };
+  const source = { file, digest, parser, parserVersion };
+
+  const kit = {
+    nodes, edges, gaps, environment, repository, file,
+
+    /** Declare a node this file defines. Adds the structural environment, repository and tenant edges. */
+    node(kind, name, o = {}) {
+      const tenant = o.tenant ?? null;
+      const n = {
+        kind, name, environment, tenant, repository: o.resolved === false ? null : repository,
+        trustZone: o.trustZone ?? 'unknown', resolved: o.resolved !== false, unresolvedReason: o.unresolvedReason ?? null,
+        attrs: o.attrs ?? {}, declaredBy: o.resolved === false ? [] : [ref],
+      };
+      nodes.push(n);
+      if (o.resolved !== false) {
+        const env = { kind: 'environment', name: environment, environment, tenant: null, repository: null, trustZone: 'unknown', resolved: true, attrs: {}, declaredBy: [ref] };
+        nodes.push(env);
+        kit.structural('deployed-in', n, env);
+        if (repository) {
+          const repo = { kind: 'repository', name: repository, environment: null, tenant: null, repository, trustZone: 'unknown', resolved: true, attrs: {}, declaredBy: [ref] };
+          nodes.push(repo);
+          kit.structural('defined-in', n, repo);
+        }
+        if (tenant) {
+          const t = { kind: 'tenant', name: tenant, environment, tenant, repository: null, trustZone: 'unknown', resolved: true, attrs: {}, declaredBy: [ref] };
+          nodes.push(t);
+          kit.structural('scoped-to', n, t);
+        }
+      }
+      return n;
+    },
+
+    /** A reference this file makes to something it does not define and cannot resolve. */
+    unresolved(kind, name, reason, o = {}) {
+      return kit.node(kind, name, { ...o, resolved: false, unresolvedReason: reason });
+    },
+
+    structural(relation, from, to) {
+      edges.push(kit.baseEdge(relation, from, to, { effect: 'none', confidence: 'high' }));
+    },
+
+    baseEdge(relation, from, to, o = {}) {
+      return {
+        relation, from: idOf(from), to: idOf(to), environment: from.environment ?? to.environment ?? null, tenant: o.tenant ?? null,
+        effect: o.effect ?? 'none', provenance: 'static-config', confidence: o.confidence ?? 'medium',
+        pathState: o.effect === 'deny' ? 'blocked' : (o.pathState ?? 'possible'),
+        observationInterval: null, completeness: null, sourceRevision: revision ?? null, source,
+        discriminator: o.discriminator ?? null, crossRepo: null, attrs: o.attrs ?? {},
+        _fromNode: from, _toNode: to,
+      };
+    },
+
+    /** Add a relation between two nodes from this file. */
+    edge(relation, from, to, o = {}) {
+      edges.push(kit.baseEdge(relation, from, to, o));
+    },
+
+    gap(code, subject, message) { gaps.push({ code, subject, file, message }); },
+
+    result() {
+      // Drop the private endpoint references now that the ids are computed.
+      return { nodes, edges: edges.map(({ _fromNode, _toNode, ...e }) => e), gaps };
+    },
+  };
+  return kit;
+}
+
+function idOf(node) {
+  return nodeIdOf({ kind: node.kind, name: node.name, environment: node.kind === 'environment' ? node.name : (node.environment ?? null), tenant: node.kind === 'tenant' ? node.name : (node.tenant ?? null) });
+}