Prefere HTTP puro? Acesse a API diretamente com curl:```bash
curl -X POST http://localhost:8080/api/v1/execute/async/sec-af.audit \
  -H "Content-Type: application/json" \
  -d '{"input": {"repo_url": "https://github.com/dolevf/Damn-Vulnerable-GraphQL-Application"}}'

Cada descoberta inclui um **veredito** (`confirmed` / `likely` / `inconclusive` / `not_exploitable`), um **objeto de prova** com o rastreamento completo de contaminação (taint trace) e a localização exata do código. Não é "isso pode ser um problema." SEC-AF rastreia dados da origem ao destino (source to sink) e comprova se é realmente explorável.

> Saída completa do benchmark (30 descobertas): [`exampl/dvga-benchmark-result.json`](https://github.com/agent-field/sec-af/blob/HEAD/exampl/dvga-benchmark-result.json) | Análise de desempenho: [`exampl/benchmark-analysis.json`](https://github.com/agent-field/sec-af/blob/HEAD/exampl/benchmark-analysis.json)

## Benchmark: DVGA

Executamos o SEC-AF contra a [Damn Vulnerable GraphQL Application](https://github.com/dolevf/Damn-Vulnerable-GraphQL-Application), um aplicativo deliberadamente vulnerável com 21 cenários de segurança documentados.

| Métrica | Valor |
|---|---|
| Descobertas brutas encontradas | 106 |
| Após deduplicação por IA | 61 |
| **Após verificação adversarial** | **28 confirmados** |
| Inconclusivo (necessita revisão manual) | 1 |
| Não explorável (corretamente rejeitado) | 1 |
| Redução de ruído | 94% |
| Arestas do DAG (chamadas de reasoner) | 82 |
| Chamadas de agente | ~166–255 |
| Estratégias executadas | 11 |
| Tempo real (wall-clock) | ~78 min |
| Custo estimado (Kimi K2.5) | ~$0.18–$0.90 |

<details>
<summary><strong>Detalhamento: 30 descobertas verificadas por categoria</strong></summary>

| Categoria | Contagem | Exemplos |
|---|---|---|
| Autenticação ausente | 8 | ImportPaste, delete_all_pastes, system_debug, CreateUser, upload de arquivo |
| Injeção de comando | 4 | `os.popen(cmd)` via ImportPaste, system_debug, system_diagnostics |
| Injeção SQL | 3 | `filter` não sanitizado em `resolve_pastes`, injeção de padrão LIKE, login |
| Bypass de autenticação | 3 | Assinatura JWT desabilitada, bypass de autorização JWT, autenticação de senha quebrada |
| Credenciais em texto plano | 3 | Armazenamento de senha em texto claro, comparação em texto plano, senha em diagnósticos |
| SSRF | 2 | Mutação ImportPaste segue URLs fornecidas pelo usuário no lado do servidor |
| Lógica de negócios / Sanitização de URL | 2 | Sanitização inadequada de URL, exclusão em massa não autenticada |
| DoS / Exaustão de recursos | 3 | Falta de paginação em consultas de usuários/auditorias, simulate_load descontrolado |
| Configuração / Segredos | 2 | Segredos JWT/Flask codificados, modo debug ativado em produção |

</details>

<details>
<summary><strong>Padrões de design: como a análise de segurança nativa em IA funciona</strong></summary>

O SEC-AF aplica vários padrões arquiteturais que são exclusivamente possibilitados pela composição de muitos agentes de IA focados em vez de executar uma varredura monolítica. Esses padrões abordam desafios fundamentais na análise de segurança orientada por IA.

**1. Tensão adversarial de agentes (HUNT vs. PROVE)**

A maioria das ferramentas de segurança com IA pergunta a um único modelo "isso é vulnerável?" e aceita a resposta. O SEC-AF separa estruturalmente os agentes de _descoberta_ dos agentes de _refutação_. Os caçadores (hunters) são incentivados a encontrar vulnerabilidades; os provadores (provers) são incentivados a refutá-las. Cada descoberta passa por uma cadeia de verificação de 4 agentes — um rastreador (tracer) reconstrói o fluxo de dados, um analisador de sanitização procura mitigações que o caçador pode ter perdido, um hipotetizador de exploit constrói um cenário de ataque concreto, e um agente de veredito pondera todas as evidências conflitantes. Essa tensão adversarial entre agentes é o que impulsiona a redução de ruído de 94% — a própria arquitetura codifica o ceticismo.

**2. Cascata de sinal com estreitamento progressivo**

Em vez de despejar todas as descobertas no usuário, o pipeline comprime o sinal em cada estágio: 106 descobertas brutas → 61 após deduplicação por IA → 30 após verificação adversarial. Cada fase é um filtro. Isso espelha como as equipes de segurança humanas realizam a triagem — descoberta ampla primeiro, depois escrutínio progressivamente mais rigoroso. A principal percepção é que cada filtro é um _tipo diferente_ de raciocínio de IA: similaridade semântica para deduplicação, análise de contaminação (taint analysis) para verificação, construção de exploit para confirmação.

**3. Economia de informação via poda de contexto**

LLMs alucinam mais quando recebem contexto irrelevante. O SEC-AF roteia apenas as informações que cada agente precisa: um caçador de injeção recebe o contexto de reconhecimento podado para mapas de fluxo de dados e pontos de entrada de entrada, enquanto um caçador de criptografia recebe árvores de dependência e padrões de gerenciamento de chaves. Os verificadores recebem visões projetadas das descobertas com apenas os campos necessários para seu método de verificação específico. Essa poda de contexto por estratégia reduz tanto a alucinação quanto o custo — os agentes não podem se confundir com informações que nunca veem.

**4. Sobreposição de fases em streaming**

Pipelines tradicionais são executados sequencialmente: terminam o reconhecimento, depois começam a caça, depois começam a prova. O SEC-AF sobrepõe fases via `asyncio.Queue` — os caçadores começam a consumir a saída do reconhecimento à medida que chega, e a deduplicação processa as descobertas à medida que cada caçador termina. Os provadores começam a verificar as primeiras descobertas deduplicadas enquanto caçadores posteriores ainda estão em execução. Essa arquitetura de streaming reduz o tempo real (wall-clock) sem sacrificar a cascata de sinal — cada descoberta ainda passa por todos os filtros, apenas mais cedo.

**5. Roteamento dinâmico via portões de IA**

O pipeline se adapta em tempo de execução com base no que descobre. Um portão de IA examina a saída do reconhecimento e seleciona quais estratégias de caça ativar — um aplicativo Flask com autenticação JWT aciona caçadores diferentes de um microsserviço Go com gRPC. Um portão separado de expansão CWE amplia dinamicamente a lista de alvos de vulnerabilidade com base na pilha de tecnologia detectada. Um portão de alcançabilidade avalia se as vulnerabilidades de dependência têm caminhos de chamadas exploráveis antes de desperdiçar recursos de verificação em código inalcançável.

**6. Autonomia guiada para agentes de codificação**

O SEC-AF é executado sobre agentes de codificação (Claude Code, OpenCode, Codex) por meio do harness AgentField. Em vez de dar ao agente um único prompt enorme, cada reasoner fornece autonomia guiada ciente da fase: o agente recebe uma definição de tarefa estreita, um esquema de saída plano (2-4 campos) e contexto específico da estratégia. O agente tem total autonomia dentro desses limites — ele pode ler arquivos, rastrear código e raciocinar livremente — mas o harness restringe a _forma_ de sua saída. Isso evita o modo de falha comum em que agentes autônomos saem da tarefa ou produzem resultados não estruturados.

**7. DAG de reasoners componível com observabilidade total**

Cada chamada de agente flui através do plano de controle do AgentField, criando um grafo acíclico direcionado completo da auditoria. Você pode ver qual caçador encontrou qual descoberta, quanto tempo cada verificação levou, quais evidências o provador gerou e onde o pipeline gastou seu tempo. Adicionar uma nova classe de vulnerabilidade é um arquivo — um novo caçador. O orquestrador o descobre, roteia contexto para ele e integra suas descobertas no pipeline existente de dedup → prova → remediação. O DAG é a arquitetura.

</details>

<details>
<summary><strong>O que ele perdeu (e por quê)</strong></summary>

Os 9 cenários perdidos são principalmente **ataques ao nível do protocolo GraphQL**: consultas em lote (batch queries), recursão profunda, abuso de alias, duplicação de campos, exposição de introspecção. Estes exigem análise em tempo de execução/DAST. O SEC-AF atualmente é focado em SAST. A detecção ao nível do protocolo está no roteiro.

</details>

## Como Funciona

O SEC-AF é construído sobre a filosofia de [Composite Intelligence](https://github.com/Agent-Field/agentfield): em vez de depender de uma única chamada de LLM monolítica, ele compõe muitas chamadas de LLM focadas e guiadas em um **DAG de reasoners** onde a própria arquitetura codifica inteligência (para um mergulho mais profundo neste padrão, veja [The Atomic Unit of Intelligence](https://www.santoshkumarradha.com/writing/atomic-unit-of-intelligence)). Cada chamada de LLM lida com uma tarefa pequena e bem definida com um esquema Pydantic plano (2-4 atributos). O orquestrador gerencia o fluxo de contexto, paralelismo e roteamento dinâmico.

### Arquitetura: Grafo de Chamadas de Reasoners (DAG)

Cada fase é um `@reasoner` que chama sub-reasoners através do plano de controle do AgentField totalizando cerca de ~200-300 agentes trabalhando síncronamente para uma determinada consulta:

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/7491/d3e99c5c9b7067b17005f71ecb0f7c7abeb9d7fc8843d33938de9f755f416b7b.png" alt="Pipeline de Cascata de Sinal do SEC-AF — RECON → HUNT → DEDUP → PROVE → OUTPUT" width="100%" />
</p>

### Pipeline de Cascata de Sinal

Cada fase estreita o sinal. As descobertas brutas são filtradas através de portões progressivamente mais rigorosos:

| Fase | Propósito | Paralelismo |
|---|---|---|
| **RECON** | Mapear arquitetura, dependências, fluxos de dados, contexto de segurança | Paralelo em 3 vias (arch + deps + config), depois em 2 vias (data flow + security) |
| **HUNT** | Executar 10+ caçadores de estratégia especializados | Paralelo limitado por semáforo (padrão 4 concorrentes) com deduplicação incremental |
| **PROVE** | Verificação adversarial: tentar **refutar** cada descoberta | Paralelo limitado por semáforo (padrão 3 concorrentes) |
| **REMEDIAÇÃO** | Gerar sugestões de correção para descobertas confirmadas/prováveis | Paralelo limitado por semáforo (padrão 3 concorrentes) |

### Por que Arquitetura Multi-Reasoner

A maioria das ferramentas de segurança com IA executa um único prompt grande e espera que o LLM acerte. O SEC-AF decompõe o problema em ~258 chamadas de agente focadas, cada uma com um esquema plano (2-4 campos) e uma tarefa estreita. A arquitetura codifica a estratégia de raciocínio, não o prompt (veja [The Atomic Unit of Intelligence](https://www.santoshkumarradha.com/writing/atomic-unit-of-intelligence) para entender por que isso é importante).

- **Muitos agentes focados > um agente poderoso.** Uma única chamada de LLM não pode mapear arquitetura, rastrear fluxos de dados, caçar injeções, verificar explorabilidade e sugerir correções simultaneamente. O SEC-AF dá cada uma dessas tarefas a um reasoner separado que faz uma coisa bem. O orquestrador lida com composição, paralelismo e roteamento de contexto.
- **Verificação adversarial, não viés de confirmação.** A fase PROVE executa 4 sub-agentes por descoberta com objetivos opostos: o rastreador reconstrói o fluxo de dados, o analisador de sanitização procura bloqueios, o hipotetizador de exploit constrói um ataque, e o agente de veredito pesa todas as evidências. Essa tensão entre agentes produz maior confiança do que perguntar a um único modelo "isso é explorável?"
- **Roteamento dinâmico via portões de IA.** O sistema se adapta em tempo de execução. Um portão de IA examina a saída do reconhecimento e seleciona quais estratégias de caça ativar. Um portão separado expande a lista de alvos CWE com base na pilha detectada. Um aplicativo Flask com autenticação JWT recebe caçadores diferentes de um microsserviço Go com gRPC.
- **Estreitamento progressivo do sinal.** 106 descobertas brutas se tornam 61 após deduplicação, depois 30 após verificação adversarial — redução de ruído de 94%. Cada fase é um filtro. O pipeline comprime o ruído, ele não apenas detecta vulnerabilidades e as despeja.
- **Economia de informação.** Cada agente vê apenas o que precisa. Caçadores recebem contexto de reconhecimento podado para sua estratégia. Verificadores recebem visões projetadas das descobertas com campos mínimos. Isso reduz alucinação, reduz custo e mantém cada chamada de LLM focada.
- **Streaming incremental.** A deduplicação é executada como um consumidor enquanto os caçadores ainda estão produzindo. As descobertas são deduplicadas por impressão digital (fingerprint) à medida que cada caçador termina, depois uma passagem semântica final captura duplicatas entre estratégias. O pipeline faz streaming, não loteamento.

## Comparação

> Alegações obtidas de documentações oficiais e páginas de preços. Se algo estiver errado, [abra uma issue](https://github.com/Agent-Field/sec-af/issues).

| | SEC-AF | Nullify | Snyk Code | Semgrep | CodeQL |
|---|---|---|---|---|---|
| **Abordagem** | **Nativa em IA** | **Nativa em IA** | **Assistida por IA** | **Baseada em regras** | **Baseada em regras** |
| | DAG multi-reasoner · LLM raciocina sobre código | Força de trabalho autônoma de segurança | Motor AI DeepCode | Correspondência de padrões + contaminação (taint) | Análise semântica + fluxo de dados |
| **Open source** | ✅ Apache 2.0 | ❌ Proprietário | ❌ Proprietário | Engine: LGPL-2.1 · Regras Pro: proprietário | Consultas: MIT · Engine: proprietário |
| **Descobertas verificadas** | ✅ Fase PROVE adversarial · veredito + prova por descoberta | ✅ Geração de prova de exploit | ❌ Score de Prioridade (opaco) · sem prova de exploit | ❌ Apenas correspondências de padrões | ❌ Alertas de análise estática |
| **Evidência por descoberta** | Rastreamento de fluxo de dados com propagação de contaminação | Caminho de exploit + etapas de reprodução | Fluxo source-to-sink mostrado | - | Consultas de caminho mostram fluxo de dados |
| **Arquitetura** | DAG de reasoners componível com observabilidade total | Agente monolítico | Motor de passagem única | Motor de regras | Motor de consultas |
| **Paralelismo** | ✅ Caçadores, verificadores e remediadores paralelos com deduplicação incremental | Não documentado | Não documentado | ✅ Paralelismo de regras | ✅ Paralelismo de consultas |
| **Pontuação** | ✅ Fórmula composta publicada | Interna | Score de Prioridade opaco | Interna | - |
| **SARIF** | ✅ Nativo 2.1.0 | Não documentado | ✅ | ✅ | ✅ Nativo |
| **Mapeamento de conformidade** | PCI-DSS, SOC2, OWASP, HIPAA, ISO27001 | Não documentado | Conformidade da plataforma apenas | Regras OWASP disponíveis | - |
| **Idiomas** | Qualquer linguagem suportada por LLM | Não documentado | 14+ | 35+ (baseado em parser) | 10 |
| **Preço** | **Gratuito · código aberto** (~$0.18–$0.90/auditoria em custos de LLM) | **$6.000/mês** | $25-105/mês/desenvolvedor | Motor OSS: uso gratuito · Pro: $30/mês/contribuidor | Gratuito para repositórios públicos · $49/mês/committer (GHAS) |

**Onde o SEC-AF é mais forte**: Descobertas verificadas com objetos de prova, pontuação transparente, mapeamento de conformidade, arquitetura multi-agente componível com observabilidade total do DAG e totalmente open source.

**Onde outros são mais fortes**: Semgrep e CodeQL têm anos de cobertura de regras testadas em batalha em mais de 35 linguagens. Snyk tem integração profunda IDE/SCA. Nullify adiciona contexto de nuvem em tempo de execução e campanhas de remediação automática. SEC-AF é mais novo e atualmente é mais forte em análise de código orientada por IA.

> **Mesma arquitetura, domínio diferente:** [Contract-AF](https://github.com/Agent-Field/contract-af) aplica HUNT→PROVE adversarial a contratos legais — agentes geram agentes para encontrar interações de cláusulas que LLMs solitários perdem.

### Por que a Arquitetura Multi-Agente Importa

Scanners de segurança tradicionais são monolíticos: um motor, uma passagem, um conjunto de regras. A arquitetura multi-reasoner do SEC-AF fornece vantagens estruturais:

- **Especialização**: Cada caçador é um especialista guiado por LLM — um caçador de injeção raciocina de forma diferente de um caçador de criptografia. A arquitetura codifica conhecimento de domínio no roteamento, não apenas nos prompts.
- **Componibilidade**: Adicione uma nova classe de vulnerabilidade adicionando um arquivo de caçador. O orquestrador o descobre e executa automaticamente. Nenhuma alteração no pipeline.
- **Verificação adversarial**: A fase PROVE é estruturalmente separada da HUNT. Caçadores tentam encontrar vulnerabilidades; provadores tentam refutá-las. Essa tensão adversarial reduz falsos positivos.
- **Observabilidade**: Cada chamada de reasoner flui através do plano de controle, criando um DAG completo. Você pode ver exatamente qual caçador encontrou qual descoberta, quanto tempo cada fase levou e o que o LLM raciocinou em cada etapa.
- **Eficiência de custo**: A poda de contexto e as visões de esquema significam que cada chamada de LLM recebe apenas o contexto de que precisa. Uma auditoria completa de profundidade padrão com 30 descobertas verificadas custa cerca de ~$0.18–$0.90 em chamadas de LLM (Kimi K2.5 via OpenRouter).

## Início Rápido

### Instalar no AgentField (`af install`)

Já está executando um plano de controle [AgentField](https://github.com/Agent-Field/agentfield)? Instale o SEC-AF diretamente do GitHub — sem clone, sem configuração local:```bash
af install https://github.com/Agent-Field/sec-af
af run sec-af

Novo no AgentField? Instale o plano de controle primeiro com `curl -fsSL https://agentfield.ai/install.sh | bash`, ou use as opções Docker / Railway abaixo.

### Implantação com Um Clique (Railway)

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/sec-af)

Implanta o plano de controle do AgentField + agente SEC-AF. Você precisará de uma `OPENROUTER_API_KEY`.

### Local (Docker Compose)```bash
git clone https://github.com/Agent-Field/sec-af.git && cd sec-af
cp .env.example .env          # Add OPENROUTER_API_KEY
docker compose up --build

Consultar por resultados:```bash
curl http://localhost:8080/api/v1/executions/<execution_id>

**Passo 2 — Criar e ativar um ambiente virtual**```bash
python3 -m venv .venv
source .venv/bin/activate

**Passo 4 — Configurar variáveis de ambiente**```bash
cp .env.example .env

Opcional — defina um diretório de trabalho personalizado para evitar problemas de permissão:```
SEC_AF_WORKSPACES_DIR=~/.sec-af/workspaces

Isto é executado em `http://localhost:8080` por padrão.

**Passo 6 — Inicie o agente SEC-AF** (em outro terminal, com o venv ativo)```bash
python3 main.py

## API

<details>
<summary><strong>Opções completas de requisição</strong></summary>```bash
curl -X POST http://localhost:8080/api/v1/execute/async/sec-af.audit \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "repo_url": "https://github.com/org/repo",
      "branch": "main",
      "depth": "thorough",
      "severity_threshold": "high",
      "scan_types": ["sast", "sca", "secrets", "config"],
      "output_formats": ["sarif", "json", "markdown"],
      "compliance_frameworks": ["pci-dss", "soc2", "owasp", "hipaa"],
      "max_cost_usd": 15.0,
      "max_provers": 30,
      "max_duration_seconds": 1800,
      "include_paths": ["src/"],
      "exclude_paths": ["tests/", "vendor/"]
    }
  }'