Code Firewall MCP

🚀 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

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
# 或者
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

獲取防火牆狀態和統計信息。

📚 詳細文檔

工具

設置與狀態工具

防火牆工具

配置

環境變量：

使用模式

作為大規模上下文 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 在執行前會自動檢查代碼是否符合防火牆規則。

構建黑名單

黑名單通過以下方式增長：

1. 初始種子：添加已知的危險模式。
2. 審計反饋：當 rlm_auto_analyze 發現安全問題時，添加模式。
3. 增量增強：記錄接近匹配的變體，以改善分類邊界。

# 在安全審計發現問題後
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 許可證。