o1js-scan

Пакет сообщества: o1js-scan указан в официальном каталоге o1js Community Packages.

Последняя версия: 0.20.0 — анализатор теперь читает контракты, которые extends TokenContract. До этого релиза проверка контрактов сопоставлялась только с SmartContract, поэтому каждый взаимозаменяемый токен, коллекция NFT и пул AMM в экосистеме сканировались как "no findings". Если вы сканировали контракт токена до 0.20.0, просканируйте его снова. См. .

| `--no-color` | Отключить цветной вывод | | `--debug` | Включить режим отладки | | `--verbose` | Включить подробный вывод | | `--silent` | Подавить весь вывод | | `--json` | Выводить результаты в формате JSON | | `--csv` | Выводить результаты в формате CSV | | `--html` | Выводить результаты в формате HTML | | `--markdown` | Выводить результаты в формате Markdown | | `--output <file>` | Записать вывод в файл | | `--config <file>` | Использовать указанный файл конфигурации | | `--threads <n>` | Количество потоков (по умолчанию: 10) | | `--timeout <n>` | Тайм-аут в секундах (по умолчанию: 30) | | `--retries <n>` | Количество повторных попыток (по умолчанию: 3) | | `--proxy <url>` | Использовать прокси | | `--user-agent <string>` | Установить User-Agent | | `--cookie <string>` | Установить Cookie | | `--header <string>` | Установить пользовательский заголовок | | `--rate-limit <n>` | Ограничить запросы в секунду | | `--random-agent` | Использовать случайный User-Agent | | `--follow-redirects` | Следовать перенаправлениям | | `--no-verify-ssl` | Отключить проверку SSL | | `--insecure` | Разрешить небезопасные соединения | | `--force` | Принудительное выполнение | | `--yes` | Автоматически отвечать «да» на все запросы | | `--no-interactive` | Отключить интерактивный режим | | `--version` | Показать версию | | `--help` | Показать справку |```nr let inv = unsafe { hint(x) }; // o1js-scan-disable-line NOIR_UNCONSTRAINED_WITNESS

Входные данные: `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: high`, когда `fail-on` оставлен на `none`; он выдаёт предупреждение об устаревании. Предпочитайте `fail-on`, который может ограничивать на любом уровне серьёзности. ## Что он обнаруживает (o1js) ### Поддерживаемые правила кратко  | Backend | Rules | High-capable | Medium-capable | Low-capable | |---------|------:|-------------:|---------------:|------------:| | o1js | 18 | 11 | 12 | 2 | | Noir | 11 | 4 | 9 | 1 | | **Total** | **29** | **15** | **21** | **3** |  Счётчики — это уникальные ID правил, поддерживаемых каждым бэкендом. Правило, которое назначает серьёзность в зависимости от контекста (например, high для перевода стоимости и medium для записи состояния), появляется более чем в одной колонке серьёзности, поэтому колонки серьёзности намеренно не суммируются в общее число правил. В настоящее время нет правил уровня critical или info. Полные описания и защиты от ложных срабатываний приведены ниже.  | Rule | Severity | What it means | |------|----------|---------------| | `O1JS_MISSING_STATE_PRECONDITION` | high | `this.x.get()` читается без соответствующего `requireEquals(...)` / `getAndRequireEquals()`. Простой `get()` не добавляет **никакого** предусловия аккаунта, поэтому доказательство не привязывает `x` к его on-chain значению — доказывающий может подставить любое значение. | | `O1JS_UNCONSTRAINED_WITNESS` | high / medium | Аргумент `@method` (приватный свидетель, контролируемый доказывающим) попадает в **сумму** отправки (`this.send(...)` или `AccountUpdate.create*(...).send(...)` в том же методе) или в `.set(...)` состояния и **никогда** не проверяется утверждением. Прямой аналог недостаточно ограниченного сигнала Circom. High, когда он достигает перевода стоимости. | | `O1JS_UNCONSTRAINED_PROVABLE_WITNESS` | high / medium / low | Локальная переменная `Provable.witness(...)` попадает в эффект отправки/состояния **без** внутрисхемного утверждения. Callback свидетеля выполняется *вне* схемы (это лишь подсказка доказывающему), поэтому результат — свежее значение, контролируемое доказывающим — другой источник свидетелей помимо аргументов `@method`. Его нужно заново вывести и утвердить (`x.assertEquals(<recomputed>)`) или привязать к состоянию. High для суммы отправки (`this.send(...)` или `AccountUpdate.create*` в том же методе). | | `O1JS_UNCONSTRAINED_RECIPIENT` | low | Аргумент `@method` используется **только** как получатель `to:` при отправке. Обычно это намеренно (пользователь указывает собственный адрес вывода) и носит информационный характер — это важно только если получатель должен быть фиксированной казной или адресом, записанным в состоянии. **Не** приводит к срабатыванию гейта кода возврата CI. | | `O1JS_WITNESS_NOT_BOUND_TO_STATE` | medium | Свидетель ограничен лишь *тривиально* (например, `> 0` или сравнением с константой) перед эффектом — никогда не привязан к on-chain состоянию. Убедитесь, что внецепочечная оркестрация делает это безопасным, иначе баланс можно опустошить вплоть до его текущего значения. | | `O1JS_STALE_MERKLE_ROOT` | high | Метод пересчитывает корень Меркла из свидетеля, предоставленного доказывающим (`computeRootAndKey` / `calculateRoot`), но не привязывает **ни один** из пересчитанных корней к текущему on-chain корню. Без `this.root.requireEquals(...)` / `assertEquals` относительно живого корня доказывающий может передать свидетеля для сфабрикованного или устаревшего дерева — подделав членство или воспроизведя старое состояние. Привязка может находиться в недекорированном вспомогательном методе того же класса (`this.verifyX(witness)`); распространение через вспомогательные методы это покрывает. | | `O1JS_UNVERIFIED_PROOF` | high | Параметр `@method` с типом `Proof<...>` / `SelfProof<...>` / `DynamicProof<...>` никогда не проходит `.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()` возвращает отправителя транзакции без его доказательства. HIGH, когда это значение (или локальная переменная из него) попадает в assert / `.set` состояния / `send` (пустая проверка); 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 «training wheels» для обновления); HIGH в сочетании со слабыми `editState`/`send` в том же `permissions.set`. | | `O1JS_LOGIC_OUTSIDE_PROOF` | high | Логика безопасности (assert / approve / send / `.set` состояния) внутри `Provable.asProver(...)` или callback `Provable.witness*`. Эти callback выполняются *вне* схемы — злонамеренный доказывающий может удалить их и всё равно получить верифицирующее доказательство. | | `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 для самосравнений (почти всегда опечатка); MEDIUM для утверждений константного Bool. | | `O1JS_CONDITIONAL_ASSERT` | medium | Утверждение внутри `if <flag> { ... }`, где `<flag>` — это контролируемый доказывающим `Bool` из `@method` (или локальная переменная из `.toBoolean()`). Условный оператор JS не ограничивает схему так, как это делает `Provable.if`. Встроенные сравнения не сообщаются ради точности. | | `O1JS_GUARDED_INVERSE` | medium | `.div()` / `.inv()` / `.sqrt()` внутри ветви `Provable.if`, защищённой условием на само значение, на котором она терпит неудачу. Обе ветви вычисляются в схеме, и эти вызовы безусловно утверждают, что обратное значение или корень существует, поэтому защита не пропускает утверждение — схема невыполнима ровно для того входа, для которого защита была написана, и метод никогда не может быть доказан для него. Сообщается 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` читается (`get()` / `getAndRequireEquals()`) после завершения `set(...)` на том же поле в том же методе. `set()` записывает изменение в AccountUpdate, но не записывает сквозь в `get()`, поэтому чтение всё ещё наблюдает значение до записи, и любая арифметика на его основе молча смещена на эту запись. Сообщается Veridise как `V-O1J-VUL-030`. Храните новое значение в локальной переменной вместо повторного чтения состояния. **Молчит, когда** чтение вложено в собственные аргументы записи (идиома read-modify-write `this.x.set(this.x.getAndRequireEquals().add(1))`, которая корректна), и когда запись и чтение находятся во взаимоисключающих ветвях JS. Ограничено одним методом — случай кэширования между методами, который также описывает Veridise, требует знания графа вызовов, которого у этого правила нет. |  ### Защиты от ложных срабатываний (o1js) Анализатор спроектирован так, чтобы молчать на корректном коде: - **Методы, защищённые подписью, пропускаются.** `@method`, который вызывает `this.requireSignature()` (или `getAndRequireSignature`, `AccountUpdate.createSigned`, `Signature.verify`), защищён владельцем/администратором — его аргументы выбираются держателем ключа, а не произвольным доказывающим — поэтому его свидетели не отмечаются. Это эквивалент `onlyOwner` в o1js. - **Свидетели, привязанные к состоянию, пропускаются.** Аргумент, утверждённый равным (или ограниченный сравнением порядка относительно) значению, полученному из `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)` **не** предполагается верифицирующим. Обратный случай (аргумент типа proof никогда не верифицирован и не урегулирован через OffchainState) сообщается как `O1JS_UNVERIFIED_PROOF`. - **Утверждённые / использованные Bool пропускаются.** Предикат, сцепленный с `.assertTrue()` / `.assertFalse()`, вложенный в `Provable.if(...)` или присвоенный локальной переменной, на которую позже ссылаются, не сообщается как `O1JS_UNASSERTED_BOOL`. - **Аутентифицированные отправители пропускаются.** `this.sender.getUnconstrained()` не срабатывает, когда тот же `@method` также вызывает `this.sender.getAndRequireSignature()`, или когда это значение свидетеля передаётся в `AccountUpdate.createSigned(...)` / аутентифицируется через `.requireSignature()` на AccountUpdate, построенном из него (требуется идентичность аргумента). - Комментарии и строковые литералы удаляются перед анализом, поэтому `assert` внутри строки не может создать ложный результат. ## Что он обнаруживает (Noir) Та же идея корректности — недостаточно ограниченные свидетели — применяется к [Noir](https://noir-lang.org) схемам (`.nr`). Направьте сканер на файлы `.nr` (или используйте `--lang noir`), и он проанализирует их с набором правил Noir. Тот же лексический подход без зависимостей. Откалиброван по идиомам оракулов aztec-nr / `unsafe` — см. [`docs/noir_calibration.md`](https://github.com/auditinfra-io/o1js-scan/blob/main/docs/noir_calibration.md).  | Rule | Severity | What it means | |------|----------|---------------| | `NOIR_UNCONSTRAINED_WITNESS` | high | Значение, полученное из блока `unsafe { ... }` — результат `unconstrained fn` (оракул / подсказка Brillig) — которое никогда не переограничивается через `assert` / `assert_eq` (или подтверждающий вспомогательный метод / проверку Меркла). Подсказка выполняется **вне** схемы. Аналог `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 / получатель), что лексически неотличимо — поэтому он не ограничивает CI при значении по умолчанию `--fail-on high`. | | `NOIR_UNCHECKED_CAST` | medium | Контролируемое доказывающим значение, приведённое к узкому беззнаковому типу (`as u8`/`u16`/`u32`) **без** утверждения о диапазоне. Аналог o1js `MissingRangeCheck`. | | `NOIR_UNCONSTRAINED_ARRAY_INDEX` | medium | Контролируемое доказывающим значение, используемое как индекс массива (`arr[i]`) **без** какой-либо проверки. Неявная проверка границ Noir устанавливает лишь то, что индекс *в пределах диапазона* — а не то, что он *правильный* — поэтому доказывающий остаётся свободным выбрать любой элемент и всё равно получить верифицирующее доказательство. Это баг свободы выбора селектора, стоящий за позициями путей Меркла, выбором нот и членством в allow-list. Подавляется, когда индекс ограничен по диапазону, закреплён равенством, ограничен перед приведением (`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 | `assert` внутри `if <flag> { ... }`, где `<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` **не** отмечается — это невыполнимо, баг живости, а не молчаливая дыра в корректности. | | `NOIR_UNSAFE_MISSING_SAFETY` | low | Блок `unsafe { ... }` без соседнего комментария `// Safety:`. Информационно; не приводит к сбою CI при значении по умолчанию `--fail-on high`. |  ### Защиты от ложных срабатываний (Noir) - **Assert / переход через let / подтверждающие вспомогательные методы в том же файле** привязывают подсказки `unsafe`. - **Имена на месте вызова** `constrain_*` / `confirm_*` / `verify_*` / `check_(non_)membership*` / `public_data_storage_read` засчитывают аргументы (с обнаружением неиспользованного результата для отброшенных проверок). - **Документированные намеренно неограниченные** (требуется соседний `// Safety:`): `random()`, `avm::…` и отложенные формулировки kernel/rollup/discovery. - **Кортежный `let` + утверждённые флаги** привязывают свидетелей Меркла, переданных в проверки членства. Пример:```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)

Релиз	Находки	HIGH	MEDIUM	LOW	Файлы
o1js 2.15.0	36	8	26	2	18
o1js 3.0.0 (Mesa)	39	8	29	2	19

o1js-scan

Популярное

or: pipx install o1js-scan

or: npm install -D o1js-scan

Подавление проверенной находки

CI-рецепт только для Noir

pre-commit (опционально)```yaml

.pre-commit-config.yaml

Известные ограничения

Где этот инструмент останавливается

Приватность и приватный код

Постквантовая проверка

Совместимость

Как это работает

Дорожная карта / участие