Metadata-Version: 2.4
Name: wasm-tools
Version: 2.1.0
Summary: A pure-Python WebAssembly binary parser, disassembler, and structured analysis library
License: MIT
License-File: LICENSE
Keywords: wasm,binary,wabt,webassembly,security,pentesting,red teaming
Author: Team AppThreat
Author-email: cloud@appthreat.com
Requires-Python: >=3.10
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Provides-Extra: dev
Requires-Dist: pytest (>=9.0.3) ; extra == "dev"
Requires-Dist: pytest-cov (>=7.1.0) ; extra == "dev"
Project-URL: Bug Tracker, https://github.com/appthreat/wasm-tools/issues
Project-URL: Homepage, https://github.com/appthreat/wasm-tools
Description-Content-Type: text/markdown

# 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.

[![AI-DECLARATION: auto](https://img.shields.io/badge/䷼%20AI--DECLARATION-auto-ede9fe?labelColor=ede9fe)](./AI-DECLARATION.md)

## Documentation site

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

| Page                                              | Contents                                         |
| ------------------------------------------------- | ------------------------------------------------ |
| [Getting started](./docs/GETTING_STARTED.md)      | Installation and first commands                  |
| [CLI reference](./docs/CLI.md)                    | Every flag, output format, and index semantics   |
| [Format primer](./docs/FORMAT_PRIMER.md)          | What the bytes in a `.wasm` file mean            |
| [JSON report reference](./docs/JSON_REFERENCE.md) | The machine-readable contract                    |
| [Findings and signals](./docs/FINDINGS.md)        | Every analysis rule, threshold, and severity     |
| [Analyst guide](./docs/ANALYST_GUIDE.md)          | Triage recipes for unknown binaries              |
| Lessons 1 to 10                                   | Hands-on tutorials against the repo fixtures     |
| [Architecture](./docs/ARCHITECTURE.md)            | Parser internals and design decisions            |
| [Development guide](./docs/DEVELOPMENT.md)        | Extending opcodes, sections, visitors, and rules |

## Quick start

```bash
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:

```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](./docs/JSON_REFERENCE.md)) 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](./docs/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](./docs/COVERAGE.md) 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](./docs/ARCHITECTURE.md) keeps malformed files from crashing batch pipelines.

## Development

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

The [development guide](./docs/DEVELOPMENT.md) 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](https://github.com/WebAssembly/spec/tree/main/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.

