Skip to content

Commit 174764a

Browse files
authored
Merge pull request #174 from PhysShell/claude/sandboy-design-readiness-22e1uw
Sandboy design-readiness: isolation ADR + WIT adapter & wrap-the-child spikes + capability-layer design
2 parents 7bae944 + 8234fe9 commit 174764a

22 files changed

Lines changed: 2029 additions & 0 deletions

File tree

‎audit/adapters/BUILD.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Building & running the adapter spike
2+
3+
> **Authored, not compiled here.** This spike was written in a network-restricted
4+
> sandbox with no wasm target and no crate downloads (`static.crates.io` egress
5+
> was policy-blocked), so it has **not** been run through `cargo`. Treat the
6+
> wasmtime/cargo-component API calls as "correct against the documented API,
7+
> version pins may need a nudge" — the two most likely spots are flagged as
8+
> **§bindings** and **§versioning** below. Everything compiles in a normal
9+
> environment with the toolchain in step 1.
10+
11+
## 1. Toolchain (one time)
12+
13+
```bash
14+
rustup target add wasm32-wasip2 # component target
15+
cargo install cargo-component # builds WIT components
16+
cargo install wasm-tools # inspect/validate components (optional)
17+
```
18+
19+
## 2. Build the adapter components
20+
21+
```bash
22+
# real transform (Infer#)
23+
(cd components/infersharp && cargo component build --release \
24+
&& cp target/wasm32-wasip2/release/adapter_infersharp.wasm ../infersharp.wasm)
25+
26+
# passthrough (Roslyn, CodeQL — validate + normalize already-SARIF output)
27+
(cd components/passthrough && cargo component build --release \
28+
&& cp target/wasm32-wasip2/release/adapter_passthrough.wasm ../passthrough.wasm)
29+
```
30+
31+
## 3. Build the host
32+
33+
```bash
34+
# from audit/adapters (step 2 used subshells, so cwd is still here)
35+
cd host
36+
cargo build --release
37+
# -> target/release/own-adapter-host
38+
cd ..
39+
```
40+
41+
## 4. Run it — happy path
42+
43+
```bash
44+
# from audit/adapters
45+
./host/target/release/own-adapter-host \
46+
--component components/infersharp.wasm \
47+
--tool infersharp \
48+
--artifact report.json=tests/infersharp/report.json \
49+
--base-uri 'file:///repo/sts' \
50+
--exit-code 0 \
51+
| python -m json.tool
52+
```
53+
54+
Expect a SARIF 2.1.0 document: one run, `tool.driver.name = "Infer#"`, two
55+
distinct rules (`NULL_DEREFERENCE`, `RESOURCE_LEAK`), three results with
56+
`level` mapped from severity, `region` line/column, logical locations from
57+
`procedure`, `inferHash/v1` fingerprints, and a
58+
`runs[0].properties.adapterComponentSha256` provenance stamp.
59+
60+
## 5. Run it — the point of the exercise (adversarial)
61+
62+
```bash
63+
./host/target/release/own-adapter-host \
64+
--component components/infersharp.wasm \
65+
--tool infersharp \
66+
--artifact report.json=tests/infersharp/adversarial.json \
67+
--base-uri 'file:///repo/sts'
68+
# stdout: empty
69+
# stderr: NO-TOOL: adapter-fault: adapter rejected input: parsing Infer# report.json: ...
70+
# exit: 1 (nothing ingested, host intact)
71+
```
72+
73+
## 6. Run the passthrough (native-SARIF tools take the same path)
74+
75+
```bash
76+
./host/target/release/own-adapter-host \
77+
--component components/passthrough.wasm \
78+
--tool roslyn \
79+
--artifact roslyn.sarif=tests/passthrough/roslyn.sarif \
80+
--base-uri 'file:///repo/sts' \
81+
| python -m json.tool
82+
```
83+
84+
Expect the same SARIF back, but normalized (`version` canonicalized from
85+
`2.1.0-rtm.6` to `2.1.0`, `$schema` filled in) and carrying the same
86+
`adapterComponentSha256` provenance stamp — proof that Roslyn/CodeQL flow
87+
through the identical validated, sandboxed path as Infer#. See `UNIFIED.md`.
88+
89+
## 7. Resource-limit paths (the spike's real claim)
90+
91+
- **Fuel:** `--fuel 100000` on a large report → `component trapped (fuel/epoch/memory?)`.
92+
- **Memory:** feed a multi-hundred-MB `report.json` → the guest hits the 256 MiB
93+
linear-memory cap and traps; the host does not OOM.
94+
- **Epoch:** `--epoch-ms 50` against a pathological input → epoch deadline trap.
95+
96+
In every case: stdout stays empty, the fault is surfaced as an honest skip, the
97+
orchestrator keeps running. That containment is the whole reason this is WASM
98+
and not an in-process parser.
99+
100+
## §bindings — if `cargo component build` disagrees on paths
101+
102+
`components/infersharp/src/lib.rs` imports `bindings::Guest` and
103+
`bindings::ownaudit::adapter::types::RawInput`. cargo-component's generated
104+
module layout occasionally differs by version. If it fails to resolve, run
105+
`cargo component build` once, open `target/.../bindings.rs` (or `cargo expand`),
106+
and adjust the two `use` lines to the generated paths. The host side uses the
107+
`wasmtime::component::bindgen!` macro against the same WIT — if the generated
108+
`RawInput`/`NamedBlob` path differs, fix the `use ownaudit::adapter::types::...`
109+
line in `host/src/main.rs` the same way.
110+
111+
## §versioning — evolving the ABI without breakage
112+
113+
Adding a field to a WIT `record` is a **breaking** ABI change. So:
114+
115+
- Route most tuning through `raw-input.options: list<u8>` (opaque bytes the host
116+
passes through) — no ABI churn.
117+
- When a field is genuinely needed, bump the package minor
118+
(`ownaudit:adapter@0.2.0`) and have the host accept both worlds for a
119+
deprecation window.
120+
- There is one canonical `wit/world.wit`. Both the host (`bindgen!`) and the
121+
component (`[package.metadata.component.target] path = "../../wit"`) point at
122+
it — no copy to keep in sync.
123+
124+
## Wiring into `aggregate` (next step, not in this spike)
125+
126+
`aggregate` calls `own-adapter-host` per non-SARIF tool, reads SARIF on stdout,
127+
and feeds it to the existing `parse_sarif`. The `adapters.toml` entry supplies
128+
the component path and per-tool caps.

‎audit/adapters/README.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# `audit/adapters/` — SARIF adapters as sandboxed WASM components
2+
3+
**Status: spike.** The audit pipeline runs many ready-made analyzers and
4+
normalizes each to SARIF. Some tools don't speak SARIF, so their output goes
5+
through a **thin `raw -> SARIF` adapter** (see `Own.NET/Plan.md`). This is the
6+
first slice of running those adapters as **capability-scoped WebAssembly
7+
components** (`ownaudit:adapter` WIT world) instead of in-process code.
8+
9+
> This is the real, useful home the parked "Sandboy WIT plugin surface" idea
10+
> found (see `docs/notes/sandboy-isolation-adr.md` §0 PARK / §6 trigger-table):
11+
> not "rules in any language", but **containing parsers of untrusted input**.
12+
13+
## Why WASM/WIT here is the right tool, not a bolt-on
14+
15+
An adapter parses **tool output derived from the audited (untrusted, legacy)
16+
code**. A bug in that parser is code execution *inside the orchestrator* — and
17+
`007/docs/verification.md` already flags these parsers as the #1 fuzz target.
18+
Running each adapter as a WASM component changes what a parser bug can do:
19+
20+
1. **Pure compute → zero capability leak.** An adapter is `bytes -> SARIF`. It
21+
needs no filesystem, no network, no clock. The world has **zero imports**,
22+
so the component *cannot* reach any of them. This is the rare tool-plugin
23+
with no legitimate need for native authority — the objection that sinks
24+
general agent-tool sandboxing ("tools need real caps") simply doesn't apply.
25+
2. **Untrusted input → the boundary is real even at N=1.** You don't need a
26+
third-party plugin market to justify the sandbox; the *input* is the threat.
27+
A crafted `report.json` can at worst make the component **trap** — it cannot
28+
corrupt the run or touch the host.
29+
3. **Polyglot + portable.** Write an adapter in Rust/Go/Python, ship one
30+
`.wasm`, run it regardless of host language — unifying today's
31+
Python-aggregate / C#-skeleton / PowerShell-runner mix behind one ABI.
32+
4. **Hot-load.** New analyzer → drop a `.wasm` in, register it in
33+
`adapters.toml`, no orchestrator rebuild.
34+
35+
## What the sandbox does and does NOT buy you
36+
37+
| Buys | Does **not** buy |
38+
|---|---|
39+
| Memory-safety faults of the parser are contained (trap, not host compromise) | Semantic correctness of the output |
40+
| Determinism (no clock/rand/IO ⇒ same input → same SARIF) | Trust in the returned bytes |
41+
42+
Because the **output is not trusted either**, the host schema-checks and
43+
size-caps the returned SARIF *before* anything downstream (`parse_sarif`) sees
44+
it. The WASM boundary contains the parse crash; the host validates the meaning.
45+
46+
## Layout
47+
48+
```text
49+
adapters/
50+
wit/world.wit canonical ownaudit:adapter@0.1.0 world
51+
host/ own-adapter-host (Rust, wasmtime component model)
52+
components/infersharp/ real transform: Infer# report.json -> SARIF
53+
components/passthrough/ validate+normalize already-SARIF tools (Roslyn, CodeQL)
54+
adapters.toml control surface: per-tool run recipes + phases + caps
55+
tests/ sample + adversarial inputs per component
56+
UNIFIED.md the single-interface path across all three tools
57+
BUILD.md how to build & run (authored, not built in-repo)
58+
```
59+
60+
For "can I run Roslyn + CodeQL + Infer# through one interface?" — see
61+
[`UNIFIED.md`](UNIFIED.md). Short version: the single interface is the SARIF
62+
contract; native-SARIF tools use the passthrough component so **all** tools take
63+
the same sandboxed, validated, provenance-stamped path.
64+
65+
## Where it plugs into the pipeline
66+
67+
```text
68+
tool runs ──▶ host reads stdout/files ──▶ own-adapter-host ──▶ .wasm adapter
69+
│
70+
SARIF bytes back
71+
│
72+
host: validate + cap + stamp sha256
73+
│
74+
parse_sarif ──▶ normalize ──▶ score
75+
```
76+
77+
`own-adapter-host` is a standalone binary `aggregate` calls per tool (raw in →
78+
SARIF on stdout), so Python never links wasmtime and the whole thing folds into
79+
the Rust core cleanly when P-022 lands.
80+
81+
**Provenance:** the host stamps the component's `sha256` into each SARIF
82+
`run.properties.adapterComponentSha256`, so a finding is traceable to the exact
83+
adapter build that produced it — reproducible and auditable, in the
84+
evidence/provenance style of the rest of the repo.
85+
86+
See `BUILD.md` to build and run the spike.

‎audit/adapters/UNIFIED.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# The unified path: Roslyn + CodeQL + Infer# through one interface
2+
3+
The question this answers: *"will it be convenient to run all of this — Roslyn,
4+
CodeQL, Infer# — through a single interface?"*
5+
6+
Yes — but the single interface is the **SARIF contract**, and the adapter layer
7+
is how every tool *reaches* it. There are two planes; only one is (and should
8+
be) unified.
9+
10+
## Plane 1 — invocation (NOT uniform, modelled as phases)
11+
12+
Each tool runs differently and pretending otherwise is a lie the driver
13+
shouldn't tell:
14+
15+
| tool | phases | native output |
16+
|---|---|---|
17+
| Roslyn | `analyze` (`dotnet build /errorlog`) | SARIF |
18+
| CodeQL | `db-build` → `analyze` | SARIF |
19+
| Infer# | `analyze` (build-free) | `report.json` |
20+
21+
`adapters.toml` captures this per tool: `phases`, `platform`, `build_free`,
22+
`output.kind`, and which `adapter` component normalizes it.
23+
24+
## Plane 2 — normalization + everything after (fully uniform)
25+
26+
Every tool converges on **validated SARIF**, then scoring/dedup/report are
27+
tool-agnostic. The adapter is the on-ramp:
28+
29+
```text
30+
Roslyn ─analyze──▶ roslyn.sarif ─▶ passthrough.wasm ─┐
31+
CodeQL ─db,analyze▶ codeql.sarif ─▶ passthrough.wasm ─┼─▶ own-adapter-host
32+
Infer# ─analyze──▶ report.json ─▶ infersharp.wasm ─┘ (validate + cap +
33+
sha256 stamp)
34+
│
35+
validated SARIF
36+
│
37+
parse_sarif ─▶ score ─▶ report
38+
```
39+
40+
**Native-SARIF tools go through a component too** (passthrough), so *all three*
41+
take the identical path: sandboxed parse of untrusted-derived output, uniform
42+
validation, uniform provenance stamp. No "SARIF tools here, non-SARIF there"
43+
split. The host binary is unchanged and tool-agnostic — only the `--component`
44+
differs.
45+
46+
## What the orchestrator loop looks like (in `aggregate`)
47+
48+
```python
49+
# pseudocode — the shape aggregate grows into; not committed here
50+
cfg = toml.load("adapters.toml")
51+
for tool_id, t in cfg["tools"].items():
52+
if not platform_ok(t.get("platform", "any")):
53+
record(f"NO-TOOL: {tool_id} skipped (platform)"); continue
54+
55+
for phase in t["phases"]: # honest: CodeQL runs 2, others 1
56+
run(expand(phase["cmd"], run_vars))
57+
58+
artifact = expand(t["output"]["artifact"], run_vars)
59+
sarif = subprocess.check_output([ # one call, same for every tool
60+
"own-adapter-host",
61+
"--component", t["adapter"],
62+
"--tool", tool_id,
63+
"--artifact", f"report={artifact}",
64+
"--base-uri", run_vars["base_uri"],
65+
"--max-results", str(cfg["defaults"]["max_results"]),
66+
]) # -> validated, stamped SARIF
67+
parse_sarif(sarif) # existing downstream, unchanged
68+
```
69+
70+
That is the "single interface" you run everything through: **one loop, one
71+
`own-adapter-host` call per tool, one SARIF contract.** Invocation heterogeneity
72+
lives in data (`phases`), not in branching code — and CodeQL's two-phase nature
73+
is visible, not hidden.
74+
75+
## What this spike ships toward it
76+
77+
- `components/passthrough/` — the SARIF→validated-SARIF component (Roslyn, CodeQL).
78+
- `components/infersharp/` — the real transform (Infer#).
79+
- `adapters.toml` — the control surface with run recipes + phases.
80+
- The loop above is the remaining wiring in `aggregate` (not in this spike — it
81+
shells out to real tools, which can't run in the authoring sandbox).

‎audit/adapters/adapters.toml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Control surface for the audit run.
2+
#
3+
# `aggregate` reads this. For each enabled tool it runs the phases in order
4+
# (respecting `platform`), collects the declared output artifact, then normalizes
5+
# it to SARIF via the tool's adapter component — passthrough for native-SARIF
6+
# tools, a real transform for the rest. Everything converges on *validated* SARIF
7+
# before scoring, so scoring/dedup/report stay tool-agnostic.
8+
#
9+
# The unified path (see UNIFIED.md):
10+
# run phases -> read output artifact -> own-adapter-host --component <adapter>
11+
# -> validated + provenance-stamped SARIF -> parse_sarif -> normalize -> score
12+
#
13+
# Placeholders in cmd/artifact ({out}, {sln}, {assemblies}, {build}, {suite}) are
14+
# expanded by the orchestrator from the run config; they are not the host's job.
15+
16+
[defaults]
17+
fuel = 2_000_000_000
18+
epoch_ms = 5_000
19+
max_results = 200_000
20+
max_bytes = 67_108_864 # 64 MiB
21+
22+
# --- Roslyn analyzers: emit SARIF natively via /errorlog -> passthrough --------
23+
[tools.roslyn]
24+
platform = "any"
25+
phases = [
26+
{ name = "analyze", cmd = "dotnet build {sln} -warnaserror /errorlog:{out}/roslyn.sarif" },
27+
]
28+
output = { kind = "native-sarif", artifact = "{out}/roslyn.sarif" }
29+
adapter = "components/passthrough.wasm"
30+
31+
# --- CodeQL: two-phase (db build, then analyze). Native SARIF -> passthrough ---
32+
[tools.codeql]
33+
platform = "linux"
34+
phases = [
35+
{ name = "db-build", cmd = "codeql database create {out}/db --language=csharp --command='{build}'" },
36+
{ name = "analyze", cmd = "codeql database analyze {out}/db {suite} --format=sarif-latest --output={out}/codeql.sarif" },
37+
]
38+
output = { kind = "native-sarif", artifact = "{out}/codeql.sarif" }
39+
adapter = "components/passthrough.wasm"
40+
41+
# --- Infer#: own report.json, build-free -> real transform adapter ------------
42+
[tools.infersharp]
43+
platform = "any"
44+
build_free = true
45+
phases = [
46+
{ name = "analyze", cmd = "infersharp {assemblies} -o {out}/infer" },
47+
]
48+
output = { kind = "raw", artifact = "{out}/infer/report.json" }
49+
adapter = "components/infersharp.wasm"
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
[package]
2+
name = "adapter-infersharp"
3+
version = "0.1.0"
4+
edition = "2021"
5+
description = "ownaudit:adapter component — Infer# report.json -> SARIF 2.1.0. Pure, capability-free."
6+
7+
[lib]
8+
crate-type = ["cdylib"]
9+
10+
[dependencies]
11+
# serde/serde_json compile to wasm cleanly; the component stays pure (no I/O).
12+
serde = { version = "1", features = ["derive"] }
13+
serde_json = "1"
14+
# Provided by cargo-component; version tracks whatever cargo-component pulls.
15+
wit-bindgen-rt = { version = "0.35", features = ["bitflags"] }
16+
17+
[package.metadata.component]
18+
package = "ownaudit:adapter"
19+
20+
[package.metadata.component.target]
21+
# Single source of truth: the canonical world, shared with the host. No copy.
22+
path = "../../wit"
23+
world = "sarif-adapter"
24+
25+
[profile.release]
26+
opt-level = "s"
27+
lto = true

0 commit comments

Comments
 (0)