o1js-scan

Paquet communautaire : o1js-scan est référencé dans le répertoire officiel o1js Community Packages.

Dernière version : 0.22.0 — un serveur MCP local permet à Claude Code, Cursor et autres assistants de codage IA d'exécuter le scanner pendant que vous écrivez une zkApp : pip install 'o1js-scan[mcp]'. Il s'exécute sur votre machine via stdio et ne téléverse rien. Un scan qui n'a analysé aucun fichier est une erreur, pas un résultat propre, et un résultat sans constat indique qu'il ne s'agit pas d'une garantie de sécurité. Le scanner principal n'a toujours aucune dépendance. Voir CHANGELOG.

Un analyseur statique rapide et sans dépendances pour les bugs de solidité des circuits zk dans :

• o1js / Mina zkApps (TypeScript .ts / .js) — circuits Kimchi issus des corps @method
• Noir (.nr) — le DSL ZK de type Rust d'Aztec (y compris les motifs de type aztec-nr)

Les bugs critiques pour la sécurité ne se trouvent généralement pas dans le système de preuve — ils sont dans les contraintes propres à l'application : des témoins que le prouveur contrôle mais que le circuit ne lie jamais. o1js-scan est le scanner de signaux sous-contraints pour les cousins de Circom dans les écosystèmes Mina et Noir.

Voir aussi : gnark-safety (circuits gnark), vk-guard (régression de clé de vérification).

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

Exemple

Étant donné un coffre-fort dont le montant de withdraw est un témoin contrôlé par le prouveur qui n'est jamais lié à l'état on-chain :

$ 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

--include-examples n'est nécessaire ici que parce que le fichier de démonstration se trouve sous examples/, que le classificateur de chemins rétrograde par défaut afin que le code d'exemple d'un dépôt ne puisse pas faire échouer sa compilation. Le même contrat dans votre src/ signale HIGH sans aucun drapeau.

La détection HIGH est le bug exploitable. Le contrat corrigé (examples/safe_vault.ts) l'élimine et se termine avec 0, ne conservant que le LOW informatif sur le destinataire choisi par le prouveur :

$ 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 of 1 file(s) — passes (--fail-on high)
$ echo $?
0

Voir examples/ pour les paires vulnérables/corrigées o1js et Noir.

Contenu

• Installation
• Utilisation · Supprimer un résultat
• GitHub Action · Serveur MCP pour assistants IA
• Ce qu'il détecte — o1js · Noir
• Limitations connues · Où cet outil s'arrête
• Confidentialité et code privé
• Revue post-quantique
• Compatibilité · Comment ça fonctionne
• Contribuer

Installation

pip install o1js-scan

Pour une installation CLI globale isolée, utilisez pipx :

pipx install o1js-scan

Pour les dépôts d'applications Node/npm basés sur Noir, Aztec ou o1js, installez le wrapper npm :

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

Le paquet npm est une fine enveloppe autour du même analyseur Python et nécessite Python 3.8+ dans le PATH (python3 ou python). Définissez O1JS_SCAN_PYTHON pour choisir un interpréteur spécifique.

Ou depuis les sources :

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

Aucune dépendance Python tierce. Python 3.8+. Le script console noir-scan est installé aux côtés de o1js-scan (même point d'entrée), y compris via le wrapper npm.

Utilisation

# 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

# a path with no o1js / Noir source exits 2; opt out where that is expected
o1js-scan packages/ --allow-empty

o1js-scan --version

Le code de sortie est 1 lorsqu'une détection au niveau --fail-on ou supérieur (par défaut high) est présente, et 0 sinon — vous pouvez donc l'intégrer directement dans la CI. Avec la valeur par défaut, une détection de niveau faible/moyen (y compris la règle informative sur les destinataires ci-dessous) ne fait pas échouer le build ; utilisez --fail-on none pour seulement signaler, ou --strict (un raccourci pour --fail-on medium) pour filtrer plus strictement tout en traitant les détections de faible sévérité comme consultatives. Les deux options sont mutuellement exclusives afin que la configuration de la CI ne puisse pas être ambiguë. Un chemin de scan manquant se termine par 2 avec une erreur sur stderr, afin qu'une faute de frappe ne puisse pas passer silencieusement la CI comme une exécution propre. Il en va de même pour un chemin qui existe mais ne contient aucun code source o1js ou Noir que l'analyseur peut lire (par exemple --lang noir pointé vers un projet o1js) ; passez --allow-empty là où c'est légitime. Chaque exécution affiche un résumé d'une ligne (comptages par sévérité et verdict du filtre) sur stderr.

Le code de test est exclu par défaut — pour les deux backends. Les tests construisent délibérément des valeurs invalides et de mauvaises transactions pour prouver que les assertions les rejettent, donc une détection à cet endroit est le but du test plutôt qu'un bug de circuit. Un fichier est considéré comme du code de test lorsque :