@provos/ironcurtain 0.11.0 → 0.13.0

package/dist/workflow/workflows/vuln-discovery/README.md

@@ -0,0 +1,54 @@
+# Vulnerability Discovery
+
+An orchestrator-driven workflow that points a Docker-isolated `claude-code` agent at a body of code, **builds tiered instrumented harnesses, and tries to execute its way to a confirmed vulnerability** — analysis → harnessing → discovery → triage → report, with human gates whenever the machine gets stuck or finishes.
+
+Run it from the web UI (**Start Workflow → `vuln-discovery`**) or the CLI:
+
+```bash
+ironcurtain workflow start vuln-discovery \
+  "find a memory-corruption bug reachable from a crafted H.264 stream" \
+  --workspace ~/src/ffmpeg
+```
+
+Point `--workspace` at a checkout of the code under investigation. The task description carries the **scope, vulnerability class, and threat model**; a one-liner like `"find a vulnerability in libavcodec/h264_slice.c"` is enough to start, since the agent prompts supply the methodology. Add detail to steer the hunt.
+
+> **Requires Docker.** This workflow only runs in Docker Agent Mode (`--network=none`); there is no builtin-mode fallback. Run `ironcurtain doctor` first if you're unsure your environment is ready. For a fresh-checkout walkthrough (build, daemon, web UI, non-Anthropic models, troubleshooting) see [`docs/vuln-discovery-onboarding/README.md`](https://github.com/provos/ironcurtain/blob/master/docs/vuln-discovery-onboarding/README.md).
+
+## What it does
+
+The orchestrator sits at the center and decides what to do next each round, reading and updating the investigation journal. Around it, the agents move a hypothesis from structural understanding to an executed, triaged finding. All artifacts land under `.workflow/` in the workspace.
+
+| Phase | State(s)                                   | Role                                                                                                             | Output                                          |
+| ----- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| 1     | `analyze`                                  | Code analyst — maps call chains, entry points, build system, trust boundaries                                    | `.workflow/analysis/analysis.md`                |
+| —     | `orchestrator`                             | Strategist — picks the next state, enforces budget, owns the journal                                             | `.workflow/journal/journal.md`                  |
+| 2     | `harness_design` → `harness_design_review` | Architect + LLM reviewer — spec an instrumented, tiered harness                                                  | `.workflow/harness_design/`                     |
+| 3     | `harness_build` → `harness_validate`       | Engineer + verifier — implement the harness, confirm it runs and produces coverage                               | `.workflow/harness_build/`, `harness_validate/` |
+| 4     | `discover` (+ `differential_validate`)     | Researcher — hypothesis-driven search using the harness; diagnose isolated-vs-live divergence                    | `.workflow/discoveries/findings.h*.md`          |
+| 5     | `triage`                                   | Independent reproducer — re-prove each finding and assess severity                                               | `.workflow/triage/triage.h*.md`                 |
+| 6     | `conclude` → `review`                      | Report writer + LLM reviewer — assemble the final report, catch scope drift and evidence/headline contradictions | `.workflow/report/report.md`                    |
+
+## Human gates
+
+Four gates pause the run for your decision. Each presents the relevant artifacts (journal, analysis, designs, reports) and accepts **APPROVE** (continue), **FORCE_REVISION** (loop back — your feedback is routed verbatim into the next agent's prompt, so brief it like an orchestrator), or **ABORT**.
+
+- **`human_escalation`** — the orchestrator detected a stall (same state 3+ times, contradictory results, or no clear next direction). Give it another round, redirect it, or stop.
+- **`harness_design_escalation`** — the design-review loop rejected the design 3× in a row. Accept the design as-is, redirect, or stop.
+- **`harness_validate_escalation`** — the validate loop rejected the build 4× in a row. Accept the harness despite validation failures, redirect, or stop.
+- **`report_review`** — the investigation reached `complete` and the final report is ready. Approve it, send it back (your assessment overrides the agent's — e.g. dispute a "mitigated" verdict and it re-investigates at a higher tier), or discard.
+
+## The orchestration loop
+
+Unlike a fixed pipeline, the **orchestrator** re-routes after every round based on the journal: forward when a harness validates and findings hold, back to re-design or re-discover when they don't. The loop is bounded by `maxRounds` (**12**) and `maxSessionSeconds` (**10800** = 3 hours). When either limit or a stall is hit, control surfaces to a human gate rather than spinning — it never loops forever.
+
+## At a glance
+
+- **Mode:** Docker (`claude-code` agent, `--network=none`, shared container)
+- **Model:** `anthropic:claude-opus-4-8`
+- **Persona:** `global` for every agent state
+- **Caps:** 12 rounds · 3-hour session budget
+- **Skills:** `memory-safety-c-cpp`, `harness-design-fuzzing`, `vulnerability-triage` (co-packaged under `skills/`)
+- **Artifacts:** `analysis`, `journal`, `harness_*`, `discoveries`, `triage`, `report` — all under `.workflow/`
+- **Terminal states:** `done` (report approved) · `aborted` (stopped at a gate)
+
+> Tip: the more precisely the task states the **threat model** (who the attacker is, how input reaches the code), the less the analyst has to guess. "Memory corruption reachable from an untrusted network packet" steers the whole run; "find bugs" does not. To run bigger targets past the default caps, copy the whole `vuln-discovery/` directory (it carries the skills it needs) into `~/.ironcurtain/workflows/` and raise the limits there.

package/dist/workflow/workflows/vuln-discovery/skills/harness-design-fuzzing/SKILL.md

@@ -61,13 +61,15 @@ Use Tier 3 when the bug depends on initialization sequences, global state, runti
 
 The harness must FUZZ, not unit-test. For each swept variable (hypothesis inputs for trigger-driven, dispatch axes for coverage-driven), the design must specify:
 
-- **Sweep range.** The full range of values to iterate over. Cover the entire representable range of the type, not just "a few specific values." For wide ranges, specify dense sampling near type boundaries (min, max, zero, `2^N - 1` for each relevant N, sign-flip points) plus sparse sampling elsewhere. For coverage-driven dispatch axes, the range is the full set of dispatch values plus their realistic combinations.
+- **Sweep range.** The full range of values to iterate over. Cover the entire representable range of the type, not just "a few specific values." For wide ranges, specify dense sampling near type boundaries (min, max, zero, `2^N - 1` for each relevant N, sign-flip points) plus sparse sampling elsewhere. When the variable feeds an allocation size through a product or other multi-term arithmetic, also sample values whose wrapped result is *small but positive*: these keep the consumer's loop/index bound large while the undersized allocation succeeds, whereas the value that wraps exactly to zero is usually intercepted by a separate zero-size guard. For coverage-driven dispatch axes, the range is the full set of dispatch values plus their realistic combinations.
 - **Search strategy.** Exhaustive enumeration if the space is < 100M combinations; boundary-dense + random sampling otherwise; coverage-guided fuzzer for large or structured input spaces.
 - **Observables.** At each input value, what does the harness record? Stored value in the target buffer, result of the bounds check at `<file>:<line>`, return value of the target function, sanitizer error, canary state, dispatch arm hit. Be specific by site.
 - **Positive-finding condition.** What pattern in the observables confirms the design's claim? For trigger-driven: be specific — not "a crash happens" but "the bounds check at `<file>:<line>` evaluates true when the input value exceeds the buffer's allocated size." For coverage-driven: "any sanitizer error within the named code region" is acceptable, but the region must be concrete.
 
 The design specifies input variables and ranges. The implementer drives the sweep. Do NOT prescribe individual "Test A / Test B / Test C" scenarios with fixed values — that's unit testing and will miss the actual boundary.
 
+**Per-input cost bound.** A coverage-guided fuzzer needs many iterations per second to work. The design must keep per-input cost bounded: cap input size (libFuzzer `-max_len`, AFL++ `-G`), and keep the fuzz entry point free of full re-initialization, process spawns, or multi-connection sweeps — move one-time setup behind a `call_once` / singleton. If an oracle genuinely needs a many-connection or many-iteration measurement (e.g. RSS amplification), that is a *separate* harness, not per-input work folded into the sweep.
+
 ### Multi-hypothesis bundling
 
 A trigger-driven design may scope a single hypothesis or a related set when they share input space and code region. Bundle when consolidating doesn't dilute the sweep (e.g., three integer-overflow hypotheses on the same allocator → one harness). Keep separate when input distributions conflict (one wants huge dimensions, another wants small) or observation points differ enough that one harness can't see both.
@@ -145,6 +147,8 @@ The harness MUST test against UNMODIFIED source code. Stripping a guard, weakeni
 
 A Tier-1 harness with hardening stripped tells you nothing about production outcomes. Triage anchors on what the harness demonstrated under production-equivalent conditions.
 
+Default the value-producing integer checks (overflow, shift, truncation) to **recover / warn-only mode**: aborting at the arithmetic site stops execution before any downstream undersized-allocation or out-of-bounds sink, masking the real impact and inviting a false "mitigated" verdict. Recover mode lets execution continue with the wrapped value (production behavior), so one run surfaces both the root-cause diagnostic and the sink.
+
 ## Delegate library realism
 
 Mitigation discipline applies at the link layer too. A harness that links against a project-internal stub of an upstream library produces evidence about the stub, not about production. Every stub the design introduces must be classified.
@@ -174,6 +178,7 @@ List every external dependency (sanitizer toolchain, fuzzer binary, coverage too
 - **Hand-picked positive scenarios masquerading as a sweep.** Five "boundary cases" are chosen by hand. The actual boundary in the target's arithmetic is not one of the five.
 - **Hardening stripped for "easier debugging."** ASLR off, canaries off, custom permissive allocator. The harness fires; production does not. Tells you nothing.
 - **Validator stubbed at link time.** A project-internal stub of a parser, validator, or decoder library is linked into the harness, omitting the upstream component's own validation. The harness fires; production rejects the trigger before the violation site is reached. Tells you nothing about reachability.
+- **Per-input heavyweight setup.** The harness does a full handshake, fixture rebuild, or N-connection sweep inside the fuzz entry point, so it runs at single-digit exec/s — an integration test in a loop, not a fuzzer. The feedback loop never gets enough iterations to reach boundary values. Move one-time setup to a singleton; split a measurement oracle that needs many connections into its own non-fuzzed harness.
 
 ## Design-document scope
 

package/dist/workflow/workflows/vuln-discovery/skills/memory-safety-c-cpp/SKILL.md

@@ -163,4 +163,5 @@ If any of the three cannot be answered from the artifacts alone, the finding is
 - **Round-tripped attacker input mistaken for leaked target state.** If the bytes the bug "leaks" are bytes the attacker just sent, that is not a confidentiality finding. Memory-read findings need to demonstrate adjacency — what _target_ state sits next to the affected region.
 - **Padding or zeroed memory mistaken for sensitive content.** A heap OOB read that returns NUL bytes, schema-sanitized placeholders, or default-config values has not demonstrated impact.
 - **Hardening-stripped harness vs production binary.** A harness compiled without `-D_FORTIFY_SOURCE`, without stack canaries, without ASLR, or with custom allocators tells you nothing about the production binary's behavior. The triage question is "what does the production build do under this input," not "what does my Tier-1 reproduction show."
+- **An abort at the arithmetic site mistaken for unreachability of the downstream sink.** In an overflow-into-undersized-allocation chain, a check that aborts at the overflow itself — an integer sanitizer in halt mode, or a precondition/zero-size guard that only fires when the value wraps exactly to zero — stops execution before the write, making the bug look pre-empted. Production builds wrap silently and reach the sink. Run the overflow checks in warn-only / recover mode (do not force-abort on them) so a single run surfaces both the root-cause diagnostic and the downstream sanitizer trip; or confirm on an allocation-sanitized build driven with a trigger whose wrapped value is small-positive. A "mitigated/pre-empted" verdict for an overflow-into-sink hypothesis is valid only when established on a build that lets execution continue past the overflow, not on the abort-at-overflow configuration.
 - **Variant tunnel-vision.** Reporting only the variant the harness reproduced when the underlying pattern (e.g., the same arithmetic in a sibling dispatch handler) reaches more of the surface. Every variant is its own attack surface; document each.

package/dist/workflow/workflows/vuln-discovery/skills/vulnerability-triage/SKILL.md

@@ -43,6 +43,8 @@ For each finding, the rubric below has eleven items. Skipping any one of them is
 
 6. **Production hardening.** What mitigations present in production (sanitizers, schema validators, CSP, ASLR, stack canaries, auth middleware, sandbox, rate limits, RELRO, FORTIFY_SOURCE) change the attacker's success rate? Did the experiment use the production profile or bypass it? A harness with hardening stripped tells you nothing about production outcomes — score what production does, not what the harness did.
 
+   When a mitigation table asserts a runtime cap, flag, or mode is at a particular default value in production, cite the line that *registers* that default (GObject property spec, struct initializer, constant read at startup) — not a call site that happens to leave it unset. A harness that overrides the default via the library's public API (`set_max_X(0)`, `set_strict(false)`) looks identical at the bug site to a real default of 0; the registration cite is what distinguishes them.
+
 7. **External exploitability trace.** Does the input originate from an external / untrusted source, and through what delivery channel? Name it concretely — network protocol, file upload, queue consumer, environment-variable propagation, IPC. Complete answer: a named delivery channel from an untrusted boundary to the bug site. Incomplete: "an attacker could supply input" without naming how.
 
 8. **Duplicate / CVE check.** Search the project's issue tracker, CVE databases, and changelog for the code location. Note overlap with existing fixes even when partial — a fix for one variant does not necessarily cover sibling variants.
@@ -162,6 +164,8 @@ Patterns the rubric catches that get missed in practice. These are surface-neutr
 
 - **Hardening-stripped harness scored as production.** The harness ran without ASLR, without canaries, without FORTIFY_SOURCE, with a permissive custom allocator, or with the validating middleware bypassed. The production binary intercepts the effect; the harness did not see that interception. The Achievable / Environmental score is what production does, not what the harness did.
 
+- **Harness API override mistaken for production default.** The harness called the library's public configuration API to lift a safety valve (`set_max_X(0)`, disable strict mode, suppress validation) so a latent bug becomes reachable — a legitimate research move. The mitigations table then asserts that the *production* default is the lifted value, conflating "the harness set it to 0" with "the default is 0". Distinct from compiler-hardening stripping: this is the library's own runtime configuration, and the registration site (property spec, initializer) is the ground truth, not the call-site override.
+
 - **Theoretical ceiling promoted to demonstrated severity by rewording.** "This pattern *could* yield RCE" gets quoted, then rewritten without the hedge, then cited as "demonstrated RCE" two paragraphs later. The rubric's reproduction and effect-realism items refute this; the hedging-elimination rule names it.
 
 - **Variant tunnel-vision.** The harness reproduced one variant of the underlying pattern; the finding reports only that variant. When the same arithmetic / lifetime / dispatch shape reaches sibling variants on the same surface, those are findings in their own right. Document each, even when the experiment exercised only one.

package/dist/workflow/workflows/vuln-discovery/workflow.yaml

@@ -6,7 +6,7 @@ settings:
   mode: docker
   dockerAgent: claude-code
   sharedContainer: true
-  model: anthropic:claude-opus-4-7
+  model: anthropic:claude-opus-4-8
   maxRounds: 12
   maxSessionSeconds: 10800
   unversionedArtifacts:
@@ -162,11 +162,12 @@ states:
 
         **If discover returned `approved` (confirmed):** route to `triage` if the evidence is solid, or back to `discover` for more evidence if it is thin.
 
-        **If discover returned `blocked` (mitigated or exhausted):** the "mitigated" claim is authoritative only when BOTH of:
+        **If discover returned `blocked` (mitigated or exhausted):** the "mitigated" claim is authoritative only when ALL of:
         - The tier matched the hypothesis scope — cross-component hypotheses require Tier 2+.
         - Evidence shows execution, not reasoning: coverage of the mitigation code AND a completed input sweep over the hypothesis's value range (fuzzing for value-dependent claims, bounded enumeration for discrete claims).
+        - The mitigation was exercised, not just present. If non-impact is attributed to an invariant the harness had to disable to reach the site (a concurrency/serialization contract, an upstream guard, a runtime/allocator check, or a first-abort that shadows a later sink), the claim holds only if discover ran the trigger under a configuration where that invariant is present and showed the effect absorbed there. An invariant-only mitigation backed by source reading is the masked-finding pattern — non-terminal.
 
-        If the evidence is text-only ("the code looks safe"), re-route to `discover` to exercise the mitigation, or to `harness_design` at a higher tier if the harness cannot exercise it.
+        If the evidence is text-only ("the code looks safe") or the mitigation rests on an un-exercised invariant, re-route to `discover` to exercise it under an invariant-present config, or to `harness_design` at a higher tier if the harness cannot. If no invariant-present config that still reaches the site can be built, treat the evidence as insufficient and keep the hypothesis open — do NOT record it as a terminal `harness-tested-and-rejected`; route to `harness_design` for an alternative reachability approach, or defer the hypothesis with an explicit reason. ("Insufficient" here describes the evidence; it is not a routing verdict to emit.)
 
         **If discover returned `rejected` (couldn't run):**
         - Coverage shows the target function IS reached but the condition doesn't fire → `differential_validate` (values need adjustment for the live context: protocol encoding, byte order, framing).
@@ -330,7 +331,7 @@ states:
 
       Do NOT include:
       - Full C/Python/etc. source code for the harness
-      - Build scripts or compile commands with full flag lists (reference them abstractly: "compile with ASAN+UBSAN")
+      - Build scripts or compile commands with full flag lists (reference them abstractly: "compile with ASAN+UBSAN, integer checks in recover/warn-only mode")
       - Test execution results or tables of "expected outcomes" — you haven't run anything yet
 
       DO include:
@@ -485,6 +486,8 @@ states:
 
       The harness should be invocable as a CLI tool or script. The discovery agent needs to: start a session, perform multiple steps, observe coverage, and reset cleanly.
 
+      **Bounded harness execution (required).** Every command that runs the built harness — reset check, smoke/baseline run, instrumentation probe, any burst — MUST be wrapped in a hard-kill wall-clock guard: `timeout -s KILL <seconds> <command>`. Plain `timeout` sends a catchable SIGTERM that a wedged harness can defer or ignore; only `-s KILL` (or `-k`) guarantees termination. This is tool-agnostic — it holds whether the harness is a fuzzer, a bounded enumerator, an analyzer, or a one-shot driver.
+
       **Instrumentation verification (required before approved).** Confirm fuzzer-feedback is present on the target, not only the harness. Method depends on the mechanism:
       - Compile-time (libFuzzer / sanitizer-coverage): `nm` / `readelf` the target archive and expect symbols like `__sanitizer_cov_trace_pc_guard` in the target's object files.
       - Compile-wrapper (AFL++): instrumented objects contain `__afl_area_ptr`; `afl-showmap` on a baseline reports non-trivial map density (≫100 edges).
@@ -523,15 +526,17 @@ states:
       2. **Linkage audit (gating).** Run `ldd` (Linux), `otool -L` (macOS), or the platform equivalent against the test binary. Confirm no shared library resolves to a project-internal stub directory (typical names: `*-stub/`, `*_mock/`, `mock-*/`, `fake-*/`). If linkage resolves to a project-internal stub of any component performing trust-boundary validation in production (parser, validator, decoder, signature checker, schema validator), return `rejected_design` regardless of coverage and crash signals. Cite the specific link path and stub component in the rejection. The linkage check is gating: it runs before the coverage and crash gates and short-circuits on failure.
       3. **Baseline run.** Run the harness with a simple benign input. Verify it exits without errors.
       4. **Target function reached.** Run the harness coverage command. Verify the **target function** (not just the target file) appears with non-zero hits. If the file has coverage but the function does not, the call chain is broken — fail.
-      5. **Fuzzer-feedback reach (load-bearing).** Run a short representative fuzz burst (30–60s) from the seed corpus. Capture the fuzzer's own reported coverage metric:
+      5. **Fuzzer-feedback reach (load-bearing).** Run a short representative fuzz burst (30–60s) from the seed corpus. Run it in the FOREGROUND under a hard kill guard — `timeout -s KILL <burst+30s>` wrapping the binary — and pass the fuzzer's own watchdogs (libFuzzer: `-max_total_time=<burst> -timeout=20 -rss_limit_mb=4096`; AFL++: the `-V` / `-t` / `-m` equivalents). Plain `timeout` sends a catchable SIGTERM that a slow fuzzer defers between iterations — it will not stop a wedged burst. Do NOT background the burst and poll with a `pgrep`/`sleep` loop: `pgrep -af <name>` matches the poll command's own arguments, so the loop never exits. Capture the fuzzer's own reported coverage metric:
          - libFuzzer (also the tools that wrap its output: jazzer.js, atheris, cargo-fuzz, Jazzer): stderr prints `#N ... cov: C ft: F`. Record `C`.
          - AFL++: `afl-fuzz` reports `map density` / `edges found`; `afl-showmap` on a sample prints non-zero map entries. Record the edge count.
          - For any other tool, the design must name the exact metric field (see harness_design coverage-instrumentation rules). If the design does not name it, that is a design defect — route `rejected_design` with a directive "design.md must specify the fuzzer-feedback metric field name for the chosen tool."
-         Fail approval unless BOTH:
+         Fail approval unless ALL of:
          (a) Target-code fuzzer-feedback count ≥ **1000** (default; configurable via directive). A count in the tens is the signature of wrapper-only instrumentation. For tools reporting in different units, interpret the threshold as "several orders of magnitude larger than a thin wrapper's footprint" and state the equivalent number used.
          (b) Audit-coverage line coverage of the target source file ≥ **20%** (default; configurable via directive) after the burst.
+         (c) Burst throughput is not pathological: record `exec/s` and the slowest-unit time. `exec/s` in the single digits, or any single unit exceeding ~10s, means the harness is too slow to fuzz — a per-input heavyweight-setup defect that both wedges the burst's own time limit and would wedge `discover`.
          If (a) fails: target code was not instrumented for fuzzer feedback — diagnose build vs. design.
          If (b) fails but (a) passes: seed corpus is too narrow — route to `harness_design` for seed-corpus revision.
+         If (c) fails: route `rejected_design` with directive "cap input size (`-max_len`) and move per-input heavyweight setup (full re-init, process spawn, multi-connection sweep) out of the fuzz entry point."
       6. **Stateful session sanity.** If the harness supports multi-step sessions, run a short sequence; verify state persists.
       7. **Branch-level audit coverage exists.** Confirm the audit tool reports branch data, not just line counts.
 
@@ -596,7 +601,7 @@ states:
       The orchestrator's directive tells you what to test. Use the harness to:
 
       1. **Design an input sequence** that exercises the hypothesized code path. Use the analysis's function catalog for guidance on types, boundaries, and assumptions.
-      2. **Send it through the harness** and observe results. Read coverage to see which lines and branches were hit. Check for sanitizer output, crashes, and invariant violations.
+      2. **Send it through the harness** and observe results. Read coverage to see which lines and branches were hit. Check for sanitizer output, crashes, and invariant violations. If you run ANY work in the background (fuzz campaign, build, etc.), wait on the launched PID (`cmd & PID=$!; wait "$PID"`); never poll with a `pgrep -f <name>`/`sleep` loop (`pgrep -f` matches the waiter's own command line and your prompt-bearing agent process, so the loop never exits) and never poll a hardcoded log/output path you did not capture from that same launch.
       3. **Refine or pivot.** If coverage shows you missed the target path, adjust inputs to hit the right branch. If you reached it with no violation, try variations before moving to a new hypothesis.
       4. **Repeat systematically.** Work through the hypotheses in the orchestrator's directive.
 
@@ -608,7 +613,7 @@ states:
 
       - **approved**: An exploitable condition fired — sanitizer error, controlled crash, invariant violation, or direct evidence the hypothesized bug triggered. Document the reproduction input, coverage proof, and severity.
       - **rejected**: The harness is insufficient — can't reach the target, missing protocol feature, broken infrastructure.
-      - **blocked**: Hypothesis did not fire despite a completed search. You may only return `blocked` if (a) coverage shows the target code was executed, AND (b) you swept the input range relevant to the hypothesis — fuzzing for value-dependent claims (sizes, offsets, indices, counters), bounded enumeration for discrete claims (protocol states, flag combinations, auth paths). "I read the code and it looks mitigated" is not `blocked` — it's `rejected` with a request to redesign the harness. If neither fuzzing nor enumeration applies to this hypothesis, name the reason explicitly in your findings doc.
+      - **blocked**: Hypothesis did not fire despite a completed search. You may only return `blocked` if (a) coverage shows the target code was executed, AND (b) you swept the input range relevant to the hypothesis — fuzzing for value-dependent claims (sizes, offsets, indices, counters), bounded enumeration for discrete claims (protocol states, flag combinations, auth paths). "I read the code and it looks mitigated" is not `blocked` — it's `rejected` with a request to redesign the harness. If neither fuzzing nor enumeration applies to this hypothesis, name the reason explicitly in your findings doc. **Invariant-only mitigations are not `blocked`.** If you attribute non-impact to an invariant your harness had to disable to reach the site — a lock/serialization or single-threaded dispatch contract, an upstream guard, a runtime/allocator check, or an earlier sanitizer abort that prevents reaching a downstream sink — you may return `blocked` only if you ALSO ran the trigger under a configuration where that invariant is present and showed the effect absorbed there. Disabling the invariant to reach the site and then citing it as the mitigation is circular; if you cannot build an invariant-present config that still reaches the site, return `blocked` only for the part you exercised and name the un-exercised invariant explicitly.
 
       Write per-hypothesis findings to `.workflow/discoveries/findings.<id>.md` where `<id>` is the orchestrator's hypothesis ID — e.g. `findings.h1.md`, `findings.h2.md`. Do not collapse hypotheses into one file. Append after each experiment (hypothesis, input, harness command, result) before starting the next one — do not batch writes to the end, so a crash or rate-limit preserves the round's work. If a hypothesis's findings file already exists from a prior run, read it first and skip experiments whose results are already recorded; do not re-read other hypotheses' files unless the directive scopes you to them.
     inputs:

package/docker/Dockerfile.base

@@ -34,6 +34,28 @@ RUN mkdir -p /workspace /etc/ironcurtain /run/ironcurtain && \
 
 RUN npm install -g node-gyp
 
+# Rust toolchain (rustc, cargo) + cargo-fuzz for the vuln-discovery workflow.
+# devcontainers/universal does NOT ship rustup (verified by an x86_64 build
+# failing with `rustup: not found`), so install it explicitly rather than
+# assuming it is present — same self-contained approach as
+# Dockerfile.base.arm64. Containers run with --network=none, so the toolchain
+# and the nightly channel that cargo-fuzz invokes (libFuzzer's unstable -Z
+# flags) must be baked in. Installed system-wide under /opt/rust so the
+# codespace user inherits it via ENV.
+ENV RUSTUP_HOME=/opt/rust/rustup
+ENV CARGO_HOME=/opt/rust/cargo
+ENV PATH=/opt/rust/cargo/bin:$PATH
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | \
+        sh -s -- -y --no-modify-path --default-toolchain stable --profile minimal \
+            --component rust-src && \
+    rustup toolchain install nightly --profile minimal --component rust-src && \
+    cargo install cargo-fuzz && \
+    rm -rf /opt/rust/cargo/registry /opt/rust/cargo/git && \
+    chmod -R a+rX /opt/rust && \
+    chown -R codespace:codespace /opt/rust/rustup /opt/rust/cargo && \
+    printf 'export RUSTUP_HOME=/opt/rust/rustup\nexport CARGO_HOME=/opt/rust/cargo\nexport PATH=/opt/rust/cargo/bin:$PATH\n' \
+        > /etc/profile.d/rust.sh
+
 # Playwright + Chromium: pre-install so containers work with --network=none.
 # Install system deps as root, then browser to a shared path.
 ENV PLAYWRIGHT_BROWSERS_PATH=/opt/playwright-browsers

package/docker/Dockerfile.base.arm64

@@ -60,6 +60,24 @@ RUN apt-get update && apt-get install -y --no-install-recommends python3-pip &&
 
 RUN npm install -g node-gyp
 
+# Rust toolchain (rustc, cargo) + cargo-fuzz for the vuln-discovery workflow.
+# Containers run with --network=none, so the toolchain and the nightly
+# channel that cargo-fuzz invokes must be baked into the image. Installed
+# system-wide under /opt/rust so the codespace user inherits it via ENV.
+ENV RUSTUP_HOME=/opt/rust/rustup
+ENV CARGO_HOME=/opt/rust/cargo
+ENV PATH=/opt/rust/cargo/bin:$PATH
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | \
+        sh -s -- -y --no-modify-path --default-toolchain stable --profile minimal \
+            --component rust-src && \
+    rustup toolchain install nightly --profile minimal --component rust-src && \
+    cargo install cargo-fuzz && \
+    rm -rf /opt/rust/cargo/registry /opt/rust/cargo/git && \
+    chmod -R a+rX /opt/rust && \
+    chown -R codespace:codespace /opt/rust/rustup /opt/rust/cargo && \
+    printf 'export RUSTUP_HOME=/opt/rust/rustup\nexport CARGO_HOME=/opt/rust/cargo\nexport PATH=/opt/rust/cargo/bin:$PATH\n' \
+        > /etc/profile.d/rust.sh
+
 # Playwright + Chromium: pre-install so containers work with --network=none.
 # Install system deps as root, then browser to a shared path.
 ENV PLAYWRIGHT_BROWSERS_PATH=/opt/playwright-browsers

package/docker/Dockerfile.claude-code

@@ -5,7 +5,9 @@ USER root
 RUN npm install -g @anthropic-ai/claude-code
 
 # The entrypoint script copies runtime-generated config into the right
-# location before the agent is invoked via docker exec.
+# location before the agent is invoked via docker exec. It sources the
+# shared UID/GID remap helper, so that must be present too.
+COPY entrypoint-uid-remap.sh /usr/local/bin/ironcurtain-uid-remap.sh
 COPY entrypoint-claude-code.sh /usr/local/bin/entrypoint.sh
 RUN chmod +x /usr/local/bin/entrypoint.sh
 

package/docker/Dockerfile.codex

@@ -0,0 +1,17 @@
+FROM ironcurtain-base:latest
+
+# Install OpenAI Codex CLI (Node.js is already in the base image).
+# Unpinned (latest), matching Dockerfile.claude-code's `npm install -g`.
+USER root
+RUN npm install -g @openai/codex
+
+# The entrypoint sources the shared UID/GID remap helper, so that must be
+# present in the image too.
+COPY entrypoint-uid-remap.sh /usr/local/bin/ironcurtain-uid-remap.sh
+COPY entrypoint-codex.sh /usr/local/bin/entrypoint.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh
+
+USER codespace
+RUN mkdir -p /home/codespace/.codex
+
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

package/docker/Dockerfile.goose

@@ -23,7 +23,9 @@ RUN apt-get update && \
     apt-get autoremove -y && \
     rm -rf /var/lib/apt/lists/*
 
-# Entrypoint: bridges UDS proxy, writes Goose config, hands off to CMD
+# Entrypoint: bridges UDS proxy, writes Goose config, hands off to CMD.
+# It sources the shared UID/GID remap helper, so that must be present too.
+COPY entrypoint-uid-remap.sh /usr/local/bin/ironcurtain-uid-remap.sh
 COPY entrypoint-goose.sh /usr/local/bin/entrypoint.sh
 RUN chmod +x /usr/local/bin/entrypoint.sh
 

package/docker/entrypoint-claude-code.sh

@@ -4,51 +4,12 @@
 # Non-PTY mode: CMD is "sleep infinity" (agent commands arrive via docker exec).
 # PTY mode: CMD is the socat PTY command from buildPtyCommand().
 
-# Runtime UID remap (Linux only).
-#
-# Issue #232: when the host UID is not 1000, bind-mounted directories
-# (e.g., the conversation-state dir) appear inside the container owned
-# by the host UID, and the baked codespace user (UID 1000) cannot write
-# to them. The host-side launcher passes `--user 0:0` plus the host
-# UID/GID via IRONCURTAIN_AGENT_UID / IRONCURTAIN_AGENT_GID so this
-# block (running as root) can renumber the codespace account to match
-# the host before dropping privileges. On macOS, Docker Desktop's
-# VirtioFS translates UIDs transparently and the env vars are not set,
-# so this block is skipped.
-if [ "$(id -u)" = "0" ] && [ -n "$IRONCURTAIN_AGENT_UID" ] && [ -n "$IRONCURTAIN_AGENT_GID" ]; then
-  if [ "$IRONCURTAIN_AGENT_UID" != "1000" ] || [ "$IRONCURTAIN_AGENT_GID" != "1000" ]; then
-    # Renumber the codespace user/group to the host UID/GID, then fix
-    # ownership on the baked home dir and workspace mount so the
-    # remapped codespace user can read/write them. Bind-mounted
-    # subdirectories (conversation state, sockets, orientation) keep
-    # their host-side ownership, which now matches codespace.
-    #
-    # FAIL HARD on remap errors. Previously these commands ran without
-    # return-code checks: if `usermod -u $HOST_UID codespace` collided
-    # with an existing image user (plausible for system UIDs like 33
-    # `www-data` or 100 `systemd-network`), the entrypoint would
-    # silently continue, then `chown` and `runuser -u codespace`
-    # would operate on the still-UID-1000 codespace — recreating the
-    # original issue #232 bug with no diagnostic. Abort with an explicit
-    # error instead so the operator sees what went wrong.
-    groupmod -g "$IRONCURTAIN_AGENT_GID" codespace || {
-      echo "[ironcurtain] groupmod failed: cannot remap codespace group to GID $IRONCURTAIN_AGENT_GID (already in use?)" >&2
-      exit 1
-    }
-    usermod -u "$IRONCURTAIN_AGENT_UID" -g "$IRONCURTAIN_AGENT_GID" codespace || {
-      echo "[ironcurtain] usermod failed: cannot remap codespace user to UID $IRONCURTAIN_AGENT_UID (already in use?)" >&2
-      exit 1
-    }
-    chown -R "$IRONCURTAIN_AGENT_UID:$IRONCURTAIN_AGENT_GID" /home/codespace /workspace || {
-      echo "[ironcurtain] chown failed: cannot reset ownership of /home/codespace and /workspace to $IRONCURTAIN_AGENT_UID:$IRONCURTAIN_AGENT_GID" >&2
-      exit 1
-    }
-  fi
-  # Re-exec the entrypoint as the (possibly remapped) codespace user.
-  # The remainder of this script runs under codespace, so $HOME and
-  # sudoers (which keys on the username) resolve correctly.
-  exec runuser -u codespace -- "$0" "$@"
-fi
+# Runtime UID/GID remap (Linux only). The shared helper renumbers the
+# baked codespace user/group to match the host UID/GID (issue #232) and
+# re-execs this entrypoint as codespace. Sourced so it shares this
+# script's $0/$@; see the helper for the full rationale (issues #232 and
+# #291). No-op on macOS and when already running as codespace.
+. /usr/local/bin/ironcurtain-uid-remap.sh
 
 # Bridge UDS to local TCP so HTTPS_PROXY works
 MITM_SOCK="/run/ironcurtain/mitm-proxy.sock"
@@ -86,6 +47,10 @@ fi
 # Auth mode determines how Claude Code gets its API credentials:
 # - OAuth mode (CLAUDE_CODE_OAUTH_TOKEN set): Claude Code reads the token from
 #   this env var directly -- no apiKeyHelper needed.
+# - OpenRouter mode (ANTHROPIC_AUTH_TOKEN set, CLAUDE_CODE_OAUTH_TOKEN not):
+#   Claude Code reads the bearer token from ANTHROPIC_AUTH_TOKEN directly, so
+#   no apiKeyHelper is written (an apiKeyHelper echoing an empty
+#   IRONCURTAIN_API_KEY would compete with the bearer token).
 # - API key mode: apiKeyHelper echoes the fake key so Claude Code skips the
 #   custom API key approval dialog entirely.
 # Always written (even on resume) because auth mode is runtime-specific.
@@ -108,6 +73,24 @@ if [ -n "$CLAUDE_CODE_OAUTH_TOKEN" ]; then
   }
 }
 EOSETTINGS
+elif [ -n "$ANTHROPIC_AUTH_TOKEN" ]; then
+  # OpenRouter mode: Claude Code reads the bearer token from ANTHROPIC_AUTH_TOKEN
+  # directly -- no apiKeyHelper (which would echo an empty IRONCURTAIN_API_KEY).
+  cat > "$HOME/.claude/settings.json" <<EOSETTINGS
+{
+  "permissions": {
+    "allow": [],
+    "deny": [],
+    "additionalDirectories": [],
+    "defaultMode": "bypassPermissions"
+  },
+  "skipDangerousModePermissionPrompt": true,
+  "skipWebFetchPreflight": true,
+  "env": {
+    "HTTPS_PROXY": "${HTTPS_PROXY}"
+  }
+}
+EOSETTINGS
 else
   # API key mode: apiKeyHelper echoes the fake key at runtime.
   cat > "$HOME/.claude/settings.json" <<EOSETTINGS

package/docker/entrypoint-codex.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# IronCurtain entrypoint for Codex CLI containers.
+
+# Runtime UID/GID remap (Linux only). Shared with the other agent
+# entrypoints so the remap logic cannot drift (issues #232 and #291).
+# Sourced so it shares this script's $0/$@; no-op on macOS and when
+# already running as codespace.
+. /usr/local/bin/ironcurtain-uid-remap.sh
+
+MITM_SOCK="/run/ironcurtain/mitm-proxy.sock"
+PROXY_PORT=18080
+if [ -S "$MITM_SOCK" ]; then
+  socat TCP-LISTEN:$PROXY_PORT,fork,reuseaddr UNIX-CONNECT:$MITM_SOCK &
+fi
+
+CODEX_CONFIG_DIR="${CODEX_HOME:-$HOME/.codex}"
+mkdir -p "$CODEX_CONFIG_DIR"
+if [ -f /etc/ironcurtain/codex-config.toml ]; then
+  cp /etc/ironcurtain/codex-config.toml "$CODEX_CONFIG_DIR/config.toml"
+fi
+if [ -n "$IRONCURTAIN_CODEX_ACCESS_TOKEN" ] && [ -n "$IRONCURTAIN_CODEX_ID_TOKEN" ]; then
+  cat > "$CODEX_CONFIG_DIR/auth.json" <<EOJSON
+{
+  "auth_mode": "chatgptAuthTokens",
+  "tokens": {
+    "id_token": "$IRONCURTAIN_CODEX_ID_TOKEN",
+    "access_token": "$IRONCURTAIN_CODEX_ACCESS_TOKEN",
+    "refresh_token": "",
+    "account_id": "${IRONCURTAIN_CODEX_ACCOUNT_ID:-ironcurtain-account}"
+  },
+  "last_refresh": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+}
+EOJSON
+  chmod 600 "$CODEX_CONFIG_DIR/auth.json"
+fi
+
+if [ -f /etc/ironcurtain/system-prompt.txt ]; then
+  export IRONCURTAIN_SYSTEM_PROMPT
+  IRONCURTAIN_SYSTEM_PROMPT=$(cat /etc/ironcurtain/system-prompt.txt)
+fi
+
+exec "$@"

package/docker/entrypoint-goose.sh

@@ -2,30 +2,11 @@
 # IronCurtain entrypoint for Goose containers.
 # Sets up proxy bridges, writes Goose config, then hands off to CMD.
 
-# Runtime UID remap (Linux only). See entrypoint-claude-code.sh for the
-# full rationale (issue #232). Skipped on macOS where Docker Desktop
-# translates UIDs and the env vars are not set.
-if [ "$(id -u)" = "0" ] && [ -n "$IRONCURTAIN_AGENT_UID" ] && [ -n "$IRONCURTAIN_AGENT_GID" ]; then
-  if [ "$IRONCURTAIN_AGENT_UID" != "1000" ] || [ "$IRONCURTAIN_AGENT_GID" != "1000" ]; then
-    # Fail hard on remap errors — see entrypoint-claude-code.sh for the
-    # full rationale. Without explicit checks, a UID collision (host UID
-    # already in use by a system user baked into the image) silently
-    # recreates the original issue #232 bug.
-    groupmod -g "$IRONCURTAIN_AGENT_GID" codespace || {
-      echo "[ironcurtain] groupmod failed: cannot remap codespace group to GID $IRONCURTAIN_AGENT_GID (already in use?)" >&2
-      exit 1
-    }
-    usermod -u "$IRONCURTAIN_AGENT_UID" -g "$IRONCURTAIN_AGENT_GID" codespace || {
-      echo "[ironcurtain] usermod failed: cannot remap codespace user to UID $IRONCURTAIN_AGENT_UID (already in use?)" >&2
-      exit 1
-    }
-    chown -R "$IRONCURTAIN_AGENT_UID:$IRONCURTAIN_AGENT_GID" /home/codespace /workspace || {
-      echo "[ironcurtain] chown failed: cannot reset ownership of /home/codespace and /workspace to $IRONCURTAIN_AGENT_UID:$IRONCURTAIN_AGENT_GID" >&2
-      exit 1
-    }
-  fi
-  exec runuser -u codespace -- "$0" "$@"
-fi
+# Runtime UID/GID remap (Linux only). Shared with the other agent
+# entrypoints so the remap logic cannot drift (issues #232 and #291).
+# Sourced so it shares this script's $0/$@; no-op on macOS and when
+# already running as codespace.
+. /usr/local/bin/ironcurtain-uid-remap.sh
 
 # 1. Bridge MITM proxy UDS to local TCP (same as Claude Code entrypoint)
 MITM_SOCK="/run/ironcurtain/mitm-proxy.sock"

package/docker/entrypoint-uid-remap.sh

@@ -0,0 +1,93 @@
+# shellcheck shell=bash
+# Shared runtime UID/GID remap block for IronCurtain agent entrypoints
+# (Linux only). SOURCED — not executed — from each agent's
+# /usr/local/bin/entrypoint.sh so the three adapters (claude-code, goose,
+# codex) cannot drift apart. Issue #291 was caused by exactly that drift:
+# only the goose entrypoint got the GID-collision fix in the field report.
+#
+# Sourcing contract:
+#   - This file is `source`d near the top of the parent entrypoint, so
+#     `$0` and `$@` resolve to the PARENT entrypoint's path and args. The
+#     `exec runuser -u codespace -- "$0" "$@"` below therefore re-execs the
+#     parent entrypoint (/usr/local/bin/entrypoint.sh) with its original
+#     args — which is what we want. `exec` replaces the current process even
+#     when reached from a sourced file.
+#   - After the re-exec, the parent entrypoint runs again and sources this
+#     file again, but `id -u` is no longer 0, so the whole block is a no-op
+#     the second time through and execution falls past it to the rest of the
+#     parent entrypoint (now running as codespace).
+#
+# Issue #232: when the host UID is not 1000, bind-mounted directories
+# (e.g., the conversation-state dir) appear inside the container owned by
+# the host UID, and the baked codespace user (UID 1000) cannot write to
+# them. The host-side launcher passes `--user 0:0` plus the host UID/GID via
+# IRONCURTAIN_AGENT_UID / IRONCURTAIN_AGENT_GID so this block (running as
+# root) can renumber the codespace account to match the host before
+# dropping privileges. On macOS, Docker Desktop's VirtioFS translates UIDs
+# transparently and the env vars are not set, so this block is skipped.
+if [ "$(id -u)" = "0" ] && [ -n "$IRONCURTAIN_AGENT_UID" ] && [ -n "$IRONCURTAIN_AGENT_GID" ]; then
+  if [ "$IRONCURTAIN_AGENT_UID" != "1000" ] || [ "$IRONCURTAIN_AGENT_GID" != "1000" ]; then
+    # Renumber the codespace user/group to the host UID/GID, then fix
+    # ownership on the baked home dir and workspace mount so the remapped
+    # codespace user can read/write them. Bind-mounted subdirectories
+    # (conversation state, sockets, orientation) keep their host-side
+    # ownership, which now matches codespace.
+    #
+    # GID and UID collisions are handled asymmetrically because they mean
+    # different things:
+    #
+    #   - A GID collision is BENIGN. It just means the host's primary group
+    #     already exists inside the image (issue #291: the universal
+    #     devcontainer image bakes `users:x:100`, and on nixos/WSL and many
+    #     Linux desktops the invoking user's primary group is GID 100).
+    #     Sharing a group is ordinary Unix, so we point codespace's PRIMARY
+    #     group at the existing group via `usermod -g` (which REQUIRES the
+    #     target GID to already exist). Only when the GID is free do we
+    #     renumber codespace's own group via `groupmod -g`. Previously this
+    #     unconditionally ran `groupmod -g`, which fails with
+    #     "GID already exists" and aborted startup.
+    #
+    #   - A UID collision is DANGEROUS and must FAIL HARD. It means the host
+    #     UID is already a distinct baked-in account (e.g. www-data=33).
+    #     Silently continuing would leave codespace at UID 1000 and then
+    #     `chown` / `runuser -u codespace` would operate on the wrong
+    #     account — recreating the original issue #232 bug with no
+    #     diagnostic. This is the regression guard from commit 2f463f3.
+    current_gid="$(id -g codespace)"
+    if [ "$current_gid" != "$IRONCURTAIN_AGENT_GID" ]; then
+      if getent group "$IRONCURTAIN_AGENT_GID" >/dev/null 2>&1; then
+        # GID already exists in the image (benign collision): reuse it as
+        # codespace's primary group instead of renumbering codespace's own
+        # group onto an occupied GID.
+        usermod -g "$IRONCURTAIN_AGENT_GID" codespace || {
+          echo "[ironcurtain] usermod failed: cannot set codespace primary group to existing GID $IRONCURTAIN_AGENT_GID" >&2
+          exit 1
+        }
+      else
+        # GID is free: renumber codespace's own group to it.
+        groupmod -g "$IRONCURTAIN_AGENT_GID" codespace || {
+          echo "[ironcurtain] groupmod failed: cannot remap codespace group to GID $IRONCURTAIN_AGENT_GID (already in use?)" >&2
+          exit 1
+        }
+      fi
+    fi
+
+    current_uid="$(id -u codespace)"
+    if [ "$current_uid" != "$IRONCURTAIN_AGENT_UID" ]; then
+      usermod -u "$IRONCURTAIN_AGENT_UID" -g "$IRONCURTAIN_AGENT_GID" codespace || {
+        echo "[ironcurtain] usermod failed: cannot remap codespace user to UID $IRONCURTAIN_AGENT_UID (already in use?)" >&2
+        exit 1
+      }
+    fi
+
+    chown -R "$IRONCURTAIN_AGENT_UID:$IRONCURTAIN_AGENT_GID" /home/codespace /workspace || {
+      echo "[ironcurtain] chown failed: cannot reset ownership of /home/codespace and /workspace to $IRONCURTAIN_AGENT_UID:$IRONCURTAIN_AGENT_GID" >&2
+      exit 1
+    }
+  fi
+  # Re-exec the entrypoint as the (possibly remapped) codespace user. The
+  # remainder of the parent entrypoint runs under codespace, so $HOME and
+  # sudoers (which keys on the username) resolve correctly. `$0`/`$@` are
+  # the parent entrypoint's because this file is sourced, not executed.
+  exec runuser -u codespace -- "$0" "$@"
+fi