|
| 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. |
0 commit comments