内容
# ebpf-mcp-tracer
这是一个MCP服务器，允许LLM编写和运行bpftrace脚本，针对您的内核，通过显式的探测器允许列表和严格的执行超时进行控制。
它**不**编译原始的eBPF C。bpftrace是引擎——它已经处理了BTF/CO-RE可移植性、钩子附件和环形缓冲区到文本的格式化，因此这个项目是在其上的协调和安全层，而不是从头开始的eBPF编译器。
`ebpf-mcp-tracer`是一个安全的MCP服务器，通过为`bpftrace`编排，实现自然语言的内核级可观察性。它不编译原始的eBPF C，而是利用`bpftrace`的内置安全性和可移植性，同时通过显式的探测器允许列表、阻止危险的内置函数和严格的执行超时来强制执行严格的防护措施。通过在本地stdio上提供用于探测器发现、预运行验证和定时跟踪执行的简单工具，它使AI代理能够安全地调试复杂的系统瓶颈和分析进程行为，而无需深入的eBPF专业知识或牺牲主机稳定性。
## 提供的内容
三个工具，可由任何MCP客户端（Claude Desktop等）调用：
- `list_probes(pattern)` -- 只读列出内核探测器（`bpftrace -l`）
- `validate_script(script)` -- 安全允许列表检查 + 编译前干运行（`bpftrace -d`，无附件）
- `run_trace(script, duration_seconds)` -- 附件并流式传输事件，最长60秒，然后分离并返回解析的JSON事件
以及一个资源：`ebpf://system/kernel-info`（内核版本，bpftrace可用性）。
## 在您的机器上设置
1. 安装bpftrace：
```bash
sudo apt update && sudo apt install -y bpftrace
```
确认它单独工作：
```bash
sudo bpftrace -e 'BEGIN { printf("it works\n"); exit(); }'
```
2. 安装Python依赖：
```bash
cd ebpf-mcp-tracer
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
3. **权限。** bpftrace需要将BPF程序加载到内核中，这通常需要root权限。你有两个选项：
- **最简单：** 将MCP服务器进程本身作为root运行。适合个人电脑，不适合共享机器。
- **更好，如果你的内核是5.8+：** 为venv的python二进制授予bpftrace所需的特定能力，而不是完全root：
```bash
sudo setcap cap_bpf,cap_perfmon,cap_sys_resource+ep $(readlink -f venv/bin/python3)
```
注意，这为*任何*由该确切python二进制运行的脚本授予了这些能力 - 请保持venv专门用于此项目。
4. 在将其连接到客户端之前，直接测试服务器：
```bash
python3 -m mcp dev src/ebpf_mcp_tracer/server.py
```
或原始运行并通过stdio与其通信：
```bash
python3 src/ebpf_mcp_tracer/server.py
```
5. 将您的MCP客户端指向它。示例Claude Desktop配置条目：
```json
{
"mcpServers": {
"ebpf-tracer": {
"command": "/absolute/path/to/ebpf-mcp-tracer/venv/bin/python3",
"args": ["/absolute/path/to/ebpf-mcp-tracer/src/ebpf_mcp_tracer/server.py"]
}
}
}
```
（根据当前Claude Desktop文档验证确切的配置文件位置和密钥名称 - 此内容已更改过。）
## 运行测试
安全允许列表测试不需要特权和bpftrace安装：
```bash
pip install pytest
python3 -m pytest tests/test_safety.py -v
```
在开发过程中，还存在一个伪造的bpftrace shim `tests/fakebin/bpftrace`，用于在不使用真实内核的情况下，测试`engine.py`中的子进程/超时/JSON解析逻辑。您不需要它，一旦您安装了真实的二进制文件，但如果您想在不使用root的情况下测试`engine.py`的更改，它就可用。
## 扩展探测器允许列表
`src/ebpf_mcp_tracer/safety.py`具有`ALLOWED_PROBE_PATTERNS`。LLM可以附加的每个探测器都必须与其中一个正则表达式匹配 - 故意没有通配符。要添加新函数：
1. 查找它执行的操作并确认它是安全的（只读跟踪，不会滥用来泄露跨进程的秘密或在负载下降低性能）。
2. 添加显式模式，例如`r"^kprobe:tcp_v4_connect$"`。
3. 重新运行安全测试。
不要添加`kprobe:*`或`kprobe:do_*`样式的通配符 - 这会破坏允许列表的意义。
## 更多文档
请参阅 https://github.com/blackdragoon26/ebpf-mcp-tracer/blob/main/INSTALL.md
## 故意不包含的内容
- 任何地方都没有`--unsafe`标志，这意味着`system()`、`override()`和其他一些危险的bpftrace内置函数是无法访问的，即使允许列表正则表达式检查可能存在漏洞。这是在两个独立层面上故意强制执行的。
- 没有自动验证错误到LLM重试循环。`validate_script`返回原始的bpftrace编译错误；将自动“LLM读取错误并重试”的循环连接起来是一个自然的下一步骤，一旦您手动使用了它几次，并对实际出现的错误有了感觉。
- 没有网络暴露。此仅stdio通信。如果您想使其稍后可远程访问，那是一个独立的身份验证/访问控制项目 - 不要在没有单独思考的情况下添加端口。
