o1js-scan

Community package: o1js-scan is listed in the official o1js Community Packages directory.

A fast, dependency-free static analyzer for zk circuit soundness bugs in:

• o1js / Mina zkApps (TypeScript .ts / .js) — Kimchi circuits from @method bodies
• Noir (.nr) — Aztec's Rust-like ZK DSL (including aztec-nr-shaped patterns)

The security-critical bugs usually aren't in the proving system — they're in the application's own constraints: witnesses the prover controls but the circuit never binds. o1js-scan is the under-constrained-signal scanner for Circom's cousins in the Mina and Noir ecosystems.

pip install o1js-scan
# or: pipx install o1js-scan
# or: npm install -D o1js-scan

o1js-scan path/to/zkapp          # o1js + Noir (auto)
noir-scan path/to/circuits       # same binary — Noir-friendly alias
noir-scan . --lang noir --fail-on high --sarif noir.sarif

Example

Given a vault whose withdraw amount is a prover-controlled witness that is never bound to on-chain state:

$ o1js-scan examples/vulnerable_vault.ts --include-examples
LOW      O1JS_UNCONSTRAINED_RECIPIENT       vulnerable_vault.ts:23  fn=withdraw  Recipient `to` is prover-chosen in `withdraw`
HIGH     O1JS_UNCONSTRAINED_WITNESS         vulnerable_vault.ts:23  fn=withdraw  Unconstrained witness `amount` flows to send_amount in `withdraw`
o1js-scan: 2 finding(s) [1 high, 1 low] in 1 file(s) — fails (--fail-on high)
$ echo $?
1

--include-examples is needed here only because the demo file lives under examples/, which the path classifier downgrades by default so that a repo's own sample code cannot fail its build. The same contract in your src/ reports HIGH with no flag.

The HIGH finding is the drainable bug. The fixed contract (examples/safe_vault.ts) drops it and exits 0, keeping only the informational LOW on the prover-chosen recipient:

$ o1js-scan examples/safe_vault.ts --include-examples
LOW      O1JS_UNCONSTRAINED_RECIPIENT       safe_vault.ts:23  fn=withdraw  Recipient `to` is prover-chosen in `withdraw`
o1js-scan: 1 finding(s) [1 low] in 1 file(s) — passes (--fail-on high)
$ echo $?
0

See examples/ for the o1js and Noir vulnerable/fixed pairs.

Contents

• Install
• Usage · Suppressing a finding
• GitHub Action
• What it detects — o1js · Noir
• Known limitations · Where this tool stops
• Privacy and private code
• Post-quantum review
• Compatibility · How it works
• Contributing

Install

pip install o1js-scan

For an isolated global CLI install, use pipx:

pipx install o1js-scan

For Node/npm-based Noir, Aztec, or o1js app repositories, install the npm wrapper:

npm install -D o1js-scan
npx noir-scan . --lang noir --fail-on high

The npm package is a thin wrapper around the same Python analyzer and requires Python 3.8+ on PATH (python3 or python). Set O1JS_SCAN_PYTHON to choose a specific interpreter.

Or from source:

git clone https://github.com/auditinfra-io/o1js-scan
cd o1js-scan
pip install -e .

No third-party Python dependencies. Python 3.8+. The noir-scan console script is installed alongside o1js-scan (same entry point), including through the npm wrapper.

Usage

# scan a directory (recursively; skips node_modules, target/, .git, …)
o1js-scan path/to/project

# Noir-only / o1js-only
noir-scan circuits --lang noir
o1js-scan src --lang o1js

# scan a single file
o1js-scan src/MyContract.ts
noir-scan src/main.nr

# machine-readable output for CI
o1js-scan src --json

# SARIF 2.1.0 for GitHub code scanning (writes o1js-scan.sarif by default)
o1js-scan src --sarif
noir-scan . --lang noir --sarif noir.sarif

# choose which severity fails CI (critical|high|medium|low|none; default high)
o1js-scan src --fail-on medium

# test code is excluded by default (both backends); opt back in
o1js-scan src --include-tests

# example code is downgraded to LOW by default; keep original severity
o1js-scan src --include-examples

o1js-scan --version

Exit code is 1 when a finding at or above the --fail-on level (default high) is present and 0 otherwise — so you can drop it straight into CI. With the default, a low/medium finding (including the informational recipient rule below) does not fail the build; use --fail-on none to only report, or --fail-on medium to gate more strictly. A missing scan path exits 2 with an error on stderr, so a typo can't silently pass CI as a clean run. Every run prints a one-line summary (counts by severity and the gate verdict) to stderr.

Test code is excluded by default — both backends. Tests deliberately build invalid values and bad transactions to prove the asserts reject them, so a finding there is the point of the test rather than a circuit bug. A file counts as test code when:

• its name matches *.test.ts / *.spec.ts (and the .js/.jsx/.tsx/.mjs /.cjs variants), or *_test.nr / test_*.nr;
• it sits under a test/, tests/, __tests__/, spec/ or __mocks__/ directory;
• (Noir only, content-based) the function carries a #[test] / #[test(...)] attribute, or sits inside a mod test { … } / mod tests { … } block — block-scoped, so a test module at the foot of a production file does not silence the rest of it.

Pass --include-tests to report them.

Example code is downgraded, not dropped. A finding in an examples/ or example/ directory, or in a file named *.eg.ts (.nr and the other JS/TS extensions too), is lowered to LOW with a note — still reported, no longer able to fail a build. Example code is deliberately simplified, and flagging a framework's own examples as vulnerabilities is noise; but it is copied into production far more often than test code is, which is why it is downgraded rather than hidden. Pass --include-examples to keep the original severity.

Whenever either policy applies, the run prints a line to stderr saying so — e.g. 6 file(s) skipped as test code, 1 finding(s) downgraded as examples — so a quiet scan is never silently quiet. The counts also appear in SARIF under invocation.properties. Note the trade-off: detection is path-based only (no describe(/it( parsing), so a production circuit stored under tests/ will be skipped — the stderr line is how you notice.

Directories skipped when walking a tree: node_modules, target (nargo), .git, dist, build, __pycache__, .venv, venv.

Suppressing a reviewed finding

Silence a finding you've triaged without loosening the gate, with an inline comment on — or on the line above — the flagged line:

this.send({ to, amount });  // o1js-scan-disable-line O1JS_UNCONSTRAINED_WITNESS

// o1js-scan-disable-next-line
this.send({ to, amount });

let inv = unsafe { hint(x) };  // o1js-scan-disable-line NOIR_UNCONSTRAINED_WITNESS

List one or more rule ids to suppress only those; a bare directive (no ids) suppresses every rule on the target line.

As a library:

from o1js_scan import analyze_file, analyze_project

for path, finding in analyze_project("src", lang="auto"):
    print(path, finding.rule_id, finding.severity.value, finding.title)

GitHub Action

Add the scanner to CI in a few lines. Findings appear as annotations on the PR diff and as alerts in the repository's Security → Code scanning tab.

# .github/workflows/o1js-scan.yml
name: o1js-scan
on: [push, pull_request]

permissions:
  contents: read
  security-events: write   # required to upload SARIF to code scanning

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: auditinfra-io/o1js-scan@v0.10.0
        with:
          path: src              # optional, defaults to the repo root
          lang: auto             # auto | o1js | noir
          # version: 0.10.0       # optional, pin the scanner version
          # fail-on-findings: true   # optional, fail the job on any high/critical

Noir-only CI recipe

Recommended for Noir projects that want code-scanning alerts and a high-severity gate:

- uses: auditinfra-io/o1js-scan@v0.10.0
  with:
    path: .
    lang: noir
    fail-on-findings: true

Or without the Action:

pip install o1js-scan
noir-scan . --lang noir --fail-on high --sarif noir.sarif

pre-commit (optional)

# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: noir-scan
      name: noir-scan
      entry: noir-scan
      language: system
      pass_filenames: false
      args: [".", "--lang", "noir", "--fail-on", "high"]

Inputs: path (default .), lang (auto|o1js|noir, default auto), version (PyPI version to install, default latest), upload-sarif (default true), fail-on-findings (default false), include-tests (default false), include-examples (default false). Output: sarif-file. SARIF upload needs security-events: write and code scanning enabled.

What it detects (o1js)

False-positive guards (o1js)

The analyzer is designed to stay quiet on correct code:

• Signature-gated methods are skipped. A @method that calls this.requireSignature() (or getAndRequireSignature, AccountUpdate.createSigned, Signature.verify) is owner/admin-gated — its arguments are chosen by the key holder, not an arbitrary prover — so its witnesses are not flagged. This is the o1js equivalent of onlyOwner.
• State-bound witnesses are skipped. An argument asserted equal to (or bounded by an ordering comparison against) a getAndRequireEquals()-derived value is sound and won't be reported. This covers both the direct form — amount.assertLessThanOrEqual(bal) — and the chained form amount.lessThanOrEqual(bal).assertTrue(). Binding that lives in an undecorated same-class helper (this.verifyX(arg)) is also recognized (depth 1 only).
• Verified proofs are skipped. A Proof / SelfProof / DynamicProof / *Proof-typed argument on which .verify() is called is constrained by the verified circuit — witness findings on it (and its publicOutput / publicInput) are suppressed. A .verifyIf(flag) is credited only when the condition is not an unconstrained method argument, or is itself asserted. The same applies to the canonical OffchainState wrapper this.offchainState.settle(proof) (the framework verifies inside settle). A hand-rolled .settle(proof) is not assumed to verify. The inverse case (proof-typed arg never verified and not OffchainState-settled) is reported as O1JS_UNVERIFIED_PROOF.
• Asserted / used Bools are skipped. A predicate chained with .assertTrue() / .assertFalse(), nested in Provable.if(...), or assigned to a local that is later referenced, is not reported as O1JS_UNASSERTED_BOOL.
• Authenticated senders are skipped. this.sender.getUnconstrained() does not fire when the same @method also calls this.sender.getAndRequireSignature(), or when that witnessed value is passed to AccountUpdate.createSigned(...) / authenticated via .requireSignature() on an AccountUpdate built from it (argument identity required).
• Comments and string literals are stripped before analysis, so an assert inside a string can't create a false result.

What it detects (Noir)

The same soundness idea — under-constrained witnesses — applies to Noir (.nr) circuits. Point the scanner at .nr files (or use --lang noir) and it analyzes them with the Noir rule set. Same lexical, dependency-free approach. Calibrated against aztec-nr oracle / unsafe idioms — see docs/noir_calibration.md.

False-positive guards (Noir)

• Assert / let-hop / same-file confirm helpers bind unsafe hints.
• Call-site names constrain_* / confirm_* / verify_* / check_(non_)membership* / public_data_storage_read credit args (with unused-result detection for discarded checks).
• Documented intentional unconstrained (requires adjacent // Safety:): random(), avm::…, and kernel/rollup/discovery deferred wording.
• Tuple let + asserted flags bind merkle witnesses passed into membership checks.

Example:

$ noir-scan examples/noir_unconstrained.nr --include-examples
HIGH     NOIR_UNCONSTRAINED_WITNESS         noir_unconstrained.nr:16  fn=main  Unconstrained `unsafe` result `inv` in `main`
LOW      NOIR_UNSAFE_MISSING_SAFETY         noir_unconstrained.nr:16  fn=  `unsafe` block without a `// Safety:` comment
noir-scan: 2 finding(s) [1 high, 1 low] in 1 file(s) — fails (--fail-on high)

$ noir-scan examples/noir_constrained.nr --include-examples
noir-scan: no findings (or no Noir / o1js sources found)

As with the o1js example above, --include-examples is only needed because these demo files live under examples/.

Known limitations

The analyzer is a lexical, name-matching pass, not a dataflow engine. Keep these blind spots in mind when triaging — they are known and intentional for this dependency-free design, not bugs:

• Only simple aliases are followed. Witness tracking follows plain same-method aliases such as const q = qty, but not derived expressions or destructuring:

  const q = qty; this.send({ to: dest, amount: q });   // followed
  const q = qty.add(1); this.send({ to: dest, amount: q }); // not followed
  const slot = this.root; slot.get();                  // missing precondition missed
  

• Cross-method binding is depth-1 only. An undecorated same-class helper called as this.verifyX(arg) can state-bind a caller's argument (one level). Deeper chains (@method → helper A → helper B) and free/imported functions are not followed. Local-variable aliasing of the helper argument also stays a documented limitation.

• Unasserted-Bool detection is statement-shaped. Tier A only flags bare expression statements whose outermost call is a Bool predicate with nothing chained after it. Predicates nested inside Provable.if(...), or assigned and later used, are not flagged. Complex control-flow uses of a Bool local may still be missed if the name is never referenced (failure mode: miss, not a false positive).

• Signature-gating is method-level and substring-based. _method_is_signature_gated treats a whole @method as owner-gated if it contains a signature idiom, and it recognizes a verifier only when the receiver name literally contains signature — so sig.verify(admin, msg) is not recognized as gating, while an unrelated signature check elsewhere in a large method can over-suppress. It is all-or-nothing per method.

• Sender authentication is name-based and same-method only. O1JS_UNCONSTRAINED_SENDER suppresses when this.sender.getAndRequireSignature() or AccountUpdate.createSigned(<that sender>) appears in the same @method body. A signature requirement that lives only in a helper (this.requireSenderSig() → getAndRequireSignature inside) is not followed — failure mode is a false positive on correct code that wraps the idiom, not a missed real bug.

• Noir cross-crate helpers are recognized by name convention only (no Nargo.toml / import resolution). Prefer miss over false positive.

These are the reason findings are a starting point for human review, not proofs. A dataflow-aware rewrite is deliberately out of scope for the lexical analyzer.

Where this tool stops

o1js-scan is deliberately a shallow, single-file lexical pass — no parser, no dataflow, no solver. That is what makes it dependency-free and instant in CI, and it is also a hard ceiling. The limitations above aren't a backlog; they're consequences of the design.

So it is worth being explicit about what this tool can and cannot tell you:

• A clean run is not an audit. It means no shape this scanner recognizes matched — not that the circuit is sound. Bug classes that need dataflow, path sensitivity, or constraint solving are out of reach for a tool of this shape, in any language.
• A finding is a lead, not a verdict. Every rule here is a heuristic with a documented false-positive class.

That trade is the right one for a linter you run on every commit. If you're working on something where the difference matters — a protocol holding real value, a circuit you can't afford to get wrong — treat this as the first pass and budget for a real review.

For deeper analysis, the separate full scanner is maintained in the audit-engine-cli repository. o1js-scan is the intentionally lightweight, open scanner; the full scanner's proprietary detection knowledge and implementation details are not reproduced here. For access or a more complete circuit review, reach out: auditinfracorp@proton.me.

Privacy and private code

The installed CLI analyzes files locally. It has no telemetry, network client, account, or upload step, and its Python runtime has no third-party dependencies. Running o1js-scan path/to/private-repo does not send the source or findings anywhere.

Like compiler logs, scanner output can contain paths, identifiers, and source fragments. SARIF also identifies exact repository locations, and the GitHub Action uploads it to GitHub code scanning. Use the same repository and CI access controls you already use for the source being scanned.

Want to contribute a useful false-positive or missed-detection report without sharing an application? Reproduce the syntax with invented names and constants, remove business logic one statement at a time, and verify the synthetic snippet still triggers the same rule before posting it. The privacy-safe contribution guide has a concrete checklist and several ways to help the o1js community without disclosing a private circuit.

This boundary does not prevent the open scanner from getting better. Public o1js documentation and repositories can support new rules and compatibility fixtures; synthetic examples can test false positives and missed constraints; and parser resilience, diagnostics, SARIF, performance, packaging, and calibration can all improve without publishing a private audit technique or client code. The open scanner should make independently explainable claims; private research can remain in the separate audit engine.

Post-quantum review

Quantum risk is related to circuit security, but it is not a missing-constraint rule. o1js-scan does not determine whether a signature, hash, commitment, the Kimchi proof system, or Mina itself meets a post-quantum security target. Those answers depend on the concrete primitive and parameters, platform assumptions, the deployment's required lifetime, and its migration plan—not merely on a TypeScript identifier that a lexical scanner can see.

Inspired by O(1) Labs' Qubit or Not Qubit, the post-quantum review guide turns that boundary into an o1js-specific inventory and crypto-agility checklist. Use it alongside this scanner rather than interpreting a clean scan as a post-quantum assessment.

Compatibility

Works on o1js 1.x and 2.x. o1js-scan analyzes TypeScript source as text and has no runtime dependency on o1js — nothing is version-pinned. It keys on the modern require* precondition API (getAndRequireEquals, requireEquals, requireSignature, getAndRequireSignature), the @method / @method() / @method.returns(...) decorators, annotated @state fields, this.send({...}), low-level AccountUpdate.balance.subInPlace(...) transfers, and Permissions.*. The established forms remain compatible across the 1.x → 2.x boundary, while the scanner also accepts the newly documented decorator and low-level transfer variants. The 2.x owner-auth idiom this.sender.getAndRequireSignature() is recognized as signature-gating. (Legacy assertEquals preconditions are still accepted, so older code isn't broken either.)

Equivalent constraint spellings are normalized for analysis: instance assertEquals(...), static Provable.assertEqual(Type, ...), and equals(...).assertTrue() equality chains all bind the same operands. Method extraction is brace-balanced after length-preserving comment and string masking, and accepts multiline decorators, nested callback-shaped parameter types, TypeScript access modifiers, and multiline identity aliases (including parenthesized and as Type forms).

Noir analysis targets Noir syntax used by Aztec / nargo projects (.nr); it does not invoke nargo or compile circuits.

How it works

It's a lexical analyzer, not a full TypeScript or Noir parser — o1js and Noir sources are brace-delimited and regex-tractable, and the output is meant to be triaged by a human. That keeps it dependency-free and instant to run in CI. Findings are a starting point for review, not proofs.

Roadmap / contributing

Contributions welcome — new rule families, more FP guards, and real-world calibration archetypes are all valuable. See CONTRIBUTING.md. Run the tests and linter with:

pip install -e ".[dev]"
pytest          # unit tests + Noir/o1js corpus
ruff check .    # lint
npm run format:check   # prettier, npm wrapper only

License

Apache-2.0. See LICENSE.