code-reason

Análise de programas para seus agentes de codificação.

Em vez de "grep e adivinhação", forneça aos seus agentes capacidades de análise de programas com code-reason.

code-reason é um servidor MCP que dá aos agentes de codificação primitivas reais de análise de programas, como alcançabilidade de fluxo de dados, travessia de grafo de chamadas e construção de cadeias de evidência, para que eles verifiquem o comportamento do código com base em fatos concretos, em vez de especulação.

Por que code-reason

Agentes de codificação são bons em ler código, mas têm dificuldade com perguntas de programa inteiro:

• A entrada controlada pelo usuário realmente alcança esta chamada SQL, ou a sanitização interrompe o fluxo?
• Quem realmente invoca esta função em todo o codebase?
• Qual é a cadeia de evidência completa da origem ao destino?

Sem uma ferramenta de análise de código, o agente responde a essas perguntas por rastreamento manual baseado em grep. Ele pode ler código, mas não consegue realmente rastrear fluxo de dados, percorrer um grafo de controle ou verificar se a entrada do usuário alcança um destino. Pergunte a qualquer agente de codificação moderno como ele rastreia taint sem uma ferramenta, e a resposta será alguma variação de "eu leio arquivos e sigo correspondências de strings."

Isso funciona para casos simples. As falhas aparecem em qualquer coisa não trivial: variáveis com aliases, fluxo interprocedural, verificações de sanitização, entradas injetadas por frameworks. O agente ainda produz uma resposta, muitas vezes com alta confiança, mas está lendo 6+ arquivos para confirmar uma única cadeia, queimando contexto em especulação e perdendo silenciosamente fluxos que nunca pensou em buscar com grep. Para trabalho sensível à segurança, uma resposta errada e confiante é mais perigosa do que nenhuma resposta, e é exatamente isso que o rastreamento baseado em grep produz em escala.

code-reason fecha essa lacuna. O agente continua no comando do que é interessante; code-reason responde o que é realmente verdadeiro, apoiado por um grafo de propriedades de código analisado uma vez e consultado de forma barata. O resultado: agentes mais determinísticos, mais eficientes em tokens, mais rápidos e fluxos de trabalho de segurança agênticos que você pode realmente confiar.

Onde ferramentas tradicionais de SAST produzem relatórios de achados para humanos triarem, code-reason expõe as primitivas de análise subjacentes para um agente conduzir sua própria investigação.

Construído sobre o Code Property Graph do Fraunhofer AISEC para análise de fluxo de dados, fluxo de controle e taint em múltiplas linguagens, e o Kotlin MCP SDK para expor essas capacidades como ferramentas chamáveis por agentes.

O que você obtém

De sessões de teste em codebases reais em Java e Python:

• 30-40% menos tokens de agente em revisões de segurança de múltiplas etapas, principalmente de consultas de grafo de chamadas que, de outra forma, exigiriam 5-10 iterações de grep para confirmar manualmente.
• Respostas estruturadas e compactas, não despejos de arquivos. Uma consulta de grafo de chamadas retorna métodos alcançáveis em JSON; o equivalente de grep-e-leitura força o agente a ler 6+ arquivos para confirmar uma única cadeia.
• Uma passagem de análise por serviço, consultas ilimitadas. reason_analyze_project constrói o CPG uma vez; todas as outras ferramentas reason_* o consultam de forma barata.
• Cadeias de evidência reais. reason_trace_taint_path retorna o caminho completo da origem ao destino com etapas intermediárias e contexto de código, não "parece SQLi, talvez."

Como funciona

code-reason fica entre o agente de codificação e um grafo de propriedades de código. O agente dirige; code-reason responde.

   Coding agent (Claude Code, Cursor, ...)
              │  MCP over stdio
              ▼
       code-reason server
              │
              ▼
   Fraunhofer CPG (Java + Python frontends)
              │
              ▼
        Target codebase

Um loop típico ocorre em três fases:

1. Analisar. O agente chama reason_analyze_project. O CPG analisa o codebase alvo em um multigrafo: sintaxe abstrata, fluxo de controle, fluxo de dados e ordem de avaliação, tudo em uma estrutura consultável.

2. Consultar. O agente chama uma ou mais ferramentas reason_*, cada uma traduzida para uma operação de grafo focada: propagação de taint, travessia de grafo de chamadas, alcançabilidade de fluxo de dados, construção de cadeias de evidência.

3. Raciocinar. Cada ferramenta retorna um resultado estruturado (localizações, caminhos, confiança, evidência). O agente combina esses resultados com seu próprio raciocínio contextual e decide o que perguntar em seguida.

O agente fornece a intenção e o raciocínio de alto nível; code-reason fornece respostas baseadas em fatos contra o grafo real. Sem grep-e-adivinhação, sem despejos de contexto excessivos.

Ferramentas

code-reason expõe nove ferramentas MCP, agrupadas por propósito:

Grupo	Ferramenta	Propósito
Configuração	reason_analyze_project	Analisar um projeto em um grafo de propriedades de código
Navegação	reason_find_entry_points	Localizar manipuladores HTTP, entradas CLI, hooks de framework
Navegação	reason_find_callers	"Quem chama esta função?"
Navegação	reason_find_callees	"O que esta função chama?"
Fluxo de dados	reason_query_dataflow	Alcançabilidade direta/retrocedente sobre o grafo de fluxo de dados
Fluxo de dados	reason_trace_taint_path	Cadeia de evidência completa da origem ao destino entre quaisquer dois pontos
Varredura de catálogo (conveniência)	reason_scan_injections	Análise de taint orientada por catálogo (SQLi/XSS/injeção de comando)
Varredura de catálogo (conveniência)	reason_list_supported_checks	Enumerar verificações de vulnerabilidade embutidas
Varredura de catálogo (conveniência)	reason_get_finding_detail	Descrição + remediação para um achado de varredura

O valor principal está nas primitivas de navegação e fluxo de dados; o agente as compõe para responder perguntas de programa inteiro por conta própria. As ferramentas de varredura de catálogo são uma linha de base conveniente para triagem rápida de primeira passagem; o raciocínio do próprio agente sobre as primitivas é o que faz a diferença em codebases reais.

Pré-requisitos

• JDK 21

A compilação puxa artefatos do CPG do Maven Central e do Sonatype Central Snapshots (este último para main-SNAPSHOT até que o CPG 11.x seja lançado como versão estável no Central). Nenhum checkout irmão é necessário.

Compilação

./gradlew installDist

O lançador fica em build/install/code-reason/bin/code-reason.

Executando testes

./gradlew test

Testes de integração executam o pipeline completo contra pequenos fixtures em Java e Python.

Configuração do Claude Code

Adicione code-reason ao seu .mcp.json (escopo do projeto) ou ~/.claude/.mcp.json (global):

{
  "mcpServers": {
    "code-reason": {
      "command": "/absolute/path/to/build/install/code-reason/bin/code-reason",
      "args": ["--stdio"]
    }
  }
}

Reinicie o Claude Code; as ferramentas reason_* aparecerão na lista de ferramentas.

Exemplo de fluxo de trabalho

Uma sessão típica dirigida por agente, com primitivas se compondo em evidência:

1. O agente chama reason_analyze_project para construir o CPG.
2. O agente chama reason_find_entry_points para enumerar onde a entrada externa entra no codebase.
3. Para um ponto de entrada suspeito, o agente usa reason_find_callees e reason_query_dataflow para mapear o alcance a jusante.
4. Quando os dados alcançam uma chamada sensível, o agente chama reason_trace_taint_path para a cadeia de evidência completa da origem ao destino.
5. O agente raciocina sobre a explorabilidade a partir do resultado estruturado e decide o que investigar em seguida.

Para triagem rápida de primeira passagem, o agente também pode chamar reason_scan_injections para superfície de fluxos candidatos do catálogo embutido e, em seguida, verificar cada um com reason_trace_taint_path.

Linguagens suportadas

• Java
• Python

Frontends adicionais do CPG (C/C++, Go, TypeScript, JVM, LLVM, Ruby) podem ser habilitados adicionando a dependência cpg-language-* correspondente em build.gradle.kts.

Status

code-reason é v0.1.0: inicial, grau de pesquisa. CI roda em cada push e pull request. A compilação está atualmente fixada no CPG main-SNAPSHOT; isso mudará para uma versão estável 11.x assim que o Fraunhofer publicar uma no Maven Central.

Licença

Apache 2.0. Veja LICENSE.

Agradecimentos

Construído sobre o Code Property Graph do Fraunhofer AISEC.