🦡 codebadger

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

前置要求

在开始之前，请确保已安装：

• Docker 和 Docker Compose

• Python 3.10+ (推荐 Python 3.13)

• pip (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 Server：静态代码分析引擎（运行 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)

• 可选地清理 playground 目录 (CPG 和缓存的代码库)

集成

GitHub Copilot 集成

编辑 VS Code (GitHub Copilot) 的 MCP 配置文件：

路径：

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

配置示例：

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

Claude Code 集成

要将 codebadger 集成到 Claude Desktop，请编辑：

路径：

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

添加以下内容：

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

可用工具

核心

• generate_cpg：为代码库生成代码属性图 (CPG)（本地路径或 GitHub URL）。

• 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：启发式检测可能的宏展开调用。

污点与漏洞分析

• find_taint_sources：查找可能的外部输入点 (sources)。

• find_taint_sinks：定位污点数据可能流向的危险接收点 (sinks)。

• find_taint_flows：检测从源到接收点的数据流（污点分析）。

• get_program_slice：为调用构建向后/向前程序切片。

• get_variable_flow：追踪特定位置变量的数据依赖关系。

• find_bounds_checks：搜索缓冲区访问附近的边界检查。

• find_use_after_free：启发式检测释放后使用 (use-after-free) 模式。

• find_double_free：检测潜在的重复释放 (double-free) 问题。

• find_null_pointer_deref：查找可能的空指针解引用。

• find_integer_overflow：检测整数溢出模式。

• find_format_string_vulns：检测格式化字符串漏洞 (CWE-134)，即非字面量格式参数被传递给 printf 系列函数。

• find_heap_overflow：检测堆溢出漏洞 (CWE-122)，即对堆缓冲区的写入可能超过其分配的大小。

• find_stack_overflow：检测栈缓冲区溢出漏洞 (CWE-121)，即对固定大小局部数组（例如 char buf[64]）的写入可能超过其声明的维度。

• find_toctou：检测 Time-of-Check-Time-of-Use 竞态条件 (CWE-367)，即文件先通过 access()/stat() 检查，随后在单独步骤中打开或操作。

• find_uninitialized_reads：检测未初始化变量读取 (CWE-457)，即局部变量在赋值前被使用。

贡献与测试

感谢您的贡献！以下是开始运行测试和贡献代码的快速指南。

前置要求

• Python 3.10+ (CI 中使用 3.13)

• Docker 和 Docker Compose (用于集成测试)

本地开发设置

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

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

2. 启动 Docker 服务 (用于集成测试)

docker-compose up -d

3. 运行单元测试

pytest tests/ -q

4. 运行集成测试 (需要运行 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"

5. 运行所有测试

pytest tests/ -q

6. 测试后清理

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.example.yaml 创建 config.yaml：

cp config.example.yaml config.yaml

然后根据需要进行自定义。

遥测 (OpenTelemetry)

CodeBadger 内置了用于分布式追踪的 OpenTelemetry 支持。启用后，所有 MCP 工具调用都会被自动追踪，此外还包括 CPG 生成、Joern 服务器管理和查询执行的自定义跨度 (spans)。

快速入门

1. 安装遥测依赖（包含在 requirements.txt 中）：

pip install opentelemetry-sdk opentelemetry-exporter-otlp

2. 通过环境变量启用：

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

追踪内容

配置参考

当遥测被禁用（默认）时，所有追踪均为无操作，零开销。