bluerock-io/bluerock
GitHub: bluerock-io/bluerock
BlueRock 是一个零代码改动的 Python MCP 服务器运行时安全传感器，通过捕获工具调用、会话生命周期和带 SHA-256 校验的模块导入事件，为 AI 代理部署提供即插即用的安全可见性。
Stars: 29 | Forks: 5
# BlueRock MCP Python Hooks
[](https://pypi.org/project/bluerock/)
[](https://pypi.org/project/bluerock/)
[](LICENSE)
**轻量级 Python MCP 服务器运行时安全传感器。** 监控您的应用程序进行的 MCP 工具调用、资源访问、会话生命周期和模块导入，无需更改任何代码，即可为每一次操作发出结构化事件。
```
pip install bluerock[oss]
mkdir -p ~/.bluerock
echo '{"enable": true, "mcp": true, "imports": true}' > ~/.bluerock/bluerock-oss.json
python -m bluepython --oss --cfg-dir ~/.bluerock your_script.py
cat ~/.bluerock/event-spool/python-*.ndjson | jq .event
```
BlueRock 会包装您的 Python 进程，并为安全敏感操作发出结构化的 NDJSON 事件。它会在您的代码运行之前的启动阶段接管 Python，因此没有任何操作会被遗漏。您的代码、您的依赖项以及它们的传递依赖项都在监控范围之内。
专为部署 MCP 代理的安全团队、AppSec 工程师和 AI 开发人员打造。无需更改一行代码，即可准确了解您的工具调用了什么、加载了哪些模块，以及在线路上传输了什么数据。适合任何想要了解其 Python 应用程序在运行时实际行为的人。
| | BlueRock | 手动日志记录 | OpenTelemetry |
|---|---|---|---|
| 代码更改 | 无 | 为每个调用埋点 | 添加 spans/traces |
| 覆盖依赖项 | 是（传递依赖） | 仅覆盖您封装的部分 | 仅覆盖您封装的部分 |
| AI/MCP 监控 | 内置（6 种事件类型） | 自己实现 | 否 |
| 导入验证 | 每个模块进行 SHA256 验证 | 否 | 否 |
| 输出格式 | NDJSON（结构化） | 临时格式 | OTLP |
## 环境要求
| 依赖 | 版本 |
|---|---|
| Python | >= 3.10 (MCP hooks 需要 3.10+) |
| Rust | stable 工具链（仅限从源码构建） |
| 操作系统 | Linux (x86_64, aarch64), macOS (arm64, x86_64) |
| Docker | 可选，用于 Grafana 仪表盘 |
## 立即体验
```
# 1. 克隆并设置
git clone https://github.com/bluerock-io/bluerock.git
cd bluerock
python3 -m venv venv && source venv/bin/activate
# 2. 安装 sensor + MCP 依赖
pip install -e "acoustic/python/"
pip install setuptools-rust && pip install acoustic/python-oss/
pip install mcp fastmcp
# 3. 创建 sensor 配置
mkdir -p ~/.bluerock
echo '{"enable": true, "mcp": true}' > ~/.bluerock/bluerock-oss.json
# 4. 运行 MCP 示例（client 启动 server，两者均被监控）
cd examples/mcp/
python -m bluepython --oss mcp_client.py --transport stdio
# 5. 查看发生的情况
cat ~/.bluerock/event-spool/python-*.ndjson | jq '.event.meta.name' | sort | uniq -c | sort -rn
```
您应该会看到诸如 `python_mcp_event`、`python_mcp_server_add`、`python_mcp_session_created`、`python_mcp_server_init` 和 `python_mcp_client_connect` 这样的事件——每一个 MCP 协议交互都会被自动捕获。
**也可以尝试导入监控：**
```
# 在配置中启用 imports
echo '{"enable": true, "mcp": true, "imports": true}' > ~/.bluerock/bluerock-oss.json
# 运行 import 监控示例
pip install requests
python -m bluepython --oss examples/core-hooks/import-monitoring/import_monitoring.py
# 查看加载的每个 module 及其 SHA-256 哈希值
cat ~/.bluerock/event-spool/python-*.ndjson \
| jq -r '.event | select(.meta.name == "python_import") | "\(.fullname) \(.version // "n/a") \(.sha256[0:16])..."'
```
## 为什么选择 BlueRock
大多数运行时检测工具侧重于可观测性（追踪 API 调用、测量延迟、收集指标）。BlueRock 则侧重于**安全**：从威胁检测的角度关注那些至关重要的操作。
- **零代码更改。** 使用 `python -m bluepython --oss your_script.py` 封装任何脚本。无需导入，无需集成 SDK。一次性配置 [传感器配置](#quick-start) 即可启用您所需的 hooks。
- **双层 Hooking。** 使用 `sys.meta_path` 监控每一次模块导入（带有 SHA256 验证），使用 `wrapt` 监控 MCP 协议。[完整版](https://www.bluerock.io/try-bluerock)中提供了额外的 hook 层（进程派生、ctypes、HTTP 框架、LLM API）。
- **全面的 MCP 覆盖。** 覆盖 stdio、HTTP 和 SSE 下的工具调用、资源访问、提示请求、会话生命周期和传输连接。
- **在代码运行前进行 Hook。** 检测机制在 Python 启动时激活。您的代码、依赖项以及它们的传递依赖所产生的操作都会发出事件。
- **开源。** Apache 2.0 许可证。检查这些 hooks，贡献新的 hooks，与您自己的工具链集成。
## 工作原理
BlueRock 通过两种机制在运行时检测您的 Python 应用程序：
- **针对 MCP 协议库的 `wrapt` 猴子补丁 (monkey-patching)**。Hooks 通过 `@wrapt.when_imported()` 进行延迟应用，因此您未使用的包不会产生任何开销。
- **用于供应链可见性的 `sys.meta_path` 导入 hooks**。每个导入的模块都会记录其 SHA-256 哈希值、版本和文件路径。
每个被 hook 的操作都会向位于 `~/.bluerock/event-spool/` 的 NDJSON 日志文件发出一个结构化 JSON 事件。事件包含完整的上下文：调用了什么、使用了什么参数、来自哪个模块以及进程 ID。
```
┌──────────────────────────────────────────────────────────────┐
│ python -m bluepython --oss your_app.py │
│ │
│ ┌──────────────┐ ┌──────────────────┐ │
│ │ import hooks │ │ MCP hooks │ │
│ │ (SHA256, │ │ (tool calls, │ │
│ │ versions) │ │ sessions, etc.) │ │
│ └──────┬───────┘ └────────┬─────────┘ │
│ └──────────────┬────────────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ bluerock-oss │ Rust DSO (libacoustic_oss) │
│ │ NDJSON writer │ │
│ └────────┬────────┘ │
│ ▼ │
│ ~/.bluerock/event-spool/*.ndjson │
└──────────────────────────────────────────────────────────────┘
│
┌─────────────┼──────────────────┐
▼ ▼ ▼
jq / grep Grafana + Loki Datadog / Splunk / SIEM
(included) (via OTLP forwarding)
```
## 安装
### 选项 A：从 PyPI 安装
```
python3 -m venv venv && source venv/bin/activate
pip install bluerock[oss]
python -m bluepython --help
python -c "import bluerock_oss; print('DSO:', bluerock_oss.get_dso_path())"
```
这会安装两个包：
- `bluerock` — Python 传感器（hooks、检测、CLI）
- `bluerock-oss` — 负责处理事件写入的 Rust DSO 后端（`libacoustic_oss.so`）
### 选项 B：从 GitHub Release Wheels 安装
对于离线安装，或者当您的平台没有可用的 PyPI wheel 时，请从 [最新发布版](../../releases/latest) 下载两个 `.whl` 文件——选择与您的 Python 版本和平台相匹配的 `bluerock_oss` wheel：
```
python3 -m venv venv && source venv/bin/activate
# 从 release wheels 安装 bluerock (pure Python sensor) + bluerock-oss (Rust DSO)
pip install bluerock--py3-none-any.whl
pip install bluerock_oss---.whl
python -m bluepython --help
python -c "import bluerock_oss; print('DSO:', bluerock_oss.get_dso_path())"
```
### 选项 C：从源码构建
适用于开发、贡献代码，或者当您的平台没有预构建的 wheel 时。
**前置条件：** Python >= 3.10、Rust 工具链、git、平台开发工具（见下方第 2 步）。
```
# 1. 克隆仓库
git clone https://github.com/bluerock-io/bluerock.git
cd bluerock
# 2. 安装平台开发工具
# Amazon Linux 2023:
sudo dnf groupinstall "Development Tools"
# Ubuntu / Debian:
sudo apt install build-essential
# openSUSE:
sudo zypper install -t pattern devel_basis
# 3. 安装 Rust toolchain（如已安装则跳过）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
export PATH="$HOME/.cargo/bin:$PATH"
rustup toolchain install stable --profile minimal
# 4. 创建 virtualenv 并安装 Python sensor
python3 -m venv venv && source venv/bin/activate
pip install -e "acoustic/python/[test]"
# 5. 构建并安装 bluerock-oss（从源码编译 Rust DSO）
pip install setuptools-rust
pip install acoustic/python-oss/
# 6. 安装 MCP + framework 依赖以运行示例和测试
pip install mcp fastmcp
# 7. 验证
python -m bluepython --help
```
两种安装方式都会产生相同的结果：一个正常运行的 `bluerock` + `bluerock-oss` 安装。传感器会通过已安装的 `bluerock_oss` Python 包自动发现 DSO。
## 卸载
对于标准的 venv 安装（推荐设置），只需一条 pip 命令即可卸载：
```
pip uninstall -y bluerock-oss bluerock
```
### 如果您启用了持久化安装
如果您还运行过 `python -m bluepython.installer install --oss` 以将传感器接入 Python 解释器启动过程（通过 `.pth` 文件，以及可选的 sitecustomize 块），请先移除它们，然后再执行 pip uninstall：
```
python -m bluepython.installer uninstall
pip uninstall -y bluerock-oss bluerock
```
两种卸载流程都会故意保留 `~/.bluerock/` 下的用户数据（传感器配置、事件池）。如果您想要彻底清除，请手动删除：
```
rm -rf ~/.bluerock
```
## 快速入门
创建一个传感器配置以启用所需的 hooks：
```
mkdir -p ~/.bluerock
cat > ~/.bluerock/bluerock-oss.json << 'EOF'
{
"enable": true,
"imports": {"enable": true, "fileslist": true},
"mcp": true
}
EOF
```
在 BlueRock 下运行任何 Python 脚本：
```
python -m bluepython --oss --cfg-dir ~/.bluerock your_script.py
```
或者运行一个 MCP 服务器模块：
```
python -m bluepython --oss --cfg-dir ~/.bluerock your_mcp_server.py
```
有关所有传感器选项，请参阅 [CONFIG.md](acoustic/python/CONFIG.md)。在此版本中，仅激活了 **MCP** 和 **Imports**。CONFIG.md 中列出的其余选项需要 [完整版](https://www.bluerock.io/try-bluerock)。
事件将写入 `~/.bluerock/event-spool/python-{pid}-{tid}.{generation}.ndjson`。可以使用 `jq` 读取它们：
```
# 所有 events（每行格式为 {"ts": "...", "event": {...}}）
cat ~/.bluerock/event-spool/python-*.ndjson | jq .event
# 仅 imports
cat ~/.bluerock/event-spool/python-*.ndjson | jq '.event | select(.meta.name == "python_import")'
# 仅 MCP events
cat ~/.bluerock/event-spool/python-*.ndjson | jq '.event | select(.meta.name | startswith("python_mcp_"))'
```
### 示例：NDJSON 事件追踪
运行 MCP 服务器会生成类似如下事件（每行一个 JSON 对象，包含在 `{"ts", "event"}` 中）：
```
// sensor startup (lifecycle event)
{"ts":"2026-04-02T10:00:00Z","event":{"meta":{"name":"sensor_startup","origin":"bluepython","sensor_id":1,"type":"sensor_lifecycle"},"pid":24241}}
// MCP server initialized
{"ts":"2026-04-02T10:00:00Z","event":{"context":{"process":{"pid":24241}},
"meta":{"name":"python_mcp_server_init","origin":"bluepython","sensor_id":1,"type":"event"},
"server":{"name":"test-mcp-server","version":"0.0.1"}}}
// tool registered on the server
{"ts":"2026-04-02T10:00:00Z","event":{"context":{"process":{"pid":24241}},
"meta":{"name":"python_mcp_server_add","origin":"bluepython","sensor_id":1,"type":"event"},
"element":{"type":"tool","name":"add","description":"Add two numbers."}}}
```
## CLI 参考
```
python3 -m bluepython --oss [OPTIONS] [script.py | -m module] [args...]
Options:
--oss Use the OSS backend (required for pip-installed bluerock)
tip: auto-detected when bluerock-oss is installed if you forget.
--cfg-dir DIR Load sensor config from DIR/bluerock-oss.json (see CONFIG.md)
-m MODULE Run a Python module instead of a script
--debug Print debug logs to stderr
--install Install bluerock autostart (sitecustomize)
--uninstall Remove bluerock autostart
```
### 编程式使用
您也可以直接在 Python 代码中导入 bluepython。当您想要检测特定的入口点，而不想从命令行封装整个进程时，这非常有用：
```
import bluepython
# 你的 MCP server 代码
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("my-server")
@mcp.tool()
def add(a: int, b: int) -> int:
return a + b
mcp.run(transport="stdio")
```
导入后，bluepython 会在当前进程中激活其 hooks。事件照常写入到 `~/.bluerock/event-spool/`。
### 持久化安装 (sitecustomize)
## 监控内容
### 本版本中已激活
| 类别 | 事件 | 捕获内容 |
|----------|--------|-----------------|
| **MCP** | `python_mcp_server_init`, `python_mcp_server_add`, `python_mcp_event`, `python_mcp_session_created`, `python_mcp_session_terminated`, `python_mcp_client_connect` | 工具调用、资源访问、提示请求、会话生命周期、传输连接 |
| **Imports** | `python_import` | 每次带有名称、路径、版本和 SHA256 的模块导入 |
框架 hooks 使用 `@wrapt.when_imported()`。Hook 模块仅在您的应用程序实际导入该框架时加载。结合针对每个功能的配置开关（`cfg.sensor_config.enabled("mcp")`），这意味着：
- 未安装的框架 = 零开销（wrapt 门控）
- 已禁用的功能 = 接近零开销（配置门控）
- 已启用 + 已安装 = 完整监控
### MCP 事件详情
BlueRock 捕获覆盖完整协议生命周期的 6 种 MCP 事件类型：
| 事件 | 触发时机 | 显示内容 |
|-------|---------------|-------------|
| `python_mcp_server_init` | 服务器启动时 | 服务器名称、版本 |
| `python_mcp_server_add` | 注册工具/资源/提示时 | 元素名称、类型、参数 |
| `python_mcp_event` | 任何请求、响应或通知时 | 带有会话 + 方向的完整协议消息 |
| `python_mcp_session_created` | 客户端或服务器会话打开时 | 会话 ID |
| `python_mcp_session_terminated` | 会话关闭时 | 会话 ID |
| `python_mcp_client_connect` | 客户端连接到服务器时 | 传输类型 (stdio/http/sse)、URL 或命令 |
`python_mcp_event` 包含覆盖双向的 10 种子类型——完整的属性模式请参阅 [EVENTS.md](acoustic/python/EVENTS.md)。
### 导入事件详情
每条 `import` 语句都会生成一个 `python_import` 事件：
| 字段 | 显示内容 |
|-------|-------------|
| `fullname` | 完全限定的模块名称（例如，`urllib3.util.retry`） |
| `path` | 传递给导入系统的查找路径 |
| `file` | 解析后的模块的绝对文件系统路径 |
| `pkg` | 顶级包名（例如，`urllib3`） |
| `version` | 来自元数据的已安装包版本（如果可用） |
| `sha256` | 磁盘上模块文件的 SHA-256 哈希值——检测运行间的篡改 |
| `hash_changed` | 当 SHA-256 与此模块上次看到的哈希值不同时为 `true` |
这涵盖了您的代码、您的依赖项及其传递依赖项。一条简单的 `import requests` 就会为 `requests`、`urllib3`、`charset_normalizer`、`certifi` 等生成事件——每个都带有自己的 SHA-256 指纹。
请参阅 [导入监控示例](examples/core-hooks/import-monitoring/)，获取带有 `jq` 查询的可运行演示。
## 仪表盘 (Grafana + Loki)
BlueRock 附带了一个 Grafana 仪表盘，可实时可视化事件。它通过 Docker Compose 在本地运行。
**您需要：** Docker、Docker Compose、Docker buildx 插件 >= 0.17.0，以及 [`just`](https://github.com/casey/just)（一个命令运行器）。
```
# 安装 just（如尚未安装）
# macOS
brew install just
# Linux
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
```
### 快速演示（无需传感器）
重放样本事件，这样您无需运行任何 MCP 服务器即可查看仪表盘：
```
cd observe/spoolfile2loki
just build # or: docker build -t spoolfile2loki:latest .
cd ../deploy
./deploy.sh mock # start Grafana + Loki + sample data
```
打开 [http://localhost:3000](http://localhost:3000)（登录：`admin` / `admin`）。“BlueRock Acoustic”仪表盘会显示事件时间线、工具调用细分和会话生命周期面板。
### 实时模式（来自传感器的真实事件）
将仪表盘指向您的实际事件池：
```
cd observe/deploy
./deploy.sh dir ~/.bluerock/event-spool
```
现在，在另一个终端中运行 BlueRock 下的任何脚本——事件会在几秒钟内出现在 Grafana 中。
### 停止并移除
```
cd observe/deploy
./deploy.sh down # removes containers and volumes
```
## 事件格式
NDJSON 日志中的每一行都是一个封装了事件并带有时间戳的信封：
```
{
"ts": "2026-04-02T10:00:00.123456Z",
"event": {
"meta": {
"name": "python_mcp_server_add",
"type": "event",
"origin": "bluepython",
"sensor_id": 1,
"source_event_id": 5
},
"context": {
"process": { "pid": 12345 }
},
"element": {
"type": "tool",
"name": "add",
"description": "Add two numbers.",
"parameters": { "a": "integer", "b": "integer" }
}
}
}
```
在读取事件时，请使用 `jq .event` 解开信封。
- `event.meta.name` — 事件类型（见上表）
- `event.meta.type` — `"event"`（可操作的）、`"nonactionable"`（遥测）或 `"sensor_lifecycle"`（信息性）
- `event.meta.source_event_id` — 每个进程单调递增的计数器
- `event.context.process.pid` — 进程 ID
- 其余字段为特定于事件的（见 [EVENTS.md](acoustic/python/EVENTS.md)）
## 实用手册
有关可运行的演示，请参阅 [`examples/`](examples/) 目录：
- **[导入监控](examples/core-hooks/import-monitoring/)** — 使用 SHA-256 哈希和版本追踪每一次模块导入
- **[MCP 示例](examples/mcp/)** — 多传输示例（stdio、带认证的 HTTP、SSE），通用客户端，天气服务器
- **[MCP 监控](examples/ai-hooks/mcp-monitoring/)** — 用于快速测试的简单客户端/服务器对
每个示例都是一个独立的脚本，您可以使用 `python -m bluepython --oss