Un analizador estático rápido y sin dependencias para bugs de solidez en circuitos zk en:

• o1js / Mina zkApps (TypeScript .ts / .js) — circuitos Kimchi a partir de cuerpos @method
• Noir (.nr) — el DSL ZK de Aztec con sintaxis similar a Rust (incluyendo patrones con forma de aztec-nr)

Los bugs críticos para la seguridad normalmente no están en el sistema de pruebas — están en las restricciones propias de la aplicación: testigos que el probador controla pero que el circuito nunca vincula. o1js-scan es el escáner de señales sub-restringidas para los primos de Circom en los ecosistemas de Mina y Noir.```bash 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

--include-examples es necesario aquí solo porque el archivo de demostración se encuentra bajo examples/, que el clasificador de rutas degrada por defecto para que el código de ejemplo de un repositorio no pueda hacer fallar su compilación. El mismo contrato en tu src/ reporta HIGH sin ninguna bandera.

El hallazgo HIGH es el bug que permite drenar fondos. El contrato corregido (examples/safe_vault.ts) lo elimina y sale con 0, conservando solo el LOW informativo sobre el destinatario elegido por el probador:```console $ 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

Para una instalación global aislada de la CLI, use pipx:```bash pipx install o1js-scan

El paquete npm es un envoltorio ligero alrededor del mismo analizador de Python y requiere Python 3.8+ en el PATH (python3 o python). Establece O1JS_SCAN_PYTHON para elegir un intérprete específico.

O desde el código fuente:```bash git clone https://github.com/auditinfra-io/o1js-scan cd o1js-scan pip install -e .

El código de salida es 1 cuando hay un hallazgo igual o superior al nivel de --fail-on (por defecto high) y 0 en caso contrario, por lo que puedes integrarlo directamente en CI. Con el valor predeterminado, un hallazgo de severidad baja/media (incluida la regla informativa de destinatarios que se describe a continuación) no hace fallar la compilación; usa --fail-on none para solo informar, o --strict (una forma abreviada de --fail-on medium) para aplicar un filtro más estricto mientras sigues tratando los hallazgos de severidad baja como informativos. Las dos opciones son mutuamente excluyentes, por lo que la configuración de CI no puede ser ambigua. Una ruta de escaneo inexistente sale con 2 y un error en stderr, de modo que un error tipográfico no puede pasar silenciosamente por CI como una ejecución limpia. Cada ejecución imprime un resumen de una línea (recuentos por severidad y el veredicto del filtro) en stderr.

El código de prueba se excluye por defecto — en ambos backends. Las pruebas construyen deliberadamente valores inválidos y transacciones incorrectas para demostrar que las aserciones las rechazan, por lo que un hallazgo allí es el objetivo de la prueba y no un error del circuito. Un archivo cuenta como código de prueba cuando:

• su nombre coincide con *.test.ts / *.spec.ts (y las variantes .js/.jsx/.tsx/.mjs/.cjs), o *_test.nr / test_*.nr;
• se encuentra bajo un directorio test/, tests/, __tests__/, spec/ o __mocks__/;
• (solo Noir, basado en contenido) la función lleva un atributo #[test] / #[test(...)], o se encuentra dentro de un bloque mod test { … } / mod tests { … } — con alcance de bloque, por lo que un módulo de prueba al final de un archivo de producción no silencia el resto de este.

Pasa --include-tests para informarlos.

El código de ejemplo se degrada, no se descarta. Un hallazgo en un directorio examples/ o example/, o en un archivo llamado *.eg.ts (también .nr y las demás extensiones de JS/TS), se reduce a LOW con una nota — sigue informándose, pero ya no puede hacer fallar una compilación. El código de ejemplo se simplifica deliberadamente, y señalar los propios ejemplos de un framework como vulnerabilidades es ruido; pero se copia a producción con mucha más frecuencia que el código de prueba, por lo que se degrada en lugar de ocultarse. Pasa --include-examples para mantener la severidad original.

Siempre que se aplique cualquiera de las dos políticas, la ejecución imprime una línea en stderr indicándolo — p. ej. 6 file(s) skipped as test code, 1 finding(s) downgraded as examples — para que un escaneo silencioso nunca sea silenciosamente silencioso. Los recuentos también aparecen en SARIF bajo invocation.properties. Ten en cuenta la contrapartida: la detección es solo basada en rutas (sin análisis de describe(/it(), por lo que un circuito de producción almacenado bajo tests/ sí se omitirá — la línea de stderr es cómo te das cuenta.

Directorios omitidos al recorrer un árbol: node_modules, target (nargo), .git, dist, build, __pycache__, .venv, venv.

Suprimir un hallazgo revisado

Silencia un hallazgo que hayas triado sin relajar el filtro, con un comentario en línea sobre — o en la línea anterior a — la línea señalada:```ts this.send({ to, amount }); // o1js-scan-disable-line O1JS_UNCONSTRAINED_WITNESS

// o1js-scan-disable-next-line this.send({ to, amount });

Modules

Configuration

The configuration file is located at config/config.yaml. You can modify the following settings:

Disclaimer

This tool is intended for educational purposes and authorized security testing only. The author is not responsible for any misuse or damage caused by this tool. Always obtain proper authorization before testing any system.```nr let inv = unsafe { hint(x) }; // o1js-scan-disable-line NOIR_UNCONSTRAINED_WITNESS

GitHub Action

Añade el escáner a CI en unas pocas líneas. Los hallazgos aparecen como anotaciones en el diff del PR y como alertas en la pestaña Security → Code scanning del repositorio.```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

O sin la Acción:```bash pip install o1js-scan noir-scan . --lang noir --fail-on high --sarif noir.sarif

Entradas: path (por defecto .), lang (auto|o1js|noir, por defecto auto), version (versión de PyPI a instalar, por defecto la última), upload-sarif (por defecto true), fail-on (critical|high|medium|low|none, por defecto none), fail-on-findings (obsoleto, por defecto false), include-tests (por defecto false), include-examples (por defecto false). Salida: sarif-file. La carga de SARIF requiere security-events: write y el escaneo de código habilitado.

El informe y la compuerta se construyen a partir de un único arreglo de argumentos, por lo que include-tests e include-examples se aplican a ambos — el SARIF que lees y el código de salida sobre el que aplicas la compuerta siempre describen el mismo conjunto de fuentes. La pasada de informes se ejecuta con --fail-on none para que los hallazgos nunca bloqueen la carga de SARIF, pero un fallo operativo (una ruta que no existe, un error de uso de la CLI) aún hace fallar el paso en lugar de reportarse como un escaneo limpio.

fail-on-findings: true se mantiene por compatibilidad y se asigna a fail-on: high cuando fail-on se deja en none; emite una advertencia de obsolescencia. Prefiere fail-on, que puede aplicar la compuerta en cualquier severidad.

Qué detecta (o1js)

Reglas compatibles de un vistazo

Los recuentos son IDs de reglas distintos compatibles con cada backend. Una regla que asigna severidad según el contexto (por ejemplo, alta para una transferencia de valor y media para una escritura de estado) aparece en más de una columna de severidad, por lo que las columnas de severidad intencionalmente no suman el total de reglas. Actualmente no hay reglas de severidad crítica ni informativa. Las descripciones completas y las protecciones contra falsos positivos se detallan a continuación.

Protecciones contra falsos positivos (o1js)

El analizador está diseñado para mantenerse silencioso ante código correcto:

• Los métodos con compuerta de firma se omiten. Un @method que llama a this.requireSignature() (o getAndRequireSignature, AccountUpdate.createSigned, Signature.verify) tiene compuerta de propietario/administrador — sus argumentos son elegidos por el titular de la clave, no por un probador arbitrario — por lo que sus testigos no se marcan. Este es el equivalente en o1js de onlyOwner.
• Los testigos vinculados al estado se omiten. Un argumento aseverado igual a (o acotado por una comparación de orden contra) un valor derivado de getAndRequireEquals() es sólido y no se reportará. Esto cubre tanto la forma directa — amount.assertLessThanOrEqual(bal) — como la forma encadenada amount.lessThanOrEqual(bal).assertTrue(). La vinculación que reside en un helper no decorado de la misma clase (this.verifyX(arg)) también se reconoce, incluso a través de una cadena de tales helpers.
• Las pruebas verificadas se omiten. Un argumento tipado como Proof / SelfProof / DynamicProof / *Proof sobre el que se llama a .verify() está restringido por el circuito verificado — los hallazgos de testigos sobre él (y su publicOutput / publicInput) se suprimen. Un .verifyIf(flag) se acredita solo cuando la condición no es un argumento de método sin restringir, o ella misma está aseverada. Lo mismo se aplica al envoltorio canónico OffchainState this.offchainState.settle(proof) (el framework verifica dentro de settle). Un .settle(proof) hecho a mano no se asume que verifica. El caso inverso (argumento tipado como prueba nunca verificado y no liquidado por OffchainState) se reporta como O1JS_UNVERIFIED_PROOF.
• Los Bool aseverados / usados se omiten. Un predicado encadenado con .assertTrue() / .assertFalse(), anidado en Provable.if(...), o asignado a una variable local que luego se referencia, no se reporta como O1JS_UNASSERTED_BOOL.
• Los remitentes autenticados se omiten. this.sender.getUnconstrained() no se activa cuando el mismo @method también llama a this.sender.getAndRequireSignature(), o cuando ese valor testificado se pasa a AccountUpdate.createSigned(...) / se autentica mediante .requireSignature() en un AccountUpdate construido a partir de él (se requiere identidad del argumento).
• Los comentarios y literales de cadena se eliminan antes del análisis, por lo que un assert dentro de una cadena no puede crear un resultado falso.

Qué detecta (Noir)

La misma idea de solidez — testigos sub-restringidos — se aplica a Noir (circuitos .nr). Apunta el escáner a archivos .nr (o usa --lang noir) y los analiza con el conjunto de reglas de Noir. Mismo enfoque léxico, sin dependencias. Calibrado contra los modismos de oráculo / unsafe de aztec-nr — consulta docs/noir_calibration.md.

Protecciones contra falsos positivos (Noir)

• Los helpers de assert / salto de let / confirmación en el mismo archivo vinculan las pistas unsafe.
• Los nombres en el sitio de llamada constrain_* / confirm_* / verify_* / check_(non_)membership* / public_data_storage_read acreditan los argumentos (con detección de resultado no usado para verificaciones descartadas).
• Sin restringir intencional documentado (requiere // Safety: adyacente): random(), avm::…, y redacción diferida de kernel/rollup/discovery.
• let de tupla + flags aseverados vinculan testigos de merkle pasados a verificaciones de pertenencia.

Ejemplo:```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)

• El binding entre métodos cubre únicamente cadenas de helpers de la misma clase. Un helper sin decorar de la misma clase invocado como this.verifyX(arg) puede enlazar por estado el argumento de un llamador, y desde 0.19.0 las cadenas de estos (@method → helper A → helper B) se siguen hasta un punto fijo. El paso helper→helper mapea solo una referencia de parámetro desnuda, por lo que helperA(x.add(1)) no se propaga. Las funciones libres e importadas siguen sin seguirse, y el aliasing de variables locales del argumento del helper sigue siendo una limitación documentada.

• La detección de Bool no asertado tiene forma de sentencia. El Tier A solo marca sentencias de expresión desnudas cuya llamada más externa es un predicado Bool sin nada encadenado después. Los predicados anidados dentro de Provable.if(...), o asignados y usados posteriormente, no se marcan. Los usos complejos de flujo de control de un local Bool aún pueden pasarse por alto si el nombre nunca se referencia (modo de fallo: omisión, no un falso positivo).

• El signature-gating es a nivel de método y basado en subcadenas. _method_is_signature_gated trata un @method completo como owner-gated si contiene un idioma de firma, y reconoce un verificador solo cuando el nombre del receptor contiene literalmente signature — por lo que sig.verify(admin, msg) no se reconoce como gating, mientras que una comprobación de firma no relacionada en otro lugar de un método grande puede sobresuprimir. Es todo o nada por método.

• La autenticación del remitente se basa en el nombre y solo en el mismo método. O1JS_UNCONSTRAINED_SENDER suprime cuando this.sender.getAndRequireSignature() o AccountUpdate.createSigned(<that sender>) aparece en el mismo cuerpo de @method. Un requisito de firma que vive solo en un helper (this.requireSenderSig() → getAndRequireSignature dentro) no se sigue — el modo de fallo es un falso positivo en código correcto que envuelve el idioma, no un bug real omitido.

• Los helpers cross-crate de Noir se reconocen solo por convención de nombres (sin resolución de Nargo.toml / imports). Preferir omisión sobre falso positivo.

Estas son la razón por la que los hallazgos son un punto de partida para la revisión humana, no pruebas. Una reescritura consciente del flujo de datos está deliberadamente fuera del alcance del analizador léxico.

Dónde se detiene esta herramienta

o1js-scan es deliberadamente un paso léxico superficial de un solo archivo — sin parser, sin flujo de datos, sin solver. Eso es lo que lo hace libre de dependencias e instantáneo en CI, y también es un techo duro. Las limitaciones anteriores no son un backlog; son consecuencias del diseño.

Por lo tanto, vale la pena ser explícito sobre lo que esta herramienta puede y no puede decirte:

• Una ejecución limpia no es una auditoría. Significa que ninguna forma que este escáner reconoce coincidió — no que el circuito sea sólido. Las clases de bugs que necesitan flujo de datos, sensibilidad a rutas o resolución de restricciones están fuera del alcance de una herramienta de esta forma, en cualquier lenguaje.
• Un hallazgo es una pista, no un veredicto. Cada regla aquí es una heurística con una clase de falso positivo documentada.

Ese intercambio es el correcto para un linter que ejecutas en cada commit. Si estás trabajando en algo donde la diferencia importa — un protocolo que contiene valor real, un circuito que no puedes permitirte equivocar — trátalo como la primera pasada y presupuesta para una revisión real.

Para un análisis más profundo, el escáner completo separado se mantiene en el repositorio audit-engine-cli. o1js-scan es el escáner abierto intencionalmente ligero; el conocimiento de detección propietario y los detalles de implementación del escáner completo no se reproducen aquí. Para acceso o una revisión de circuito más completa, contacta: [email protected].

Privacidad y código privado

El CLI instalado analiza archivos localmente. No tiene telemetría, cliente de red, cuenta ni paso de subida, y su runtime de Python no tiene dependencias de terceros. Ejecutar o1js-scan path/to/private-repo no envía el código fuente ni los hallazgos a ningún lugar.

Como los logs del compilador, la salida del escáner puede contener rutas, identificadores y fragmentos de código fuente. SARIF también identifica ubicaciones exactas del repositorio, y la GitHub Action lo sube al code scanning de GitHub. Usa los mismos controles de acceso de repositorio y CI que ya usas para el código fuente que se está escaneando.

¿Quieres contribuir con un informe útil de falso positivo o detección omitida sin compartir una aplicación? Reproduce la sintaxis con nombres y constantes inventados, elimina la lógica de negocio una sentencia a la vez, y verifica que el fragmento sintético sigue disparando la misma regla antes de publicarlo. La guía de contribución segura para la privacidad tiene una checklist concreta y varias formas de ayudar a la comunidad o1js sin divulgar un circuito privado.

Este límite no impide que el escáner abierto mejore. La documentación pública de o1js y los repositorios pueden respaldar nuevas reglas y fixtures de compatibilidad; los ejemplos sintéticos pueden probar falsos positivos y restricciones omitidas; y la resiliencia del parser, los diagnósticos, SARIF, el rendimiento, el empaquetado y la calibración pueden mejorar sin publicar una técnica de auditoría privada o código de cliente. El escáner abierto debe hacer afirmaciones explicables de forma independiente; la investigación privada puede permanecer en el motor de auditoría separado.

Revisión post-cuántica

El riesgo cuántico está relacionado con la seguridad del circuito, pero no es una regla de restricción faltante. o1js-scan no determina si una firma, hash, commitment, el sistema de pruebas Kimchi o Mina mismo cumple un objetivo de seguridad post-cuántica. Esas respuestas dependen de la primitiva y los parámetros concretos, los supuestos de la plataforma, el tiempo de vida requerido del despliegue y su plan de migración — no meramente de un identificador de TypeScript que un escáner léxico puede ver.

Inspirado por Qubit or Not Qubit de O(1) Labs, la guía de revisión post-cuántica convierte ese límite en un inventario específico de o1js y una checklist de agilidad criptográfica. Úsala junto con este escáner en lugar de interpretar un escaneo limpio como una evaluación post-cuántica.

Compatibilidad

Funciona en o1js 1.x, 2.x y 3.x, incluido el hard fork Mesa al que apunta o1js 3.0.0. o1js-scan analiza el código fuente de TypeScript como texto y no tiene dependencia en tiempo de ejecución de o1js — nada está fijado a una versión. Se basa en la API moderna de precondiciones require* (getAndRequireEquals, requireEquals, requireSignature, getAndRequireSignature), los decoradores @method / @method() / @method.returns(...), los campos @state anotados, this.send({...}), las transferencias de bajo nivel AccountUpdate.balance.subInPlace(...) y Permissions.*. Las formas establecidas siguen siendo compatibles a través de los límites 1.x → 2.x → 3.x, mientras que el escáner también acepta las variantes de decorador y transferencia de bajo nivel recientemente documentadas. El idioma de autenticación de propietario de 2.x this.sender.getAndRequireSignature() se reconoce como signature-gating. (Las precondiciones heredadas assertEquals todavía se aceptan, así que el código más antiguo tampoco se rompe.)

Los cambios disruptivos de Mesa son todos a nivel de runtime y protocolo — la eliminación de Transaction.setFeePerSnarkCost() y las constantes TransactionCost.*, la nueva forma de VerificationKey.toJSON(), las claves de verificación regeneradas, MAX_ZKAPP_STATE_FIELDS elevado de 8 a 32, y el formato de transacción de mina-signer v4. Ninguno de ellos renombra una API que este escáner detecte, por lo que ninguna regla cambió para Mesa, y eso está verificado en lugar de afirmado. scripts/o1js_release_matrix.sh escanea dos releases de o1js fijados que abarcan el límite del protocolo — 2.15.0 (9620ef08, el último release de 2.x) y 3.0.0 (cc18a919, Mesa) — y compara cada hallazgo contra tests/fixtures/o1js_release_matrix.json:

33 hallazgos son idénticos a través del límite, ninguno se perdió, y los tres nuevos están en src/examples/zkapps/big-state-zkapp.ts — el ejemplo de 32 campos de estado que existe solo porque Mesa elevó MAX_ZKAPP_STATE_FIELDS. Ese delta está fijado por un test, por lo que no puede desviarse silenciosamente. La matriz se ejecuta en cada build de CI; el job semanal o1js-upstream-canary además rastrea o1js en HEAD, por delante de cualquier release.

Las grafías equivalentes de restricciones se normalizan para el análisis: instancia assertEquals(...), estático Provable.assertEqual(Type, ...), y cadenas de igualdad equals(...).assertTrue() todas enlazan los mismos operandos. La extracción de métodos está balanceada por llaves tras el enmascaramiento de comentarios y cadenas que preserva la longitud, y acepta decoradores multilínea, tipos de parámetros con forma de callback anidados, modificadores de acceso de TypeScript y alias de identidad multilínea (incluyendo formas entre paréntesis y as Type).

El análisis de Noir apunta a la sintaxis de Noir usada por proyectos Aztec / nargo (.nr); no invoca nargo ni compila circuitos.

Cómo funciona

Es un analizador léxico, no un parser completo de TypeScript o Noir — las fuentes de o1js y Noir están delimitadas por llaves y son tratables con regex, y la salida está pensada para ser triada por un humano. Eso lo mantiene libre de dependencias e instantáneo de ejecutar en CI. Los hallazgos son un punto de partida para la revisión, no pruebas.

Roadmap / contribuir

Contribuciones bienvenidas — nuevas familias de reglas, más guardas de FP y arquetipos de calibración del mundo real son todos valiosos. Consulta CONTRIBUTING.md.

Para una ruta propuesta desde el listado de Community Packages hasta una comprobación de aviso en el repositorio de o1js, consulta la propuesta de integración upstream de o1js lista para enviar.

Ejecuta los tests y el linter con:```bash pip install -e ".[dev]" pytest # unit tests + Noir/o1js corpus ruff check . # lint npm run format:check # prettier, npm wrapper only