scrypto-audit-kit

Pre-audit harness for Scrypto blueprints on the Radix network. Runs a hybrid analysis — deterministic static rules plus an LLM pass over a curated checklist + reference patterns — and produces a findings report (markdown + JSON) you can hand to a human auditor (or use to fix issues yourself). The static pass alone is free and needs no API key. This is a pre-audit tool, not an audit: it catches the kinds of issues a careful reviewer would catch on a first read so that paid auditors can spend their time on the harder, second-read findings, and it does not replace a human audit before mainnet deployment.

Status (as of 2026-10-12)

• Version: alpha. The latest release is v0.8.1, tagged 2026-10-12 and published on PyPI. Anything that lands on main after it is listed under CHANGELOG → Unreleased, and this README marks those parts main only.
• Run it: pip install scrypto-audit-kit, then sak-static path/to/your/package — the free static pass, no API key. The full LLM audit (./audit.sh) runs from a clone — see Quickstart.
• Who it is for: Scrypto developers who want a cheap first read of a blueprint before paying for an audit; reviewers who want a checklist-driven starting point; and agent builders who want audit tools over MCP or a Python SDK.
• Who maintains it: one person, bigdev (@bigdevxrd). Independent; no affiliation with, endorsement by, or backing from the Radix Foundation, RDX Works or the Radix DAO.
• Security contact: GitHub private vulnerability reporting, or message the maintainer privately on Telegram: @bigdev_xrd. Details in SECURITY.md.

Two recent, real incidents in the wild are worth naming so a clean report is never read as a safety signal: a blueprint with no logic defect at all was fed a price input that was orders of magnitude wrong at the source, and the kit only ever reads the blueprint's own code, never the data flowing into it at runtime; separately, a serious failure traced to a missing authority check at the seam between two systems, a boundary this kit — which audits one Scrypto package at a time — does not model. Neither is a Scrypto anti-pattern the checklist enumerates, and both needed a human looking at the whole system, not just the blueprint, to catch.

The live posture scan

Separate from the audit harness below, and the fastest way to see what this kit actually does: a read-only pass over live Radix mainnet entities that reports what each one states about itself on-ledger — dApp-definition two-way verification, owner role, resource authority, package upgrades, metadata claims. Clone or sdist only — it lives in the repository (scanner/) and runs from a clone (or an unpacked sdist); the wheel that pip install scrypto-audit-kit fetches does not include it.

→ Current scan · latest.md · latest.json · how the checks work

The published page covers only the entities Radix Guild — the maintainer's own project — operates; third-party projects are not listed, scored or named on it. Radix Guild's own entities are graded by the same rules and are not exempted from a failing result. Findings that describe a way to take funds are held — the page states that such a finding exists and its severity, and publishes the detail on a fixed clock after the project has been told.

Where it stands, as of 2026-10-11:

• Scans are run by hand, on demand. There is no schedule and nothing refreshes automatically. Two are committed: 2026-09-08, taken while Radix mainnet was halted (halted 2026-08-31, resumed 2026-09-11), and 2026-09-11, the first taken after it resumed (ledger state 557872098). The page and latest.* show the 2026-09-11 scan.
• The cohort is ahead of the scan. scanner/data/cohort.json lists five Radix Guild entities; the 2026-09-11 scan covers the first three. The two added since — the Wave B escrow component and dApp definition 2 — have not been scanned yet, so they show no result.
• Two of the three scanned entities fail. Radix Guild's Badge Manager and Badge Factory both FAIL check 1 (dApp-definition two-way verification, medium): the Badge Manager names no dApp Definition at all, and the Badge Factory is listed by Radix Guild's dApp Definition account but does not claim it back. Both are published as found. The on-chain metadata behind them has not been changed — fixing it is a separate, on-ledger operation that this repository does not perform.

Where this fits — the kit is the entry rung of a trust ladder that climbs from cargo check up to a full human audit. The bigger plan — agentic audit→fix→verify loops, reproducible attested runs, and on-chain attestation — lives in VISION.md.

What it does

For each scrypto package you point it at, the kit:

1. Runs a deterministic static pass (free, no API) — a curated set of high-precision Scrypto rules (unbounded drains, no-owner globalize, self-rotating roles, floats, hardcoded addresses, …).
2. Sends the package's source (Cargo.toml + everything under src/ and tests/) to an LLM through an interchangeable backend — the Anthropic API directly by default, or aider, or your own agent (docs/backends.md).
3. Loads a vulnerability checklist (11 classes — auth, reentrancy, decimal, resource handling, time, state machine, external calls, upgrade, oracle, slippage, allowances) and a catalogue of reference patterns (Ignition, CaviarNine HyperStake, subintents, a strategy-vault threat model, general scrypto knowledge) as read-only context.
4. Asks Claude Sonnet 4.6 (the default model) to produce a structured findings report — summary, findings (Critical → Info), checklist coverage walk, pattern conformance check, test-coverage gaps, open questions for the human auditor.
5. Merges both passes and writes a markdown report to audit-reports/<repo>-<package>-<date>.md and a machine-readable report.json (schema) that agents and the CI gate consume.

The kit is read-only by design. It produces reports; it does not edit your blueprint. Edits to audit-grade code must go through a separate, human-supervised session.

Quickstart

pip install scrypto-audit-kit        # v0.8.1 on PyPI: the deterministic toolkit, no API key needed
# ...add the extra for the MCP server (needs Python 3.10+):
pip install "scrypto-audit-kit[mcp]"
# ...or clone for the full LLM audit harness (audit.sh):
git clone https://github.com/bigdevxrd/scrypto-audit-kit

The pip package (PyPI, currently v0.8.1) gives you the free static analysis, test-scaffold generation and the attestation bridge — importable and as sak-* commands; the MCP server (sak-mcp) needs the [mcp] extra. The full ./audit.sh (the LLM checklist pass) lives in the clone. docs/quickstart.md walks all three tiers end to end.

Requirements (for the full ./audit.sh audit)

• The default claude-api backend: python3, the anthropic package (pip install ".[llm]"), and an Anthropic API key (defaults to Claude Sonnet 4.6 — get one at https://console.anthropic.com).
• bash, awk, find (standard on macOS / Linux).
• Other backends have their own needs — --backend aider wants aider (pip install aider-chat ≥ 0.86); --backend cmd runs your own command. See docs/backends.md.
• For --static-only you need none of the above — no API key, no anthropic package, no aider, no Rust toolchain. It does need python3 (the static pass is Python) and the same bash, awk and find; without python3 the script exits with an error.

The key can be provided in any of three ways:

# 1. Export in your shell (preferred for CI)
export ANTHROPIC_API_KEY=sk-ant-...

# 2. Point AIDER_ENV_FILE at an existing env file
AIDER_ENV_FILE=~/some/.env ./audit.sh /path/to/package

# 3. Drop a .env file (gitignored) in the kit directory
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

Verify with:

make check-deps

Run an audit

Needs the anthropic package and an API key first — see Requirements above (pip install ".[llm]"; export ANTHROPIC_API_KEY=...; verify with make check-deps) — or add --static-only below for a free, no-API pass.

git clone https://github.com/bigdevxrd/scrypto-audit-kit
cd scrypto-audit-kit
chmod +x audit.sh

./audit.sh /path/to/your/scrypto/package
# or:
make audit TARGET=/path/to/your/scrypto/package

The target must be a scrypto package directory (has a Cargo.toml and a src/lib.rs). The kit will read everything under src/ and tests/.

The report lands in audit-reports/<repo>-<package>-<YYYY-MM-DD>.md. Reports are gitignored — share them by other means, don't commit them.

Example

./audit.sh ~/scrypto/my-vault
[pre-flight] compile check OFF (default; compiling runs the target's build scripts).
             opt in with --compile-check for code you trust.

==> scrypto-audit-kit
    target:    scrypto / my-vault
    path:      /home/me/scrypto/my-vault
    mode:      claude-api / claude-sonnet-4-6 + static
    sources:   3 files
    refs:      6 files (read-only)
    report ->  audit-reports/scrypto-my-vault-2026-05-11.md

[the backend runs ...]

==> done. report: audit-reports/scrypto-my-vault-2026-05-11.md

Note: an opt-in --compile-check pre-flight runs cargo check --release --target wasm32-unknown-unknown first and bails if the package doesn't compile. It is off by default: compiling executes the target's build scripts and proc-macros on your machine, so enable it only for code you trust enough to run (rustup target add wasm32-unknown-unknown sets up the target).

Choosing a backend and model

The LLM pass runs through an interchangeable backend (full guide: docs/backends.md). The default is claude-api — the Anthropic API directly, no aider — on Claude Sonnet 4.6:

./audit.sh <path>                            # claude-api + Sonnet 4.6 (default)
./audit.sh --model claude-opus-4-8 <path>    # a different Anthropic model
./audit.sh --backend aider --model both <path>   # aider: DeepSeek broad → Claude deep
./audit.sh --backend cmd --backend-cmd 'python3 my_agent.py' <path>   # your own agent

The cross-model modes --model deepseek and --model both run on the aider backend (passing either selects it automatically). both runs DeepSeek first for a wide net, feeds its findings to Claude, and tags findings both models agree on as HIGH confidence — a second opinion on a high-stakes blueprint.

Free tier: deterministic static analysis

A static pass runs on every audit, and you can run it alone with no API key, no aider, and no toolchain:

./audit.sh --static-only <path>     # free, instant, deterministic

It applies a curated set of high-precision Scrypto rules — comment/string-aware, so code rules don't match inside comments or string literals — and writes the same report.json. Suppress a finding with a // sak:allow <rule-id> comment; add --no-static to a full run to skip the pass. See docs/static-analysis.md for the rule list and how to add one.

Try it on the bundled example

The repo ships a deliberately-vulnerable blueprint so you can see real output without writing any code — the static tier needs no API key:

./audit.sh --static-only examples/vulnerable-vault   # free; drop --static-only for the full hybrid run

The expected result is committed beside it — examples/vulnerable-vault.pre-audit.md (human) and .json (machine-readable). Every file:line in it is exact, because the bugs are planted.

Machine-readable output

Alongside the markdown, the kit writes report.json conforming to schema/audit-report.schema.json — stable ids (F-### from the LLM, S-### from the static pass, each tagged with its source), severities, full checklist coverage, and a provenance block (kit version, model, checklist version, and a sha256 of the analyzed source). This is what agents, the CI gate, and (later) on-chain attestation consume; the markdown is a render of it.

Continuous integration & a badge

Run the pre-audit on every PR and show a status badge — full setup in docs/ci.md. In short, call the reusable workflow:

jobs:
  scrypto-pre-audit:
    uses: bigdevxrd/scrypto-audit-kit/.github/workflows/pre-audit.yml@v0.8.1
    with:
      package: packages/my-blueprint
      fail-on: high
      kit-ref: v0.8.1   # pin the audit code too — it defaults to main
    secrets:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

It audits, uploads the report, and fails on High/Critical findings — an honest "pre-audit passing" signal, not a safety guarantee. It does not compile your package: the cargo pre-flight is opt-in (--compile-check) and this workflow never passes it.

Pin v0.8.1 or later — it is the floor for CI callers. Tags before v0.8.0 let code from the package you are auditing run inside the job that holds your ANTHROPIC_API_KEY: v0.7.0 through the backend-install probe, and v0.5.0 and v0.6.0 by interpolating caller inputs into run: scripts. docs/ci.md has the detail and how to pin a commit SHA instead of a tag.

Use it from an agent (MCP + Claude Code)

The kit ships an MCP server so an agent can run the pre-audit as tools and walk you through audit → fix → re-verify:

# from a clone (the MCP SDK needs Python 3.10+):
pip install ".[mcp]"
claude mcp add --transport stdio scrypto-audit-kit -- python3 "$PWD/bin/mcp_server.py"

# ...or from PyPI:
pip install "scrypto-audit-kit[mcp]"
claude mcp add --transport stdio scrypto-audit-kit -- sak-mcp

Tools: static_scan (free), audit_package, propose_tests, attestation_payload, get_findings, show_finding_source, reaudit_diff, gate, get_checklist. There's also a Claude Code skill (/scrypto-pre-audit) and an AGENTS.md playbook for any agent. Full setup — including the audit→fix→verify loop — in docs/agents.md; the nine tools and their formal contracts are in docs/mcp-tools.md.

Build on it — the Python SDK

pip install scrypto-audit-kit makes the deterministic core importable, with zero required dependencies:

from scrypto_audit_kit import static_analysis, sak_lib
findings = static_analysis.analyze_package("path/to/package")     # free, no API key
verdict  = sak_lib.gate_verdict(sak_lib.build_report(findings), "high")

The full API, the nine tools in-process, and the sak-* console scripts are in docs/sdk.md. Three runnable example agents — a free-tier CI gate, the audit→fix→verify loop, and an MCP client — are in examples/agents/.

Generate tests, attest on-chain

• Property tests. propose_tests (or python3 bin/gen_tests.py <pkg>) emits compilable #[ignore]d scrypto-test scaffolds for the coverage gaps — auth negative-paths, happy paths, a value invariant — so closing them is fill-in-the-blank.
• On-chain attestation (L3). attestation_payload (or python3 bin/attest.py <report.json>) turns a report into a Radix transaction manifest that records an attestation on-ledger via the attestation/ registry blueprint — bound to your exact source hash (the deterministic anchor). A coverage record, not a safety guarantee, and for the LLM tier not byte-reproducible (see attestation/README.md).

Dapp-scope pass (operator questionnaire)

Everything above audits one Scrypto package's own source. A dapp losing money is usually a data source, a listing, an admin key, or an incident response gap around the package, not a defect in it — see docs/DAPP-SCOPE-EXTENSION.md for why. The first slice of that proposal is a structured questionnaire an operator (not the kit) fills in, and a deterministic CLI that turns it into a report. New in v0.8.1 — the sak-dapp-scope command ships in the PyPI package, and a clone runs it as a script:

python3 bin/dapp_scope.py examples/dapp-scope/questionnaire.example.json    # installed from PyPI: sak-dapp-scope <path>

It validates your answers against schema/dapp-scope-questionnaire.schema.json (see the example alongside it and prompts/dapp-scope-checklist.md for the questions it's asking) and renders a markdown report with a freshness marker — the answered_at date, because organizational facts go stale the day a listing is added or an admin key rotates, which the kit has no way to detect on its own. Every listed data source, listing, and admin power carries a required "max loss if this one input is maximally wrong" answer; "no bound exists" is rendered as a finding, never left silent. This pass is not automatic, not merged into the eleven-class blueprint checklist, and not scored under the L1–L4 attestation ladder — see docs/attestation-levels.md. The rest of the proposal (an MCP tool, a real-world trial run) is still open.

What's in the kit

scrypto-audit-kit/
├── audit.sh                The harness — dispatches the LLM pass to a pluggable backend.
├── Makefile                Convenience targets (audit, lint, test, check-deps).
├── pyproject.toml          Pip packaging — importable SDK + sak-* console scripts.
├── VERSION                 Kit version, stamped into every report.
├── VISION.md / ROADMAP.md  The trust-ladder strategy + the live phase checklist.
├── AGENTS.md               How an agent should drive the kit (audit → fix → verify).
├── .mcp.json               MCP server config (auto-wires the tools in Claude Code).
├── .aider.conf.yml         Config for the (optional) aider backend — Sonnet 4.6, no edits.
├── prompts/
│   ├── audit.md            Auditor-role prompt + report structure (incl. the JSON appendix).
│   └── checklist.md        Eleven vulnerability classes with concrete questions per class.
├── references/             Read-only context — production patterns + threat models (5 files).
├── schema/                 JSON Schemas — the report + the MCP tool contracts.
├── bin/                    engine + tools: static_analysis.py, llm_audit.py (claude-api backend), gen_tests.py, attest.py, mcp_server.py, …
├── tests/                  Stdlib unit tests for the tooling (`make test`).
├── docs/                   The docs suite (quickstart · sdk · mcp-tools · architecture · …).
├── attestation/            On-chain attestation registry blueprint (Scrypto, L3).
├── scanner/                Posture scanner — read-only checks on live mainnet entities (in the sdist, not in the wheel).
├── LICENSE / NOTICE        Apache-2.0, and its copyright notice.
├── .claude/skills/         The scrypto-pre-audit Claude Code skill.
├── audit-reports/          Output dir, gitignored.
└── examples/
    ├── vulnerable-vault/   Deliberately-vulnerable fixture + its committed report.
    ├── agents/             Runnable example agents (CI gate, audit→fix→verify, MCP client).
    └── ci/                 Drop-in pre-audit workflow for your repo.

Documentation

Everything is in docs/; the short list:

• quickstart.md — install + run, all three tiers
• backends.md — the pluggable LLM backends (claude-api · aider · your own)
• static-analysis.md — the deterministic rules (and adding one)
• agents.md · mcp-tools.md — drive it from an agent / over MCP
• sdk.md — the Python API + console scripts
• ci.md — CI gate + badge
• posture-scanner.md — the live posture scan: five on-chain checks, how severity is derived (clone or sdist only)
• architecture.md — how the pieces fit together
• SECURITY.md — reporting a vulnerability in the kit (not a finding it reported)
• VISION.md · ROADMAP.md · CHANGELOG.md — strategy, status, history

Limitations — read this before relying on the output

The kit is honest about what it is. Things it explicitly does not do:

• It is not a formal verifier. No theorem proving, no symbolic execution, no fuzzing. Findings are derived from pattern matching against a checklist by an LLM.
• It does not run cargo build or cargo test. Compilation issues, dependency vulnerabilities, and test failures are not in scope. Run those separately.
• It does not catch novel attack classes. It will surface known footguns reliably and propose novel concerns as low-confidence open questions. Novel-attack discovery is the human auditor's job.
• The LLM can hallucinate file:line citations. Every finding cites a location; you must verify those citations before acting on them. The audit prompt explicitly instructs the model to cite, but verification is on the reader.
• It is not a deployment gate. Do not block deploys on a clean report. The kit is an aid, not approval.

If any of these limitations matter for your use case, do not use this kit as a substitute for a paid audit.

Cost

With the default config (Sonnet 4.6, prompt caching on, references cached across runs):

• First audit of a session: ~50k input tokens (references) + 5–20k input tokens (target source) + ~5–15k output tokens → roughly $0.20–$0.40 per run.
• Subsequent audits in the same prompt-cache window: cached references reduce cost ~70% → roughly $0.10 per run.

These figures are estimates as of 2026. Check current Anthropic pricing for accurate numbers. The kit deliberately does not use the architect/editor split (which would add a second model call) because we want analysis, not code edits.

Contributing

This kit is maintained by one person (bigdev) and gets stronger with more eyes on it. The most valuable contributions:

• New vulnerability classes for the checklist. Real-world Scrypto exploits or footguns we haven't catalogued yet.
• New reference patterns. Open-source Radix blueprints with patterns worth catalogue-ing — adapter scaffolds, role hierarchies, panic modes, etc.
• Trial reports. Run the kit against a public blueprint and share what it found (or missed). Negative results are valuable.
• Harness fixes. False-positive patterns, brittle parsing, missing edge cases in audit.sh.

See CONTRIBUTING.md for the workflow.

License

Apache 2.0 — Copyright 2026 bigdev (https://github.com/bigdevxrd); see NOTICE. Forks, derivatives, and commercial use all welcome; attribution preserved per the license.

Related

• Radix Scrypto docs
• radixdlt/Ignition — the canonical Radix-team-maintained reference codebase (most of our references/ignition-patterns.md extracts from here)
• caviarnine/caviarnine-scrypto — Apache-licensed CaviarNine production blueprints
• aider — one of the kit's LLM backends (--backend aider); the default backend calls the Anthropic API directly