deepsec

deepsec es un escáner de vulnerabilidades impulsado por agentes que puedes ejecutar en tu propia infraestructura, optimizado para realizar revisiones bajo demanda de todo el código en repositorios a gran escala existentes.

deepsec está diseñado para sacar a la luz problemas difíciles de encontrar que han estado ocultos en las aplicaciones durante mucho tiempo. Está configurado para usar los mejores modelos con los niveles máximos de razonamiento (ajustable mediante --thinking-level, consulta docs/models.md), lo que significa que los escaneos pueden costar miles o incluso decenas de miles de dólares para bases de código grandes. Nuestros clientes han considerado que el costo vale la pena por la rapidez con la que pudieron parchear vulnerabilidades que de otro modo habrían quedado sin corregir.

Para bases de código grandes, el trabajo se distribuye en paralelo entre máquinas worker. Si una ejecución se interrumpe o falla a mitad de camino, solo vuelve a ejecutar el mismo comando: deepsec retoma donde lo dejó, omitiendo los archivos que ya analizó e investigando solo el resto.

Primeros pasos

Navega a la raíz del repositorio que quieres escanear y luego:

npx deepsec init       # creates .deepsec/ with this repo as the first project
cd .deepsec
pnpm install           # installs deepsec from npm

# Proceed as instructed by `init` output

Ahora haz que tu agente de codificación arranque tu instalación. Abre el agente que elijas y dale el prompt:

Lee .deepsec/node_modules/deepsec/SKILL.md para entender la herramienta. Luego lee .deepsec/data/<id>/SETUP.md y síguelo: repasa el README de este repositorio, cualquier AGENTS.md/CLAUDE.md y un puñado de archivos de código representativos, y luego reemplaza cada sección de .deepsec/data/<id>/INFO.md.

Mantenlo CORTO: apunta a un total de 50–100 líneas. Elige de 3 a 5 ejemplos por sección, no una enumeración exhaustiva. Nombra primitivas (helpers de autenticación, middleware) pero sin números de línea. Omite las categorías CWE genéricas — los matchers integrados ya las cubren. Cubre solo lo específico del proyecto. INFO.md se inyecta en cada lote de escaneo; el contexto verboso diluye la señal.

Luego escanea desde dentro de .deepsec/:

pnpm deepsec scan
pnpm deepsec process    
pnpm deepsec revalidate # optional, cuts FP rate
pnpm deepsec export --format md-dir --out ./findings

Si sientes que deepsec debería revisar más partes del código, pásale el documento de escritura de matchers para encontrar puntos de partida más valiosos en tu base de código.

Documentación

• docs/getting-started.md — tutorial para el primer escaneo
• docs/reviewing-changes.md — process --diff para revisión de PR y control en CI
• docs/supported-tech.md — frameworks y ecosistemas que deepsec reconoce de serie
• docs/writing-matchers.md — pide a tu agente de codificación que amplíe tu conjunto de matchers
• docs/configuration.md — referencia de deepsec.config.ts
• docs/plugins.md — creación de plugins
• docs/models.md — selección de modelos, valores predeterminados, rechazos, modelos futuros
• docs/vercel-setup.md — claves / tokens de AI Gateway + Vercel Sandbox
• docs/architecture.md — detalles internos del pipeline
• docs/data-layout.md — esquemas de data/ (FileRecord, RunMeta, …)
• docs/faq.md — coste, elección de modelo, modo sandbox, tasa de FP
• samples/ — puntos de partida listos para copiar y pegar (actualmente: webapp/)
• CONTRIBUTING.md — estructura del repositorio, flujo de trabajo de desarrollo

Proveedor de IA

Cuando se ejecuta localmente, deepsec usa como alternativa tu suscripción existente de claude / codex si has iniciado sesión en esta máquina. Las suscripciones (Claude Pro/Max, ChatGPT Plus) son útiles para evaluar deepsec, pero por lo general no tienen suficiente margen para escaneos completos de repositorios.

Para escaneos reales, usa Vercel AI Gateway. Una sola clave cubre tanto Claude como Codex, y las cuotas predeterminadas de la puerta de enlace están dimensionadas para investigación altamente concurrente.

AI_GATEWAY_API_KEY=vck_...

Consulta docs/vercel-setup.md para obtener una clave y para la configuración de Vercel Sandbox. Para omitir la puerta de enlace, establece explícitamente ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL (o el par de OpenAI). Los valores explícitos siempre tienen prioridad sobre la expansión de AI_GATEWAY_API_KEY.

Si una ejecución de process o revalidate se detiene porque la credencial upstream agotó su cuota o créditos, deepsec se detiene correctamente y te indica dónde recargar. Vuelve a ejecutar el mismo comando después y retomará donde se quedó.

Ejecución distribuida (opcional)

Los monorepos grandes pueden distribuir el trabajo entre microVMs de Vercel Sandbox:

pnpm deepsec sandbox process --project-id my-app --sandboxes 10 --concurrency 4

Requiere una cuenta de Vercel. El árbol de trabajo local se empaqueta en un tarball y se sube; .git queda excluido. Se admiten tanto tokens OIDC (local) como tokens de acceso (CI); consulta docs/vercel-setup.md.

Modelo de seguridad del propio deepsec

Trata a deepsec como a un agente de codificación con acceso completo al shell en el entorno donde se ejecuta. Está diseñado para ejecutarse sobre entradas confiables (tu código fuente), pero quizás aún te preocupe la inyección de prompts debido a dependencias externas o código vendored.

Ejecutarlo en un sandbox (ver arriba) limita sustancialmente la exposición potencial:

• Las claves de API de los agentes de codificación se inyectan fuera del sandbox y, por lo tanto, no pueden ser exfiltradas
• En los sandboxes de worker, el tráfico de salida de red del sandbox está limitado a los hosts de los agentes de codificación (la salida está permitida durante el proceso de arranque, pero este no ejecuta al agente de codificación)

Referencia de flujos de trabajo