### 示例

给定一个 vault，其 `withdraw` 金额是由 prover 控制的 witness，且从未绑定到链上状态：```console
$ 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 of 1 file(s) — fails (--fail-on high)
$ echo $?
1

有关 o1js 和 Noir 的易受攻击/已修复配对示例，请参见 [`examples/`](https://github.com/auditinfra-io/o1js-scan/blob/main/examples)。

## 目录

- [安装](#install)
- [用法](#usage) · [抑制已审查的发现](#suppressing-a-reviewed-finding)
- [GitHub Action](#github-action)
- [检测内容 — o1js](#what-it-detects-o1js) · [Noir](#what-it-detects-noir)
- [已知限制](#known-limitations) · [本工具的适用范围止于何处](#where-this-tool-stops)
- [隐私与私有代码](#privacy-and-private-code)
- [后量子审查](#post-quantum-review)
- [兼容性](#compatibility) · [工作原理](#how-it-works)
- [贡献](#roadmap--contributing)

## 安装```bash
pip install o1js-scan

对于基于 Node/npm 的 Noir、Aztec 或 o1js 应用仓库，请安装 npm 封装包：```bash
npm install -D o1js-scan
npx noir-scan . --lang noir --fail-on high

无第三方 Python 依赖。Python 3.8+。`noir-scan` 控制台脚本与 `o1js-scan` 一同安装（同一入口点），包括通过 npm 包装器安装。

## 用法```bash
# 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

# progressive/power-user gate (equivalent to --fail-on medium)
o1js-scan src --strict

# 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

- **`--no-verify`**：跳过 SSL 证书验证（默认：`false`）
- **`--timeout`**：请求超时时间（秒）（默认：`10`）
- **`--user-agent`**：自定义 User-Agent 字符串
- **`--proxy`**：用于请求的代理 URL
- **`--headers`**：自定义请求头（JSON 格式）
- **`--cookies`**：自定义 Cookie（JSON 格式）
- **`--follow-redirects`**：跟随 HTTP 重定向（默认：`true`）
- **`--max-redirects`**：最大重定向次数（默认：`5`）
- **`--retry`**：失败请求的重试次数（默认：`3`）
- **`--retry-delay`**：重试之间的延迟时间（秒）（默认：`1`）
- **`--concurrency`**：最大并发请求数（默认：`10`）
- **`--rate-limit`**：每秒最大请求数（默认：`0` = 无限制）
- **`--random-agent`**：为每个请求使用随机 User-Agent
- **`--delay`**：请求之间的延迟时间（秒）（默认：`0`）
- **`--jitter`**：添加到延迟的随机抖动（秒）（默认：`0`）
- **`--encoding`**：响应编码（默认：`utf-8`）
- **`--no-color`**：禁用彩色输出
- **`--quiet`**：抑制除结果外的所有输出
- **`--verbose`**：启用详细输出
- **`--debug`**：启用调试输出
- **`--log-file`**：日志文件路径
- **`--log-level`**：日志级别（默认：`INFO`）
- **`--output`**：输出文件路径
- **`--output-format`**：输出格式（`text`、`json`、`csv`、`html`）（默认：`text`）
- **`--config`**：配置文件路径
- **`--save-config`**：将当前配置保存到文件
- **`--version`**：显示版本信息并退出
- **`--help`**：显示帮助信息并退出```nr
let inv = unsafe { hint(x) };  // o1js-scan-disable-line NOIR_UNCONSTRAINED_WITNESS

## GitHub Action

只需几行即可将扫描器添加到 CI 中。发现的问题会以注释形式显示在 PR diff 上，并作为警报出现在仓库的 **Security → Code scanning** 标签页中。```yaml
# .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/[email protected]
        with:
          path: src              # optional, defaults to the repo root
          lang: auto             # auto | o1js | noir
          # version: 0.20.0       # optional, pin the scanner version
          # fail-on: high         # optional, fail the job on high/critical

或者不使用 Action：```bash
pip install o1js-scan
noir-scan . --lang noir --fail-on high --sarif noir.sarif

输入：`path`（默认 `.`）、`lang`（`auto`|`o1js`|`noir`，默认 `auto`）、
`version`（要安装的 PyPI 版本，默认最新）、`upload-sarif`（默认
`true`）、`fail-on`（`critical`|`high`|`medium`|`low`|`none`，默认 `none`）、
`fail-on-findings`（已弃用，默认 `false`）、`include-tests`（默认
`false`）、`include-examples`（默认 `false`）。输出：`sarif-file`。SARIF
上传需要 `security-events: write` 并启用代码扫描。

报告和门禁由同一个参数数组构建，因此 `include-tests`
和 `include-examples` 同时作用于两者——你读取的 SARIF 和你据以设置门禁的退出码
始终描述同一组源文件。报告阶段以
`--fail-on none` 运行，因此发现项永远不会阻止 SARIF 上传，但操作性
失败（路径不存在、CLI 用法错误）仍会使该步骤失败，
而不是被报告为一次干净的扫描。

`fail-on-findings: true` 为兼容性而保留，当 `fail-on` 保持为 `none` 时映射为 `fail-on: high`；它会发出弃用警告。优先使用
`fail-on`，它可以在任意严重级别设置门禁。

## 它检测什么（o1js）

### 支持的规则一览

<!-- BEGIN GENERATED RULE SUMMARY -->
| 后端 | 规则数 | 高严重级能力 | 中严重级能力 | 低严重级能力 |
|---------|------:|-------------:|---------------:|------------:|
| o1js | 18 | 11 | 12 | 2 |
| Noir | 11 | 4 | 9 | 1 |
| **总计** | **29** | **15** | **21** | **3** |
<!-- END GENERATED RULE SUMMARY -->

计数是每个后端支持的不同规则 ID 数量。根据上下文分配
严重级别的规则（例如，对价值转移为高，对状态写入为中）会出现在多个严重级别列中，因此
严重级别列有意不等于规则总数。目前
没有 critical 或 info 严重级别的规则。完整描述和
误报防护如下。

<!-- BEGIN GENERATED O1JS RULE TABLE -->
| 规则 | 严重级别 | 含义 |
|------|----------|---------------|
| `O1JS_MISSING_STATE_PRECONDITION` | high | `this.x.get()` 读取时没有匹配的 `requireEquals(...)` / `getAndRequireEquals()`。裸 `get()` 不添加**任何**账户前置条件，因此证明不会将 `x` 绑定到其链上值——证明者可以替换任意值。 |
| `O1JS_UNCONSTRAINED_WITNESS` | high / medium | 一个 `@method` 参数（证明者控制的私有见证）流入发送**金额**（`this.send(...)` 或同一方法内的 `AccountUpdate.create*(...).send(...)`）或状态 `.set(...)`，并且**从未**被断言。这是约束不足的 Circom 信号的直接类比。当它到达价值转移时为高。 |
| `O1JS_UNCONSTRAINED_PROVABLE_WITNESS` | high / medium / low | 一个 `Provable.witness(...)` 局部变量流入发送/状态效果，且**没有**电路内断言。见证回调在电路*之外*运行（它只是证明者提示），因此结果是证明者控制的新值——这是除 `@method` 参数之外的另一个见证来源。它必须被重新推导并断言（`x.assertEquals(<recomputed>)`）或绑定到状态。在发送金额（`this.send(...)` 或同一方法内的 `AccountUpdate.create*`）上为高。 |
| `O1JS_UNCONSTRAINED_RECIPIENT` | low | 一个 `@method` 参数**仅**用作发送的 `to:` 接收者。这通常是故意的（用户指定自己的提款目的地），属于信息性提示——只有当目的地本应是固定金库或状态记录的地址时才有意义。**不会**触发 CI 退出码门禁。 |
| `O1JS_WITNESS_NOT_BOUND_TO_STATE` | medium | 一个见证在效果之前仅被*平凡地*约束（例如 `> 0`，或与常量比较）——从未绑定到链上状态。确认链下编排使其安全，否则余额可被抽干至其现有值。 |
| `O1JS_STALE_MERKLE_ROOT` | high | 一个方法从证明者提供的见证（`computeRootAndKey` / `calculateRoot`）重新计算 Merkle 根，但没有将任何重新计算的根绑定到当前链上根。如果没有针对实时根的 `this.root.requireEquals(...)` / `assertEquals`，证明者可以传入伪造或过期树的见证——伪造成员资格或重放旧状态。绑定可能位于未装饰的同类辅助函数（`this.verifyX(witness)`）中；辅助函数传播覆盖了这种情况。 |
| `O1JS_UNVERIFIED_PROOF` | high | 一个类型为 `Proof<...>` / `SelfProof<...>` / `DynamicProof<...>` 的 `@method` 参数在其公共字段被使用之前从未被 `.verify()`。传入 Proof 并不会验证它——如果没有显式验证，证明者可以提供任意证明对象，并且对其 `publicOutput` 的任何使用都是不受约束的。当 `.verifyIf(flag)` 由不受约束的 `@method` 参数门控且证明的公共字段被读取时也会触发，因为证明者可以使条件为假。 |
| `O1JS_UNASSERTED_BOOL` | high / medium | 一个 o1js 谓词（`equals` / `lessThanOrEqual` / …）返回 `Bool`，除非结果被断言或使用，否则**不添加**任何约束。当调用是裸的丢弃语句时为 HIGH；当赋值给一个之后从未被引用的局部变量时为 MEDIUM。 |
| `O1JS_UNCONSTRAINED_SENDER` | high / medium | `this.sender.getUnconstrained()` 返回交易发送者而不证明它。当该值（或由它派生的局部变量）流入断言 / 状态 `.set` / `send`（空洞检查）时为 HIGH；否则为 MEDIUM。优先使用 `this.sender.getAndRequireSignature()`，或展开的惯用法 `AccountUpdate.createSigned(sender)`。**在以下情况保持安静**：(1) 同一 `@method` 也在任何位置调用了 `this.sender.getAndRequireSignature()`（签名要求是方法作用域的），或 (2) 见证的发送者值是 `AccountUpdate.createSigned(...)` 的参数 / 对同一密钥的 `AccountUpdate.create(...).requireSignature()`（要求参数同一性——对不同密钥的 `createSigned` 不会抑制）。 |
| `MissingRangeCheck` | high | 一个原始 `Field`（不是经过范围检查的 `UInt64`/`UInt32`）被用作转移金额。`Field` 是模 p 的元素，不受范围限制。 |
| `O1JS_WEAK_PERMISSIONS` | high / medium | `editState` / `send` 设置为 `proofOrSignature()` 或 `none()`，让 zkApp 账户密钥通过签名绕过电路。还会标记 `setVerificationKey` / `setPermissions` 保持为 `signature` / `proofOrSignature` / `none`（Mina 文档所述的升级辅助轮）；当与同一 `permissions.set` 中弱的 `editState`/`send` 组合时为 HIGH。 |
| `O1JS_LOGIC_OUTSIDE_PROOF` | high | 安全逻辑（assert / approve / send / 状态 `.set`）位于 `Provable.asProver(...)` 或 `Provable.witness*` 回调内。这些回调在电路*之外*运行——恶意证明者可以删除它们并仍产生可验证的证明。 |
| `O1JS_APPROVE_WITHOUT_BINDING` | medium | 一个 `@method` 调用 `approve` / `approveAccountUpdate` / `approveBase` 而不读取 `balanceChange` / `publicKey`，也没有 `assertCanMint` / `assertCanBurn` / `forEachUpdate` 守恒检查——即 Mina FlawedTokenContract 原型。 |
| `O1JS_VACUOUS_ASSERT` | high / medium | 一个构造上即满足的断言：`x.assertEquals(x)`、`x.equals(x).assertTrue()` 或 `Bool(true).assertTrue()`。自比较为 HIGH（几乎总是笔误）；常量 Bool 断言为 MEDIUM。 |
| `O1JS_CONDITIONAL_ASSERT` | medium | 一个位于 `if <flag> { ... }` 内的断言，其中 `<flag>` 是证明者控制的 `@method` `Bool`（或来自 `.toBoolean()` 的局部变量）。JS 条件语句不会像 `Provable.if` 那样约束电路。内联比较为精确性而保持不报告。 |
| `O1JS_GUARDED_INVERSE` | medium | 一个位于 `Provable.if` 分支内的 `.div()` / `.inv()` / `.sqrt()`，由针对其失败值的条件守护。两个分支都在电路内求值，并且这些调用无条件地断言逆或根存在，因此守护不会跳过断言——电路对于守护本要处理的那个输入恰好不可满足，并且该方法永远无法为其证明。由 Veridise 报告为 `V-O1J-VUL-060`。先计算安全除数（`Provable.if(isZero, Field(1), d)`），然后选择结果。**在以下情况保持安静**：守护对除数没有任何说明，因此围绕安全除法的无关 `Provable.if` 不会被标记。 |
| `O1JS_PRECONDITION_OVERWRITTEN` | medium | 在一个方法中对**同一**属性有两个或更多 `requireEquals` / `requireBetween` / `requireNothing` 调用，且参数不同。前置条件是*设置*在 AccountUpdate 上而非累积，因此每次调用都会覆盖前一次，只有最后一次被强制执行——不像电路内断言那样组合。`a.requireEquals(b)` 然后 `a.requireEquals(c)` 意味着 `a === c`，而不是 `a === b`。由 Veridise 报告为 `V-O1J-VUL-012`。**在以下情况保持安静**：参数相同（幂等，无损失）、在 `getAndRequireEquals()` 上（不同方法，因此重复状态读取没问题），以及调用位于互斥的 JS 分支中（在电路构建时解析）。最后一项豁免可能隐藏跨越无关 `if`/`else` 的真实覆盖。 |
| `O1JS_STATE_READ_AFTER_WRITE` | medium | 一个 `@state` 字段在同一方法中对同一字段的 `set(...)` 完成后被读取（`get()` / `getAndRequireEquals()`）。`set()` 在 AccountUpdate 上记录更改但不会写穿到 `get()`，因此读取仍观察到写入之前的值，任何基于它的算术都会因该写入而静默偏差。由 Veridise 报告为 `V-O1J-VUL-030`。将新值保存在局部变量中，而不是读回状态。**在以下情况保持安静**：读取嵌套在写入自身的参数内（读-改-写惯用法 `this.x.set(this.x.getAndRequireEquals().add(1))`，这是正确的），以及写入和读取位于互斥的 JS 分支中。作用域限于单个方法——Veridise 也描述的跨方法缓存情况需要此规则不具备的调用图知识。 |
<!-- END GENERATED O1JS RULE TABLE -->

### 误报防护（o1js）

分析器设计为对正确代码保持安静：

- **签名门控方法被跳过。** 一个调用
  `this.requireSignature()`（或 `getAndRequireSignature`、`AccountUpdate.createSigned`、
  `Signature.verify`）的 `@method` 是所有者/管理员门控的——其参数由密钥
  持有者选择，而非任意证明者——因此其见证不会被标记。这是
  o1js 中 `onlyOwner` 的等价物。
- **状态绑定的见证被跳过。** 一个被断言等于（或通过排序比较
  受限于）`getAndRequireEquals()` 派生值的参数是可靠的，不会被报告。这涵盖直接形式——
  `amount.assertLessThanOrEqual(bal)`——以及链式形式
  `amount.lessThanOrEqual(bal).assertTrue()`。位于
  未装饰的同类辅助函数（`this.verifyX(arg)`）中的绑定也被识别，
  包括通过此类辅助函数的链。
- **已验证的证明被跳过。** 一个 `Proof` / `SelfProof` / `DynamicProof` /
  `*Proof` 类型的参数，若其上调用了 `.verify()`，则受已验证电路约束——对其（及其 `publicOutput` /
  `publicInput`）的见证发现被抑制。`.verifyIf(flag)` 仅在
  条件不是不受约束的方法参数，或本身被断言时才被认可。这同样适用于规范的 OffchainState 包装器
  `this.offchainState.settle(proof)`（框架在 `settle` 内部验证）。
  手工编写的 `.settle(proof)` **不**被假定为验证。相反情况（证明类型参数从未验证
  且未 OffchainState 结算）被报告为 `O1JS_UNVERIFIED_PROOF`。
- **已断言/已使用的 Bool 被跳过。** 一个用
  `.assertTrue()` / `.assertFalse()` 链式调用、嵌套在 `Provable.if(...)` 中，或
  赋值给之后被引用的局部变量的谓词，不会被报告为
  `O1JS_UNASSERTED_BOOL`。
- **已认证的发送者被跳过。** `this.sender.getUnconstrained()`
  在同一 `@method` 也调用
  `this.sender.getAndRequireSignature()` 时不会触发，或当该见证值被
  传递给 `AccountUpdate.createSigned(...)` / 通过
  由它构建的 AccountUpdate 上的 `.requireSignature()` 认证时（要求参数
  同一性）。
- 注释和字符串字面量在分析前被剥离，因此字符串内的 `assert`
  不会产生错误结果。

## 它检测什么（Noir）

同样的可靠性理念——约束不足的见证——适用于
[Noir](https://noir-lang.org)（`.nr`）电路。将扫描器指向 `.nr`
文件（或使用 `--lang noir`），它会用 Noir 规则集分析它们。
相同的词法、无依赖方法。针对 aztec-nr oracle /
`unsafe` 惯用法进行了校准——参见 [`docs/noir_calibration.md`](https://github.com/auditinfra-io/o1js-scan/blob/main/docs/noir_calibration.md)。

<!-- BEGIN GENERATED NOIR RULE TABLE -->
| 规则 | 严重级别 | 含义 |
|------|----------|---------------|
| `NOIR_UNCONSTRAINED_WITNESS` | high | 一个从 `unsafe { ... }` 块绑定的值——`unconstrained fn`（oracle / Brillig 提示）的结果——从未被 `assert` / `assert_eq`（或确认辅助函数 / merkle 检查）重新约束。提示在电路*之外*运行。`O1JS_UNCONSTRAINED_PROVABLE_WITNESS` 的类比。 |
| `NOIR_UNCONSTRAINED_INPUT` | medium | `fn main` 的一个私有（见证）输入，它不流入**任何** `assert` / `assert_eq`，并且**不是**公共输出的一部分。`O1JS_UNCONSTRAINED_WITNESS` 的类比。 |
| `NOIR_UNCONSTRAINED_PUBLIC_INPUT` | medium | `fn main` 的一个**公共**输入，它不触及任何约束也不触及任何输出——电路从不读取它。这是私有见证规则的*对偶*：验证者提供该值并相信语句是关于它的，而电路忽略它（例如一个从未被检查的 `merkle_root: pub Field`，因此成员资格从未真正被证明）。为 MEDIUM，因为故意未使用的公共输入也是将证明绑定到上下文（nonce / chain id / recipient）的合法惯用法，这在词法上无法区分——因此它不会在默认 `--fail-on high` 下门控 CI。 |
| `NOIR_UNCHECKED_CAST` | medium | 一个证明者控制的值被转换为窄无符号类型（`as u8`/`u16`/`u32`）且**没有**范围断言。o1js `MissingRangeCheck` 的类比。 |
| `NOIR_UNCONSTRAINED_ARRAY_INDEX` | medium | 一个证明者控制的值被用作数组索引（`arr[i]`）且对其**没有任何**检查。Noir 的隐式边界检查仅确立索引*在范围内*——而非它是*正确的*索引——因此证明者仍可自由选择任意元素并仍产生可验证的证明。这是 Merkle 路径位置、note 选择和允许列表成员资格背后的选择器自由 bug。当索引受范围限制、被相等性固定、在转换前受限（`index.assert_max_bit_size::<8>(); let i = index as u32;`），或读回的值本身被 `assert_eq` 固定时被抑制。 |
| `NOIR_UNASSERTED_BOOL` | high / medium | 一个比较，其 `bool` 结果被**丢弃**。o1js `O1JS_UNASSERTED_BOOL` 的类比。 |
| `NOIR_CONDITIONAL_ASSERT` | medium | 一个位于 `if <flag> { ... }` 内的 `assert`，其中 `<flag>` 是证明者控制的裸 `bool` 或从证明者控制值派生的局部变量。条件内的约束仅在条件为真时适用，因此证明者选择的分支可以跳过检查。内联比较（`if x != 0`）为精确性而保持不动；将守护赋值给局部变量（`let gate = x != 0; if gate`）会被报告，除非 `gate` 本身被断言。 |
| `NOIR_CONDITIONAL_CONSTRAIN` | medium | 一个 `constrain_*` / `confirm_*` / `verify_*` 调用仅在证明者控制的 `if` 下，而 `unsafe` 提示仍到达输出。 |
| `NOIR_UNUSED_CHECK_RESULT` | high / medium | 一个 `check_*` / `confirm_*` / `verify_*` / `constrain_*` 结果被丢弃（裸调用）或赋值后从未被断言——检查不绑定电路。 |
| `NOIR_VACUOUS_CONSTRAINT` | high / medium | 一个构造上即满足的约束：自比较（`assert(x == x)`、`assert_eq(x, x)`、`x >= x`）或常量条件（`assert(true)`）。它不添加任何限制，但该行*读起来*像检查——这使其比缺失约束更危险，因为审查到此为止。自比较为 HIGH（几乎总是真实检查的笔误：`assert(computed == expected)` 误写为 `assert(expected == expected)`）；常量为 MEDIUM，更常是占位符。`x != x` **不**被标记——那是不可满足的，是活性 bug 而非静默的可靠性漏洞。 |
| `NOIR_UNSAFE_MISSING_SAFETY` | low | 一个 `unsafe { ... }` 块没有相邻的 `// Safety:` 注释。信息性；在默认 `--fail-on high` 下不会使 CI 失败。 |
<!-- END GENERATED NOIR RULE TABLE -->

### 误报防护（Noir）

- **Assert / let 跳转 / 同文件确认辅助函数**绑定 `unsafe` 提示。
- **调用点名称** `constrain_*` / `confirm_*` / `verify_*` /
  `check_(non_)membership*` / `public_data_storage_read` 认可参数（对丢弃的检查进行未使用结果检测）。
- **文档化的有意不受约束**（需要相邻 `// Safety:`）：
  `random()`、`avm::…`，以及 kernel/rollup/discovery 延迟措辞。
- **元组 `let` + 已断言标志**绑定传入成员资格检查的 merkle 见证。

示例：```console
$ 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 of 1 file(s) — fails (--fail-on high)

$ noir-scan examples/noir_constrained.nr --include-examples
noir-scan: no findings in 1 o1js or Noir file(s) — passes (--fail-on high)

## 许可证

Apache-2.0。参见 [`LICENSE`](https://github.com/auditinfra-io/o1js-scan/blob/main/LICENSE)。