Joern MCP

🦡 编码员

一个容器化的模型上下文协议（MCP）服务器，使用Joern的代码属性图（CPG）技术提供静态代码分析，支持Java、C/C++、JavaScript、Python、Go、Kotlin、C#、Ghidra、Jimple、PHP、Ruby和Swift。

新闻

codeadger及其附属论文-- *用于程序分析的桥接代码属性图和语言模型* --已被接受 软件漏洞管理研讨会@ICSE 2026. 🎉

引用

@article{lekssays2026bridging,
  title={Bridging Code Property Graphs and Language Models for Program Analysis},
  author={Lekssays, Ahmed},
  journal={arXiv preprint arXiv:2603.24837},
  year={2026}
}

使用codepadger发现漏洞？

如果codepadger帮助您发现了一个真实世界的漏洞，我们很乐意听到它的消息。打开一个pull请求，将其添加到 TROPHIES.md --包括CVE ID、项目、单行描述和日期。

先决条件

在开始之前，请确保您已经：

• 码头工人 和 Docker Compose 安装
• Python 3.10+ （推荐使用Python 3.13）
• 点 （Python包管理器）

要验证您的设置：

docker --version
docker-compose --version
python --version

快速开始

1.安装Python依赖项

# Create a virtual environment (optional but recommended)
python -m venv venv

# Install dependencies
pip install -r requirements.txt

2.启动Docker服务（Joern）

docker compose up -d

这将开始：

• Joern服务器：静态代码分析引擎（运行CPG生成和查询）

验证服务是否正在运行：

docker compose ps

3.启动MCP服务器

# Start the server
python main.py &

MCP服务器将在 http://localhost:4242.

4.停止所有服务

# Stop MCP server (Ctrl+C in terminal)

# Stop Docker services
docker-compose down
# Optional: Clean up everything
bash cleanup.sh

清理脚本

使用提供的清理脚本重置您的环境：

bash cleanup.sh

这将：

• 停止并删除Docker容器
• 杀死孤立的Joern/MCP进程
• 清除Python缓存(__pycache__, .pytest_cache)
• （可选）清除游乐场目录（CPG和缓存代码库）

集成

GitHub复制集成

编辑VS代码的MCP配置文件（GitHub Copilot）：

路径：

~/.config/Code/User/mcp.json

配置示例：

{
  "inputs": [],
  "servers": {
    "codebadger": {
      "url": "http://localhost:4242/mcp",
      "type": "http"
    }
  }
}

______________________________________________________________________

Claude代码集成

整合 codebadger 进入 克劳德桌面版，编辑：

路径：

Claude → Settings → Developer → Edit Config → claude_desktop_config.json

添加以下内容：

{
  "mcpServers": {
    "codebadger": {
      "url": "http://localhost:4242/mcp",
      "type": "http"
    }
  }
}

可用工具

核心

• generate_cpg：为代码库（本地路径或GitHub URL）生成代码属性图（CPG）。
• get_cpg_status：检查CPG是否存在并检索状态元数据。
• run_cpgql_query：对CPG执行原始CPGQL查询，并返回结构化结果。
• get_cpgql_syntax_help：显示CPGQL语法帮助程序、提示和常见错误修复。

代码浏览

• list_methods：列出带有可选正则表达式/文件过滤器的方法/函数。
• list_files：以分页树视图显示源文件。
• get_method_source：检索命名方法的源代码。
• list_calls：列出函数之间的调用站点（调用者→ 被叫方）。
• get_call_graph：构建一个人类可读的调用图（传入或传出）。
• list_parameters：获取方法的参数名称、类型和顺序。
• get_codebase_summary：高级指标（文件、方法、调用、语言）。
• get_code_snippet：按开始/结束行号返回文件片段。

语义分析

• get_cfg：为方法生成控制流图（节点和边）。
• get_type_definition：检查结构/类类型及其成员。
• get_macro_expansion：启发式检测可能的宏扩展呼叫。

Taint和漏洞分析

• find_taint_sources：查找可能的外部输入点（来源）。
• find_taint_sinks：找到可能流入受污染数据的危险汇。
• find_taint_flows：检测从源到汇的数据流（污染分析）。
• get_program_slice：为调用构建反向/正向程序切片。
• get_variable_flow：跟踪某个位置变量的数据依赖关系。
• find_bounds_checks：搜索缓冲区访问附近的边界检查。
• find_use_after_free：自由模式后使用的启发式检测。
• find_double_free：检测潜在的双重自由问题。
• find_null_pointer_deref：查找可能的空指针解引用。
• find_integer_overflow：检测整数溢出模式。
• find_format_string_vulns：检测将非文字格式参数传递给printf家族函数的格式字符串漏洞（CWE-134）。
• find_heap_overflow：检测堆溢出漏洞（CWE-122），其中对堆缓冲区的写入可能超过其分配的大小。
• find_stack_overflow：检测堆栈缓冲区溢出漏洞（CWE-121），其中写入固定大小的本地数组（例如。 char buf[64])可能超过其声明的维度。
• find_toctou：检测文件检查的时间使用时间竞赛条件（CWE-367） access()/stat() 然后在单独的步骤中打开或操作。
• find_uninitialized_reads：检测未初始化的变量读取（CWE-457），其中在分配值之前使用了局部变量。

定制工具

您可以添加自己的检测器，而无需修改核心代码库：

1. 在中编写Scala查询模板 src/tools/queries/your_query.scala.
2. 在中注册Python工具函数 src/tools/custom_tools.py.
3. 重新启动服务器——该工具会自动出现在每个MCP客户端中。

看 CUSTOM_TOOLS_GUIDE.md 获取完整的分步指南、CPGQL参考和设计决策。

贡献与测试

感谢您的贡献！这里有一个快速指南，可以开始运行测试和贡献代码。

先决条件

• Python 3.10+（3.13用于CI）
• Docker和Docker Compose（用于集成测试）

地方发展设置

1. 创建虚拟环境并安装依赖项

python -m venv venv
pip install -r requirements.txt

1. 启动Docker服务（用于集成测试）

docker-compose up -d

1. 运行单元测试

pytest tests/ -q

1. 运行集成测试（需要运行Docker Compose）

# Start MCP server in background
python main.py &

# Run integration tests
pytest tests/integration -q

# Stop MCP server
pkill -f "python main.py"

1. 运行所有测试

pytest tests/ -q

1. 测试后的清理

bash cleanup.sh
docker-compose down

代码贡献

投稿时请遵循以下准则：

1. 遵循存储库惯例
2. 编写行为变化测试
3. 在提交PR之前，确保所有测试都通过
4. 在PR描述中包含清晰的变更日志
5. 必要时更新文档

配置

MCP服务器可以通过环境变量或 config.yaml.

环境变量

关键设置（可选-显示默认值）：

# Server
MCP_HOST=0.0.0.0
MCP_PORT=4242

# Joern
JOERN_BINARY_PATH=joern
JOERN_JAVA_OPTS="-Xmx4G -Xms2G -XX:+UseG1GC -Dfile.encoding=UTF-8"

# CPG Generation
CPG_GENERATION_TIMEOUT=600
MAX_REPO_SIZE_MB=500

# Query
QUERY_TIMEOUT=30
QUERY_CACHE_ENABLED=true
QUERY_CACHE_TTL=300

# Telemetry (OpenTelemetry)
OTEL_ENABLED=false
OTEL_SERVICE_NAME=codebadger
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc

配置文件

创建一个 config.yaml 从 config.example.yaml:

cp config.example.yaml config.yaml

然后根据需要进行定制。

遥测（开放遥测）

CodeBadger内置了OpenTetry支持，用于分布式跟踪。启用后，将自动跟踪所有MCP工具调用，以及CPG生成、Joern服务器管理和查询执行的自定义范围。

快速开始

1. 安装遥测依赖项（包含在 requirements.txt):

pip install opentelemetry-sdk opentelemetry-exporter-otlp

1. 通过环境变量启用：

export OTEL_ENABLED=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
python main.py

或通过 config.yaml:

telemetry:
  enabled: true
  service_name: codebadger
  otlp_endpoint: http://localhost:4317
  otlp_protocol: grpc  # or "http/protobuf"

与Jaeger共同进行地方发展

# Start Jaeger (provides UI at http://localhost:16686)
docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

# Start CodeBadger with telemetry
OTEL_ENABLED=true python main.py

什么被追踪

配置参考

禁用遥测（默认）时，所有跟踪都是零开销的无操作。