diff --git a/.agents/skills/reverse-engineer-anything/SKILL.md b/.agents/skills/reverse-engineer-anything/SKILL.md index 910f961fc2..9c1f948ff3 100644 --- a/.agents/skills/reverse-engineer-anything/SKILL.md +++ b/.agents/skills/reverse-engineer-anything/SKILL.md @@ -256,11 +256,12 @@ explicit path or endpoint and do not need it. other versions are unsupported. Optional matching `binary_path` enables static native addresses and type references; query `method_addresses` with indices or addresses/states, preserving every shared-body method and both artifact identities. Without a linked binary native counts remain unknown. Byte-pattern fallback is inferred; no runtime behavior or same-build pairing is proved. See the [IL2CPP metadata guide](https://github.com/morluto/rea/blob/main/docs/il2cpp-metadata.md). - Embedded cargo-auditable Rust dependency metadata: `inspect_rust_binary` - with the explicit local ELF, PE, or thin Mach-O file. This built-in - target-free inspection requires no Rust installation or disassembler. Preserve - package order, dependency indices, and the section file range. A missing - `.dep-v0` section is null metadata, not proof the binary has no dependencies. - A rustc commit hash is an inference from a read-only `/rustc/<40-hex>/` path. + with the explicit local ELF, PE, thin Mach-O, or WebAssembly core-module + file. This built-in target-free inspection requires no Rust installation or + disassembler. Preserve package order, dependency indices, and the section file + range. A missing `.dep-v0` section is null metadata, not proof the binary has + no dependencies. A rustc commit hash is an inference from a + `/rustc/<40-hex>/` path in read-only data or a WebAssembly data section. For selected crates, use `view: {collection: "packages", names: [...], fields: ["name", "version", "source"]}` on the first call; explicitly include `dependencies` for direct index references. Use `detail: "summary"` for counts diff --git a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md index 671e10747a..740f590897 100644 --- a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md +++ b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md @@ -125,16 +125,20 @@ See [IL2CPP metadata](https://github.com/morluto/rea/blob/main/docs/il2cpp-metad ## Rust dependency metadata -Use `inspect_rust_binary` for an explicit local ELF, PE, or Mach-O (universal -files need `architecture`) when -the question concerns the cargo-auditable crate list embedded in `.dep-v0` -(Mach-O: `__DATA,.dep-v0`). No `open_binary`, Rust installation, or target -execution is required. The CLI equivalent is `inspect-rust-binary PATH`. -Preserve artifact SHA-256, package order, dependency indices, and the section -file range. A missing section is null metadata, not proof the binary has no -dependencies. An omitted package kind stays null. A rustc commit hash is -inferred from a read-only `/rustc/<40-hex>/` path and does not by itself -identify the compiler. Project the retained parent with `inspect_analysis_view` +Use `inspect_rust_binary` for an explicit local ELF, PE, Mach-O (universal +files need `architecture`), or WebAssembly core module when the question +concerns the cargo-auditable crate list embedded in `.dep-v0` (Mach-O: +`__DATA,.dep-v0`; WebAssembly: a custom section). No `open_binary`, Rust +installation, or target execution is required. The CLI equivalent is +`inspect-rust-binary PATH`. Preserve artifact SHA-256, package order, +dependency indices, and the section file range. A missing section is null +metadata, not proof the binary has no dependencies. An omitted package kind +stays null. WebAssembly reports `bits: null` on a `32 | 64 | null` word size; +null means the container declares no word size and must not be coerced to a +number. ELF, PE and Mach-O stay 32 or 64. Components such as +`wasm32-wasip2` output are unsupported. A rustc commit hash is inferred from a +`/rustc/<40-hex>/` path in read-only data or a WebAssembly data section and +does not by itself identify the compiler. Project the retained parent with `inspect_analysis_view` kind `cyclonedx` for one CycloneDX 1.6 document. Build-kind packages are `scope: excluded`. See [Rust binaries](https://github.com/morluto/rea/blob/main/docs/rust-binaries.md) and [CycloneDX dependencies](https://github.com/morluto/rea/blob/main/docs/guides/native/cyclonedx-view.md). diff --git a/.cursor-plugin/skills/reverse-engineer-anything/SKILL.md b/.cursor-plugin/skills/reverse-engineer-anything/SKILL.md index 910f961fc2..9c1f948ff3 100644 --- a/.cursor-plugin/skills/reverse-engineer-anything/SKILL.md +++ b/.cursor-plugin/skills/reverse-engineer-anything/SKILL.md @@ -256,11 +256,12 @@ explicit path or endpoint and do not need it. other versions are unsupported. Optional matching `binary_path` enables static native addresses and type references; query `method_addresses` with indices or addresses/states, preserving every shared-body method and both artifact identities. Without a linked binary native counts remain unknown. Byte-pattern fallback is inferred; no runtime behavior or same-build pairing is proved. See the [IL2CPP metadata guide](https://github.com/morluto/rea/blob/main/docs/il2cpp-metadata.md). - Embedded cargo-auditable Rust dependency metadata: `inspect_rust_binary` - with the explicit local ELF, PE, or thin Mach-O file. This built-in - target-free inspection requires no Rust installation or disassembler. Preserve - package order, dependency indices, and the section file range. A missing - `.dep-v0` section is null metadata, not proof the binary has no dependencies. - A rustc commit hash is an inference from a read-only `/rustc/<40-hex>/` path. + with the explicit local ELF, PE, thin Mach-O, or WebAssembly core-module + file. This built-in target-free inspection requires no Rust installation or + disassembler. Preserve package order, dependency indices, and the section file + range. A missing `.dep-v0` section is null metadata, not proof the binary has + no dependencies. A rustc commit hash is an inference from a + `/rustc/<40-hex>/` path in read-only data or a WebAssembly data section. For selected crates, use `view: {collection: "packages", names: [...], fields: ["name", "version", "source"]}` on the first call; explicitly include `dependencies` for direct index references. Use `detail: "summary"` for counts diff --git a/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md index 671e10747a..740f590897 100644 --- a/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md +++ b/.cursor-plugin/skills/reverse-engineer-anything/references/native-and-artifacts.md @@ -125,16 +125,20 @@ See [IL2CPP metadata](https://github.com/morluto/rea/blob/main/docs/il2cpp-metad ## Rust dependency metadata -Use `inspect_rust_binary` for an explicit local ELF, PE, or Mach-O (universal -files need `architecture`) when -the question concerns the cargo-auditable crate list embedded in `.dep-v0` -(Mach-O: `__DATA,.dep-v0`). No `open_binary`, Rust installation, or target -execution is required. The CLI equivalent is `inspect-rust-binary PATH`. -Preserve artifact SHA-256, package order, dependency indices, and the section -file range. A missing section is null metadata, not proof the binary has no -dependencies. An omitted package kind stays null. A rustc commit hash is -inferred from a read-only `/rustc/<40-hex>/` path and does not by itself -identify the compiler. Project the retained parent with `inspect_analysis_view` +Use `inspect_rust_binary` for an explicit local ELF, PE, Mach-O (universal +files need `architecture`), or WebAssembly core module when the question +concerns the cargo-auditable crate list embedded in `.dep-v0` (Mach-O: +`__DATA,.dep-v0`; WebAssembly: a custom section). No `open_binary`, Rust +installation, or target execution is required. The CLI equivalent is +`inspect-rust-binary PATH`. Preserve artifact SHA-256, package order, +dependency indices, and the section file range. A missing section is null +metadata, not proof the binary has no dependencies. An omitted package kind +stays null. WebAssembly reports `bits: null` on a `32 | 64 | null` word size; +null means the container declares no word size and must not be coerced to a +number. ELF, PE and Mach-O stay 32 or 64. Components such as +`wasm32-wasip2` output are unsupported. A rustc commit hash is inferred from a +`/rustc/<40-hex>/` path in read-only data or a WebAssembly data section and +does not by itself identify the compiler. Project the retained parent with `inspect_analysis_view` kind `cyclonedx` for one CycloneDX 1.6 document. Build-kind packages are `scope: excluded`. See [Rust binaries](https://github.com/morluto/rea/blob/main/docs/rust-binaries.md) and [CycloneDX dependencies](https://github.com/morluto/rea/blob/main/docs/guides/native/cyclonedx-view.md). diff --git a/README.md b/README.md index 4ccd45edee..bb4828fb62 100644 --- a/README.md +++ b/README.md @@ -201,7 +201,7 @@ Additional tools and host support depend on the target: | Model artifacts | GGUF / safetensors metadata, tensor declarations and derived totals | Built-in header inspection; optional full-file hash; [model files](docs/model-artifacts.md) | | IL2CPP metadata | Unity global-metadata.dat assembly images, type and method names and index ranges | Built-in static decoding of versions 24, 27, 29, 31 and 39; no Unity required | | Godot PCK | Archive inventory and extraction, original header/directory facts and selected content identities | Built-in static formats 2, 3 and 4; no Godot required | -| Rust binaries | Embedded cargo-auditable crate names, versions, sources and dependency edges | Built-in static ELF/PE/thin Mach-O inspection; [Rust binaries](docs/rust-binaries.md) | +| Rust binaries | Embedded cargo-auditable crate names, versions, sources and dependency edges | Built-in static ELF/PE/thin Mach-O/WebAssembly module inspection; [Rust binaries](docs/rust-binaries.md) | | PE certificates | Authenticode WIN_CERTIFICATE entries and PKCS#7 signer/X.509 identity fields | Built-in static PE inspection; [PE certificates](docs/pe-certificates.md) | | PE imports | Import and delay-load DLL names, ordinals, IAT RVAs and pefile import hash | Built-in static PE inspection; [PE imports](docs/pe-imports.md) | | Windows shortcuts | Shell Link target, arguments, working dir, ExtraData and Tracker droid facts | Built-in static LNK inspection; [Windows shortcuts](docs/guides/native/windows-shortcut.md) | diff --git a/docs/readme/README_el.md b/docs/readme/README_el.md index c4b0fb8a06..bfea42f0a8 100644 --- a/docs/readme/README_el.md +++ b/docs/readme/README_el.md @@ -160,7 +160,7 @@ npx rea-agents@latest setup | Δυαδικά αρχεία με κώδικα μηχανής | Ψευδοκώδικα, κώδικα assembly, συμβολοσειρές, σύμβολα, κλήσεις και αναφορές | Hopper, Ghidra, IDA ή Kuna· [ανάλυση κώδικα μηχανής](../guides/native/native-investigation.md) | | Δομή ELF χωρίς εκτέλεση | Ενότητες, τμήματα, αρχικά σύμβολα/εγγραφές μετεγκατάστασης και ενδείξεις πιθανών μέτρων προστασίας από στατική ανάλυση | pwntools που παρέχει ο χρήστης σε Linux x64· [διαγνωστικά δυαδικών αρχείων](../guides/native/binary-diagnostics.md) | | Δυαδικά αρχεία Go | Ενσωματωμένη έκδοση μεταγλωττιστή, modules, αντικαταστάσεις και ρυθμίσεις μεταγλώττισης | Ενσωματωμένη στατική εξέταση ELF/PE/thin Mach-O· δεν απαιτείται εγκατάσταση του Go | -| Δυαδικά αρχεία Rust | Ενσωματωμένα ονόματα, εκδόσεις, πηγές και σχέσεις εξάρτησης των crates από το cargo-auditable | Ενσωματωμένη στατική εξέταση ELF/PE/thin Mach-O· [δυαδικά αρχεία Rust](../rust-binaries.md) | +| Δυαδικά αρχεία Rust | Ενσωματωμένα ονόματα, εκδόσεις, πηγές και σχέσεις εξάρτησης των crates από το cargo-auditable | Ενσωματωμένη στατική εξέταση ELF/PE/thin Mach-O/WebAssembly· [δυαδικά αρχεία Rust](../rust-binaries.md) | | PE certificates | Authenticode WIN_CERTIFICATE entries and PKCS#7 signer/X.509 identity fields | Built-in static PE inspection; [PE certificates](../pe-certificates.md) | | PE imports | Import and delay-load DLL names, ordinals, IAT RVAs and pefile import hash | Built-in static PE inspection; [PE imports](../pe-imports.md) | | Windows shortcuts | Shell Link target, arguments, working dir, ExtraData and Tracker droid facts | Built-in static LNK inspection; [Windows shortcuts](../guides/native/windows-shortcut.md) | diff --git a/docs/readme/README_ko.md b/docs/readme/README_ko.md index 9ccba10672..ed0b0ebbd8 100644 --- a/docs/readme/README_ko.md +++ b/docs/readme/README_ko.md @@ -160,7 +160,7 @@ REA에는 Node.js 22.x(>=22.23.4), 24.x(>=24.22.1) 또는 26+ (>=26.12.1)와 npm | 네이티브 바이너리 | 의사 코드, 어셈블리, 문자열, 심볼, 호출, 참조 | Hopper, Ghidra, IDA 또는 Kuna; [네이티브 분석](../guides/native/native-investigation.md) | | 오프라인 ELF 레이아웃 | 섹션, 세그먼트, 원본 심볼/재배치 정보, 정적 분석으로 얻은 보안 완화 기법 후보 | Linux x64에서 호출자가 제공하는 pwntools; [바이너리 진단](../guides/native/binary-diagnostics.md) | | Go 바이너리 | 내장된 컴파일러 버전, 모듈, `replace` 지시어, 빌드 설정 | REA 내장 ELF/PE/thin Mach-O 정적 검사; Go 설치 불필요 | -| Rust 바이너리 | cargo-auditable이 내장한 크레이트 이름, 버전, 소스, 의존성 관계 | REA 내장 ELF/PE/thin Mach-O 정적 검사; [Rust 바이너리](../rust-binaries.md) | +| Rust 바이너리 | cargo-auditable이 내장한 크레이트 이름, 버전, 소스, 의존성 관계 | REA 내장 ELF/PE/thin Mach-O/WebAssembly 정적 검사; [Rust 바이너리](../rust-binaries.md) | | PE certificates | Authenticode WIN_CERTIFICATE entries and PKCS#7 signer/X.509 identity fields | Built-in static PE inspection; [PE certificates](../pe-certificates.md) | | PE imports | Import and delay-load DLL names, ordinals, IAT RVAs and pefile import hash | Built-in static PE inspection; [PE imports](../pe-imports.md) | | Windows shortcuts | Shell Link target, arguments, working dir, ExtraData and Tracker droid facts | Built-in static LNK inspection; [Windows shortcuts](../guides/native/windows-shortcut.md) | diff --git a/docs/readme/README_ml.md b/docs/readme/README_ml.md index 8e704d95bf..d40deeccfe 100644 --- a/docs/readme/README_ml.md +++ b/docs/readme/README_ml.md @@ -160,7 +160,7 @@ REA-യ്ക്ക് Node.js 22.x (>=22.23.4), 24.x (>=24.22.1), അല്ല | Native binaries | Pseudocode, assembly, strings, symbols, calls, references | Hopper, Ghidra, IDA അല്ലെങ്കിൽ Kuna; [native analysis](../guides/native/native-investigation.md) | | Offline ELF layout | Sections, segments, യഥാർത്ഥ symbols/relocations, static mitigation candidates | Linux x64-ൽ caller നൽകുന്ന pwntools; [binary diagnostics](../guides/native/binary-diagnostics.md) | | Go binaries | ഉൾച്ചേർത്ത compiler version, modules, replacements, build settings | Built-in static ELF/PE/thin Mach-O പരിശോധന; Go installation ആവശ്യമില്ല | -| Rust binaries | ഉൾച്ചേർത്ത cargo-auditable crate പേരുകൾ, versions, sources, dependency edges | Built-in static ELF/PE/thin Mach-O പരിശോധന; [Rust binaries](../rust-binaries.md) | +| Rust binaries | ഉൾച്ചേർത്ത cargo-auditable crate പേരുകൾ, versions, sources, dependency edges | Built-in static ELF/PE/thin Mach-O/WebAssembly പരിശോധന; [Rust binaries](../rust-binaries.md) | | PE certificates | Authenticode WIN_CERTIFICATE entries and PKCS#7 signer/X.509 identity fields | Built-in static PE inspection; [PE certificates](../pe-certificates.md) | | PE imports | Import and delay-load DLL names, ordinals, IAT RVAs and pefile import hash | Built-in static PE inspection; [PE imports](../pe-imports.md) | | Windows shortcuts | Shell Link target, arguments, working dir, ExtraData and Tracker droid facts | Built-in static LNK inspection; [Windows shortcuts](../guides/native/windows-shortcut.md) | diff --git a/docs/readme/README_tr.md b/docs/readme/README_tr.md index 1a7e04a504..40bd42fbb4 100644 --- a/docs/readme/README_tr.md +++ b/docs/readme/README_tr.md @@ -158,7 +158,7 @@ REA; Node.js 22.x (>=22.23.4), 24.x (>=24.22.1) veya 26+ (>=26.12.1) ve npm gere | Yerel makine kodu içeren ikili dosyalar | Sözde kod, assembly kodu, dizeler, semboller, çağrılar ve referanslar | Hopper, Ghidra, IDA veya Kuna; [yerel kod analizi](../guides/native/native-investigation.md) | | Çevrimdışı ELF yapısı | Bölümler, segmentler, özgün semboller/yeniden konumlandırmalar ve statik analizden olası güvenlik önlemleri | Linux x64 üzerinde çağıranın sağladığı pwntools; [ikili dosya tanılama](../guides/native/binary-diagnostics.md) | | Go ikili dosyaları | Gömülü compiler sürümü, modüller, replacement'lar ve build ayarları | Yerleşik statik ELF/PE/thin Mach-O incelemesi; Go kurulumu gerekmez | -| Rust ikili dosyaları | Gömülü cargo-auditable crate adları, sürümleri, kaynakları ve bağımlılık ilişkileri | Yerleşik statik ELF/PE/thin Mach-O incelemesi; [Rust ikili dosyaları](../rust-binaries.md) | +| Rust ikili dosyaları | Gömülü cargo-auditable crate adları, sürümleri, kaynakları ve bağımlılık ilişkileri | Yerleşik statik ELF/PE/thin Mach-O/WebAssembly incelemesi; [Rust ikili dosyaları](../rust-binaries.md) | | PE certificates | Authenticode WIN_CERTIFICATE entries and PKCS#7 signer/X.509 identity fields | Built-in static PE inspection; [PE certificates](../pe-certificates.md) | | PE imports | Import and delay-load DLL names, ordinals, IAT RVAs and pefile import hash | Built-in static PE inspection; [PE imports](../pe-imports.md) | | Windows shortcuts | Shell Link target, arguments, working dir, ExtraData and Tracker droid facts | Built-in static LNK inspection; [Windows shortcuts](../guides/native/windows-shortcut.md) | diff --git a/docs/rust-binaries.md b/docs/rust-binaries.md index 083cd4603c..bf6e9e6bce 100644 --- a/docs/rust-binaries.md +++ b/docs/rust-binaries.md @@ -2,8 +2,9 @@ `inspect_rust_binary` / `inspect-rust-binary` answers which crate names, versions, sources, and dependency edges are embedded by cargo-auditable in one -selected local executable or library. It reads the file without running it and -requires no Rust installation, active binary target, Hopper, Ghidra, or IDA. +selected local executable, library, or WebAssembly module. It reads the file +without running it and requires no Rust installation, active binary target, +Hopper, Ghidra, or IDA. ```bash rea inspect-rust-binary /absolute/path/to/application --json @@ -94,12 +95,17 @@ limitation and leaves `.dep-v0` presence unknown rather than reporting the section absent. The inline Evidence result contains the artifact path, SHA-256, byte length, -container format, architecture, word size, and byte order. When a `.dep-v0` +container format, architecture, word size, and byte order. `bits` is +`32 | 64 | null`. ELF, PE and Mach-O reports are 32 or 64. WebAssembly is +null: the container declares no word size, null is not a number, and +consumers must not coerce it. The summary view uses the same field. When a `.dep-v0` section is present, `auditable_metadata` contains: -- `section_name`, `.dep-v0` for ELF and PE or `__DATA,.dep-v0` for Mach-O; +- `section_name`, `.dep-v0` for ELF, PE, and WebAssembly or `__DATA,.dep-v0` + for Mach-O; - `file_offset` and `section_bytes`, the exact file range of the dependency section in the selected artifact, including accepted PE file-alignment bytes; + for WebAssembly, the custom-section payload after its name; - `compressed_bytes`, the zlib stream length used for the inflate-ratio limit, and `uncompressed_bytes`; - `format_version`, the embedded integer, or `null` when the field is omitted; @@ -122,7 +128,8 @@ removed the field entirely, as recorded in its [changelog](https://github.com/rust-secure-code/cargo-auditable/blob/v0.5.0/CHANGELOG.md). `rustc_commit` is present only when a `/rustc/<40-hex>/` path is found in -read-only data; its `evidence_kind` is `inferred`. For ELF, read-only +read-only data, or in the data section of a WebAssembly module; its +`evidence_kind` is `inferred`. For ELF, read-only non-executable `PT_LOAD` file ranges are searched alongside read-only sections, so an optional missing section-header table does not remove this search source. An empty or unavailable section name @@ -137,6 +144,28 @@ distinct hashes leave a single commit unknown. Windows builds join the rest of the path with a backslash, as in `/rustc/<40-hex>\library\core`, and that form counts too. +## WebAssembly modules + +cargo-auditable stores the same zlib-compressed JSON in a WebAssembly custom +section named `.dep-v0`. For a version 1 core module, such as +`wasm32-unknown-unknown` or `wasm32-wasip1` output, the reader walks the +section framing without validating, instantiating, or executing the module. +The report's `format` and `architecture` are `wasm` and its `byte_order` is +`little`. `bits` is `null` on the `32 | 64 | null` word size: WebAssembly +declares no container word size, and memory address types are not inspected. +JSON output keeps that null. The shared CLI renderer does not substitute a +number. The Evidence subject format is +`file`, as for `inspect_wasm_artifact`. + +A header, section or section size that ends past the file is truncated. A +custom-section name or name length that extends past its section, a size that +does not fit a 32-bit LEB128 integer, a custom-section name that is not UTF-8, +a second `.dep-v0` section, or a second data section is malformed. Both are +invalid input. WebAssembly +components, such as `wasm32-wasip2` output, embed several core modules. They +are unsupported: no input selects one embedded module the way `architecture` +selects a universal Mach-O slice. + ## Limits and failures The selected file is limited to 256 MiB. A dependency section's zlib stream is @@ -163,8 +192,8 @@ verified. An omitted revision remains `null` and follows revision 0 semantics. Embedded names and versions are file content. They do not authenticate the packages or the compiler. -ELF, PE, thin Mach-O and one selected slice of a universal Mach-O are the -supported containers. +ELF, PE, thin Mach-O, one selected slice of a universal Mach-O, and +WebAssembly core modules are the supported containers. A universal (FAT) Mach-O needs `architecture` (`x86`, `x86_64`, `arm`, `arm64` or `arm64e`; CLI `--architecture`). REA reads its own FAT table, without `lipo`, rejects a table whose slices overlap, and validates the selected slice's range, @@ -203,6 +232,12 @@ to retain a larger prefix; no restart is required. The complete-report byte allowance still applies. Optional compiler paths are shortened before they can displace independently observed dependency facts. +WebAssembly section framing is walked synchronously, and the format sets no +section count, so a module with more than 65,536 sections is refused with a +`cpu` resource constraint whose `reported_limits` name the `max_wasm_sections` +boundary and its maximum. This allowance is fixed; `producer_limits` does not +raise it. Producer output holds a few dozen sections. + Reader architecture names remain verbatim in the report. Evidence subjects use the recognized canonical family: `386` maps to `x86`, `amd64` to `x86_64`, and `ppc` to `powerpc`. Unknown families such as `ppc64` remain unknown rather than diff --git a/docs/specs/README.md b/docs/specs/README.md index b016d00e97..e455d11f05 100644 --- a/docs/specs/README.md +++ b/docs/specs/README.md @@ -39,6 +39,7 @@ for new work, roadmap granularity and producer-owned contracts. - [ELF unwind function ranges](native/elf-unwind-ranges/spec.md) ([plan](native/elf-unwind-ranges/plan.md), [tasks](native/elf-unwind-ranges/tasks.md)) - [Linux kernel build config](native/kernel-build-config/spec.md) ([plan](native/kernel-build-config/plan.md), [tasks](native/kernel-build-config/tasks.md)) - [Native initializers](native/native-initializers/spec.md) ([plan](native/native-initializers/plan.md), [tasks](native/native-initializers/tasks.md)) +- [Rust dependency metadata in WebAssembly modules](native/rust-wasm-auditable/spec.md) ([plan](native/rust-wasm-auditable/plan.md), [tasks](native/rust-wasm-auditable/tasks.md)) - [Release exposure audit](artifacts/release-exposure/spec.md) ([plan](artifacts/release-exposure/plan.md), [tasks](artifacts/release-exposure/tasks.md)) - [CycloneDX dependency view](analysis-views/cyclonedx-dependencies/spec.md) ([plan](analysis-views/cyclonedx-dependencies/plan.md), [tasks](analysis-views/cyclonedx-dependencies/tasks.md)) diff --git a/docs/specs/native/rust-wasm-auditable/plan.md b/docs/specs/native/rust-wasm-auditable/plan.md new file mode 100644 index 0000000000..e657317a09 --- /dev/null +++ b/docs/specs/native/rust-wasm-auditable/plan.md @@ -0,0 +1,51 @@ +# Implementation plan + +## Boundary and contract + +`src/rust/RustWasmImage.ts` owns WebAssembly section framing: the preamble, +layer and version, section sizes read with the shared `readLeb128`, +custom-section names, the `.dep-v0` payload ranges and the data-section range. It reports failures through the +`ParseFailure` algebra with format `wasm`, and the section bound as a +`max_wasm_sections` decode limit. + +`src/rust/RustBinaryImage.ts` builds one layout for either container: identity +facts, the dependency span and the spans searched for compiler paths. The +native layout comes from `readBinaryContainer`; the WebAssembly layout comes +from `RustWasmImage`. The dependency decoder, PE alignment allowance and rustc +path retention are shared and unchanged. + +`src/domain/rust/rustBinary.ts` owns the report contract: `format` gains +`wasm`, and `bits` is explicitly `32 | 64 | null`. Null is valid only when +`format` is `wasm` and is not a number. Refinements bind `bits`, +`architecture`, `byte_order` and the dependency section name to the container. +`rustDependencySectionName` is the one owner of that name for the reader and +the schema. `metadataReportSubjectFormat` in +`src/domain/apple/machoTargetSelection.ts` maps a `wasm` report to the `file` +subject, and `requireMetadataReportSubject` accepts it, so the service, the +retained views and the CycloneDX view agree on one mapping. + +`src/rust/RustBinaryProvider.ts` projects the section-bound limit with +`parseLimitConstraint` as a `cpu` constraint and a fixed work ceiling, and +names the searched compiler-path source in limitations. + +## Incremental work and validation + +1. Walk section framing with boundary tests over synthetic modules. +2. Read `.dep-v0` and data-section rustc paths through the shared layout, and + widen the report contract. +3. Bound the section walk after review showed a 256 MiB module of three-byte + sections kept the synchronous walk busy for seconds. +4. Map the Evidence subject once and run the retained-view workflow on a + module. +5. Bind the remaining container facts in the report schema. +6. Update the guide, README rows, skill instructions, tool description and CLI + help, then run focused tests, `check`, `docs:check` and the source group. + +## Effects and compatibility + +Output widening only: `format` gains `wasm` and `bits` is `32 | 64 | null` +on the report and its summary view. Null is admitted only for `wasm` +reports, which were previously refused. ELF, PE and Mach-O reports remain +32 or 64. No new tool, input, subprocess, +temporary file or network access. Native reports change only in limitation +wording. diff --git a/docs/specs/native/rust-wasm-auditable/spec.md b/docs/specs/native/rust-wasm-auditable/spec.md new file mode 100644 index 0000000000..492252bca1 --- /dev/null +++ b/docs/specs/native/rust-wasm-auditable/spec.md @@ -0,0 +1,82 @@ +# Rust dependency metadata in WebAssembly modules + +## Problem and outcome + +`cargo auditable build` for a `wasm32` target stores the same zlib-compressed +`.dep-v0` JSON that native builds carry, in a WebAssembly custom section. +`inspect_rust_binary` and `inspect-rust-binary` recognized only ELF, PE and +Mach-O containers, so every `.wasm` input was refused as an unsupported target +and an agent could not read a module's embedded crate list. + +This feature lets the existing tool and command read that list from a +WebAssembly core module. It adds no tool, command or input. + +[Rust binary dependency metadata](../../../rust-binaries.md#webassembly-modules) +describes the current behavior and limitations. This directory is the feature +specification, implementation plan and task list. The guide does not replace +these files. + +This record was written on 2026-11-17, during review, after the repository +adopted feature records. The requirements restate the contract the +implementation already had; no earlier plan is reconstructed. + +## Requirements + +1. The module is a local file read through the stable artifact read. It is not + validated, instantiated or executed. Only section framing is walked. +2. A version 1 core module is accepted. A component (layer 1) and any other + module version are unsupported targets, because a component embeds several + core modules and no input selects one. +3. A custom section named `.dep-v0` supplies the dependency list, and the + report's `section_name` is `.dep-v0`; the report schema binds each + container to its section name. `file_offset` and `section_bytes` locate the + payload after the section name, in the original file. A second `.dep-v0` + section is malformed; the walk ends there, so a later failure such as the + section bound does not replace it. +4. A missing `.dep-v0` section is null metadata with a limitation. It is not + evidence that the module has no dependencies. +5. `format` and `architecture` are `wasm` and `byte_order` is `little`. + `bits` is `32 | 64 | null`, and is `null` for this container because + WebAssembly declares no container word size and memory address types are + not inspected. Null is not a number and must not be coerced. ELF, PE and + Mach-O reports stay 32 or 64. The report schema, its field description and + the summary view refuse any report that combines these facts differently. +6. The rustc commit is inferred from `/rustc/<40-hex>/` paths in the module's + data section. Limitations name that source. A second data section is + malformed. +7. A header, section or section size that ends past the file is truncated. A + size or name length that does not fit a 32-bit LEB128 integer, a + custom-section name or name length that extends past its section, and a + name that is not UTF-8 are malformed. Integers are decoded by the shared + LEB128 reader. +8. The section walk stops after 65,536 sections with a `cpu` resource + constraint. The format sets no section count and the walk is synchronous. + The allowance is fixed; `producer_limits` does not raise it. Retained state + is at most two `.dep-v0` ranges and one data-section range. +9. The Evidence subject format is `file`, as for `inspect_wasm_artifact`, with + no architecture. Retained summaries, package and edge pages and the + CycloneDX view accept a WebAssembly parent. +10. `architecture` on a module is rejected, as on any image that is not a + universal Mach-O. +11. ELF, PE and Mach-O reports are unchanged apart from limitation wording + that names where compiler paths were searched. + +## Acceptance + +- Boundary tests cover a module with and without `.dep-v0`, each refusal in + requirements 2, 3, 6 and 7 by failure kind, format, offset and field, and + the section bound at 65,536 and 65,537 sections. +- CLI acceptance covers a module report, its `file` subject and the component + refusal. The retained-view acceptance workflow runs on a module. +- MCP boundary tests validate a module report against the advertised output + schema and check the section-bound refusal through the public error + contract. +- A view test refuses imported reports whose container facts contradict + requirements 3 and 5. + +## Non-goals + +- Reading a component's embedded core modules. +- Validating, instantiating or executing a module. +- Decoding memory address types or any section other than the framing, the + `.dep-v0` payload and the data-section byte range. diff --git a/docs/specs/native/rust-wasm-auditable/tasks.md b/docs/specs/native/rust-wasm-auditable/tasks.md new file mode 100644 index 0000000000..2dcf4bed21 --- /dev/null +++ b/docs/specs/native/rust-wasm-auditable/tasks.md @@ -0,0 +1,11 @@ +# Tasks + +- [x] Walk core-module section framing and refuse components and other versions (requirements 1, 2 and 7). +- [x] Read `.dep-v0` and data-section rustc paths through the shared layout (requirements 3, 4 and 6). +- [x] Widen the report contract and bind its container facts (requirements 5 and 11). +- [x] Bound the synchronous section walk (requirement 8). +- [x] Map the Evidence subject once for the service, retained views and CycloneDX (requirements 9 and 10). +- [x] Cover the public contract with CLI acceptance and MCP boundary tests. +- [x] Document the guide, README rows, skill instructions, tool description and CLI help. +- [x] Verify on 2026-10-18 against `wasm32-wasip1` and `wasm32-unknown-unknown` builds from rustc 1.97.0 and cargo-auditable 0.7.7, comparing each field with an independent LEB128, zlib and JSON reader. +- [ ] Verify against wasm-bindgen or wasm-opt output, `wasm32-wasip1-threads`, `wasm64-unknown-unknown`, and macOS or Windows hosts. diff --git a/src/cli/rustCommands.ts b/src/cli/rustCommands.ts index 20438fe048..f4ed35567c 100644 --- a/src/cli/rustCommands.ts +++ b/src/cli/rustCommands.ts @@ -33,7 +33,8 @@ export const registerRustCommands = ( }, fields: { path: { - description: "Local ELF, PE, thin Mach-O or universal Mach-O image", + description: + "Local ELF, PE, thin or universal Mach-O, or WebAssembly core-module image", }, producer_limits: { description: PRODUCER_LIMITS_HELP }, architecture: { diff --git a/src/contracts/rust/rustToolContracts.ts b/src/contracts/rust/rustToolContracts.ts index e62ef44296..fde59b3868 100644 --- a/src/contracts/rust/rustToolContracts.ts +++ b/src/contracts/rust/rustToolContracts.ts @@ -19,7 +19,7 @@ export const RUST_TOOL_CONTRACTS = [ kind: "artifact-provider", requiresActiveTarget: true, description: - "Read the embedded cargo-auditable crate dependencies of a local ELF, PE or selected Mach-O slice without running it or requiring Rust. Returns artifact identity, source ranges, ordered packages and dependency edges. Missing metadata does not prove no dependencies; a rustc commit from an observed source path is inferred. Default complete returns the report; detail summary retains it for inspect_analysis_view kind rust, collections packages/edges, or kind cyclonedx for one CycloneDX 1.6 document, via parent_evidence_id. Optional view selects a page in this call and cannot accompany explicit complete detail. Original row indices and every matching version survive selection; select dependencies explicitly for package dependency vectors. Runtime dependencies remain unknown; malformed or oversized inputs fail rather than return partial success.", + "Read the embedded cargo-auditable crate dependencies of a local ELF, PE, selected Mach-O slice or WebAssembly core module without running it or requiring Rust. Returns artifact identity, source ranges, ordered packages and dependency edges. Missing metadata does not prove no dependencies; a rustc commit from an observed source path is inferred. Default complete returns the report; detail summary retains it for inspect_analysis_view kind rust, collections packages/edges, or kind cyclonedx for one CycloneDX 1.6 document, via parent_evidence_id. Optional view selects a page in this call and cannot accompany explicit complete detail. Original row indices and every matching version survive selection; select dependencies explicitly for package dependency vectors. Runtime dependencies remain unknown; malformed or oversized inputs fail rather than return partial success.", inputSchema: inspectRustBinaryRequestSchema, outputSchema: evidenceResultOf( z.union([ diff --git a/src/domain/analysisView/metadataReportSubject.ts b/src/domain/analysisView/metadataReportSubject.ts index 4a6e5de924..56fa90eb09 100644 --- a/src/domain/analysisView/metadataReportSubject.ts +++ b/src/domain/analysisView/metadataReportSubject.ts @@ -16,7 +16,7 @@ import type { AnalysisViewParent } from "./analysisViewParent.js"; export const requireMetadataReportSubject = ( parent: AnalysisViewParent, report: { - readonly format: "elf" | "pe" | "macho"; + readonly format: "elf" | "pe" | "macho" | "wasm"; readonly architecture: string; readonly artifact: { readonly sha256: string }; readonly selected_slice?: MachoTargetSelection; diff --git a/src/domain/analysisView/rustBinaryView.test.ts b/src/domain/analysisView/rustBinaryView.test.ts index dd02b9192a..68aa904a55 100644 --- a/src/domain/analysisView/rustBinaryView.test.ts +++ b/src/domain/analysisView/rustBinaryView.test.ts @@ -3,6 +3,8 @@ import { changedEvidenceSubject, fileIdentity, } from "../../../tests/fixtures/evidenceSubject.js"; +import { metadataReportSubjectFormat } from "../apple/machoTargetSelection.js"; +import { binaryMetadataArchitecture } from "../binaryMetadataArchitecture.js"; import { createEvidence } from "../evidence.js"; import { freezeJsonSnapshot } from "../immutableJson.js"; import type { RustBinary } from "../rust/rustBinary.js"; @@ -41,12 +43,13 @@ const report: RustBinary = { limitations: [], }; const parent = (value = structuredClone(report)): AnalysisViewParent => { + const architecture = binaryMetadataArchitecture(value.architecture); const evidence = createEvidence( { path: value.artifact.path, sha256: value.artifact.sha256, - format: "elf", - architecture: "x86_64", + format: metadataReportSubjectFormat(value), + ...(architecture === undefined ? {} : { architecture }), }, { id: "rust-auditable", name: "Rust reader", version: "1" }, { @@ -140,12 +143,55 @@ it("checks exact artifact identity and subject architecture for every Rust view" } }); +const withSectionName = ( + value: RustBinary, + section_name: NonNullable["section_name"], +): RustBinary => ({ + ...value, + auditable_metadata: + value.auditable_metadata === null + ? null + : { ...value.auditable_metadata, section_name }, +}); + +it("refuses imported reports whose container facts contradict their format", () => { + const wasm: RustBinary = { + ...structuredClone(report), + format: "wasm", + architecture: "wasm", + bits: null, + byte_order: "little", + }; + const accepted = projectAnalysisView(parent(wasm), { kind: "summary" }); + if (!accepted.ok || accepted.value.kind !== "summary") + throw new Error("WebAssembly summary failed"); + expect(accepted.value.summary).toMatchObject({ + format: "wasm", + architecture: "wasm", + bits: null, + byte_order: "little", + }); + for (const value of [ + { ...wasm, architecture: "x86_64" }, + { ...wasm, byte_order: "big" as const }, + { ...wasm, bits: 32 as const }, + { ...structuredClone(report), architecture: "wasm" }, + withSectionName(wasm, "__DATA,.dep-v0"), + withSectionName(structuredClone(report), "__DATA,.dep-v0"), + ]) + expect(projectAnalysisView(parent(value), { kind: "summary" }).ok).toBe( + false, + ); +}); + it("bounds inherited warnings and retains cycle counts without walking a cyclic graph", () => { const input = { ...parent(), limitations: ["x".repeat(300_000)] }; const result = projectAnalysisView(input, { kind: "summary" }); if (!result.ok) throw result.error; expect(result.value).toMatchObject({ summary: { + format: "elf", + bits: 64, auditable_metadata: { format_version: null, counts: { packages: 1, edges: 1, cyclic_packages: 1 }, diff --git a/src/domain/apple/machoTargetSelection.ts b/src/domain/apple/machoTargetSelection.ts index 82b09f9afb..eda6a33458 100644 --- a/src/domain/apple/machoTargetSelection.ts +++ b/src/domain/apple/machoTargetSelection.ts @@ -156,16 +156,21 @@ export const sameMachoTargetSelection = ( left.cpu_subtype === right.cpu_subtype && left.container_table_sha256 === right.container_table_sha256; -/** Evidence subject format of a metadata report that read an ELF, PE, thin Mach-O or universal slice. */ +/** + * Evidence subject format of a metadata report that read an ELF, PE, thin + * Mach-O or universal slice, or a WebAssembly module, which is a file as for WABT. + */ export const metadataReportSubjectFormat = (report: { - readonly format: "elf" | "pe" | "macho"; + readonly format: "elf" | "pe" | "macho" | "wasm"; readonly selected_slice?: MachoTargetSelection; -}): "elf" | "pe" | "mach-o" | "mach-o-universal" => - report.format !== "macho" - ? report.format - : report.selected_slice === undefined - ? "mach-o" - : "mach-o-universal"; +}): "elf" | "pe" | "mach-o" | "mach-o-universal" | "file" => + report.format === "wasm" + ? "file" + : report.format !== "macho" + ? report.format + : report.selected_slice === undefined + ? "mach-o" + : "mach-o-universal"; /** * Whether a metadata report's own container and CPU agree with the universal @@ -173,7 +178,7 @@ export const metadataReportSubjectFormat = (report: { */ export const selectedSliceAgreesWithReport = ( selection: MachoTargetSelection, - format: "elf" | "pe" | "macho", + format: "elf" | "pe" | "macho" | "wasm", architecture: BinaryArchitecture | undefined, ): boolean => selection.container === "fat" && diff --git a/src/domain/rust/rustBinary.ts b/src/domain/rust/rustBinary.ts index ad15aee62c..4098246ad5 100644 --- a/src/domain/rust/rustBinary.ts +++ b/src/domain/rust/rustBinary.ts @@ -43,9 +43,17 @@ const dependencyEdgeSchema = z.strictObject({ to_index: index, }); +const DEPENDENCY_SECTION_NAMES = [".dep-v0", "__DATA,.dep-v0"] as const; + +/** The dependency section's name in a container: Mach-O qualifies it with its segment. */ +export const rustDependencySectionName = ( + format: "elf" | "pe" | "macho" | "wasm", +): (typeof DEPENDENCY_SECTION_NAMES)[number] => + format === "macho" ? "__DATA,.dep-v0" : ".dep-v0"; + /** zlib JSON from one `.dep-v0` section, in the section's package order. */ export const rustAuditableMetadataSchema = z.strictObject({ - section_name: z.enum([".dep-v0", "__DATA,.dep-v0"]), + section_name: z.enum(DEPENDENCY_SECTION_NAMES), file_offset: index, /** Stored section range, including accepted PE file-alignment bytes. */ section_bytes: z.int().positive(), @@ -140,6 +148,21 @@ export const inspectRustBinaryInputSchema = z.strictObject({ ), }); +/** + * Container word size on a Rust dependency report and its summary view. + * ELF, PE and Mach-O are 32 or 64. WebAssembly declares no container word + * size, so the value is null. Null is not a number and must not be coerced. + */ +export type RustContainerBits = 32 | 64 | null; + +/** `32 | 64 | null`. Null is valid only for a WebAssembly report. */ +export const rustContainerBitsSchema = z + .union([z.literal(32), z.literal(64)]) + .nullable() + .describe( + "Container word size: 32 or 64 for ELF, PE and Mach-O. null for WebAssembly, which declares no container word size. null is not a number and must not be coerced to 32 or 64.", + ) satisfies z.ZodType; + /** Bounded cargo-auditable observation. A missing section is null, not an empty dependency list. */ export const rustBinarySchema = z .strictObject({ @@ -148,9 +171,9 @@ export const rustBinarySchema = z sha256: digestSchema, bytes: index, }), - format: z.enum(["elf", "pe", "macho"]), + format: z.enum(["elf", "pe", "macho", "wasm"]), architecture: z.string(), - bits: z.union([z.literal(32), z.literal(64)]), + bits: rustContainerBitsSchema, byte_order: z.enum(["little", "big"]), /** The universal slice that was read; file offsets stay inside it. */ selected_slice: machoTargetSelectionSchema.exactOptional(), @@ -164,8 +187,28 @@ export const rustBinarySchema = z limitations: z.array(z.string()), }) .superRefine((report, context) => { + if ((report.format === "wasm") !== (report.bits === null)) + issue( + context, + ["bits"], + "Word size is null exactly when the container is WebAssembly.", + ); + if ((report.format === "wasm") !== (report.architecture === "wasm")) + issue( + context, + ["architecture"], + "Architecture is wasm exactly when the container is WebAssembly.", + ); + if (report.format === "wasm" && report.byte_order !== "little") + issue(context, ["byte_order"], "A WebAssembly module is little-endian."); const metadata = report.auditable_metadata; if (metadata !== null) { + if (metadata.section_name !== rustDependencySectionName(report.format)) + issue( + context, + ["auditable_metadata", "section_name"], + "Dependency section name does not belong to the report's container.", + ); checkSection(report.artifact.bytes, metadata, context); checkPackages(metadata, context); } diff --git a/src/rust/RustBinaryImage.ts b/src/rust/RustBinaryImage.ts index 214847a38f..4ca0e1f36e 100644 --- a/src/rust/RustBinaryImage.ts +++ b/src/rust/RustBinaryImage.ts @@ -1,6 +1,5 @@ import { BinaryResourceFailure, - type BinaryContainer, type ImageSection, } from "../domain/binaryContainer.js"; import { malformedInput, unsupportedInput } from "../domain/parseFailure.js"; @@ -9,10 +8,12 @@ import { readBinaryContainer } from "../domain/native/readBinaryContainer.js"; import type { RustAuditableMetadata, RustBinary, + RustContainerBits, } from "../domain/rust/rustBinary.js"; import { DEFAULT_RUSTC_HASH_LIMIT, rustcPartialCoverage, + rustDependencySectionName, } from "../domain/rust/rustBinary.js"; import { RUST_PRODUCER_DEFAULTS } from "../domain/rust/rustResourceLimits.js"; import { @@ -20,6 +21,7 @@ import { RUST_AUDITABLE_FORMAT, RustAuditableResourceFailure, } from "./RustAuditableReader.js"; +import { hasWasmPreamble, readRustWasmSections } from "./RustWasmImage.js"; const RUSTC_PREFIX = Buffer.from("/rustc/"); const HASH_BYTES = 40; @@ -28,37 +30,125 @@ const HASH_BYTES = 40; export interface RustBinaryImage { readonly format: RustBinary["format"]; readonly architecture: string; - readonly bits: 32 | 64; + readonly bits: RustContainerBits; readonly byte_order: RustBinary["byte_order"]; readonly auditable_metadata: RustAuditableMetadata | null; readonly rustc_commit: RustBinary["rustc_commit"]; readonly section_names_limitation?: string; } +interface FileSpan { + readonly offset: number; + readonly size: number; +} + +/** The stored dependency stream and the PE padding allowance that may follow it. */ +interface DependencySpan extends FileSpan { + readonly peFileAlignment?: number | undefined; +} + +/** Container identity and the exact file spans that Rust metadata lookups read. */ +interface RustImageLayout extends Pick< + RustBinaryImage, + "format" | "architecture" | "bits" | "byte_order" | "section_names_limitation" +> { + readonly section_name: RustAuditableMetadata["section_name"]; + readonly dependency: DependencySpan | null; + /** Spans where rustc stores constant `/rustc//` path strings. */ + readonly compiler_strings: readonly FileSpan[]; +} + /** Read dependency metadata from container sections without executing the image. */ export const readRustBinaryImage = ( bytes: Buffer, maxRustcHashes = DEFAULT_RUSTC_HASH_LIMIT, maxOutputBytes: number = RUST_PRODUCER_DEFAULTS.output_bytes, ): RustBinaryImage => { + const { section_name, dependency, compiler_strings, ...identity } = + hasWasmPreamble(bytes) ? wasmLayout(bytes) : nativeLayout(bytes); + return { + ...identity, + auditable_metadata: + dependency === null + ? null + : readAuditableSection( + section_name, + dependency.offset, + bytes.subarray( + dependency.offset, + dependency.offset + dependency.size, + ), + { maxOutputBytes, peFileAlignment: dependency.peFileAlignment }, + ), + rustc_commit: rustcCommit( + bytes, + compiler_strings, + maxRustcHashes, + maxOutputBytes, + ), + }; +}; + +const nativeLayout = (bytes: Buffer): RustImageLayout => { const container = readContainer(bytes); - const dependency = dependencySection(container.format, container.sections); + const section_name = rustDependencySectionName(container.format); + const dependency = dependencySection(section_name, container.sections); return { format: container.format, architecture: container.architecture, bits: container.bits, byte_order: container.byte_order, - auditable_metadata: - dependency === null - ? null - : readDependency(bytes, container.format, dependency, maxOutputBytes), - rustc_commit: rustcCommit(bytes, container, maxRustcHashes, maxOutputBytes), ...(container.section_names_limitation === undefined ? {} : { section_names_limitation: container.section_names_limitation }), + section_name, + dependency: + dependency === null + ? null + : { + offset: dependency.offset, + size: dependency.size, + peFileAlignment: + dependency.format === "pe" && + dependency.virtual_size === 0 && + dependency.file_alignment > 0 && + dependency.raw_size % dependency.file_alignment === 0 + ? dependency.file_alignment + : undefined, + }, + compiler_strings: [ + ...container.sections.filter((section) => section.read_only), + ...(container.format === "elf" + ? (container.load_regions ?? []) + .filter((region) => region.read && !region.write && !region.execute) + .map(({ mapping }) => mapping) + : []), + ], }; }; +/** WebAssembly fixes little-endian encoding but declares no container word size. */ +const wasmLayout = (bytes: Buffer): RustImageLayout => { + const { dependency_sections, data_section } = readRustWasmSections(bytes); + if (dependency_sections.length > 1) throw duplicateDependencySection(); + return { + format: "wasm", + architecture: "wasm", + bits: null, + byte_order: "little", + section_name: rustDependencySectionName("wasm"), + dependency: dependency_sections[0] ?? null, + compiler_strings: data_section === null ? [] : [data_section], + }; +}; + +/** cargo-auditable writes one dependency section; a second leaves the list ambiguous. */ +const duplicateDependencySection = () => + malformedInput( + RUST_AUDITABLE_FORMAT, + "Image contains more than one dependency section", + ); + const readContainer = (bytes: Buffer) => { try { return readBinaryContainer(bytes); @@ -81,19 +171,14 @@ const readContainer = (bytes: Buffer) => { }; const dependencySection = ( - format: RustBinaryImage["format"], + expected: RustAuditableMetadata["section_name"], sections: readonly ImageSection[], ): ImageSection | null => { - const expected = format === "macho" ? "__DATA,.dep-v0" : ".dep-v0"; const selected = uniqueKeyed( keyedBy(sections, ({ name }) => name), expected, ); - if (!selected.ok) - throw malformedInput( - RUST_AUDITABLE_FORMAT, - "Image contains more than one dependency section", - ); + if (!selected.ok) throw duplicateDependencySection(); const section = selected.value; if (section === undefined) return null; if (section.compressed) @@ -110,31 +195,9 @@ const dependencySection = ( return section; }; -const readDependency = ( - bytes: Buffer, - format: RustBinaryImage["format"], - section: ImageSection, - maxOutputBytes: number, -): RustAuditableMetadata => - readAuditableSection( - format === "macho" ? "__DATA,.dep-v0" : ".dep-v0", - section.offset, - bytes.subarray(section.offset, section.offset + section.size), - { - maxOutputBytes, - peFileAlignment: - section.format === "pe" && - section.virtual_size === 0 && - section.file_alignment > 0 && - section.raw_size % section.file_alignment === 0 - ? section.file_alignment - : undefined, - }, - ); - const rustcCommit = ( bytes: Buffer, - container: BinaryContainer, + spans: readonly FileSpan[], maxHashes: number, maxOutputBytes: number, ): RustBinaryImage["rustc_commit"] => { @@ -146,18 +209,9 @@ const rustcCommit = ( bytes: 2, reason: undefined, }; - const sections = container.sections - .filter((section) => section.read_only) - .map(({ offset, size }) => ({ offset, size })); - const loadRegions = - container.format === "elf" - ? (container.load_regions ?? []) - .filter((region) => region.read && !region.write && !region.execute) - .map(({ mapping }) => mapping) - : []; // Overlapping section and ELF load ranges are scanned once, so total work // stays bounded by the file size however many mappings reference a range. - for (const range of mergedReadOnlyFileRanges([...sections, ...loadRegions])) { + for (const range of mergedFileRanges(spans)) { collectHashes(bytes, range, retention); if (retention.reason !== undefined) break; } @@ -189,8 +243,8 @@ interface RustcPathRetention { reason: "max_rustc_hashes" | "report_bytes" | undefined; } -const mergedReadOnlyFileRanges = ( - ranges: readonly { readonly offset: number; readonly size: number }[], +const mergedFileRanges = ( + ranges: readonly FileSpan[], ): { readonly offset: number; readonly end: number }[] => { const sorted = ranges .filter(({ size }) => size > 0) diff --git a/src/rust/RustBinaryProvider.ts b/src/rust/RustBinaryProvider.ts index 900dbd55bb..0bebf89dc5 100644 --- a/src/rust/RustBinaryProvider.ts +++ b/src/rust/RustBinaryProvider.ts @@ -40,7 +40,12 @@ import { } from "./RustBinaryImage.js"; import { requireSelectedNativeImage } from "../domain/apple/machoSliceSelection.js"; import { RustAuditableResourceFailure } from "./RustAuditableReader.js"; -import { parseFailureAnalysisError } from "../domain/parseFailureAnalysisError.js"; +import { MAX_WASM_SECTIONS, WASM_FORMAT } from "./RustWasmImage.js"; +import { + isParseLimit, + parseFailureAnalysisError, + parseLimitConstraint, +} from "../domain/parseFailureAnalysisError.js"; import { RUST_PRODUCER_DEFAULTS, @@ -139,7 +144,7 @@ export class RustBinaryProvider implements RustBinaryPort { retainCompilerPathsWithinReport( report, limits.output_bytes, - rustcLimitation(image.rustc_commit), + rustcLimitation(image.rustc_commit, image.format), ); if ( Buffer.byteLength(JSON.stringify(report), "utf8") > @@ -212,7 +217,12 @@ const limitationsFor = ( image: ReturnType, ): string[] => [ "Embedded dependency metadata is file content. It does not authenticate package names, versions, sources, or the compiler that produced the binary.", - "Only the .dep-v0 dependency section and read-only compiler path strings are inspected. Functions, types, and runtime behavior are not recovered.", + `Only the .dep-v0 dependency section and compiler path strings in ${compilerPathSource(image.format)} are inspected. Functions, types, and runtime behavior are not recovered.`, + ...(image.format === "wasm" + ? [ + `WebAssembly declares no container word size, so bits is null. Memory address types were not inspected. Section framing is bounded to ${MAX_WASM_SECTIONS} sections.`, + ] + : []), RUST_RESOURCE_GUARD_LIMITATION, ...(image.section_names_limitation === undefined ? [] @@ -257,12 +267,18 @@ const unknownFormatLimitation = ( ]; }; +/** rustc keeps constant path strings in native read-only data or WebAssembly data segments. */ +const compilerPathSource = (format: RustBinary["format"]): string => + format === "wasm" ? "the WebAssembly data section" : "read-only data"; + const rustcLimitation = ( commit: ReturnType["rustc_commit"], + format: RustBinary["format"], ): string[] => { + const source = compilerPathSource(format); if (commit === null) return [ - "No /rustc/<40-hex>/ path was found in read-only data, so a rustc commit hash is unknown.", + `No /rustc/<40-hex>/ path was found in ${source}, so a rustc commit hash is unknown.`, ]; if (commit.coverage?.reason === "report_bytes") return [ @@ -274,10 +290,10 @@ const rustcLimitation = ( ]; if (commit.hashes.length === 1) return [ - "The rustc commit hash is inferred from a /rustc/<40-hex>/ path in read-only data. It does not by itself prove which compiler produced the binary.", + `The rustc commit hash is inferred from a /rustc/<40-hex>/ path in ${source}. It does not by itself prove which compiler produced the binary.`, ]; return [ - "Read-only data contains more than one /rustc/<40-hex>/ path, so a single rustc commit is unknown.", + `More than one /rustc/<40-hex>/ path was found in ${source}, so a single rustc commit is unknown.`, ]; }; @@ -382,6 +398,15 @@ const failureForPrimary = ( )), }, ); + if (isParseLimit(cause, WASM_FORMAT)) + return parseLimitConstraint(OPERATION, "cpu", cause, { + path, + ...fixedAllowanceOptions( + "The WebAssembly section-walk allowance", + "work", + { limit: cause.failure.limit.maximum, unit: "sections" }, + ), + }); return ( parseFailureAnalysisError(OPERATION, path, cause) ?? artifactFailure(facts, path, limits) diff --git a/src/rust/RustWasmImage.ts b/src/rust/RustWasmImage.ts new file mode 100644 index 0000000000..0e79231be4 --- /dev/null +++ b/src/rust/RustWasmImage.ts @@ -0,0 +1,174 @@ +import { isUtf8 } from "node:buffer"; +import { readLeb128, ULEB32 } from "../domain/leb128.js"; +import { + decodeLimit, + malformedInput, + truncatedInput, + unsupportedInput, +} from "../domain/parseFailure.js"; + +/** The ParseFailure format of WebAssembly section framing. */ +export const WASM_FORMAT = "wasm"; + +/** + * Producer output holds a few dozen sections. The format sets no bound, and a + * 256 MiB input of three-byte custom sections would otherwise keep this + * synchronous walk busy for about 89 million sections. + */ +export const MAX_WASM_SECTIONS = 65_536; +const PREAMBLE = Buffer.from("\0asm", "latin1"); +const CORE_MODULE_VERSION = Buffer.from([1, 0, 0, 0]); +const COMPONENT_LAYER = Buffer.from([1, 0]); +const CUSTOM_SECTION = 0; +const DATA_SECTION = 11; +const DEPENDENCY_SECTION = Buffer.from(".dep-v0", "latin1"); + +/** One exact file range inside the selected WebAssembly module. */ +export interface WasmSectionRange { + readonly offset: number; + readonly size: number; +} + +/** Section ranges that Rust metadata lookups read from one core module. */ +export interface RustWasmSections { + /** + * `.dep-v0` custom-section payloads. Two establish a duplicate, and the walk + * ends there, so later sections are not examined. + */ + readonly dependency_sections: readonly WasmSectionRange[]; + /** The module's data section, where rustc stores constant path strings. */ + readonly data_section: WasmSectionRange | null; +} + +/** Every WebAssembly binary layer, module or component, opens with `\0asm`. */ +export const hasWasmPreamble = (bytes: Buffer): boolean => + bytes.subarray(0, PREAMBLE.length).equals(PREAMBLE); + +/** + * Walk the section framing of one WebAssembly core module without validating, + * instantiating or executing it. Components embed several core modules and no + * input selects one, so they are refused. + */ +export const readRustWasmSections = (bytes: Buffer): RustWasmSections => { + if (bytes.length < 8) + throw truncatedInput(WASM_FORMAT, "WebAssembly header is truncated", { + offset: 0, + }); + if (bytes.subarray(6, 8).equals(COMPONENT_LAYER)) + throw unsupportedInput( + WASM_FORMAT, + "WebAssembly components are unsupported; their embedded core modules are not inspected", + { offset: 6, field: "layer" }, + ); + if (!bytes.subarray(4, 8).equals(CORE_MODULE_VERSION)) + throw unsupportedInput( + WASM_FORMAT, + "Only version 1 WebAssembly core modules are supported", + { offset: 4, field: "version" }, + ); + const dependencies: WasmSectionRange[] = []; + let data: WasmSectionRange | null = null; + let cursor = 8; + for (let sections = 0; cursor < bytes.length; sections += 1) { + if (sections === MAX_WASM_SECTIONS) + throw decodeLimit( + WASM_FORMAT, + `WebAssembly module declares more than ${MAX_WASM_SECTIONS} sections`, + { name: "max_wasm_sections", maximum: MAX_WASM_SECTIONS }, + { offset: cursor }, + ); + const id = bytes[cursor]!; + const size = readU32(bytes, cursor + 1, bytes.length, { + label: "section size", + boundary: "file", + }); + const end = size.end + size.value; + if (end > bytes.length) + throw truncatedInput( + WASM_FORMAT, + "WebAssembly section extends past the end of the file", + { offset: cursor, field: "section" }, + ); + if (id === CUSTOM_SECTION) { + const custom = customSection(bytes, size.end, end); + if (custom.name.equals(DEPENDENCY_SECTION)) { + dependencies.push({ + offset: custom.payload, + size: end - custom.payload, + }); + // A second match establishes the duplicate. Walking on could only + // replace that failure with a later one, such as the section bound. + if (dependencies.length === 2) break; + } + } else if (id === DATA_SECTION) { + if (data !== null) + throw malformedInput( + WASM_FORMAT, + "WebAssembly module declares more than one data section", + { offset: cursor, field: "data section" }, + ); + data = { offset: size.end, size: size.value }; + } + cursor = end; + } + return { dependency_sections: dependencies, data_section: data }; +}; + +/** Decode a custom section's UTF-8 name and locate the payload that follows it. */ +const customSection = ( + bytes: Buffer, + start: number, + end: number, +): { readonly name: Buffer; readonly payload: number } => { + const length = readU32(bytes, start, end, { + label: "custom section name length", + boundary: "section", + }); + if (length.value > end - length.end) + throw malformedInput( + WASM_FORMAT, + "WebAssembly custom section name extends past its section", + { offset: start, field: "custom section name" }, + ); + const payload = length.end + length.value; + const name = bytes.subarray(length.end, payload); + if (!isUtf8(name)) + throw malformedInput( + WASM_FORMAT, + "WebAssembly custom section name is not valid UTF-8", + { offset: length.end, field: "custom section name" }, + ); + return { name, payload }; +}; + +/** + * Decode one unsigned LEB128 u32 that must end before `end`. An integer the + * file cuts off is truncated; one its enclosing section cuts off is malformed, + * wherever that section lies in the file. + */ +const readU32 = ( + bytes: Buffer, + offset: number, + end: number, + { + label, + boundary, + }: { readonly label: string; readonly boundary: "file" | "section" }, +): { readonly value: number; readonly end: number } => { + const read = readLeb128(bytes, offset, end, ULEB32); + if ("value" in read) return { value: Number(read.value), end: read.next }; + const site = { offset, field: label }; + if (read.failure === "truncated" && boundary === "file") + throw truncatedInput( + WASM_FORMAT, + `WebAssembly ${label} extends past the end of the file`, + site, + ); + throw malformedInput( + WASM_FORMAT, + read.failure === "truncated" + ? `WebAssembly ${label} extends past its section` + : `WebAssembly ${label} does not fit a 32-bit LEB128 integer`, + site, + ); +}; diff --git a/tests/acceptance/rustBinaryCli.test.ts b/tests/acceptance/rustBinaryCli.test.ts index dd0efd3840..ab5d720279 100644 --- a/tests/acceptance/rustBinaryCli.test.ts +++ b/tests/acceptance/rustBinaryCli.test.ts @@ -11,10 +11,12 @@ import { compressRustElfSectionNames, createRustHashOverflowImage, createRustImage, + createRustWasmModule, createRustImageWithGoSection, RUSTC_HASH, rustDependencyPayload, } from "../fixtures/rust/image.js"; +import { fileIdentity } from "../fixtures/evidenceSubject.js"; import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; import { cliTest } from "../support/cli/cliFixture.js"; import { lazyLocalToolsMcp } from "../fixtures/localToolsMcp.js"; @@ -105,6 +107,59 @@ cliTest( }, ); +cliTest( + "reports cargo-auditable packages from a WebAssembly module", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-rust-cli-wasm-"); + const path = join(root, "sample.wasm"); + await writeFile(path, createRustWasmModule()); + const result = await cli.run({ + arguments: ["inspect-rust-binary", path, "--json"], + }); + expect(result.exitCode, result.stderr).toBe(0); + const evidence = toolContract("inspect_rust_binary").outputSchema.parse( + result.json, + ); + expect(fileIdentity(evidence.subject)).toMatchObject({ + format: "file", + architecture: null, + }); + const report = rustBinarySchema.parse(evidence.normalized_result); + expect(report.format).toBe("wasm"); + expect(report.architecture).toBe("wasm"); + expect(report.bits).toBeNull(); + expect(report.byte_order).toBe("little"); + expect(report.auditable_metadata).toMatchObject({ + section_name: ".dep-v0", + root_package_index: 1, + packages: [ + { name: "itoa", version: "1.0.18" }, + { name: "sample", version: "0.1.0", root: true }, + ], + }); + }, +); + +cliTest( + "refuses a WebAssembly component as an unsupported target", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-rust-cli-component-"); + const path = join(root, "component.wasm"); + await writeFile(path, Buffer.from("0061736d0d000100", "hex")); + const result = await cli.run({ + arguments: ["inspect-rust-binary", path, "--json"], + }); + expect(result.exitCode).toBe(1); + expect(result.json).toMatchObject({ + code: "unsupported_target", + details: { + operation: "inspect_rust_binary", + reason: expect.stringContaining("components are unsupported"), + }, + }); + }, +); + cliTest( "preserves historical cargo-auditable features through CLI and stdio MCP", async ({ cli }) => { diff --git a/tests/acceptance/rustDependencyViews.test.ts b/tests/acceptance/rustDependencyViews.test.ts index 700363f96a..4db8613fcb 100644 --- a/tests/acceptance/rustDependencyViews.test.ts +++ b/tests/acceptance/rustDependencyViews.test.ts @@ -3,6 +3,7 @@ import { readFile, unlink, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { expect } from "vitest"; import { parseEvidence, createEvidence } from "../../src/domain/evidence.js"; +import { metadataReportSubjectFormat } from "../../src/domain/apple/machoTargetSelection.js"; import { createEvidenceBundle } from "../../src/domain/evidenceBundle.js"; import { rustBinarySchema } from "../../src/domain/rust/rustBinary.js"; import { analysisViewResultSchema } from "../../src/domain/analysisView/analysisViewResult.js"; @@ -12,11 +13,21 @@ import { parseMcpToolError } from "../fixtures/mcpToolError.js"; import { createRustImage, createRustHashOverflowImage, + createRustWasmModule, rustDependencyPayload, } from "../fixtures/rust/image.js"; import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; import { cliTest } from "../support/cli/cliFixture.js"; +/** One synthetic cargo-auditable artifact for each supported container. */ +const rustArtifact = ( + format: "elf" | "pe" | "macho" | "wasm", + payload: Buffer, +): Buffer => + format === "wasm" + ? createRustWasmModule({ payload }) + : createRustImage({ format, payload }); + cliTest( "keeps compiler-prefix coverage in CLI summaries until the selected budget admits every hash", async ({ cli }) => { @@ -225,7 +236,7 @@ cliTest( async ({ cli }) => { const root = await createTestTempDirectory("rea-rust-views-"); const { call } = await connectLocalToolsMcp(); - for (const format of ["elf", "pe", "macho"] as const) { + for (const format of ["elf", "pe", "macho", "wasm"] as const) { const path = join(root, `source.${format}`); const output = join(root, `${format}-source.json`); const payload = rustDependencyPayload({ @@ -253,7 +264,7 @@ cliTest( }, ], }); - await writeFile(path, createRustImage({ format, payload })); + await writeFile(path, rustArtifact(format, payload)); const fullReply = await call("inspect_rust_binary", { path }); expect(fullReply.isError).not.toBe(true); const full = parseEvidence(fullReply.structuredContent); @@ -347,7 +358,7 @@ cliTest( { path, sha256: report.artifact.sha256, - format: format === "macho" ? "mach-o" : format, + format: metadataReportSubjectFormat({ format }), ...fileSubjectArchitecture(full.subject), }, full.provider, diff --git a/tests/boundary/cli/cliOutputFormatter.test.ts b/tests/boundary/cli/cliOutputFormatter.test.ts index 0fa8578ebc..20fc47f4f7 100644 --- a/tests/boundary/cli/cliOutputFormatter.test.ts +++ b/tests/boundary/cli/cliOutputFormatter.test.ts @@ -181,6 +181,37 @@ it.each([" =1+1", "+1", "-1", "@SUM(A1:A2)"])( }, ); +it("keeps a null word size null and a native word size numeric", () => { + const wasm = { format: "wasm", bits: null }; + const native = { format: "elf", bits: 64 }; + expect(formatCliOutput(wasm, "json")).toBe( + '{\n "format": "wasm",\n "bits": null\n}', + ); + expect(formatCliOutput(native, "json")).toBe( + '{\n "format": "elf",\n "bits": 64\n}', + ); + expect(formatCliOutput(wasm, "yaml")).toBe("format: wasm\nbits: null\n"); + expect(formatCliOutput(native, "yaml")).toBe("format: elf\nbits: 64\n"); + expect(formatCliOutput(wasm, "toon")).toBe("format: wasm\nbits: null"); + expect(formatCliOutput(native, "toon")).toBe("format: elf\nbits: 64"); + expect(formatCliOutput(wasm, "md")).toContain("| bits | null |"); + expect(formatCliOutput(native, "md")).toContain("| bits | 64 |"); + for (const format of ["csv", "tsv"] as const) { + const rows = formatCliOutput([wasm, native], format, { + fields: ["bits"], + metadata: {}, + }); + const lineEnding = format === "csv" ? "\r\n" : "\n"; + const body = rows.slice(rows.indexOf(lineEnding) + lineEnding.length); + expect( + parseDelimited( + body.replace(/\r?\n$/u, ""), + format === "csv" ? "," : "\t", + ), + ).toEqual([["bits"], [""], ["64"]]); + } +}); + it("refuses formula-leading column headers", () => { expect( prepareDelimitedOutput([{ value: "safe" }], "csv", { diff --git a/tests/boundary/mcp/rustBinaryMcp.test.ts b/tests/boundary/mcp/rustBinaryMcp.test.ts index c1836a832e..af66efb047 100644 --- a/tests/boundary/mcp/rustBinaryMcp.test.ts +++ b/tests/boundary/mcp/rustBinaryMcp.test.ts @@ -11,6 +11,8 @@ import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; import { createRustImage, createRustHashOverflowImage, + createRustWasmModule, + createWasmSectionFlood, } from "../../fixtures/rust/image.js"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; import { mcpTest, type TestMcp } from "../../support/mcp/mcpFixture.js"; @@ -74,6 +76,26 @@ mcpTest( rustBinarySchema.parse(absentEvidence.normalized_result) .auditable_metadata, ).toBeNull(); + // The listed tools let the client check WebAssembly's null word size + // against the advertised output schema, not only the source contract. + const module = join(root, "sample.wasm"); + await writeFile(module, createRustWasmModule()); + const wasm = await client.callTool({ + name: "inspect_rust_binary", + arguments: { path: module }, + }); + expect(wasm.isError, JSON.stringify(wasm.content)).not.toBe(true); + expect( + rustBinarySchema.parse( + toolContract("inspect_rust_binary").outputSchema.parse( + wasm.structuredContent, + ).normalized_result, + ), + ).toMatchObject({ + format: "wasm", + bits: null, + auditable_metadata: { section_name: ".dep-v0", root_package_index: 1 }, + }); } finally { await session.close(); } @@ -197,3 +219,36 @@ mcpTest( } }, ); + +mcpTest( + "refuses a WebAssembly section walk past its fixed work allowance", + async ({ mcp }) => { + const { client, session } = await connect(mcp); + try { + const root = await createTestTempDirectory("rea-rust-mcp-"); + const path = join(root, "many-sections.wasm"); + await writeFile(path, createWasmSectionFlood(65_537)); + const response = await client.callTool({ + name: "inspect_rust_binary", + arguments: { path }, + }); + expect(parseMcpToolError(response).error).toMatchObject({ + code: "resource_constraint", + retryable: false, + details: { + operation: "inspect_rust_binary", + resource: "cpu", + reported_limits: { boundary: "max_wasm_sections", maximum: 65_536 }, + refusal: { + kind: "fixed_ceiling", + allowance_kind: "work", + limit: 65_536, + unit: "sections", + }, + }, + }); + } finally { + await session.close(); + } + }, +); diff --git a/tests/boundary/rust/rustBinaryImage.test.ts b/tests/boundary/rust/rustBinaryImage.test.ts index 8ada7ecde7..5d454b4bc0 100644 --- a/tests/boundary/rust/rustBinaryImage.test.ts +++ b/tests/boundary/rust/rustBinaryImage.test.ts @@ -4,10 +4,15 @@ import { createRustImage, createRustImageWithGoSection, createRustHashOverflowImage, + createRustWasmModule, + createWasmSectionFlood, compressRustElfSectionNames, rustElfSectionNameFixture, RUSTC_HASH, rustDependencyPayload, + WASM_MODULE_HEADER, + wasmCustomSection, + wasmSection, } from "../../fixtures/rust/image.js"; import { readRustBinaryImage } from "../../../src/rust/RustBinaryImage.js"; import { readBinaryContainer } from "../../../src/domain/native/readBinaryContainer.js"; @@ -145,6 +150,175 @@ it("reads a Mach-O __DATA,.dep-v0 section", () => { }); }); +it("reads a .dep-v0 custom section and a data-section rustc hash from a WebAssembly module", () => { + const bytes = createRustWasmModule(); + expect(readRustBinaryImage(bytes)).toEqual({ + format: "wasm", + architecture: "wasm", + bits: null, + byte_order: "little", + auditable_metadata: expect.objectContaining({ + section_name: ".dep-v0", + file_offset: bytes.indexOf(rustDependencyPayload()), + section_bytes: rustDependencyPayload().length, + format_version: 1, + root_package_index: 1, + packages, + dependency_edges: [{ from_index: 1, to_index: 0 }], + }), + rustc_commit: { + evidence_kind: "inferred", + hashes: [{ hash: RUSTC_HASH, file_offset: bytes.indexOf("/rustc/") }], + }, + }); +}); + +it("returns null metadata for a WebAssembly module without .dep-v0", () => { + const bytes = createRustWasmModule({ omitSection: true }); + const image = readRustBinaryImage(bytes); + expect(image).toMatchObject({ format: "wasm", bits: null }); + expect(image.auditable_metadata).toBeNull(); + expect(image.rustc_commit?.hashes).toEqual([ + { hash: RUSTC_HASH, file_offset: bytes.indexOf("/rustc/") }, + ]); +}); + +it.each([ + [ + "a component", + Buffer.from("0061736d0d000100", "hex"), + { kind: "unsupported", format: "wasm", offset: 6, field: "layer" }, + ], + [ + "a pre-release core module", + Buffer.from("0061736d0d000000", "hex"), + { kind: "unsupported", format: "wasm", offset: 4, field: "version" }, + ], + [ + "a truncated header", + WASM_MODULE_HEADER.subarray(0, 6), + { kind: "truncated", format: "wasm", offset: 0 }, + ], + [ + "a section past the end of the file", + Buffer.concat([WASM_MODULE_HEADER, Buffer.from([0x01, 0x05, 0x00])]), + { kind: "truncated", format: "wasm", offset: 8, field: "section" }, + ], + [ + "a section size cut off by the end of the file", + Buffer.concat([WASM_MODULE_HEADER, Buffer.from([0x00, 0x80])]), + { kind: "truncated", format: "wasm", offset: 9, field: "section size" }, + ], + [ + "a custom name length cut off by its section", + Buffer.concat([ + WASM_MODULE_HEADER, + wasmSection(0, Buffer.from([0x80])), + wasmSection(1, Buffer.from([0x00])), + ]), + { + kind: "malformed", + format: "wasm", + offset: 10, + field: "custom section name length", + }, + ], + [ + "a custom name length cut off by the final section", + Buffer.concat([WASM_MODULE_HEADER, wasmSection(0, Buffer.from([0x80]))]), + { + kind: "malformed", + format: "wasm", + offset: 10, + field: "custom section name length", + }, + ], + [ + "a section size over 32 bits", + Buffer.concat([ + WASM_MODULE_HEADER, + Buffer.from([0x00, 0xff, 0xff, 0xff, 0xff, 0x1f]), + ]), + { kind: "malformed", format: "wasm", offset: 9, field: "section size" }, + ], + [ + "a custom name past its section", + Buffer.concat([ + WASM_MODULE_HEADER, + wasmSection(0, Buffer.from([0x05, 0x61])), + ]), + { + kind: "malformed", + format: "wasm", + offset: 10, + field: "custom section name", + }, + ], + [ + "a non-UTF-8 custom section name", + Buffer.concat([ + WASM_MODULE_HEADER, + wasmCustomSection(Buffer.from([0xff]), Buffer.alloc(0)), + ]), + { + kind: "malformed", + format: "wasm", + offset: 11, + field: "custom section name", + }, + ], + [ + "a duplicate .dep-v0 custom section", + createRustWasmModule({ + sections: [wasmCustomSection(".dep-v0", rustDependencyPayload())], + }), + { kind: "malformed", format: "rust-auditable" }, + ], + [ + "a second data section", + createRustWasmModule({ sections: [wasmSection(11, Buffer.from([0]))] }), + { kind: "malformed", format: "wasm", field: "data section" }, + ], +] as const)("refuses WebAssembly with %s", (_name, bytes, failure) => { + expect(() => readRustBinaryImage(bytes)).toThrow( + expect.objectContaining({ + failure: expect.objectContaining(failure), + }), + ); +}); + +it("reports a duplicate .dep-v0 section ahead of the section bound that follows it", () => { + const bytes = createRustWasmModule({ + sections: [ + wasmCustomSection(".dep-v0", rustDependencyPayload()), + createWasmSectionFlood(65_537).subarray(WASM_MODULE_HEADER.length), + ], + }); + expect(() => readRustBinaryImage(bytes)).toThrow( + expect.objectContaining({ + failure: expect.objectContaining({ + kind: "malformed", + format: "rust-auditable", + }), + }), + ); +}); + +it("bounds the synchronous WebAssembly section walk", () => { + expect( + readRustBinaryImage(createWasmSectionFlood(65_536)).auditable_metadata, + ).toBeNull(); + expect(() => readRustBinaryImage(createWasmSectionFlood(65_537))).toThrow( + expect.objectContaining({ + failure: expect.objectContaining({ + kind: "limit", + format: "wasm", + limit: { name: "max_wasm_sections", maximum: 65_536 }, + }), + }), + ); +}); + it("preserves the arm64_32 Mach-O CPU family when dependency metadata is absent", () => { const bytes = createRustImage({ format: "macho", diff --git a/tests/fixtures/rust/image.ts b/tests/fixtures/rust/image.ts index 2e3dbdf91d..09c007ebcd 100644 --- a/tests/fixtures/rust/image.ts +++ b/tests/fixtures/rust/image.ts @@ -292,6 +292,81 @@ const writeMachoSegment = ({ body.copy(bytes, fileOffset); }; +/** Unsigned LEB128, as the WebAssembly binary format encodes sizes and counts. */ +const leb128 = (value: number): Buffer => { + const bytes: number[] = []; + let remaining = value; + do { + const low = remaining & 0x7f; + remaining = Math.floor(remaining / 0x80); + bytes.push(remaining === 0 ? low : low | 0x80); + } while (remaining !== 0); + return Buffer.from(bytes); +}; + +export const WASM_MODULE_HEADER = Buffer.from("0061736d01000000", "hex"); + +/** One framed WebAssembly section. */ +export const wasmSection = (id: number, content: Buffer): Buffer => + Buffer.concat([Buffer.from([id]), leb128(content.length), content]); + +/** A custom section with an exact name encoding and opaque payload. */ +export const wasmCustomSection = ( + name: string | Buffer, + payload: Buffer, +): Buffer => { + const encoded = typeof name === "string" ? Buffer.from(name) : name; + return wasmSection( + 0, + Buffer.concat([leb128(encoded.length), encoded, payload]), + ); +}; + +/** + * Core module shaped like cargo-auditable output: one memory, a rustc path in + * an active data segment, and a `.dep-v0` custom section beside an unrelated + * one. Extra sections follow the module's own sections. + */ +export const createRustWasmModule = ( + options: { + readonly payload?: Buffer; + readonly omitSection?: boolean; + readonly includeRustc?: boolean; + readonly sections?: readonly Buffer[]; + } = {}, +): Buffer => { + const rustc = Buffer.from(RUSTC_PATH); + // One active segment at i32.const 1024 in memory 0. + const segment = Buffer.concat([ + Buffer.from([0x01, 0x00, 0x41, 0x80, 0x08, 0x0b]), + leb128(rustc.length), + rustc, + ]); + return Buffer.concat([ + WASM_MODULE_HEADER, + wasmSection(1, Buffer.from([0x00])), + wasmSection(5, Buffer.from([0x01, 0x00, 0x01])), + ...(options.includeRustc === false ? [] : [wasmSection(11, segment)]), + ...(options.omitSection === true + ? [] + : [ + wasmCustomSection( + ".dep-v0", + options.payload ?? rustDependencyPayload(), + ), + ]), + wasmCustomSection("producers", Buffer.from([0x00])), + ...(options.sections ?? []), + ]); +}; + +/** The densest section framing: three-byte custom sections with empty names. */ +export const createWasmSectionFlood = (count: number): Buffer => + Buffer.concat([ + WASM_MODULE_HEADER, + Buffer.alloc(count * 3, Buffer.from([0x00, 0x01, 0x00])), + ]); + /** Read-only ELF data exceeding the distinct rustc-hash retention capacity. */ export const createRustHashOverflowImage = (): Buffer => { const bytes = Buffer.alloc(8192);