金大哥 - code-firewall-mcp MCP 详情

article

README

🚀 Code Firewall MCP

Code Firewall MCP 是一款基于结构相似度的代码安全过滤器，适用于 MCP（模型上下文协议）。它通过将代码结构与已知的危险模式黑名单进行比对，在危险代码模式到达执行工具之前将其拦截。

🚀 快速开始

Code Firewall MCP 是一个基于结构相似度的 MCP（模型上下文协议）代码安全过滤器。它通过将代码结构与已知的危险模式黑名单进行比较，在危险代码模式到达执行工具之前将其阻止。

工作原理

flowchart LR
    A[Code<br/>file/string] --> B[Parse & Normalize<br/>tree-sitter]
    B --> C[Embed<br/>Ollama]
    C --> D{Similarity Check<br/>vs Blacklist}
    D -->|≥ threshold| E[🚫 BLOCKED]
    D -->|< threshold| F[✅ ALLOWED]
    F --> G[Execution Tools<br/>rlm_exec, etc.]

    style E fill:#ff6b6b,color:#fff
    style F fill:#51cf66,color:#fff
    style D fill:#339af0,color:#fff

解析：使用 tree-sitter 将代码解析为具体语法树（CST）。
归一化：去除标识符和字面量，得到结构骨架。
嵌入：通过 Ollama 对归一化后的结构进行嵌入。
比较：与 ChromaDB 中的黑名单模式进行比较。
拦截：如果相似度超过阈值，则拦截；否则允许执行。

关键洞察

像 os.system("rm -rf /") 和 os.system("ls") 这样的代码模式具有相同的结构。通过归一化去除特定的命令和标识符，我们可以检测到危险模式，而不管使用的具体参数如何。

在归一化过程中，对安全敏感的标识符会被保留（例如 eval、exec、os、system、subprocess、Popen、shell），以确保嵌入对危险模式具有区分性。

📦 安装指南

快速开始

选项 1：PyPI（推荐）

uvx code-firewall-mcp
# 或者
pip install code-firewall-mcp

选项 2：Claude Desktop 一键安装 从 Releases 下载 .mcpb 文件，然后双击安装。

选项 3：从源代码安装

git clone https://github.com/egoughnour/code-firewall-mcp.git
cd code-firewall-mcp
uv sync

连接到 Claude Code / Claude Desktop

将以下内容添加到 ~/.claude/.mcp.json（Claude Code）或 claude_desktop_config.json（Claude Desktop）中：

{
  "mcpServers": {
    "code-firewall": {
      "command": "uvx",
      "args": ["code-firewall-mcp"],
      "env": {
        "FIREWALL_DATA_DIR": "~/.code-firewall",
        "OLLAMA_URL": "http://localhost:11434"
      }
    }
  }
}

要求

Python 3.10+（由于 onnxruntime 兼容性，需小于 3.14）
Ollama（用于嵌入）
ChromaDB（用于向量存储）
tree-sitter（可选，用于更好的解析）

设置 Ollama（嵌入）

Code Firewall 可以在带有 Apple Silicon 的 macOS 上自动安装和配置 Ollama。有两种安装方法：

方法 1：使用 Homebrew 安装

# 1. 检查系统要求
firewall_system_check()

# 2. 通过 Homebrew 安装
firewall_setup_ollama(install=True, start_service=True, pull_model=True)

此操作的作用：

通过 Homebrew 安装 Ollama (brew install ollama)
将 Ollama 作为托管的后台服务启动
拉取 nomic-embed-text 模型用于嵌入

方法 2：直接下载（无需 sudo）

# 1. 检查系统
firewall_system_check()

# 2. 通过直接下载安装 - 无需 sudo，无需 Homebrew
firewall_setup_ollama_direct(install=True, start_service=True, pull_model=True)

此操作的作用：

从 https://ollama.com 下载 Ollama
解压到 ~/Applications/（无需管理员权限）
通过 ollama serve 启动 Ollama
拉取 nomic-embed-text 模型

手动设置

# 安装 Ollama
brew install ollama
# 或者从 https://ollama.ai 下载

# 启动服务
brew services start ollama
# 或者：ollama serve

# 拉取嵌入模型
ollama pull nomic-embed-text

# 验证
firewall_ollama_status()

💻 使用示例

`firewall_check`

检查代码文件是否可以安全地传递给执行工具。

result = await firewall_check(file_path="/path/to/script.py")
# 返回: {allowed: bool, blocked: bool, similarity: float, ...}

`firewall_check_code`

直接检查代码字符串（无需文件）。

result = await firewall_check_code(
    code="import os; os.system('rm -rf /')",
    language="python"
)

`firewall_blacklist`

将危险模式添加到黑名单中。

result = await firewall_blacklist(
    code="os.system(arbitrary_command)",
    reason="Arbitrary command execution",
    severity="critical"
)

`firewall_record_delta`

记录接近匹配的变体，以增强分类器。

result = await firewall_record_delta(
    code="subprocess.run(['ls', '-la'])",
    similar_to="abc123",
    notes="Legitimate use case for file listing"
)

`firewall_list_patterns`

列出黑名单或增量集合中的模式。

`firewall_remove_pattern`

从黑名单或增量集合中移除模式。

`firewall_status`

获取防火墙状态和统计信息。

📚 详细文档

工具

设置与状态工具

| 工具 | 用途 | |------|---------| | firewall_system_check | 检查系统要求 — 验证 macOS、Apple Silicon、内存 | | firewall_setup_ollama | 通过 Homebrew 安装 — 托管服务，自动更新 | | firewall_setup_ollama_direct | 通过直接下载安装 — 无需 sudo，完全无头模式 | | firewall_ollama_status | 检查 Ollama 可用性 — 验证嵌入是否准备好 |

防火墙工具

| 工具 | 用途 | |------|---------| | firewall_check | 检查代码文件是否可以安全执行 | | firewall_check_code | 直接检查代码字符串（无需文件） | | firewall_blacklist | 将危险模式添加到黑名单中 | | firewall_record_delta | 记录接近匹配的变体，以增强分类器 | | firewall_list_patterns | 列出黑名单或增量集合中的模式 | | firewall_remove_pattern | 从黑名单或增量集合中移除模式 | | firewall_status | 获取防火墙状态和统计信息 |

配置

环境变量： | 变量 | 默认值 | 描述 | |----------|---------|-------------| | FIREWALL_DATA_DIR | /tmp/code-firewall | 数据存储目录 | | OLLAMA_URL | http://localhost:11434 | Ollama 服务器 URL | | EMBEDDING_MODEL | nomic-embed-text | Ollama 嵌入模型 | | SIMILARITY_THRESHOLD | 0.85 | 拦截阈值（0 - 1） | | NEAR_MISS_THRESHOLD | 0.70 | 接近匹配记录阈值 |

使用模式

作为大规模上下文 MCP 的预过滤器

在将代码传递给 rlm_exec 之前，使用 code-firewall-mcp 作为守门人：

# 1. 检查代码安全性
check = await firewall_check_code(user_code)

if check["blocked"]:
    print(f"BLOCKED: {check['reason']}")
    return

# 2. 如果允许，继续执行
result = await rlm_exec(code=user_code, context_name="my-context")

与大规模上下文 MCP 集成

安装带有防火墙集成的大规模上下文 MCP：

pip install massive-context-mcp[firewall]

启用后，rlm_exec 在执行前会自动检查代码是否符合防火墙规则。

构建黑名单

黑名单通过以下方式增长：

初始种子：添加已知的危险模式。
审计反馈：当 rlm_auto_analyze 发现安全问题时，添加模式。
增量增强：记录接近匹配的变体，以改善分类边界。

# 在安全审计发现问题后
await firewall_blacklist(
    code=dangerous_code,
    reason="Command injection via subprocess",
    severity="critical"
)

结构归一化

flowchart TD
    subgraph Input
        A1["os.system('rm -rf /')"]
        A2["os.system('ls -la')"]
        A3["os.system(user_cmd)"]
    end

    subgraph Normalization
        B[Strip literals & identifiers<br/>Preserve security keywords]
    end

    subgraph Output
        C["os.system('S')"]
    end

    A1 --> B
    A2 --> B
    A3 --> B
    B --> C

    style C fill:#ff922b,color:#fff

归一化器会去除：

标识符：my_var → _（安全敏感的标识符除外）
字符串字面量："hello" → "S"
数字：42 → N
注释：完全移除

保留的标识符（用于更好的模式匹配）：

eval、exec、compile、__import__
os、system、popen、subprocess、Popen、shell
open、read、write、socket、connect
getattr、setattr、__globals__、__builtins__
以及更多安全敏感的名称...

示例：

# 原始代码
subprocess.run(["curl", url, "-o", output_file])

# 归一化后（保留 'subprocess' 和 'run'）
subprocess.run(["S", _, "S", _])

subprocess.run(["curl", ...]) 和 subprocess.run(["wget", ...]) 归一化后具有相同的结构，因此将其中一个列入黑名单可以同时拦截两者。

📄 许可证

本项目采用 MIT 许可证。

code-firewall-mcp