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

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) });
+}