wasm-tools

wasm-tools is a pure-Python WebAssembly parser, disassembler, and security triage toolkit. It decodes core modules and Component Model binaries, produces objdump-style disassembly, extracts strings with linear-memory provenance, builds a static call graph, and emits a structured JSON report with capability and risk analysis. It never executes the code it parses, and the library has zero runtime dependencies.

Documentation site

The full documentation is published at appthreat.github.io/wasm-tools and lives in this repository under docs/. The site is plain markdown served by docsify, so every page is readable both on GitHub and in the browser. Highlights:

Quick start

pip install wasm-tools
wasm-tools module.wasm --headers     # section map
wasm-tools module.wasm -d            # disassembly
wasm-tools module.wasm --json --analysis-only   # risk tier, capabilities, findings

From Python:

from wasm_tools.api import parse_wasm_file

report = parse_wasm_file("module.wasm")
print(report["analysis"]["summary"]["risk_tier"])
for finding in report["analysis"]["findings"]:
    print(finding["id"], finding["severity"], finding["title"])

Every command is safe on untrusted files: parse failures land in report["errors"] instead of raising, and nothing in the pipeline evaluates the decoded code.

What the tool reports

The JSON report (documented field by field in the reference) includes section tables, function bodies with decoded instructions, imports and exports, memory and table limits, data segments, extracted strings with secret and IoC screening, a labeled call graph with reachability, toolchain fingerprints from producers and target_features custom sections, and, for Component Model binaries, the full interface inventory with per-core-module reports.

The analysis layer on top is heuristic by design and intended for triage. It infers host capability tokens (fs.path, network, process.terminate, and others), detects WASI and JavaScript-interface modules, classifies the binary format, computes behavior profiles, and raises stable-id findings (WASM-CAP-001 through WASM-STR-007) with severity, evidence, and remediation text. Exact rule behavior is in FINDINGS.md.

Supported coverage

The decoder covers the WebAssembly binary format through the post-3.0 proposals: SIMD, threads, GC, exception handling, memory64 and table64, wide arithmetic, half-precision, custom page sizes, and shared limits, plus Component Model binaries. The coverage matrix records implementation status per area against the bundled spec snapshot under specification/wasm-latest/. Spec validation and text-format (.wat) parsing are deliberate scope exclusions; the tool decodes and reports, it does not judge correctness.

Trust and provenance

The source code in this repository was fully generated by AI assistants, with human edits limited to formatting and minor changes. Treat the codebase as useful but review it before depending on it in a security workflow. The repository reflects that posture: parser failures are covered by malformed-input tests, end-to-end tests assert exact disassembly substrings, and the error model keeps malformed files from crashing batch pipelines.

Development

poetry install
poetry run pytest -q
poetry run python tests/fixtures/build.py   # requires WABT wat2wasm

The development guide covers the extension recipes (opcodes, sections, visitors, analysis rules) and the conventions that keep the error model and output contract stable.

License

This project is licensed under the MIT License. See LICENSE for details.

The inputs to the AI agents came from the WebAssembly specification, the WABT project, and the author's knowledge of Python and WebAssembly. The outputs are original code generated by the AI agents based on those inputs. It is possible this project is therefore not MIT-licensed due to the presence of third-party specification text in the training data. The author has made a good faith effort to generate original code and to avoid copying any specific text from the specification, but this cannot be guaranteed. Users should review the code and the specification to ensure compliance with their licensing needs.