### Exemplo

Dado um cofre cujo valor de `withdraw` é uma testemunha controlada pelo provador que
nunca é vinculada ao estado 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

Consulte [`examples/`](https://github.com/auditinfra-io/o1js-scan/blob/main/examples) para os pares vulneráveis/corrigidos de o1js e Noir.

## Conteúdo

- [Instalação](#install)
- [Uso](#usage) · [Suprimindo um achado](#suppressing-a-reviewed-finding)
- [GitHub Action](#github-action)
- [O que ele detecta — o1js](#what-it-detects-o1js) · [Noir](#what-it-detects-noir)
- [Limitações conhecidas](#known-limitations) · [Onde esta ferramenta para](#where-this-tool-stops)
- [Privacidade e código privado](#privacy-and-private-code)
- [Revisão pós-quântica](#post-quantum-review)
- [Compatibilidade](#compatibility) · [Como funciona](#how-it-works)
- [Contribuindo](#roadmap--contributing)

## Instalação```bash
pip install o1js-scan

Sem dependências Python de terceiros. Python 3.8+. O script de console `noir-scan` é
instalado juntamente com `o1js-scan` (mesmo ponto de entrada), inclusive através do wrapper
npm.

## Uso```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-color` | Desativa a saída colorida |
| `--debug` | Ativa a saída de depuração |
| `--verbose` | Ativa a saída detalhada |
| `--version` | Exibe a versão do programa |
| `--help` | Exibe a mensagem de ajuda |

### Exemplos de Uso

```bash
# Escanear um único repositório
python3 GitDorker.py -tf tokens.txt -q "example" -d repos.txt -o results.txt

# Escanear uma organização
python3 GitDorker.py -tf tokens.txt -q "example" -org "myorg" -o results.txt

# Escanear um usuário
python3 GitDorker.py -tf tokens.txt -q "example" -u "myuser" -o results.txt

# Escanear um único repositório
python3 GitDorker.py -tf tokens.txt -q "example" -r "https://github.com/user/repo" -o results.txt

Liste um ou mais ids de regras para suprimir apenas essas; uma diretiva isolada (sem ids)
suprime todas as regras na linha de destino.

Como biblioteca:```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)

### Receita de CI somente para Noir

Recomendada para projetos Noir que desejam alertas de varredura de código e um
gate de alta severidade:```yaml
- uses: auditinfra-io/[email protected]
  with:
    path: .
    lang: noir
    fail-on: high

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

Regra	Severidade	O que significa
`O1JS_MISSING_STATE_PRECONDITION`	high	Leitura de `this.x.get()` sem um `requireEquals(...)` / `getAndRequireEquals()` correspondente. Um `get()` simples não adiciona nenhuma pré-condição de conta, pelo que a prova não vincula `x` ao seu valor on-chain — um provador pode substituir qualquer valor.
`O1JS_UNCONSTRAINED_WITNESS`	high / medium	Um argumento de `@method` (uma testemunha privada controlada pelo provador) flui para um montante de envio (`this.send(...)` ou um `AccountUpdate.create(...).send(...)` do mesmo método) ou para um `.set(...)` de estado e nunca* é asseverado. Análogo direto de um sinal Circom sub-restrito. High quando atinge uma transferência de valor.
`O1JS_UNCONSTRAINED_PROVABLE_WITNESS`	high / medium / low	Uma variável local de `Provable.witness(...)` flui para um efeito de envio/estado com nenhuma asserção in-circuit. O callback da testemunha corre fora do circuito (é apenas uma dica para o provador), pelo que o resultado é um valor novo controlado pelo provador — a outra fonte de testemunhas além dos argumentos de `@method`. Tem de ser re-derivado e asseverado (`x.assertEquals(<recomputed>)`) ou vinculado ao estado. High num montante de envio (`this.send(...)` ou `AccountUpdate.create*` do mesmo método).
`O1JS_UNCONSTRAINED_RECIPIENT`	low	Um argumento de `@method` é usado apenas como o destinatário `to:` de um envio. Isto é habitualmente intencional (um utilizador nomeia o seu próprio destino de levantamento) e é informativo — só importa se o destino se destinar a ser um tesouro fixo ou um endereço registado em estado. Não aciona o gate do código de saída da CI.
`O1JS_WITNESS_NOT_BOUND_TO_STATE`	medium	Uma testemunha é apenas trivialmente restringida (por exemplo, `> 0`, ou comparada com uma constante) antes de um efeito — nunca ligada ao estado on-chain. Confirme que a orquestração off-chain torna isto seguro, ou o saldo é drenável até ao seu valor permanente.

Métodos com gate de assinatura são ignorados. Um @method que chama this.requireSignature() (ou getAndRequireSignature, AccountUpdate.createSigned, Signature.verify) tem gate de proprietário/admin — os seus argumentos são escolhidos pelo detentor da chave, não por um provador arbitrário — pelo que as suas testemunhas não são sinalizadas. Este é o equivalente o1js de onlyOwner.
Testemunhas vinculadas ao estado são ignoradas. Um argumento asseverado como igual a (ou limitado por uma comparação de ordenação contra) um valor derivado de getAndRequireEquals() é sólido e não será reportado. Isto cobre tanto a forma direta — amount.assertLessThanOrEqual(bal) — como a forma encadeada amount.lessThanOrEqual(bal).assertTrue(). A vinculação que reside num helper não decorado da mesma classe (this.verifyX(arg)) também é reconhecida, incluindo através de uma cadeia de tais helpers.
Provas verificadas são ignoradas. Um argumento tipado como Proof / SelfProof / DynamicProof / *Proof sobre o qual .verify() é chamado é restringido pelo circuito verificado — os achados de testemunha sobre ele (e o seu publicOutput / publicInput) são suprimidos. Um .verifyIf(flag) só é creditado quando a condição não é um argumento de método sem restrições, ou é ela própria asseverada. O mesmo se aplica ao wrapper canónico OffchainState this.offchainState.settle(proof) (o framework verifica dentro de settle). Um .settle(proof) feito à mão não é assumido como verificador. O caso inverso (argumento tipado como prova nunca verificado e não liquidado via OffchainState) é reportado como O1JS_UNVERIFIED_PROOF.
Bools asseverados / usados são ignorados. Um predicado encadeado com .assertTrue() / .assertFalse(), aninhado em Provable.if(...), ou atribuído a uma variável local que é posteriormente referenciada, não é reportado como O1JS_UNASSERTED_BOOL.
Remetentes autenticados são ignorados. this.sender.getUnconstrained() não dispara quando o mesmo @method também chama this.sender.getAndRequireSignature(), ou quando esse valor testemunhado é passado a AccountUpdate.createSigned(...) / autenticado via .requireSignature() num AccountUpdate construído a partir dele (é exigida identidade do argumento).
Comentários e literais de string são removidos antes da análise, pelo que um assert dentro de uma string não pode criar um resultado falso.

Regra	Severidade	O que significa
`NOIR_UNCONSTRAINED_WITNESS`	high	Um valor vinculado a partir de um bloco `unsafe { ... }` — o resultado de uma `unconstrained fn` (oráculo / dica Brillig) — que nunca é re-restringido por um `assert` / `assert_eq` (ou um helper de confirmação / verificação de merkle). A dica corre fora do circuito. Análogo de `O1JS_UNCONSTRAINED_PROVABLE_WITNESS`.
`NOIR_UNCONSTRAINED_INPUT`	medium	Uma entrada privada (testemunha) de `fn main` que não flui para nenhum `assert` / `assert_eq` e não faz parte da saída pública. Análogo de `O1JS_UNCONSTRAINED_WITNESS`.
`NOIR_UNCONSTRAINED_PUBLIC_INPUT`	medium	Uma entrada pública de `fn main` que não atinge nenhuma restrição nem nenhuma saída — o circuito nunca a lê. O dual da regra da testemunha privada: o verificador fornece o valor e acredita que a afirmação é sobre ele, enquanto o circuito o ignora (por exemplo, um `merkle_root: pub Field` que nunca é verificado, pelo que a pertença nunca foi realmente provada). MEDIUM porque uma entrada pública deliberadamente não usada é também um idioma legítimo para vincular uma prova a um contexto (nonce / chain id / destinatário), que é lexicalmente indistinguível — pelo que não faz o gate da CI no `--fail-on high` padrão.
`NOIR_UNCHECKED_CAST`	medium	Um valor controlado pelo provador convertido para um tipo unsigned estreito (`as u8`/`u16`/`u32`) com nenhuma asserção de intervalo. Análogo de `MissingRangeCheck` do o1js.
`NOIR_UNCONSTRAINED_ARRAY_INDEX`	medium	Um valor controlado pelo provador usado como índice de array (`arr[i]`) com nenhuma verificação de qualquer tipo sobre ele. A verificação implícita de limites do Noir estabelece apenas que o índice está dentro do intervalo — não que é o índice correto — pelo que o provador continua livre de selecionar qualquer elemento e ainda produzir uma prova que verifica. Este é o bug de liberdade de seletor por trás das posições de caminho de Merkle, seleção de notas e pertença a allow-list. Suprimido quando o índice tem limite de intervalo, é fixado por uma igualdade, é limitado antes de uma conversão (), ou quando o valor lido de volta é ele próprio fixado por um .

Como no exemplo o1js acima, `--include-examples` só é necessário porque
esses arquivos de demonstração ficam em `examples/`.

## Limitações conhecidas

O analisador é um **frontend lexical sem dependências mais uma camada semântica leve** que faz rastreamento de alias e propagação interprocedural através de helpers da mesma classe. Ele não é um frontend do compilador TypeScript, um verificador de tipos ou um motor de fluxo de dados de programa inteiro, e não há camada de SMT ou prova formal neste scanner.
Tenha esses pontos cegos em mente ao fazer a triagem — eles são conhecidos e intencionais
para este design sem dependências, não bugs:

- **Apenas aliases simples são seguidos.** O rastreamento de testemunhas segue aliases
  simples do mesmo método, como `const q = qty`, mas não expressões derivadas ou
  desestruturação:  ```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

A vinculação entre métodos cobre apenas cadeias de helpers da mesma classe. Um helper da mesma classe sem decorador, chamado como this.verifyX(arg), pode vincular o argumento de um chamador ao estado, e desde a 0.19.0 cadeias deles (@method → helper A → helper B) são seguidas até um ponto fixo. O passo helper→helper mapeia apenas uma referência de parâmetro simples, então helperA(x.add(1)) não se propaga. Funções livres e importadas ainda não são seguidas, e o aliasing de variável local do argumento do helper permanece uma limitação documentada.
A detecção de Bool não asseverado tem forma de instrução. O Tier A apenas sinaliza instruções de expressão simples cuja chamada mais externa é um predicado Bool sem nada encadeado depois. Predicados aninhados dentro de Provable.if(...), ou atribuídos e usados posteriormente, não são sinalizados. Usos complexos de fluxo de controle de um local Bool ainda podem passar despercebidos se o nome nunca for referenciado (modo de falha: omissão, não um falso positivo).
O gating por assinatura é em nível de método e baseado em substring. _method_is_signature_gated trata um @method inteiro como gated pelo proprietário se ele contiver um idioma de assinatura, e reconhece um verificador apenas quando o nome do receptor contém literalmente signature — então sig.verify(admin, msg) não é reconhecido como gating, enquanto uma verificação de assinatura não relacionada em outro lugar de um método grande pode suprimir em excesso. É tudo ou nada por método.
A autenticação do remetente é baseada em nome e apenas no mesmo método. O1JS_UNCONSTRAINED_SENDER suprime quando this.sender.getAndRequireSignature() ou AccountUpdate.createSigned(<that sender>) aparece no mesmo corpo do @method. Um requisito de assinatura que vive apenas em um helper (this.requireSenderSig() → getAndRequireSignature dentro) não é seguido — o modo de falha é um falso positivo em código correto que envolve o idioma, não um bug real perdido.
Helpers cross-crate do Noir são reconhecidos apenas por convenção de nome (sem resolução de Nargo.toml / import). Prefira omissão a falso positivo.

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

assert_eq

Backend	Regras	Capaz de High	Capaz de Medium	Capaz de Low
o1js	18	11	12	2
Noir	11	4	9	1
Total	29	15	21	3

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

o1js-scan

Mais Populares

or: pipx install o1js-scan

or: npm install -D o1js-scan

Suprimindo um achado revisado

Solução de Problemas

Problemas Comuns

Modo de Depuração

Aviso Legal

Licença

Agradecimentos

Aviso

Contato

GitHub Action

.github/workflows/o1js-scan.yml

O que deteta (o1js)

Regras suportadas num relance

Proteções contra falsos positivos (o1js)

O que deteta (Noir)

Proteções contra falsos positivos (Noir)

Onde esta ferramenta para

Privacidade e código privado

Revisão pós-quântica

Compatibilidade

Como funciona

Roadmap / contribuição