code-reason

Análisis de programas para tus agentes de codificación.

En lugar de grep y adivinar, proporciona a tus agentes capacidades de análisis de programas con code-reason.

code-reason es un servidor MCP que proporciona a los agentes de codificación primitivas reales de análisis de programas, como alcanzabilidad de flujo de datos, recorrido de grafo de llamadas y construcción de cadenas de evidencia, para que verifiquen el comportamiento del código a partir de la verdad fundamental en lugar de especulaciones.

Por qué code-reason

Los agentes de codificación son buenos leyendo código, pero les cuesta responder preguntas de programa completo:

• ¿La entrada controlada por el usuario realmente llega a esta llamada SQL, o la sanitización corta el flujo?
• ¿Quién invoca realmente esta función en todo el código base?
• ¿Cuál es la cadena de evidencia completa desde el origen hasta el sumidero?

Sin una herramienta de análisis de código, el agente responde a estas preguntas mediante trazado manual basado en grep. Puede leer código, pero no puede realmente rastrear el flujo de datos, recorrer un grafo de control, ni verificar que la entrada del usuario llega a un sumidero. Pregunta a cualquier agente de codificación moderno cómo rastrea la contaminación sin una herramienta, y la respuesta será alguna variante de "Leo archivos y sigo coincidencias de cadenas."

Eso funciona para casos simples. Las grietas aparecen en cualquier cosa no trivial: variables con alias, flujo interprocedural, comprobaciones de sanitización, entradas inyectadas por el framework. El agente sigue produciendo una respuesta, a menudo con alta confianza, pero está leyendo 6+ archivos para confirmar una sola cadena, quemando contexto en especulaciones, y perdiendo silenciosamente flujos que nunca pensó en buscar con grep. Para trabajos sensibles a la seguridad, una respuesta incorrecta con confianza es más peligrosa que ninguna respuesta, y eso es exactamente lo que produce el trazado basado en grep a escala.

code-reason cierra la brecha. El agente sigue a cargo de lo que es interesante; code-reason responde lo que es realmente cierto, respaldado por un grafo de propiedades de código analizado una vez y consultado de forma económica. El resultado: agentes más deterministas, más eficientes en tokens, más rápidos, y flujos de trabajo de seguridad agénticos en los que realmente puedes confiar.

Mientras que las herramientas SAST tradicionales producen informes de hallazgos para que los humanos los trien, code-reason expone las primitivas de análisis subyacentes para que un agente dirija su propia investigación.

Construido sobre Fraunhofer AISEC's Code Property Graph para análisis de flujo de datos, flujo de control y contaminación en múltiples lenguajes, y el Kotlin MCP SDK para exponer esas capacidades como herramientas invocables por agentes.

Lo que obtienes

De sesiones de dogfooding en bases de código reales de Java y Python:

• 30-40% menos de tokens de agente en revisiones de seguridad de múltiples pasos, principalmente gracias a consultas de grafo de llamadas que de otro modo requerirían de 5 a 10 iteraciones de grep para confirmar manualmente.
• Respuestas estructuradas y compactas, no volcados de archivos. Una consulta de grafo de llamadas devuelve métodos alcanzables en JSON; el equivalente de grep y lectura obliga al agente a leer 6+ archivos para confirmar una sola cadena.
• Un solo pase de análisis por servicio, consultas ilimitadas. reason_analyze_project construye el CPG una vez; cualquier otra herramienta reason_* lo consulta de forma económica.
• Cadenas de evidencia reales. reason_trace_taint_path devuelve la ruta completa de origen a sumidero con pasos intermedios y contexto de código, no "parece SQLi quizás."

Cómo funciona

code-reason se sitúa entre el agente de codificación y un grafo de propiedades de código. El agente dirige; code-reason responde.

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

Un bucle típico se ejecuta en tres fases:

1. Analizar. El agente llama a reason_analyze_project. El CPG analiza la base de código objetivo en un multigrafo: sintaxis abstracta, flujo de control, flujo de datos y orden de evaluación, todo en una estructura consultable.

2. Consultar. El agente llama a una o más herramientas reason_*, cada una de las cuales se traduce en una operación de grafo enfocada: propagación de contaminación, recorrido de grafo de llamadas, alcanzabilidad de flujo de datos, construcción de cadenas de evidencia.

3. Razonar. Cada herramienta devuelve un resultado estructurado (ubicaciones, rutas, confianza, evidencia). El agente combina esos resultados con su propio razonamiento contextual y decide qué preguntar a continuación.

El agente proporciona la intención y el razonamiento de alto nivel; code-reason proporciona respuestas de verdad fundamental contra el grafo real. Sin grep y adivinar, sin volcados de contexto sobredimensionados.

Herramientas

code-reason expone nueve herramientas MCP, agrupadas por propósito:

Grupo	Herramienta	Propósito
Configuración	reason_analyze_project	Analizar un proyecto en un grafo de propiedades de código
Navegación	reason_find_entry_points	Localizar manejadores HTTP, entradas CLI, enganches de framework
Navegación	reason_find_callers	"¿Quién llama a esta función?"
Navegación	reason_find_callees	"¿Qué llama esta función?"
Flujo de datos	reason_query_dataflow	Alcanzabilidad hacia adelante/atrás sobre el grafo de flujo de datos
Flujo de datos	reason_trace_taint_path	Cadena de evidencia completa de origen a sumidero entre dos puntos cualesquiera
Escaneo de catálogo (conveniencia)	reason_scan_injections	Análisis de contaminación basado en catálogo (SQLi/XSS/inyección de comandos)
Escaneo de catálogo (conveniencia)	reason_list_supported_checks	Enumerar comprobaciones de vulnerabilidades integradas
Escaneo de catálogo (conveniencia)	reason_get_finding_detail	Descripción + remediación para un hallazgo de escaneo

El valor principal son las primitivas de navegación y flujo de datos; el agente las compone para responder preguntas de programa completo por sí mismo. Las herramientas de escaneo de catálogo son una línea base de conveniencia para un triaje rápido de primera pasada; el propio razonamiento del agente sobre las primitivas es lo que marca la diferencia en bases de código reales.

Requisitos previos

• JDK 21

La compilación obtiene artefactos de CPG desde Maven Central y Sonatype Central Snapshots (este último para main-SNAPSHOT hasta que CPG 11.x se publique como versión estable en Central). No se requieren checkouts hermanos.

Compilación

./gradlew installDist

El lanzador se encuentra en build/install/code-reason/bin/code-reason.

Ejecución de pruebas

./gradlew test

Las pruebas de integración ejecutan el pipeline completo contra pequeños fixtures de Java y Python.

Configuración de Claude Code

Añade code-reason a tu .mcp.json (a nivel de proyecto) o ~/.claude/.mcp.json (global):

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

Reinicia Claude Code; las herramientas reason_* aparecerán en su lista de herramientas.

Ejemplo de flujo de trabajo

Una sesión típica dirigida por un agente, con primitivas que se componen en evidencia:

1. El agente llama a reason_analyze_project para construir el CPG.
2. El agente llama a reason_find_entry_points para enumerar dónde entra la entrada externa en la base de código.
3. Para un punto de entrada sospechoso, el agente usa reason_find_callees y reason_query_dataflow para mapear el alcance aguas abajo.
4. Cuando los datos llegan a una llamada sensible, el agente llama a reason_trace_taint_path para obtener la cadena de evidencia completa de origen a sumidero.
5. El agente razona sobre la explotabilidad a partir del resultado estructurado y decide qué investigar a continuación.

Para un triaje rápido de primera pasada, el agente también puede llamar a reason_scan_injections para revelar flujos candidatos del catálogo integrado, y luego verificar cada uno con reason_trace_taint_path.

Lenguajes soportados

• Java
• Python

Se pueden habilitar frontends adicionales de CPG (C/C++, Go, TypeScript, JVM, LLVM, Ruby) añadiendo la dependencia cpg-language-* correspondiente en build.gradle.kts.

Estado

code-reason es v0.1.0: temprano, de grado de investigación. CI se ejecuta en cada push y pull request. La compilación está actualmente fijada a CPG main-SNAPSHOT; esto se moverá a una versión estable 11.x una vez que Fraunhofer publique una en Maven Central.

Licencia

Apache 2.0. Ver LICENSE.

Agradecimientos

Construido sobre Fraunhofer AISEC's Code Property Graph.