mirror of
https://github.com/morluto/rea.git
synced 2026-11-19 21:23:45 +00:00
* feat(rust): read cargo-auditable dependencies from WebAssembly modules cargo-auditable embeds the same zlib-compressed `.dep-v0` JSON in a WebAssembly custom section for wasm32 targets, but inspect_rust_binary rejected every module as an unsupported target because only ELF, PE and thin Mach-O containers were recognized. Walk the section framing of version 1 core modules to locate the `.dep-v0` custom-section payload and the data section, where rustc keeps its constant /rustc/<hash>/ paths. Rust lookups now read one format-neutral layout, so native and WebAssembly images share a single dependency-section owner. WebAssembly declares no container word size, so `bits` is null for that format only; the Evidence subject format is `file`, as for inspect_wasm_artifact. Truncated sections, invalid LEB128 sizes, custom-section names that run past their section or are not UTF-8, duplicate `.dep-v0` sections and a second data section are malformed. Components, such as wasm32-wasip2 output, embed core modules and are refused as unsupported, like universal Mach-O containers, rather than inspected through one selected module. * fix(rust): bound the WebAssembly section walk The WebAssembly reader visited every section synchronously, and the format sets no section count. A 256 MiB input of three-byte custom sections with empty names walked about 89 million sections and held the event loop for about 7.4 seconds, delaying cancellation and other MCP requests; empty type sections took about 1.9 seconds. Refuse a module with more than 65,536 sections with a typed cpu resource constraint that reports maximum_wasm_sections, as the Go header search reports its work budget. Producer output holds a few dozen sections, and the same inputs are now refused within tens of milliseconds. * fix(rust): accept WebAssembly Evidence in retained dependency views Retained Rust views compared the parent subject with a Mach-O-only format mapping, so WebAssembly Evidence, whose subject format is file, was refused as a different artifact. The report domain now owns the subject format next to the architecture mapping, and the service and the view both use it. The real CLI/MCP view workflow now also covers a WebAssembly module. * fix(rust): name the WebAssembly section-walk allowance in recovery Fixed-allowance recovery mapped every Rust resource other than capacity and transport to the parser allowance, so the section-walk refusal said host memory does not raise it. Each Rust resource now maps to its own allowance, and the cpu bound is a fixed work allowance. The MCP error contract test checks that the refusal is not retryable and names that allowance. * fix(rust): require WebAssembly container facts in reports The report schema tied a null word size to WebAssembly, but it accepted a wasm report that named a native architecture or big-endian byte order, and a native report that named the wasm architecture. Retained views parse imported Evidence with this schema, so such a contradictory report was accepted. The architecture is now wasm exactly when the container is WebAssembly, and a WebAssembly report must be little-endian. * docs(rust): record the WebAssembly dependency-metadata feature Feature work now carries a spec, plan and task list under docs/specs. This adds that record for reading cargo-auditable metadata from WebAssembly core modules and indexes it. The record states that it was written during review and lists the verification that remains open. * fix(rust): bind section names to containers and share the LEB128 reader The report schema accepted a dependency section name that does not belong to the report's container, such as a WebAssembly report naming the Mach-O section. rustDependencySectionName now owns that name for the reader and the schema, which refuses a mismatch for every container. The WebAssembly reader decoded section sizes with its own loop. It now uses the shared readLeb128, and an integer cut off by the end of the file is truncated rather than malformed. * fix(rust): classify a cut-off WebAssembly integer by its boundary The reader called an unfinished LEB128 integer truncated whenever its limit equalled the file length. A name length cut off inside the final section was therefore truncated, and the same bytes followed by another section were malformed. Each caller now states whether the file or the enclosing section bounds the integer. * fix(rust): report a duplicate WebAssembly dependency section first The section walk kept two .dep-v0 matches but walked on, so a module with two dependency sections and more than 65,536 sections after them was refused for the section bound instead of the duplicate it had already established. The walk now ends at the second match. * test(rust): assert WebAssembly container facts instead of limitation prose The CLI acceptance test matched an English limitation sentence. It now checks format, architecture, bits and byte order on the parsed report. * fix(rust): state container word size as 32 | 64 | null Output contract: inspect_rust_binary bits, including the summary view, is 32 | 64 | null. Null is valid only for WebAssembly and is not a number. ELF, PE and Mach-O reports stay 32 or 64. The schema description, guide, feature record and skill state that, and CLI renderers keep null instead of substituting a word size. --------- Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Cursor Agent <cursoragent@cursor.com>
254 lines
13 KiB
Markdown
254 lines
13 KiB
Markdown
# Rust binary dependency metadata
|
|
|
|
`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, 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
|
|
```
|
|
|
|
The CLI resolves relative paths against the caller's working directory. MCP
|
|
requires an absolute filesystem path and preserves that exact selection:
|
|
|
|
```json
|
|
{
|
|
"name": "inspect_rust_binary",
|
|
"arguments": { "path": "/artifacts/application" }
|
|
}
|
|
```
|
|
|
|
## Observations
|
|
|
|
Complete delivery remains the default. For a dependency question, select the
|
|
needed records on the first call instead of returning the complete graph:
|
|
|
|
```json
|
|
{
|
|
"name": "inspect_rust_binary",
|
|
"arguments": {
|
|
"path": "/artifacts/application",
|
|
"view": {
|
|
"collection": "packages",
|
|
"names": ["serde", "serde_derive"],
|
|
"fields": ["name", "version", "source", "dependencies"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
`detail: "summary"` returns section ranges, root index, package/edge/cycle counts
|
|
and compiler-hash count. A `view` selects compact delivery automatically;
|
|
combining it with explicit `detail: "complete"` is an input error. The complete
|
|
parent Evidence is retained in the MCP session and remains exportable. Subsequent
|
|
`inspect_analysis_view` calls accept that `parent_evidence_id`, or its portable
|
|
Evidence file, without reopening the binary:
|
|
|
|
```json
|
|
{
|
|
"source": {
|
|
"kind": "retained-evidence",
|
|
"evidence_id": "ev_<parent digest>"
|
|
},
|
|
"view": {
|
|
"kind": "rust",
|
|
"collection": "edges",
|
|
"from_indices": [12],
|
|
"limit": 20
|
|
}
|
|
}
|
|
```
|
|
|
|
Package filters accept exact `names`, `versions` and original `indices`; edge
|
|
filters accept original edge `indices`, `from_indices` and `to_indices`.
|
|
Filters intersect, and an empty filter array selects nothing. `offset` counts
|
|
matching records; `limit` defaults to 64. Pages retain original indices scoped
|
|
to the parent Evidence, selected fields, examined coverage and the next offset.
|
|
Default package fields omit dependency vectors; explicitly select
|
|
`dependencies` to obtain direct references. No dependency path is traversed.
|
|
|
|
The same parent also projects one CycloneDX 1.6 document with
|
|
`view: { "kind": "cyclonedx" }`. It reads no target bytes. See
|
|
[CycloneDX dependencies](guides/native/cyclonedx-view.md).
|
|
|
|
The CLI uses the same views and requires an exclusive output bundle for compact
|
|
delivery so the complete Evidence survives process exit:
|
|
|
|
```bash
|
|
rea inspect-rust-binary /artifacts/application --json \
|
|
--view '{"collection":"packages","names":["serde"],"fields":["name","version"]}' \
|
|
--evidence_output /artifacts/rust-evidence.json
|
|
```
|
|
|
|
Compact results distinguish complete embedded-record coverage from unknown
|
|
runtime dependency coverage. A missing section remains unknown rather than an
|
|
empty dependency set. Retained views describe the captured artifact digest;
|
|
they do not assert that the current file or running application is unchanged.
|
|
|
|
ELF section names are resolved through the section-header string table.
|
|
Zlib- and Zstandard-compressed name tables are decoded within the native structural
|
|
budget. Zstandard decoding also uses a 128 MiB window limit.
|
|
If a name table uses unsupported compression, the result reports that
|
|
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. `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, 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;
|
|
- `packages`, in the section's original order, with `name`, `version`, `source`,
|
|
`kind`, `dependencies`, `features`, and `root`;
|
|
- `root_package_index`, the single package marked `root`, or `null` when none is marked;
|
|
- `dependency_edges`, pairs of package indices in package-then-dependency order;
|
|
- `cyclic_dependency_indices`, sorted unique indices that participate in a cycle.
|
|
|
|
An omitted `kind` stays `null`. The embedded format treats that omission as
|
|
runtime, and that default is not stored in the section. An omitted dependency
|
|
list is an empty array. An omitted `features` field is `null`, because it does
|
|
not establish whether features were empty or the producer did not record them;
|
|
an explicit empty array establishes an empty list. An omitted `root` flag is
|
|
false.
|
|
Historical [cargo-auditable 0.4 package records](https://github.com/rust-secure-code/cargo-auditable/blob/v0.4.0/auditable-serde/src/lib.rs)
|
|
may include the package `features` list; REA preserves those strings. That
|
|
version omitted empty feature lists during serialization, while version 0.5
|
|
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, 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
|
|
does not erase a section's validated read-only range: ELF defines the
|
|
[section-name index](https://gabi.xinuos.com/elf/03-sheader.html#section-header-table-entry)
|
|
separately from its type and flags, and
|
|
[string-table index zero](https://gabi.xinuos.com/elf/04-strtab.html) means no name.
|
|
REA preserves known empty names separately from unavailable names; an unavailable
|
|
name table still leaves `.dep-v0` presence unknown.
|
|
The hash is not a claim that that compiler produced the binary. Several
|
|
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
|
|
limited to 1 MiB compressed. Inflated JSON is limited to the smaller of 8 MiB
|
|
and 64 times the compressed stream length. The complete report is limited to
|
|
8 MiB. Empty sections,
|
|
truncated streams, nonpadding bytes after a zlib stream, invalid JSON, duplicate
|
|
object fields, unknown fields, dependency
|
|
indices outside the package list, more than one root package, and compressed
|
|
dependency sections are typed failures. A cycle is reported and is not walked.
|
|
|
|
For PE images with `VirtualSize` zero, the raw-size fallback can include file
|
|
alignment bytes. REA excludes a zero suffix only when the raw section size is
|
|
the zlib stream length rounded up to the declared `FileAlignment`; nonzero or
|
|
oversized suffixes and truncated streams remain failures.
|
|
|
|
A missing section returns success with `auditable_metadata: null` and a
|
|
limitation. Absence of `.dep-v0` does not mean the binary has no dependencies.
|
|
Unknown embedded format revisions are retained in `format_version` and
|
|
interpreted using the highest known preceding revision, following the
|
|
cargo-auditable schema. The output includes a limitation that identifies this
|
|
fallback and notes that the particular revision has not been independently
|
|
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, 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,
|
|
alignment and Mach-O header CPU against the table. The result keeps the
|
|
universal file as `artifact` (its SHA-256 and size), adds `selected_slice` with
|
|
the slice offset, length, raw CPU type/subtype and the FAT table digest, and
|
|
reports the section and rustc-path offsets as a file offset inside that slice.
|
|
Without `architecture`, or when the file has no slice of that CPU family, the
|
|
request fails on `architecture` and lists the slices present. A CPU family with
|
|
one slice is selected by its family name, so `arm64` also reads a lone `arm64e`
|
|
slice; `arm64e` reads only an `arm64e` slice. When several slices share the
|
|
family, the value must name the slice's subtype, as `lipo -thin` does: `arm64`
|
|
reads the `arm64` (or `arm64v8`) slice, `arm64e` the `arm64e` (or `arm64e.x1`)
|
|
slice, and `x86_64` the canonical `x86_64` slice. Capability bits are ignored
|
|
when subtypes are compared. REA does not choose a slice by preference. When no
|
|
slice or several slices carry the named subtype, the request fails on
|
|
`architecture` and names any other value that selects exactly one verified
|
|
slice; `arm64e` beside `arm64e.x1`, for example, is refused. Other subtypes,
|
|
such as `x86_64h` and the `x86` (i386) and 32-bit `arm` subtypes, have no value
|
|
of their own; they are read only as the only slice of their family.
|
|
`limitations` lists the same-family slices that were not read and the value, if
|
|
any, that selects each. A slice whose Mach-O header does not match its FAT
|
|
declaration, such as a different CPU subtype, is listed as unverified, and no
|
|
value is offered for it. `architecture` on any other image is rejected rather
|
|
than ignored.
|
|
|
|
Package and dependency counts are checked against the minimum required JSON
|
|
representation before graph allocation or schema cloning. Oversized graphs
|
|
report the output byte budget.
|
|
|
|
The inferred compiler-path facet keeps at most `max_rustc_hashes` distinct
|
|
hashes by default (64). Reaching that selection leaves the dependency report
|
|
available and adds `rustc_commit.coverage` with partial status and the effective
|
|
limit. Increase `max_rustc_hashes` (CLI `--max-rustc-hashes`) on the next call
|
|
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
|
|
being inferred from a related spelling.
|
|
|
|
Input and complete-report admission are caller choices through `producer_limits`:
|
|
`input_bytes` defaults to 256 MiB and `output_bytes` to 8 MiB. Both accept positive
|
|
safe integers and apply to the next call without restarting REA. On CLI, use
|
|
`--producer-limits '{"input_bytes":536870912,"output_bytes":16777216}'`.
|
|
Graph expansion and compiler-path retention consume the same selected report
|
|
allowance. The independent compressed dependency limit (1 MiB), inflated JSON
|
|
limits (8 MiB and 64 times the consumed stream), parser nesting and transport
|
|
budgets remain enforced; increasing report admission does not raise those.
|