deepsec

deepsec é um scanner de vulnerabilidades alimentado por agentes que você pode executar em sua própria infraestrutura, otimizado para realizar revisão sob demanda de todo o código em repositórios de grande escala existentes.

deepsec foi projetado para revelar problemas difíceis de encontrar que estão escondidos em aplicações há muito tempo. Ele é configurado para usar os melhores modelos nos níveis máximos de raciocínio (ajustável via --thinking-level, veja docs/models.md), o que significa que as varreduras podem custar milhares ou até dezenas de milhares de dólares para bases de código grandes. Nossos clientes consideraram o custo válido pela rapidez com que conseguiram corrigir vulnerabilidades que, de outra forma, permaneceriam sem correção.

Para bases de código grandes, o trabalho é distribuído em paralelo entre máquinas worker. Se uma execução for interrompida ou falhar no meio do caminho, basta executar novamente o mesmo comando — o deepsec retoma de onde parou, pulando arquivos já analisados e investigando apenas o restante.

Primeiros passos

Navegue até a raiz do repositório que deseja escanear, então:

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

Agora, peça ao seu agente de codificação para inicializar sua instalação. Abra o agente de sua escolha e solicite:

Leia .deepsec/node_modules/deepsec/SKILL.md para entender a ferramenta. Depois leia .deepsec/data/<id>/SETUP.md e siga-o: percorra rapidamente o README deste repositório, quaisquer AGENTS.md/CLAUDE.md e um punhado de arquivos de código representativos, então substitua cada seção de .deepsec/data/<id>/INFO.md.

Mantenha CURTO — mire 50–100 linhas no total. Escolha 3–5 exemplos por seção, não uma enumeração exaustiva. Nomeie primitivas (auxiliares de autenticação, middleware) mas sem números de linha. Pule categorias CWE genéricas — os matchers internos cobrem isso. Cubra apenas o que é específico do projeto. INFO.md é injetado em cada lote de varredura; contexto verboso dilui o sinal.

Então escaneie de dentro de .deepsec/:

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

Se você achar que o deepsec deve examinar mais partes do código, forneça a ele o documento writing matchers para encontrar pontos de partida mais valiosos em sua base de código.

Documentação

• docs/getting-started.md — passo a passo da primeira varredura
• docs/reviewing-changes.md — process --diff para revisão de PR e CI gating
• docs/supported-tech.md — frameworks e ecossistemas que o deepsec reconhece de fábrica
• docs/writing-matchers.md — instrua seu agente de codificação a expandir seu conjunto de matchers
• docs/configuration.md — referência do deepsec.config.ts
• docs/plugins.md — criação de plugins
• docs/models.md — seleção de modelos, padrões, recusas, modelos futuros
• docs/vercel-setup.md — chaves/tokens do AI Gateway e Vercel Sandbox
• docs/architecture.md — internos do pipeline
• docs/data-layout.md — esquemas de data/ (FileRecord, RunMeta, …)
• docs/faq.md — custo, escolha de modelo, modo sandbox, taxa de FP
• samples/ — pontos de partida copiáveis (atualmente: webapp/)

Provedor de IA

Ao executar localmente, o deepsec recorre à sua assinatura existente de claude / codex se você estiver logado nesta máquina. Assinaturas (Claude Pro/Max, ChatGPT Plus) são úteis para avaliar o deepsec, mas geralmente não têm capacidade suficiente para varreduras completas de repositórios.

Para varreduras reais, use o Vercel AI Gateway. Uma única chave cobre tanto Claude quanto Codex, e as cotas padrão do gateway são dimensionadas para pesquisa altamente concorrente.

AI_GATEWAY_API_KEY=vck_...

Veja docs/vercel-setup.md para obter uma chave e para a configuração do Vercel Sandbox. Para bypassar o gateway, defina ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL (ou o par OpenAI) explicitamente. Valores explícitos sempre prevalecem sobre a expansão de AI_GATEWAY_API_KEY.

Se uma execução de process ou revalidate parar porque a credencial upstream ficou sem cota ou créditos, o deepsec para de forma graciosa e informa onde recarregar. Execute novamente o mesmo comando depois e ele retoma de onde parou.

Execução distribuída (opcional)

Monorepos grandes podem distribuir trabalho entre microVMs do Vercel Sandbox:

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

Requer uma conta Vercel. A árvore de trabalho local é compactada em tar e enviada; .git é excluído. Ambos tokens OIDC (local) e tokens de acesso (CI) são suportados — veja docs/vercel-setup.md.

Modelo de segurança do próprio deepsec

Trate o deepsec como um agente de codificação com acesso total ao shell no ambiente em que está sendo executado. Ele foi projetado para ser executado em entradas confiáveis (seu código fonte), mas você ainda pode estar preocupado com injeção de prompt devido a dependências externas ou código fornecido.

Executar em um sandbox (veja acima) limita substancialmente a exposição potencial:

• As chaves de API para os agentes de codificação são injetadas fora do sandbox e, portanto, não podem ser exfiltradas
• Para os sandboxes worker, a saída de rede do sandbox é limitada aos hosts dos agentes de codificação (a saída é permitida durante o processo de inicialização, mas isso não executa o agente de codificação)

Referência do fluxo de trabalho

Licença

Apache 2.0. Veja LICENSE e NOTICE.