Lekssays/codebadger

# 🦡 codebadger 一个容器化的 Model Context Protocol (MCP) 服务器，利用 Joern 的 Code Property Graph (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 依赖 ``` # 创建虚拟环境（可选但推荐） python -m venv venv # 安装依赖 pip install -r requirements.txt ``` ### 2. 启动 Docker 服务 (Joern) ``` docker compose up -d ``` 此步骤会启动： - **Joern Server**：静态代码分析引擎（负责运行 CPG 生成和查询） 验证服务是否正在运行： ``` docker compose ps ``` ### 3. 启动 MCP 服务器 ``` # 启动服务器 python main.py & ``` MCP 服务器将运行于 `http://localhost:4242`。 ### 4. 停止所有服务 ``` # 停止 MCP server（在终端中按 Ctrl+C） # 停止 Docker 服务 docker-compose down # 可选：清理所有内容 bash cleanup.sh ``` ## 清理脚本 使用提供的清理脚本重置您的环境： ``` bash cleanup.sh ``` 此操作将： - 停止并移除 Docker 容器 - 终止孤立的 Joern/MCP 进程 - 清除 Python 缓存（`__pycache__`、`.pytest_cache`） - 可选清除 playground 目录（CPG 和缓存的代码库） ## 集成 ### GitHub Copilot 集成 编辑 VS Code 的 MCP 配置文件 (GitHub Copilot)： **路径：** ``` ~/.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`：为代码库（本地路径或 GitHub URL）生成 Code Property Graph (CPG)。 - `get_cpg_status`：检查 CPG 是否存在并获取状态元数据。 - `run_cpgql_query`：针对 CPG 执行原生 CPGQL 查询并返回结构化结果。 - `get_cpgql_syntax_help`：显示 CPGQL 语法帮助、提示和常见错误修复。 ### 代码浏览 - `list_methods`：列出方法/函数，支持可选的正则/文件过滤器。 - `list_files`：以分页树状视图显示源文件。 - `get_method_source`：获取指定名称方法的所有源代码。 - `list_calls`：列出函数间的调用点（caller → callee）。 - `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`：检测从 sources 到 sinks 的数据流（污点分析）。 - `get_program_slice`：为某个调用构建向后/向前程序切片。 - `get_variable_flow`：追踪某位置变量的数据依赖关系。 - `find_bounds_checks`：搜索缓冲区访问附近的边界检查。 - `find_use_after_free`：启发式检测释放后使用模式。 - `find_double_free`：检测潜在的二次释放问题。 - `find_null_pointer_deref`：查找可能的空指针解引用。 - `find_integer_overflow`：检测整数溢出模式。 ### 导出与报告 - `store_findings`：解析分析结果并将其存储到数据库中。 - `export_sarif`：以 SARIF 格式导出高置信度的发现结果。 ## 贡献与测试 感谢您的贡献！以下是运行测试和贡献代码的快速指南。 ### 前置条件 - 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 处于运行状态） ``` # 在后台启动 MCP server python main.py & # 运行集成测试 pytest tests/integration -q # 停止 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` 进行配置。 ### 环境变量 关键设置（可选 - 显示为默认值）： ``` # 服务器 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 生成 CPG_GENERATION_TIMEOUT=600 MAX_REPO_SIZE_MB=500 # 查询 QUERY_TIMEOUT=30 QUERY_CACHE_ENABLED=true QUERY_CACHE_TTL=300 # 遥测（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 进行本地开发 ``` # 启动 Jaeger（在 http://localhost:16686 提供 UI） docker run -d --name jaeger \ -p 16686:16686 \ -p 4317:4317 \ jaegertracing/all-in-one:latest # 启动 CodeBadger 并启用遥测 OTEL_ENABLED=true python main.py ``` ### 追踪内容 | Span | 描述 | |------|-------------| | `tools/call {name}` | 每次 MCP 工具调用（通过 FastMCP 自动进行） | | `cpg.generate` | 完整的 CPG 生成流程 | | `cpg.joern_cli_exec` | Docker 内部的 Joern CLI 命令执行 | | `cpg.spawn_server` | Joern 服务器实例创建 | | `cpg.load_cpg` | 将 CPG 文件加载到 Joern 服务器 | | `query.execute` | CPGQL 查询执行，包含耗时和成功属性 | ### 配置参考 | 设置 | 环境变量 | 默认值 | 描述 | |---------|-------------|---------|-------------| | `enabled` | `OTEL_ENABLED` | `false` | 启用/禁用遥测 | | `service_name` | `OTEL_SERVICE_NAME` | `codebadger` | 追踪中的服务名称 | | `otlp_endpoint` | `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4317` | OTLP collector 端点 | | `otlp_protocol` | `OTEL_EXPORTER_OTLP_PROTOCOL` | `grpc` | 导出协议（`grpc` 或 `http/protobuf`） | 当遥测禁用时（默认），所有追踪操作均为无操作，零开销。

标签：C/C++, Claude, CPG, CVE检测, DevSecOps, Docker, Ghidra, GitHub Copilot, Go, Joern, Kotlin, LLM工具, MCP服务器, NIDS, OpenVAS, PHP, Python, Ruby, Ruby工具, Swift, 上游代理, 事务性I/O, 云资产清单, 人工智能辅助, 代码安全, 代码属性图, 代码智能, 可配置连接, 多语言支持, 安全专业人员, 安全测试框架, 安全防御评估, 容器化, 对称加密, 无后门, 浏览器安全, 漏洞枚举, 用户代理, 知识库, 程序分析, 网络安全, 自动化审计, 请求拦截, 逆向工具, 逆向工程, 错误基检测, 隐私保护, 静态代码分析