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

package/CHANGELOG.md

@@ -9,6 +9,50 @@
 > make the history less accurate, not more.
 
 
+## 0.163.0 - the rest of the differentiation programme: deployment graph, invariants, capability enforcement, routing, portfolio assurance, evaluation machinery, loop controller and closure
+
+This completes the **implementation** of the Agentic Security Differentiation PRD (all 70 requirements are built, each with tests named by criterion id and deliberate-breakage checks). It does **not** close the PRD: the controller's real final verification ends `blocked`, and several gates need data or hosts this repository cannot supply. Read the status section before relying on anything here. Every new execution-capable feature is off by default and gated by the assurance feature flags.
+
+**Status, measured by the controller's own final verification (disposable checkout, scripted worker, no model calls, no spend).** All 70 requirements verified on the first pass; the final phase then did not close. The unmet items were the committed bundle being stale against source (rebuilt in this release), the self-scan baseline having drifted (reviewed and rebaselined in this release), a documentation walk-through that raced the controller's exit (made deterministic in this release), the Haskell toolchain step needing `ghc` (not available on the verifying host), and two measured gates that read insufficient-population or unmeasured because **no independently adjudicated real-code population exists**. None of the PRD's real-code accuracy targets (per-language F1 of at least 0.80 and the rest of section 5) has been measured or met; every number produced by this programme is synthetic and labelled so.
+
+**Deployment-aware boundaries (X-301 to X-308).** A typed boundary graph built only from local deployment files (Kubernetes, compose, Terraform plan JSON, identity policy), runtime traces with an allowlisted import, cross-repository links bound to exact revisions, deployment-conditioned attack paths, drift between revisions with dependency-aware invalidation, and presentation additive to the existing outputs. New operator command `agentic-security boundaries --from <dir>` (read-only, off by default). On a frozen synthetic paired set the graph removed 3 false positives, added 3 confirmed defects, lost none, and added 1 false positive; only the Kubernetes and compose adapters are claimed as validated.
+
+**Executable invariants (X-401 to X-408).** Reviewer-approved tenant and business-state contracts (inferred contracts stay advisory), bounded seed-deterministic stateful scenarios, a durable-effect oracle, shrinking with linked hashes, repair verification against invariants, bounded coverage reporting and a scenario-export tool. Evaluated on synthetic fixtures only.
+
+**Capability enforcement (X-501 to X-508).** Task capability manifests enforced at the runner for filesystem, structured commands and outbound network, tool and delegation binding (a child can only receive a subset), operator-signed explicit recovery, hash-chained receipts, and an adversarial corpus. **On macOS the confinement is host-proved, not an advertised enforced backend; Linux is unverified and no process-count cap is claimed on any platform.** A detached grandchild can outlive a task between supervisor sweeps; that known limit is recorded.
+
+**Routing (X-601 to X-608).** Outcome records with provenance-backed labels, auditable economics (unknown stays unknown, never zero), calibration that refuses a reliable label below the preregistered minimum, constrained decisions with explanations and bounded fallback, shadow mode and paired replay with the section 5 promotion gate, drift and canary rollback, protected feedback, and a repeatable offline replay (`npm run reproduce:routing`). No cost or quality improvement is claimed.
+
+**Portfolio assurance (X-701 to X-708).** A release assurance manifest, offline-verifiable evidence bundles, bounded claims signed with a self-issued local key (never presented as independent certification), durable leased work units with stable ids and dependency-aware resume, a fair bounded scheduler with scoped cancellation, coverage-aware progress views, and retention with legal holds over local and customer-operated shared backends. Consistency is verified for processes sharing one local filesystem only.
+
+**Evaluation machinery and engine repairs (QA-001 to QA-008).** A frozen, hash-pinned evaluation protocol that cannot be amended after results exist, custody and leakage controls, layer ablations, grouped-bootstrap intervals, cost accounting, custodian-signed release gates, why-missed diagnostics, and an offline miniature reproduction. Five real engine repairs, with ablations: implicit handler parameters (C# MVC, Spring), Laravel request sources, a static-prefix gate for redirect headers plus Go redirect helpers, Go statement line attribution, and suppression only by a guard that dominates the sink. Measured by the layer-recall bench: taint-attributed entries 122 to 126 of 220 (c# 12 to 13, go 13 to 14, php 13 to 15); corpus raw alerts 326 to 315 with root causes unchanged at 305. The self-scan precision on hand-reviewed targets got slightly worse (hooks 19 to 20, scripts 53 to 54) as the price of the dominance rule.
+
+**Loop controller (LOOP-001 to LOOP-004) and closure (REL-001 to REL-003).** The supervised controller now has an independent heartbeat, finite worker stops, controller-issued evidence only, crash recovery, drift freezing, a signed final verification and a resumable report; the assurance profile runs all eleven suites. A closure judge counts a criterion only inside a passing, fresh, controller-issued receipt, and was shown to fail for every kind of unmet criterion and pass only on a synthetic fixture. Release checks bind suite versions and logs to an exact commit; staged rollout and rollback keep earlier evidence.
+
+**Documentation.** Twelve guides under `docs/guides` generated from or tested against the code, with runnable local examples, policy cards that keep historical baselines, new synthetic measurements and aspirational targets in separate sections, and a drift check that rejects universal safe, certified or fully-covered claims.
+
+**Known issues, not fixed here.** The taint engine still reports a regular expression's `.exec()` on request data as command injection (present since at least 0.161.0). The Linux process-cap assertion remains macOS-only. Several controller limits (subprocess wall time, network limits, the provider envelope) are listed as unenforced in the profile.
+
+## 0.162.0 - first slice of the differentiation programme: versioned evidence contracts, an enforced trust boundary, one verification record, trusted oracles, patch-negative verification, and a conformance gate
+
+This is the foundation and verification slice of the Agentic Security Differentiation PRD (CORE-001 to 004, CORE-003 trust boundary, LOOP-001, X-201 to X-208). It is **not** the whole programme: the evaluation work (QA-001 to 008, which holds the accuracy gates), the deployment graph, tenant invariants, capability enforcement, model routing and portfolio assurance are unstarted, and no accuracy number is claimed or changed by this release. The new capabilities that execute anything are off by default.
+
+**Evidence contracts (CORE-001, 002).** Versioned schemas, validators, stable identities and legacy migration adapters for verification records, observation bindings, capability decisions, routing labels and release evidence. A model verdict can only ever be an inference: `confirmed` needs trusted runtime proof or independent adjudication, and the six states (not-run, unsupported, inconclusive, error, refuted, confirmed) stay distinct through every round trip. A baseline capture tool (`npm run baseline:capture`) records source and bundle digests, dirty paths and an inventory of 18 existing capabilities, each checked against real paths and symbols; it invalidates only the capabilities whose files changed and never modifies source.
+
+**Trust boundary (CORE-003).** Four trust domains (target, worker, verifier, signer) with a default-deny policy. `runInBoundary` runs a target only after active probes prove the controls it needs, and returns `blocked` (target never run) otherwise; target output is untrusted and never sets a status. Process trees are killed on timeout or cancel, with a descendant sweep and an orphan check. Signed evidence bundles now carry an `issuance` block that labels them `self-issued-local-key`, never independently certified. **Compatibility:** bundles signed before this release still verify and report no declared trust basis, but a verifier older than this release rejects newly signed bundles (strict unknown-key rule).
+
+**One verification record, oracles, replay (X-201 to X-203).** Every verification surface emits the same record. Seven oracle adapters (injection execution, authorization decision, state transition, side-effect reachability, parser/resource behaviour, replay/idempotency, functional regression) each have positive, negative and inconclusive fixtures; an unavailable prerequisite is `unsupported`, never a pass. Replay manifests pin commit, patch, fixture, toolchain, oracle and budgets and reject any that fail validation.
+
+**Patch-negative verification and non-taint classes (X-204, X-205).** A fix reaches `verified-fix` only with an exploit-positive original, an exploit-negative patched revision and a passing functional check; the specific incomplete step is recorded otherwise, and promotion requires receipts bound to the exact diff and revision. Tenant authorization, privileged action, workflow order, replay/idempotency and bounded resource exhaustion have executable oracles; taint absence never refutes them.
+
+**Parity, gating and conformance (X-206 to X-208).** CLI JSON, MCP, reports and the autopilot response now share one projection (`verificationView`, additive; previous output fields are pinned by fixtures; migration notes in `docs/guides/verification-schema-migration.md`). Advisory hunt hypotheses cannot touch authoritative scan state and are promoted only with a verified receipt and an explicit policy, never on confidence or model agreement. A conformance suite over all oracle adapters runs as a new release check (`verification-conformance-gate`).
+
+**Loop registration (LOOP-001).** `assurance-differentiation` profile for the supervised controller: the unmodified importer parses all 70 requirements, 269 weight and 210 criteria. Preflight on the real profile refuses launch, by design, until the other suites have runnable wrappers. Several limits the PRD names (heartbeat setting, subprocess wall time, network limits, provider envelope) are not enforced by the controller and are listed as unenforced.
+
+**Known issue, not fixed here (present since at least 0.161.0).** The taint engine reports a regular expression's `.exec()` called on request data as a high-severity command injection (`child_process.exec`), for example `SEMVER.exec(req.query.v)`. This is a false positive that will appear in ordinary JavaScript. Fixing the sink model touches the corpus and recall gates, so it is left for its own change. The self-scan baseline records the two such findings in this repository as reviewed false positives.
+
+**Not verified here.** Everything that executes targets was exercised on macOS only; Linux enforcement is declared unverified in every manifest, and on a host where the boundary cannot run the conformance gate reports execution as not-run, never passed. Receipts are unsigned and valid only within the verifier's process. The patch-negative ledger and the promotion audit record are returned, not persisted.
+
 ## 0.161.0 - the first honest out-of-sample numbers, a ReDoS in the scanner itself fixed, large Haskell projects now finish, multi-file fixes over MCP, auth-guard order proved structurally, sturdier tests and a sharded CI
 
 **Measured, and not flattering.** The unseen shape set the engine had been tuned against (v2) was retired and a fresh one (v3: 13 Haskell and 12 Nix families, 300 cases, written without reading the engine's rules) was measured exactly once, with nothing tuned afterwards. On it: Haskell SAST precision 75.0% / recall 50.0% / F1 60.0% (24 TP, 8 FP, 24 FN); Haskell taint 84.6% / 73.3% / 78.6%; Nix config-SAST 100% / 87.9% / 93.5%; Nix config-taint precision 60.0% (all four false positives are duplicate findings on scripts the new set's author wrote with two sinks each, an authoring artefact, not an engine fault). The previous set had scored the Haskell rows 91.7% and 93.3% after being tuned against. All four generalization rows are now below target and the published support tables say so. The misses are concrete and listed in `docs/language-support.md` (for example session cookies set without Secure, missing ownership checks in Yesod and Servant handlers, `randomIO` as a CSRF token, `printf` logging a secret, some HDBC, Scotty `file` and `Network.HTTP.Req` shapes). Closing them is a tuning round that consumes this set; it was deliberately not done here, so the numbers stand as measured. The retired set is kept as a development set (`shape-dev-2`), which now scores 96% to 100%: that is a tuned-on set and is not a generalization number.
@@ -25,6 +69,8 @@
 
 **Tests and CI.** The PR `test` job is sharded four ways behind an aggregator that keeps the required check name `test` and fails unless every shard and the bundle check succeed (the speedup is estimated at 4 to 6 minutes against 13 to 14, and is not yet measured). The `--list-shard` output could lose its last lines when stdout was a pipe under load and turned `main` red; it now exits from the write callback. Load-sensitive tests (the sandbox process cap, the 300 ms witness probe, a lock-reaping loop that could spin past its deadline) are made deterministic without weakening what they prove; the Nix permission-model probe works in a git worktree; and the suite runs in one private temp root that it removes, instead of leaving thousands of directories behind. `scripts/ship.mjs` no longer prints a stale failure after a resumed run, prints the exact resume command and per-phase timings, and defaults the gate's temp directory to a fresh one.
 
+**Hosted release gate.** The release workflow's closure leg runs only the static closure on the hosted Linux runner, because the trust boundary is unverified there and the execution suites correctly skip; the execution closure is established by `ship.mjs` on the maintainer's host before a tag is created, and the hosted leg states that it does not claim it. The controller tests no longer depend on the untracked PRD documents (they use committed structural fixtures; the comparison with the real documents is the separate `npm run test:loop-real-prd`).
+
 **Not verified here.** On the hosted Linux runner a process cap of 1 did not refuse a command (the new refusing-direction assertion in `test/sandbox.test.js` failed there while passing on macOS, and the cause was not established), so that assertion now runs on macOS only; Linux process-cap enforcement is not asserted by any test. The sharded CI job and the aarch64 NixOS changes have not yet run as real CI; the unseen-set misses above are not fixed; the live nixpkgs feed has only been exercised against a fake feed plus a few real requests.
 
 ## 0.160.0 - a faster, sturdier release path: a parallel hosted gate, a one-command release orchestrator, and fixes for the failing workflow runs

package/bin/agentic-security.js

@@ -175,6 +175,12 @@ Commands:
   scan-baseline --current <f> --previous <f>
                                Finding-level diff between two scan JSON outputs.
                                Reports added / removed / changed findings.
+  boundaries --from <dir> [--findings <last-scan.json>] [--environment <name>] [--out <file>] [--json]
+                               Build a deployment boundary graph from local configuration
+                               (and optional sanitized traces) and attach a boundary context
+                               to each finding of a scan result. Read-only, local files only.
+                               Off by default: set AGENTIC_SECURITY_ASSURANCE_DEPLOYMENT_BOUNDARIES=1.
+                               Exit: 0 ok, 1 failed, 2 usage, 3 feature off or blocked.
   explore [path] [--port <n>] [--keep-open]
                                Start a local, read-only server over an
                                already-scanned lineage graph (run
@@ -216,6 +222,30 @@ Commands:
   federate list [path] [--output <file>]
                                List every declared cross-repo link, reporting
                                whether each side still resolves.
+  invariants export --invariant <file> --fixture <dir> [--ledger <file>] [--commit <sha>] [--seed <n>] [--output <file>]
+                               Reproducible bounded business-logic scenario package for
+                               one contract (no fixture source, no secrets, not a proof
+                               of correctness). Needs the invariant-scenarios feature.
+  invariants coverage --invariant <file> | --invariants-dir <dir> [--ledger <file>] [--results <file>] [--json]
+                               Bounded business coverage: approved vs proposed contracts,
+                               exercised actors/states/transitions, explicit gaps.
+  portfolio progress --store <file> [--budgets <file>] [--findings <file>] [--blocking-severity <s>] [--json]
+                               Coverage-aware portfolio progress: verified units, blocked/failed/stale
+                               units, repository coverage, remaining budget, pending human review and
+                               stale workers. A finished controller is never reported as passed.
+                               Needs the portfolio-assurance feature.
+  portfolio retention plan|apply|verify-log --records <file> --root <dir> [--policy <file>] [--holds <file>] [--store <file>] [--log <file> --actor <name>]
+                               Retention by class (replay evidence, metadata, model traces, secrets)
+                               with legal holds; a required current receipt is never deleted and
+                               every deletion is logged first.
+  portfolio backend probe --mode local|shared --dir <dir>
+                               Is a storage backend usable? An unavailable shared backend is the
+                               typed blocked state; nothing falls back to a local write.
+  portfolio export --store <file> --out <file> | portfolio import --from <file> --mode <m> --dir <d>
+                               One self-checking, secret-free state file for an air-gapped machine.
+  invariants regress <artifact.json>
+                               Re-execute a verified-repair regression artifact from the
+                               file alone. Exit 0 passed, 1 failed, 3 not run.
   remediation open [path] --assessment <impact-report.json> --owner <id> --due <YYYY-MM-DD>
                                --control <text> --required-evidence <flowId,...>
                                [--id <itemId>] [--snapshot <commit>] [--allow-manual-attestation]
@@ -2290,7 +2320,7 @@ async function cmdVerify(args) {
     process.env.AGENTIC_SECURITY_VERIFY_LIVE = '1';
     process.env.AGENTIC_SECURITY_VERIFY_TARGET = targetFlag;
   }
-  const { annotateVerifierVerdicts, verifierCoverageSummary, recordVerifierRun } = await import('../src/posture/verifier.js');
+  const { annotateVerifierVerdicts, verifierCoverageSummary, recordVerifierRun, verifierVerificationRecords } = await import('../src/posture/verifier.js');
   const filter = args.flags.finding ? findings.filter(f => f.id === args.flags.finding || f.stableId === args.flags.finding) : findings;
   if (!filter.length) {
     console.error(`No matching findings (use --finding <id>).`);
@@ -2319,7 +2349,13 @@ async function cmdVerify(args) {
   // Adversarial premortem Q1: a durable record that a security assessment of
   // findings actually happened, so module:verifier has something real to
   // point at (see verifier.js's recordVerifierRun header comment).
-  recordVerifierRun(scanRoot, { findingCount: filter.length, live: liveFlag, target: targetFlag || null, summary: sum });
+  // X-201: one version-1 verification record per verified finding, in the durable run record (never on the findings,
+  // which are written back to last-scan.json below).
+  const { headCommit } = await import('../src/posture/verification/emit.js');
+  recordVerifierRun(scanRoot, {
+    findingCount: filter.length, live: liveFlag, target: targetFlag || null, summary: sum,
+    verificationRecords: verifierVerificationRecords(filter, { commit: headCommit(scanRoot) }),
+  });
   if (args.flags.verbose || args.flags.finding) {
     for (const f of filter) {
       console.log(`  ${f.file}:${f.line}  ${f.vuln}`);
@@ -3289,6 +3325,9 @@ async function cmdVerifyAttestation(args) {
   console.log('');
   console.log(`  proves:        ${bundle.proves}`);
   console.log(`  does NOT prove: ${bundle.doesNotProve}`);
+  // CORE-003.AC03: who vouches. Informational only; the exit code is unchanged.
+  console.log(`  trust basis:   ${r.trustBasis}${r.issuer ? ` (issuer ${r.issuer.id})` : ''}`);
+  console.log(`  ${r.trustNote}`);
   return 0;
 }
 
@@ -3889,6 +3928,48 @@ Do not suppress anything you are not certain is a false positive. When in doubt,
   return 0;
 }
 
+// `agentic-security boundaries --from <dir> [--findings <last-scan.json>] ...` (differentiation PRD, X-308 wiring).
+// Builds a deployment boundary graph from LOCAL configuration (and optional sanitized traces) and attaches a boundary context to
+// each finding of an existing scan result. Read-only and local: no network, no scan, no execution of configuration; the only
+// write is the report file named by --out. Behind the `deployment-boundaries` feature, which is OFF by default.
+// Exit codes: 0 report produced; 1 failed (invalid or unreadable input, ingest refused, --out refused); 2 usage error;
+// 3 the feature is disabled, blocked or unsupported on this platform (nothing was read).
+async function cmdBoundaries(args) {
+  const f = args.flags;
+  const usage = 'Usage: agentic-security boundaries --from <dir> [--findings <last-scan.json>] [--environment <name>] [--repository <name>] [--revision <sha>] [--root <project>] [--out <file>] [--json] [--now <iso>]';
+  if (typeof f.from !== 'string' || !f.from) { console.error(usage); return 2; }
+  for (const k of ['findings', 'environment', 'repository', 'revision', 'out', 'now', 'root']) {
+    if (f[k] !== undefined && (typeof f[k] !== 'string' || !f[k])) { console.error(`agentic-security boundaries: --${k} needs a value\n${usage}`); return 2; }
+  }
+  const scanRoot = path.resolve(f.root || '.');
+  const { resolveAssuranceConfig } = await import('../src/posture/assurance/config.js');
+  const { runBoundaries, renderBoundariesText } = await import('../src/lineage/deployment/boundaries-run.js');
+  const config = resolveAssuranceConfig({ scanRoot });
+  const result = runBoundaries({
+    config, from: path.resolve(f.from), environment: f.environment || 'prod', repository: f.repository || null, revision: f.revision || null,
+    findingsFile: f.findings ? path.resolve(f.findings) : null, verifySignature: _verifyLastScan, now: f.now,
+  });
+  if (result.status === 'disabled' || result.status === 'blocked' || result.status === 'unsupported') {
+    console.error(`agentic-security boundaries: not run (${result.status}): ${result.reason}`);
+    if (result.status === 'disabled') console.error('The deployment-boundaries feature is off by default. Enable it for one run with AGENTIC_SECURITY_ASSURANCE_DEPLOYMENT_BOUNDARIES=1.');
+    return 3;
+  }
+  if (result.status !== 'ok') { console.error(`agentic-security boundaries: ${result.reason}`); return 1; }
+  const report = result.report;
+  const body = f.json ? `${JSON.stringify(report, null, 2)}\n` : renderBoundariesText(report);
+  if (f.out) {
+    const outPath = path.resolve(f.out);
+    try {
+      let st = null;
+      try { st = fs.lstatSync(outPath); } catch { /* absent */ }
+      if (st && !st.isFile()) throw new Error('the output path is a symbolic link or not a regular file');
+      fs.writeFileSync(outPath, body, { mode: 0o644 });
+    } catch (e) { console.error(`agentic-security boundaries: cannot write ${outPath}: ${e.message}`); return 1; }
+    console.log(`agentic-security boundaries: wrote ${outPath}`);
+  } else writeStdout(body);
+  return 0;
+}
+
 // `agentic-security explore [path] [--port <n>] [--keep-open]` — Milestone 3,
 // sub-project Server, increment 1. Starts a local, read-only, loopback-only
 // HTTP server over an already-built, signed lineage graph
@@ -7064,6 +7145,7 @@ async function main() {
         startLspServer();
         return;
       }
+      case 'boundaries': process.exit(await cmdBoundaries(args));
       case 'explore':  process.exit(await cmdExplore(args));
       case 'dataflow': {
         const sub = args._[1];
@@ -7141,6 +7223,20 @@ async function main() {
         }
         break;
       }
+      case 'portfolio': {
+        // X-707, X-708: coverage-aware portfolio progress, evidence retention and offline operation. The logic is in
+        // src/posture/portfolio/cli.js so tests run it without spawning this file. Off unless `portfolio-assurance` is on.
+        const { runPortfolioCommand } = await import('../src/posture/portfolio/cli.js');
+        process.exit(await runPortfolioCommand(args));
+        break;
+      }
+      case 'invariants': {
+        // X-405 to X-407: scenario export, bounded coverage and regression-artifact replay. The logic is in
+        // src/posture/invariants/cli.js so tests run it without spawning this file.
+        const { runInvariantsCommand } = await import('../src/posture/invariants/cli.js');
+        process.exit(await runInvariantsCommand(args));
+        break;
+      }
       case 'federate': {
         // NOT a `dataflow` subcommand — this writes operator-declared
         // config (cross-repo-links.json), never the scanned graph. Same