Code Reason

面向编码 Agent 的程序分析。

与其通过 grep 猜测，不如用 code-reason 为你的 Agent 提供程序分析能力。

code-reason 是一个 MCP 服务，为编码 Agent 提供真正的程序分析原语，例如数据流可达性、调用图遍历和证据链构建，让它们能够基于事实验证代码行为，而不是凭空猜测。

为什么选择 code-reason

编码 Agent 擅长阅读代码，但难以回答涉及整个程序的问题：

• 用户控制的输入真的会到达这个 SQL 调用吗？还是经过清理后数据流就中断了？
• 整个代码库中究竟有哪些地方会调用这个函数？
• 从源到汇的完整证据链是什么？

没有代码分析工具时，Agent 会通过手动 grep 追踪来回答这些问题。它可以阅读代码，却无法真正追踪数据流、遍历控制流图，或验证用户输入是否会到达汇点。问问任何现代编码 Agent，在没有工具时如何追踪污点，它们的回答大致都是：“我会阅读文件并查找字符串匹配。”

对于简单情况，这样做行得通。但遇到稍复杂的问题时，缺陷就会显现：变量别名、跨过程数据流、清理检查、框架注入的输入。Agent 仍然会给出答案，而且往往信心十足，但它需要阅读 6 个以上的文件才能确认一条链路，在推测上消耗上下文，还会悄无声息地漏掉那些它根本没想到要 grep 的数据流。对于安全敏感的工作，信心十足的错误答案比没有答案更危险，而这正是基于 grep 的追踪大规模运行时会产生的结果。

code-reason 弥补了这一差距。Agent 负责判断哪些内容值得关注；code-reason 则基于一次解析、可低成本查询的代码属性图，回答实际情况究竟如何。结果是：更确定、更节省 token、速度更快的 Agent，以及真正值得信赖的 Agent 安全工作流。

传统 SAST 工具会生成供人类分类处理的问题报告，而 code-reason 则向 Agent 提供底层分析原语，让 Agent 自行开展调查。

code-reason 基于 Fraunhofer AISEC 的 Code Property Graph 实现多语言数据流、控制流和污点分析，并使用 Kotlin MCP SDK 将这些能力封装成 Agent 可调用的工具。

你将获得

来自真实 Java 和 Python 代码库的内部试用：

• 多步骤安全审查中，Agent 的 token 消耗减少 30-40%。 这主要得益于调用图查询；否则，手动确认通常需要 5-10 轮 grep。
• 返回精简的结构化答案，而非文件内容转储。 调用图查询会以 JSON 返回可达方法；而 grep 加阅读的方式则迫使 Agent 阅读 6 个以上的文件才能确认一条链路。
• 每个服务只需分析一次，查询次数不限。 reason_analyze_project 会构建一次 CPG；其他所有 reason_* 工具都能以很低的成本查询它。
• 真实的证据链。 reason_trace_taint_path 会返回完整的源到汇路径，包括中间步骤和代码上下文，而不是“看起来可能有 SQLi”。

工作原理

code-reason 位于编码 Agent 与代码属性图之间。Agent 负责驱动；code-reason 提供解答。

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

典型的循环分为三个阶段：

1. 分析。 Agent 调用 reason_analyze_project。CPG 会将目标代码库解析为多图：抽象语法、控制流、数据流和求值顺序都包含在一个可查询的结构中。

2. 查询。 Agent 调用一个或多个 reason_* 工具，每个工具都会转换为一个专门的图操作：污点传播、调用图遍历、数据流可达性、证据链构建。

3. 推理。 每个工具都会返回结构化结果（位置、路径、置信度、证据）。Agent 将这些结果与自身的上下文推理相结合，并决定接下来要询问什么。

Agent 提供意图和高层推理；code-reason 则根据实际图提供真实答案。无需 grep 后猜测，也无需倾倒过多上下文。

工具

code-reason 提供九个 MCP 工具，按用途分组：

分组	工具	用途
设置	reason_analyze_project	将项目解析为代码属性图
导航	reason_find_entry_points	定位 HTTP 处理程序、CLI 入口、框架钩子
导航	reason_find_callers	“谁调用了此函数？”
导航	reason_find_callees	“此函数调用了什么？”
数据流	reason_query_dataflow	在数据流图上进行正向／反向可达性查询
数据流	reason_trace_taint_path	任意两个位置之间完整的源到汇证据链
目录扫描（便捷工具）	reason_scan_injections	基于目录的污点分析（SQLi/XSS/命令注入）
目录扫描（便捷工具）	reason_list_supported_checks	列出内置漏洞检查项
目录扫描（便捷工具）	reason_get_finding_detail	扫描发现项的描述和修复建议

核心价值在于导航和数据流基础工具；Agent 可以组合使用这些工具，自行回答整个程序层面的问题。目录扫描工具是便捷的基线，可用于快速初步筛查；真正让它在实际代码库中发挥作用的，是 Agent 基于这些基础工具进行的自主推理。

先决条件

• JDK 21

构建过程会从 Maven Central 和 Sonatype Central Snapshots 拉取 CPG 构件（在 CPG 11.x 作为稳定版本发布到 Central 之前，后者用于获取 main-SNAPSHOT）。无需检出其他同级代码库。

构建

./gradlew installDist

启动器位于 build/install/code-reason/bin/code-reason。

运行测试

./gradlew test

集成测试会使用小型 Java 和 Python 样例运行完整流水线。

Claude Code 设置

将 code-reason 添加到 .mcp.json（项目范围）或 ~/.claude/.mcp.json（全局）：

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

重启 Claude Code；reason_* 工具就会出现在工具列表中。

示例工作流

典型的 Agent 驱动会话，通过组合基础工具生成证据：

1. Agent 调用 reason_analyze_project 构建 CPG。
2. Agent 调用 reason_find_entry_points，列出外部输入进入代码库的位置。
3. 对于可疑入口点，Agent 使用 reason_find_callees 和 reason_query_dataflow 绘制下游影响范围。
4. 当数据到达敏感调用时，Agent 调用 reason_trace_taint_path 获取完整的源到汇证据链。
5. Agent 根据结构化结果推理其可利用性，并决定接下来要调查什么。

若要快速初步筛查，Agent 也可以调用 reason_scan_injections，利用内置目录发现候选数据流，然后使用 reason_trace_taint_path 逐一验证。

支持的语言

• Java
• Python

添加 build.gradle.kts 中相应的 cpg-language-* 依赖，即可启用其他 CPG 前端（C/C++、Go、TypeScript、JVM、LLVM、Ruby）。

状态

code-reason 为 v0.1.0 版本：处于早期阶段，属于研究级项目。每次推送和拉取请求都会触发 CI。当前构建固定使用 CPG main-SNAPSHOT；Fraunhofer 将 11.x 稳定版本发布到 Maven Central 后，构建将切换到该版本。

许可证

Apache 2.0。参见 LICENSE。

致谢

基于 Fraunhofer AISEC 的代码属性图（Code Property Graph） 构建。