o1js-scan — Analizzatore statico senza dipendenze per bug di solidità dei circuiti zk in o1js/Mina zkApps e circuiti Noir | Kitploit

### Esempio

Dato un vault il cui importo di `withdraw` è un witness controllato dal prover che
non è mai vincolato allo stato on-chain:```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

Consulta [`examples/`](https://github.com/auditinfra-io/o1js-scan/blob/main/examples) per le coppie vulnerabili/corrette di o1js e Noir.

## Contenuti

- [Installazione](#install)
- [Utilizzo](#usage) · [Sopprimere un risultato](#suppressing-a-reviewed-finding)
- [GitHub Action](#github-action)
- [Cosa rileva — o1js](#what-it-detects-o1js) · [Noir](#what-it-detects-noir)
- [Limitazioni note](#known-limitations) · [Dove si ferma questo strumento](#where-this-tool-stops)
- [Privacy e codice privato](#privacy-and-private-code)
- [Revisione post-quantum](#post-quantum-review)
- [Compatibilità](#compatibility) · [Come funziona](#how-it-works)
- [Contribuire](#roadmap--contributing)

## Installazione```bash
pip install o1js-scan

Nessuna dipendenza Python di terze parti. Python 3.8+. Lo script console `noir-scan` è
installato insieme a `o1js-scan` (stesso entry point), anche tramite il wrapper
npm.

## Utilizzo```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

| `-s` | `--server` | `SERVER` | `http://localhost:8080` | URL del server MCP |
| `-t` | `--token` | `TOKEN` | `None` | Token di autenticazione |
| `-k` | `--insecure` | flag | `False` | Disabilita la verifica del certificato TLS |
| `-v` | `--verbose` | flag | `False` | Abilita il logging dettagliato |
| `-o` | `--output` | `FILE` | `None` | Salva l'output su file |
| `-f` | `--format` | `FORMAT` | `text` | Formato di output (`text`, `json`) |
| `-c` | `--config` | `FILE` | `None` | File di configurazione |
| `-h` | `--help` | flag | - | Mostra il messaggio di aiuto |

### Esempi

```bash
# Elenca tutti gli strumenti disponibili
mcp-client --server http://localhost:8080 --list-tools

# Chiama uno strumento specifico
mcp-client --server http://localhost:8080 --call-tool scan_target --args '{"target": "example.com"}'

# Usa un file di configurazione
mcp-client --config ~/.mcp/config.json --list-tools

# Output in formato JSON
mcp-client --server http://localhost:8080 --list-tools --format json

# Clona il repository
git clone https://github.com/example/mcp-client.git
cd mcp-client

# Crea un ambiente virtuale
python3 -m venv venv
source venv/bin/activate  # Su Windows: venv\Scripts\activate

# Installa le dipendenze di sviluppo
pip install -r requirements-dev.txt

# Installa in modalità modificabile
pip install -e .

# Verifica che il server sia in esecuzione
curl http://localhost:8080/health

# Controlla la connettività di rete
ping localhost

# Verifica la configurazione del firewall
sudo ufw status

Elenca uno o più id di regole per sopprimere solo quelle; una direttiva nuda (senza id)
sopprime ogni regola sulla riga di destinazione.

Come libreria:```python
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)

### Ricetta CI solo per Noir

Consigliata per i progetti Noir che desiderano avvisi di scansione del codice e un gate per le vulnerabilità ad alta gravità:```yaml
- uses: auditinfra-io/[email protected]
  with:
    path: .
    lang: noir
    fail-on: high

### pre-commit (opzionale)```yaml
# .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"]

Regola	Severità	Cosa significa
`O1JS_MISSING_STATE_PRECONDITION`	high	`this.x.get()` letto senza un corrispondente `requireEquals(...)` / `getAndRequireEquals()`. Un `get()` nudo non aggiunge nessuna precondizione sull'account, quindi la proof non vincola `x` al suo valore on-chain — un prover può sostituire qualsiasi valore.
`O1JS_UNCONSTRAINED_WITNESS`	high / medium	Un argomento di `@method` (un witness privato controllato dal prover) confluisce in un importo di invio (`this.send(...)` o un `AccountUpdate.create(...).send(...)` dello stesso metodo) o in un `.set(...)` di stato e non* viene mai asserito. Analogo diretto di un segnale Circom sotto-vincolato. High quando raggiunge un trasferimento di valore.
`O1JS_UNCONSTRAINED_PROVABLE_WITNESS`	high / medium / low	Una variabile locale `Provable.witness(...)` confluisce in un effetto di invio/stato con nessuna asserzione nel circuito. Il callback del witness viene eseguito fuori dal circuito (è solo un suggerimento per il prover), quindi il risultato è un valore fresco controllato dal prover — l'altra fonte di witness oltre agli argomenti di `@method`. Deve essere ri-derivato e asserito (`x.assertEquals(<recomputed>)`) o vincolato allo stato. High su un importo di invio (`this.send(...)` o `AccountUpdate.create*` dello stesso metodo).
`O1JS_UNCONSTRAINED_RECIPIENT`	low	Un argomento di `@method` è usato solo come destinatario `to:` di un invio. Di solito è intenzionale (un utente indica la propria destinazione di prelievo) ed è informativo — conta solo se la destinazione deve essere una tesoreria fissa o un indirizzo registrato nello stato. Non attiva il gate del codice di uscita della CI.
`O1JS_WITNESS_NOT_BOUND_TO_STATE`	medium	Un witness è vincolato solo trivialmente (ad es. `> 0`, o confrontato con una costante) prima di un effetto — mai legato allo stato on-chain. Conferma che l'orchestrazione off-chain lo renda sicuro, altrimenti il saldo è drenabile fino al suo valore corrente.

I metodi protetti da firma vengono saltati. Un @method che chiama this.requireSignature() (o getAndRequireSignature, AccountUpdate.createSigned, Signature.verify) è protetto da owner/admin — i suoi argomenti sono scelti dal detentore della chiave, non da un prover arbitrario — quindi i suoi witness non vengono segnalati. Questo è l'equivalente o1js di onlyOwner.
I witness vincolati allo stato vengono saltati. Un argomento asserito uguale a (o limitato da un confronto d'ordinamento rispetto a) un valore derivato da getAndRequireEquals() è corretto e non verrà segnalato. Questo copre sia la forma diretta — amount.assertLessThanOrEqual(bal) — sia la forma concatenata amount.lessThanOrEqual(bal).assertTrue(). Anche il binding che risiede in un helper non decorato della stessa classe (this.verifyX(arg)) è riconosciuto, anche attraverso una catena di tali helper.
Le proof verificate vengono saltate. Un argomento tipizzato Proof / SelfProof / DynamicProof / *Proof su cui viene chiamato .verify() è vincolato dal circuito verificato — i risultati sui witness su di esso (e sui suoi publicOutput / publicInput) sono soppressi. Un .verifyIf(flag) è accreditato solo quando la condizione non è un argomento di metodo non vincolato, o è essa stessa asserita. Lo stesso vale per il wrapper canonico OffchainState this.offchainState.settle(proof) (il framework verifica dentro settle). Un .settle(proof) scritto a mano non si presume che verifichi. Il caso inverso (argomento tipizzato proof mai verificato e non regolato da OffchainState) è segnalato come O1JS_UNVERIFIED_PROOF.
I Bool asseriti / usati vengono saltati. Un predicato concatenato con .assertTrue() / .assertFalse(), annidato in Provable.if(...), o assegnato a una variabile locale successivamente referenziata, non è segnalato come O1JS_UNASSERTED_BOOL.
I mittenti autenticati vengono saltati. this.sender.getUnconstrained() non scatta quando lo stesso @method chiama anche this.sender.getAndRequireSignature(), o quando quel valore witness è passato a AccountUpdate.createSigned(...) / autenticato tramite .requireSignature() su un AccountUpdate costruito da esso (è richiesta l'identità dell'argomento).
I commenti e i letterali stringa vengono rimossi prima dell'analisi, quindi un assert dentro una stringa non può creare un risultato falso.

Regola	Severità	Cosa significa
`NOIR_UNCONSTRAINED_WITNESS`	high	Un valore vincolato da un blocco `unsafe { ... }` — il risultato di una `unconstrained fn` (hint oracle / Brillig) — che non viene mai ri-vincolato da un `assert` / `assert_eq` (o un helper di conferma / controllo merkle). L'hint viene eseguito fuori dal circuito. Analogo di `O1JS_UNCONSTRAINED_PROVABLE_WITNESS`.
`NOIR_UNCONSTRAINED_INPUT`	medium	Un input privato (witness) di `fn main` che non confluisce in nessun `assert` / `assert_eq` e non fa parte dell'output pubblico. Analogo di `O1JS_UNCONSTRAINED_WITNESS`.
`NOIR_UNCONSTRAINED_PUBLIC_INPUT`	medium	Un input pubblico di `fn main` che non raggiunge alcun vincolo e nessun output — il circuito non lo legge mai. Il duale della regola sul witness privato: il verificatore fornisce il valore e crede che l'asserzione lo riguardi, mentre il circuito lo ignora (ad es. un `merkle_root: pub Field` che non viene mai controllato, quindi l'appartenenza non è mai stata realmente provata). MEDIUM perché un input pubblico deliberatamente inutilizzato è anche un idioma legittimo per vincolare una proof a un contesto (nonce / chain id / destinatario), che è lessicalmente indistinguibile — quindi non applica il gate della CI al valore predefinito `--fail-on high`.
`NOIR_UNCHECKED_CAST`	medium	Un valore controllato dal prover convertito a un tipo unsigned stretto (`as u8`/`u16`/`u32`) con nessuna asserzione di intervallo. Analogo di `MissingRangeCheck` di o1js.
`NOIR_UNCONSTRAINED_ARRAY_INDEX`	medium	Un valore controllato dal prover usato come indice di array (`arr[i]`) con nessun controllo di alcun tipo su di esso. Il controllo implicito dei limiti di Noir stabilisce solo che l'indice è nell'intervallo — non che sia l'indice corretto — quindi il prover resta libero di selezionare qualsiasi elemento e produrre comunque una proof che verifica. Questo è il bug della libertà di selezione dietro le posizioni dei percorsi di Merkle, la selezione delle note e l'appartenenza alle allow-list. Soppresso quando l'indice è limitato a un intervallo, fissato da un'uguaglianza, limitato prima di un cast (), o quando il valore riletto è esso stesso fissato da un .

Come con l'esempio o1js sopra, `--include-examples` è necessario solo perché
questi file demo si trovano sotto `examples/`.

## Limitazioni note

L'analizzatore è un **frontend lessicale senza dipendenze più un livello semantico leggero** che effettua il tracciamento degli alias e la propagazione interprocedurale attraverso helper della stessa classe. Non è un frontend del compilatore TypeScript, un type checker o un motore di dataflow sull'intero programma, e non c'è alcun livello SMT o di prova formale in questo scanner.
Tieni presenti questi punti ciechi durante la triage — sono noti e intenzionali
per questo design senza dipendenze, non bug:

- **Vengono seguiti solo gli alias semplici.** Il tracciamento dei witness segue
  alias semplici dello stesso metodo come `const q = qty`, ma non espressioni
  derivate o destrutturazione:  ```ts
  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

Il binding cross-method copre solo catene di helper della stessa classe. Un helper non decorato della stessa classe chiamato come this.verifyX(arg) può fare state-binding dell'argomento di un chiamante, e dalla 0.19.0 le catene di questi (@method → helper A → helper B) vengono seguite fino a un punto fisso. Il passaggio helper→helper mappa solo un riferimento a parametro nudo, quindi helperA(x.add(1)) non si propaga. Le funzioni libere e importate non vengono ancora seguite, e l'aliasing tramite variabile locale dell'argomento dell'helper resta una limitazione documentata.
Il rilevamento di Bool non asseriti è basato sulla forma dell'istruzione. Il Tier A segnala solo istruzioni di espressione nude la cui chiamata più esterna è un predicato Bool senza nulla concatenato dopo. I predicati annidati dentro Provable.if(...), o assegnati e usati successivamente, non vengono segnalati. Usi complessi di controllo di flusso di un Bool locale possono ancora sfuggire se il nome non viene mai referenziato (modalità di fallimento: mancata rilevazione, non un falso positivo).
Il signature-gating è a livello di metodo e basato su sottostringhe. _method_is_signature_gated tratta un intero @method come owner-gated se contiene un idioma di firma, e riconosce un verificatore solo quando il nome del receiver contiene letteralmente signature — quindi sig.verify(admin, msg) non viene riconosciuto come gating, mentre un controllo di firma non correlato altrove in un metodo grande può sopprimere eccessivamente. È tutto-o-niente per metodo.
L'autenticazione del sender è basata sul nome e solo nello stesso metodo. O1JS_UNCONSTRAINED_SENDER sopprime quando this.sender.getAndRequireSignature() o AccountUpdate.createSigned(<quel sender>) appare nello stesso corpo del @method. Un requisito di firma che risiede solo in un helper (this.requireSenderSig() → getAndRequireSignature all'interno) non viene seguito — la modalità di fallimento è un falso positivo su codice corretto che incapsula l'idioma, non un bug reale mancato.
Gli helper cross-crate di Noir sono riconosciuti solo per convenzione di nome (nessuna risoluzione di Nargo.toml / import). Preferire la mancata rilevazione al falso positivo.

index.assert_max_bit_size::<8>(); let i = index as u32;

assert_eq

Backend	Regole	High-capable	Medium-capable	Low-capable
o1js	18	11	12	2
Noir	11	4	9	1
Totale	29	15	21	3

Release	Findings	HIGH	MEDIUM	LOW	Files
o1js 2.15.0	36	8	26	2	18
o1js 3.0.0 (Mesa)	39	8	29	2	19

o1js-scan

Più Popolari

or: pipx install o1js-scan

or: npm install -D o1js-scan

Sopprimere un finding revisionato

Configurazione

Sviluppo

Configurazione dell'ambiente

Esecuzione dei test

Linting e formattazione

Sicurezza

Risoluzione dei problemi

Impossibile connettersi al server

Errori di autenticazione

Timeout

Contribuire

Licenza

Ringraziamenti

Supporto

GitHub Action

.github/workflows/o1js-scan.yml

Cosa rileva (o1js)

Regole supportate in sintesi

Protezioni contro i falsi positivi (o1js)

Cosa rileva (Noir)

Protezioni contro i falsi positivi (Noir)

Dove si ferma questo strumento

Privacy e codice privato

Revisione post-quantum

Compatibilità

Come funziona

Roadmap / contribuire