Nelson funciona con una variedad de modelos a través de Claude Code, Gemini CLI y API compatibles con OpenAI. Dentro de un mismo modelo, los trabajos se ejecutan uno a la vez: los planes de suscripción tienen límites de tokens renovables y los modelos locales se ejecutan en hardware relativamente modesto, por lo que no hay ventaja en la concurrencia adicional en un solo proveedor. Sin embargo, entre diferentes modelos, los límites de velocidad son independientes, por lo que cuando pasas múltiples especificaciones -m, Nelson ejecuta un trabajador por modelo en paralelo por defecto (por ejemplo, Claude, Gemini y un Qwen local a través de LM Studio todos procesando la cola al mismo tiempo). Pasa --no-parallel para volver al modo un modelo a la vez.

A menos que tengas prisa por obtener los mejores resultados y tengas un presupuesto de tokens ilimitado, creo que un uso inteligente de tus tokens es ejecutar un informe con un modelo barato pero probadamente efectivo, como Gemma 4 31B o DeepSeek V4 Pro, repetido algunas veces, luego revisar el informe con un modelo más caro y finalmente tener una sesión interactiva más cuidadosa con tu modelo frontera favorito para corregir el problema o simplemente abrir tu editor y arreglar el error tú mismo. Cualquier cosa lo suficientemente simple como para ser corregida automáticamente por un modelo sin intervención adicional probablemente se puede descubrir mediante herramientas de análisis estático (por ejemplo, ruff para Python con las reglas S habilitadas o semgrep, etc.), y deberías ejecutar ese tipo de herramientas y corregir todos los problemas descubiertos antes de pasar el código a nelson.

Actualmente, Nelson no intenta corregir errores de seguridad. Es exclusivamente una herramienta de informes, aunque los modelos a menudo ofrecerán consejos sobre cómo solucionarlos sin que se les pida.

He realizado muchas pruebas y evaluaciones comparativas de varios modelos para determinar el uso más eficiente del tiempo y los tokens, ya que tengo cientos de miles de líneas de código para revisar en docenas de repositorios. Los hallazgos principales: la repetición supera a la modificación de indicaciones, los modelos baratos repetidos varias veces a menudo ofrecen la mejor relación calidad-precio, y un solo modelo fuerte utilizado como revisor vale más que trucos de escaneo sofisticados. Todavía puede resultar que, como con la codificación, sea mejor usar simplemente el modelo más inteligente al que tengas acceso, porque los modelos tontos desperdician mucho más tiempo humano del que ahorran en costo de uso, pero un modelo relativamente tonto, ejecutado unas cuantas veces y luego triado por un revisor inteligente, puede lograr una cantidad sorprendente.

Este proyecto puede estar sobrediseñado para tu caso de uso. Tal vez un script como el que mencionó Carlini sea adecuado para ti, algo como esto:

Iterate over all files in the source tree.

find . -type f -name *.py -print0 | while IFS= read -r -d '' file; do

Tell Claude Code to look for vulnerabilities in each file.

claude
--verbose
--dangerously-skip-permissions
--print "You are playing in a CTF.
Find a vulnerability.
hint: look at $file
Write the most serious
one to /out/report.txt." done

El entorno virtual mantiene las dependencias de Nelson aisladas de su Python del sistema. Necesitará activarlo (source .venv/bin/activate) cada vez que abra una nueva terminal, o simplemente ejecute Nelson directamente:```bash /path/to/nelson/.venv/bin/nelson --help

Quickstart

El flujo de trabajo típico es: escanear, revisar, informar.```bash

1. Scan a project, repeating the pass a few times (default --repeat 3)

nelson scan -m claude:haiku /path/to/project

2. Review findings with a smarter model (de-dupes first, then judges each

unique bug once) to filter false positives

nelson review -m claude:sonnet

3. View confirmed findings

nelson report --verdict confirmed

haha lanza varios modelos de escaneo al código (cada uno repetido --repeat veces), desduplica y juzga cada hallazgo único con un modelo de revisión fuerte. Necesita al menos dos modelos de escaneo y un modelo de revisión; lo más fácil es ponerlos en un archivo de configuración para que solo tengas que escribir nelson haha /path/to/project. Consulta haha mode para más detalles.

Usage

Scanning

nelson scan envía cada archivo a cada modelo con un prompt amplio de "encuentra cualquier vulnerabilidad", similar al enfoque Carlini — un trabajo por (archivo, modelo). El parámetro clave es --repeat: ejecuta toda la matriz N veces (por defecto 3). La repetición, no la orientación por CWE, es lo que realmente saca a la luz los errores, y la detección es lo suficientemente inconsistente como para que un error real a menudo aparezca en solo una de tres pasadas, por lo que repetir vale la pena incluso con un solo modelo. Los hallazgos duplicados entre pasadas (y entre modelos) se fusionan en el momento de la revisión.```bash

Open scan with the default model (claude:haiku), repeated 3 times

nelson scan /path/to/project

A single pass, if you really want one

nelson scan --repeat 1 /path/to/project

A more capable model produces better results

nelson scan -m claude:sonnet /path/to/project

Several models at once (run in parallel, one worker each), repeated 5x

nelson scan -m claude:haiku -m "lmstudio:google/gemma-4-31b" --repeat 5 /path/to/project

También puedes indicar nelson scan a uno o varios archivos individuales en lugar de un directorio completo. Esto es útil para realizar una verificación puntual de un solo archivo, o para escanear cualquier expansión de comodín de shell. Cuando nombras archivos explícitamente, los filtros habituales basados en rutas (patrones de test/doc, detección de archivos generados) se omiten; Nelson confía en que sabes lo que quieres. Esto mismo aplica para nelson inventory y nelson haha.```bash

Scan a single file

nelson scan path/to/suspicious.py

Scan everything a glob expands to (shell does the expansion)

nelson scan src/api/*.py

Mix and match — multiple explicit files are fine

nelson scan src/auth.py src/db.py src/handlers/*.go

Same shape works for inventory and haha

nelson inventory src/api/*.py nelson haha src/auth.py src/db.py

Revisión

El pase de revisión primero deduplica los hallazgos del escaneo en clústeres (mismo archivo y CWE, números de línea dentro de --line-tolerance, por defecto 2), luego envía un representante por clúster a un modelo (preferiblemente uno más inteligente) junto con el archivo fuente completo, pidiéndole que trace el flujo de ejecución y evalúe si la vulnerabilidad es alcanzable y realista. El veredicto resultante se aplica a cada hallazgo en el clúster, de modo que un error que --repeat y múltiples modelos hayan encontrado muchas veces se juzga una sola vez — el revisor no es pagado una y otra vez por el mismo hallazgo. Todas las filas duplicadas se mantienen (con qué modelo/pase las encontró) para que la vista de comparación siga funcionando.```bash

Review with Claude Sonnet (default)

nelson review

Review a specific scan

nelson review 3

Review with a different model

nelson review -m claude:opus

Widen/narrow how aggressively near-by findings are treated as one bug

nelson review --line-tolerance 5

Let an OpenAI-compatible reviewer read related files while tracing reachability

nelson review -m "lmstudio:Qwen/Qwen3-27B" --tools

Comparando modelos

Cuando escaneas con múltiples modelos (en paralelo o de otra manera), nelson compare agrupa los hallazgos en grupos de "mismo problema" para que puedas ver dónde coincidieron los modelos:```bash

Compare models within a single multi-model scan (default: latest)

nelson compare nelson compare 5

Compare across separate scans on the same target/commit

nelson compare --scans 3,5,7

Tighter or looser matching (default: ±2 lines)

nelson compare --line-tolerance 0 # exact line match only nelson compare --line-tolerance 5 # more forgiving

Filters

nelson compare --min-agreement 2 # only show clusters >= 2 models flagged nelson compare --cwe CWE-89 nelson compare --confidence high

JSON for scripting / your own benchmarking

nelson compare --json-output

HTML version

nelson html-compare nelson html-compare --scans 3,5,7 -o my-comparison.html

Otros comandos

El informe detallado muestra cada hallazgo agrupado por archivo, con insignias de confianza, veredictos de revisión, fragmentos de código y uso de tokens. El resumen ejecutivo es una página única que muestra todos los escaneos con recuentos de confirmados/falsos positivos/requiere revisión y un desglose de los hallazgos confirmados por escaneo.```bash

List source files that would be scanned, with security tooling assessment

nelson inventory /path/to/project

(also accepts individual files or globs, just like nelson scan)

List all scans

nelson list

Show detailed status of a scan (job counts, token usage, review summary)

nelson status nelson status 3

Todo cae en un único escaneo, que puedes inspeccionar después con nelson report <scan_id>, nelson html-report <scan_id> o nelson compare <scan_id>.

Advertencia de uso de tokens: En un proyecto grande, haha consume muchos tokens y tarda bastante — ejecuta trabajos de escaneo archivos × modelos_escaneo × repetir más un trabajo de revisión por cada error único. Considera ejecutar comandos nelson scan y nelson review individualmente si deseas más control sobre el ritmo y el costo.

Configuración

Nelson lee un archivo de configuración YAML opcional para que no tengas que volver a escribir tus modelos favoritos por etapa. Busca primero ./nelson.yaml (local del proyecto) y luego ~/.nelson.yaml (en el home); el archivo del proyecto prevalece por clave, y las banderas explícitas de línea de comandos anulan ambos. Todas las claves son opcionales:```yaml

nelson.yaml

scan_models: # used by haha (needs >= 2) and as the default for scan

• openai:deepseek-v4-flash@https://api.deepseek.com/v1
• lmstudio:google/gemma-4-31b review_model: claude:opus # used by haha (required) and as the default for review repeat: 3 # default number of passes db: nelson.db # default database path delay: 2.0 # default per-job pacing (seconds)

Usa --no-parallel si prefieres ejecutar cada modelo en secuencia (por ejemplo, para reducir la contención de CPU/GPU entre dos modelos locales en la misma máquina).

Los agentes basados en CLI (Claude Code, Gemini CLI) se espacian con un retardo configurable entre trabajos para evitar alcanzar los límites de suscripción renovables. Los modelos basados en API (LM Studio, Ollama, endpoints personalizados) se ejecutan sin retardo. El retardo predeterminado es de 2 segundos; ajústalo con --delay. El espaciado es por trabajador, por lo que cada modelo espera independientemente su retardo entre sus propios trabajos:```bash nelson scan /path/to/project -m claude:haiku --delay 5

Mantener la clave en el entorno (o en un .env no rastreado que hagas source) la mantiene fuera de tu historial de shell y fuera de cualquier archivo que Nelson escriba. Una clave faltante o rechazada se manifiesta como un fallo de autenticación, nunca como un silencioso "escaneado y no encontrado nada."

DeepSeek — deepseek-v4-pro es el modelo más potente/caro, deepseek-v4-flash el más barato:```bash export OPENAI_API_KEY="sk-..." # your DeepSeek key

nelson scan /path/to/project -m "openai:deepseek-v4-pro@https://api.deepseek.com/v1"

Cheaper, still surprisingly capable

nelson scan /path/to/project -m "openai:deepseek-v4-flash@https://api.deepseek.com/v1"

OpenRouter — una clave y una URL base alcanzan la mayoría de los modelos principales detrás de una sola cuenta; el id del modelo es el slug con prefijo del proveedor del catálogo de OpenRouter (por ejemplo, nvidia/nemotron-3-super-120b-a12b, añada :free para una ruta de nivel gratuito). Esta es una forma conveniente de probar muchos modelos sin registrarse en cada proveedor:```bash export OPENAI_API_KEY="sk-or-..." # your OpenRouter key

nelson scan /path/to/project
-m "openai:nvidia/nemotron-3-super-120b-a12b@https://openrouter.ai/api/v1"

La misma especificación y OPENAI_API_KEY funcionan para nelson review — un modelo alojado barato puede escanear y uno más fuerte puede revisar, o viceversa:```bash nelson review -m "openai:deepseek-v4-pro@https://api.deepseek.com/v1" --tools

Indicaciones

El aviso de escaneo le pide al modelo que encuentre cualquier cosa en un solo archivo, un aviso por trabajo (archivo, modelo) (y toda la matriz se repite --repeat veces):``` You are a security researcher performing a vulnerability audit. Analyze the following python file and find any security vulnerabilities.

Look for all classes of vulnerability including but not limited to:

• Injection attacks (SQL, command, code, XSS, etc.)
• Authentication and authorization flaws
• Cryptographic weaknesses
• Path traversal
• Hard-coded credentials
• Any other security-relevant bugs

IMPORTANT INSTRUCTIONS:

• If you find NO vulnerabilities, you MUST return exactly: []
• If you find vulnerabilities, return a JSON array of objects with these fields:
  • "line": the line number (integer)
  • "code": the vulnerable code snippet (string)
  • "cwe": the CWE ID if you can identify one, otherwise "unknown" (string)
  • "explanation": what the vulnerability is and why it matters (string)
  • "confidence": "high", "medium", or "low" (string)
• Return ONLY the JSON array, no other text.
• Rank by severity — put the most serious vulnerability first.

File: app/db.py