code-firewall-mcp

Code Firewall MCP

基于结构相似性的代码安全过滤器，适用于 MCP（Model Context Protocol）。通过将代码结构与已知恶意模式黑名单进行比较，在危险代码到达执行工具之前将其拦截。

工作原理

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

1. 解析：使用 tree-sitter 将代码解析为具体语法树（CST）
2. 规范化：去除标识符和字面量 → 结构骨架
3. 嵌入：通过 Ollama 对规范化后的结构生成嵌入
4. 比较：与 ChromaDB 中的黑名单模式进行比较
5. 如果相似度超过阈值则拦截，否则允许

核心洞察

像 os.system("rm -rf /") 和 os.system("ls") 这样的代码模式具有相同的结构。通过规范化处理，去除具体命令和标识符，我们可以检测危险模式，而不受具体参数的影响。

规范化期间会保留安全敏感标识符（例如 eval、exec、os、system、subprocess、Popen、shell），以确保嵌入能够区分危险模式。

安装

快速开始

选项 1：PyPI（推荐）

uvx code-firewall-mcp
# or
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. Check system requirements
firewall_system_check()

# 2. Install via Homebrew
firewall_setup_ollama(install=True, start_service=True, pull_model=True)

此操作会：

• 通过 Homebrew 安装 Ollama（brew install ollama）
• 将 Ollama 作为受管理的后台服务启动
• 拉取 nomic-embed-text 模型以生成嵌入

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

# 1. Check system
firewall_system_check()

# 2. Install via direct download - no sudo, no Homebrew
firewall_setup_ollama_direct(install=True, start_service=True, pull_model=True)

此操作会：

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

手动设置

# Install Ollama
brew install ollama
# or download from https://ollama.ai

# Start service
brew services start ollama
# or: ollama serve

# Pull embedding model
ollama pull nomic-embed-text

# Verify
firewall_ollama_status()

工具

设置与状态工具

工具	用途
firewall_system_check	检查系统要求 — 验证 macOS、Apple Silicon 和 RAM
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_check

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

result = await firewall_check(file_path="/path/to/script.py")
# Returns: {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_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	近似误判记录阈值

使用模式

为 massive-context-mcp 预先筛选

在将代码传递给 rlm_exec 之前，将 code-firewall-mcp 用作把关工具：

# 1. Check code safety
check = await firewall_check_code(user_code)

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

# 2. If allowed, proceed with execution
result = await rlm_exec(code=user_code, context_name="my-context")

与 massive-context-mcp 集成

安装集成防火墙的 massive-context-mcp：

pip install massive-context-mcp[firewall]

启用后，rlm_exec 会在执行前自动使用防火墙检查代码。

构建黑名单

黑名单会随着使用不断扩充：

1. 初始填充：添加已知的危险模式
2. 审计反馈：当 rlm_auto_analyze 发现安全问题时，添加相应模式
3. 增量强化：记录近似误判，以改进分类边界

# After security audit finds issues
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__
• 以及更多安全敏感名称……

示例：

# Original
subprocess.run(["curl", url, "-o", output_file])

# Normalized (preserves 'subprocess' and 'run')
subprocess.run(["S", _, "S", _])

subprocess.run(["curl", ...]) 和 subprocess.run(["wget", ...]) 都会规范化为相同的结构，因此将其中一个加入黑名单即可拦截两者。

许可证

MIT