Pipelock

🚀 Pipelock

Pipelock 是一款開源的 AI 代理防火牆，採用單二進制文件，無需運行時依賴。它能有效防止 AI 代理的密鑰洩露和惡意請求，為 AI 應用提供安全保障。

🚀 快速開始

安裝方式

# macOS / Linux
brew install luckyPipewrench/tap/pipelock

# 或者下載二進制文件（無依賴）
# 請查看 https://github.com/luckyPipewrench/pipelock/releases

# 或者使用 Docker
docker pull ghcr.io/luckypipewrench/pipelock:latest

# 或者從源代碼構建（需要 Go 1.24+）
go install github.com/luckyPipewrench/pipelock/cmd/pipelock@latest

30 秒快速體驗

# 1. 生成配置文件
pipelock generate config --preset balanced > pipelock.yaml

# 2. 此請求應被阻止（DLP 檢測到偽造的 API 密鑰）
pipelock check --config pipelock.yaml --url "https://example.com/?key=sk-ant-api03-fake1234567890"

# 3. 此請求應被允許（乾淨的 URL，無敏感信息）
pipelock check --config pipelock.yaml --url "https://docs.python.org/3/"

正向代理模式（無需更改代碼，適用於任何 HTTP 客戶端）

正向代理會攔截標準的 HTTPS_PROXY 流量。在配置文件中啟用該模式，然後將任何進程指向 Pipelock：

# 編輯 pipelock.yaml：將 forward_proxy.enabled 設置為 true
pipelock run --config pipelock.yaml

export HTTPS_PROXY=http://127.0.0.1:8888
export HTTP_PROXY=http://127.0.0.1:8888

# 現在每個 HTTP 請求都會通過 Pipelock 的掃描器
curl "https://example.com/?key=sk-ant-api03-fake1234567890"  # 被阻止

無需 SDK、包裝器或代碼更改。只要代理使用 HTTP 協議，Pipelock 就能對其進行掃描。

獲取代理模式（適用於使用專用獲取工具的代理）

# 啟動代理（代理連接到 localhost:8888/fetch?url=...）
pipelock run --config pipelock.yaml

# 實現完全網絡隔離（代理只能訪問 Pipelock）
pipelock generate docker-compose --agent claude-code -o docker-compose.yaml
docker compose up

驗證版本完整性（SLSA 來源證明 + SBOM）

每個版本都包含 SLSA 構建來源證明和 SBOM（CycloneDX）。使用 GitHub CLI 進行驗證：

# 驗證下載的二進制文件
gh attestation verify pipelock_*_linux_amd64.tar.gz --owner luckyPipewrench

# 驗證容器鏡像（替換為實際的版本號）
gh attestation verify oci://ghcr.io/luckypipewrench/pipelock:<version> --owner luckyPipewrench

✨ 主要特性

9 層 URL 掃描器

每個請求都會經過以下檢查：協議驗證、域名黑名單、DLP 模式匹配（內置 36 種 API 密鑰、令牌和憑證的匹配模式）、路徑熵分析、子域名熵分析、SSRF 防護（防止 DNS 重綁定）、按域名限速、URL 長度限制和按域名數據預算控制。

DLP 在 DNS 解析之前運行，確保在任何 DNS 查詢離開代理之前捕獲敏感信息。完整的規避測試矩陣請參考 docs/bypass-resistance.md。

響應掃描

獲取的內容在到達代理之前會進行提示注入掃描。通過 6 遍歸一化處理，可捕獲零寬度字符規避、同形替代、字母替換編碼和 Base64 包裝的有效負載。支持的操作包括：block（阻止）、strip（去除）、warn（警告）或 ask（人工確認）。

MCP 代理

對任何 MCP 服務器進行雙向掃描。支持三種傳輸模式：標準輸入輸出子進程包裝、可流式 HTTP 橋接和 HTTP 反向代理。對客戶端請求進行 DLP 洩漏檢查，對服務器響應進行注入掃描，並檢查 tools/list 響應是否存在中毒描述和會話中惡意更改。

# 包裝本地 MCP 服務器（標準輸入輸出）
pipelock mcp proxy --config pipelock.yaml -- npx -y @modelcontextprotocol/server-filesystem /tmp

# 代理遠程 MCP 服務器（HTTP）
pipelock mcp proxy --upstream http://localhost:8080/mcp

# 組合模式（獲取/正向代理 + MCP 在不同端口）
pipelock run --config pipelock.yaml --mcp-listen 0.0.0.0:8889 --mcp-upstream http://localhost:3000/mcp

MCP 工具策略

預執行規則可在危險工具調用到達 MCP 服務器之前進行阻止。內置 17 條規則，涵蓋破壞性操作、憑證訪問、反向 shell、持久化機制和編碼命令執行。內置 shell 混淆檢測功能。

工具調用鏈檢測

檢測 MCP 工具調用序列中的攻擊模式。內置 10 種模式，涵蓋偵察、憑證竊取、數據暫存、持久化和數據外洩鏈。使用可配置間隙容忍度的子序列匹配，確保插入無害調用不會逃避檢測。

緊急開關

提供四種獨立的激活源（配置文件、SIGUSR1、哨兵文件和遠程 API）實現緊急全拒絕功能。任何一個激活源生效都會阻止所有流量。API 可以在單獨的端口上運行，防止代理禁用自己的緊急開關。

# 從操作機器激活
curl -X POST http://localhost:9090/api/v1/killswitch \
  -H "Authorization: Bearer TOKEN" -d '{"active": true}'

事件發射

將審計事件轉發到外部系統（SIEM、Webhook 接收器、Syslog）。事件採用即發即棄模式，不會阻塞代理。每個事件在適用情況下包含 MITRE ATT&CK 技術 ID（如 T1048 表示數據外洩，T1059 表示注入，T1195.002 表示供應鏈攻擊）。

詳細的日誌架構、轉發模式和示例 SIEM 查詢請參考 docs/guides/siem-integration.md。

更多特性

📦 安裝指南

不同環境安裝方式

# macOS / Linux
brew install luckyPipewrench/tap/pipelock

# 或者下載二進制文件（無依賴）
# 請查看 https://github.com/luckyPipewrench/pipelock/releases

# 或者使用 Docker
docker pull ghcr.io/luckypipewrench/pipelock:latest

# 或者從源代碼構建（需要 Go 1.24+）
go install github.com/luckyPipewrench/pipelock/cmd/pipelock@latest

驗證版本完整性

# 驗證下載的二進制文件
gh attestation verify pipelock_*_linux_amd64.tar.gz --owner luckyPipewrench

# 驗證容器鏡像（替換為實際的版本號）
gh attestation verify oci://ghcr.io/luckypipewrench/pipelock:<version> --owner luckyPipewrench

💻 使用示例

基礎用法

# 生成配置文件
pipelock generate config --preset balanced > pipelock.yaml

# 檢查 URL
pipelock check --config pipelock.yaml --url "https://example.com/?key=sk-ant-api03-fake1234567890"

高級用法

正向代理模式

# 編輯 pipelock.yaml：將 forward_proxy.enabled 設置為 true
pipelock run --config pipelock.yaml

export HTTPS_PROXY=http://127.0.0.1:8888
export HTTP_PROXY=http://127.0.0.1:8888

# 現在每個 HTTP 請求都會通過 Pipelock 的掃描器
curl "https://example.com/?key=sk-ant-api03-fake1234567890"  # 被阻止

獲取代理模式

# 啟動代理（代理連接到 localhost:8888/fetch?url=...）
pipelock run --config pipelock.yaml

# 實現完全網絡隔離（代理只能訪問 Pipelock）
pipelock generate docker-compose --agent claude-code -o docker-compose.yaml
docker compose up

MCP 代理

# 包裝本地 MCP 服務器（標準輸入輸出）
pipelock mcp proxy --config pipelock.yaml -- npx -y @modelcontextprotocol/server-filesystem /tmp

# 代理遠程 MCP 服務器（HTTP）
pipelock mcp proxy --upstream http://localhost:8080/mcp

# 組合模式（獲取/正向代理 + MCP 在不同端口）
pipelock run --config pipelock.yaml --mcp-listen 0.0.0.0:8889 --mcp-upstream http://localhost:3000/mcp

📚 詳細文檔

配置參考

Configuration Reference 包含所有配置字段、默認值、熱重載行為和預設配置。

部署方案

Deployment Recipes 提供 Docker Compose、K8s 邊車 + NetworkPolicy、iptables、macOS PF 等部署方案。

繞過抗性

Bypass Resistance 介紹已知的規避技術、緩解措施和實際侷限性。

已知攻擊攔截

Known Attacks Blocked 展示實際攻擊的重現代碼片段以及阻止這些攻擊的 Pipelock 配置。

策略規範

Policy Spec v0.1 定義了可移植的代理防火牆策略格式。

SIEM 集成

SIEM Integration 包含日誌架構、轉發模式和 KQL/SPL/EQL 查詢示例。

指標參考

Metrics Reference 介紹所有 30 個 Prometheus 指標和警報規則模板。

OWASP 映射

OWASP Mapping 展示 Pipelock 對 OWASP Agentic AI Top 10 的覆蓋情況。

比較分析

Comparison 對比 Pipelock 與 agent-scan、srt、agentsh、MCP Gateway 等工具的差異。

發現抑制

Finding Suppression 介紹規則名稱、路徑匹配、內聯註釋和 CI 集成等內容。

OpenClaw 指南

OpenClaw Guide 介紹網關邊車、初始化容器和 generate mcporter 包裝的使用方法。

安全保障

Security Assurance 闡述安全模型、信任邊界和供應鏈相關內容。

傳輸模式

Transport Modes 比較所有代理模式及其掃描能力。

EU AI 法案映射

EU AI Act Mapping 提供逐條合規映射。

🔧 技術細節

工作原理

Pipelock 是一種 代理防火牆，類似於 Web 應用的 WAF，它位於 AI 代理和互聯網之間。採用 能力分離 原則：代理進程（擁有敏感信息）受到網絡限制，而 Pipelock（不持有代理敏感信息）通過 9 層掃描器管道檢查所有流量。部署（如 Docker 網絡隔離、Kubernetes NetworkPolicy 等）確保分離邊界的實施。

支持三種代理模式，使用相同的端口：

• 獲取代理 (/fetch?url=...)：Pipelock 獲取 URL 內容，提取文本，掃描響應中的提示注入，並返回乾淨的內容。適用於使用專用獲取工具的代理。
• 正向代理 (HTTPS_PROXY)：標準的 HTTP CONNECT 隧道和絕對 URI 轉發。代理可以將 Pipelock 作為系統代理，無需更改代碼。主機名掃描可在隧道打開之前捕獲被阻止的域名和 SSRF 攻擊。請求體和頭的 DLP 掃描可捕獲 POST 請求體和認證頭中的敏感信息。可選的 TLS 攔截功能可解密 CONNECT 隧道，實現完整的請求體/頭 DLP 和響應注入掃描（需要通過 pipelock tls init 和 pipelock tls install-ca 進行 CA 設置）。
• WebSocket 代理 (/ws?url=ws://...)：雙向幀掃描，對文本幀進行 DLP 和注入檢測。內置片段重組、消息大小限制、空閒超時和連接生命週期控制功能。

flowchart LR
    subgraph PRIVILEGED["Privileged Zone"]
        Agent["AI Agent\n(has API keys)"]
    end
    subgraph FETCH["Firewall Zone"]
        Proxy["Pipelock\n(no agent secrets)"]
        Scanner["Scanner Pipeline\nSSRF · Blocklist · Rate Limit\nDLP · Env Leak · Entropy · Length"]
    end
    subgraph NET["Internet"]
        Web["Web"]
    end

    Agent -- "fetch URL\nCONNECT\nor WebSocket" --> Proxy
    Proxy --> Scanner
    Scanner -- "content or\ntunnel" --> Agent
    Scanner -- "request" --> Web
    Web -- "response" --> Scanner
    Scanner -- "clean content" --> Agent

    style PRIVILEGED fill:#fee,stroke:#c33
    style FETCH fill:#efe,stroke:#3a3
    style NET fill:#eef,stroke:#33c

┌──────────────────────┐         ┌───────────────────────┐
│  PRIVILEGED ZONE     │         │  FIREWALL ZONE        │
│                      │         │                       │
│  AI Agent            │  IPC    │  Pipelock             │
│  - Has API keys      │────────>│  - No agent secrets   │
│  - Has credentials   │ fetch / │  - Full internet      │
│  - Restricted network│ CONNECT │  - Returns text       │
│                      │ /ws     │  - WS frame scanning  │
│                      │<────────│  - URL scanning       │
│  Can reach:          │ content │  - Audit logging      │
│  ✓ api.anthropic.com │         │                       │
│  ✓ discord.com       │         │  Can reach:           │
│  ✗ evil.com          │         │  ✓ Any URL            │
│  ✗ pastebin.com      │         │  But has:             │
└──────────────────────┘         │  ✗ No env secrets     │
                                 │  ✗ No credentials     │
                                 └───────────────────────┘

安全矩陣

Pipelock 支持三種模式：

各模式對不同攻擊向量的處理方式：

客觀評估：嚴格模式會阻止除白名單 API 域名之外的所有出站 HTTP 請求，因此不存在通過代理進行數據外洩的通道。平衡模式將攻擊難度從“一個 curl 命令”提高到“複雜的預先計劃攻擊”。審計模式可提供當前所沒有的可見性。Pipelock 不進行進程沙箱化或系統調用限制，它是一個內容檢查層。為實現全面的縱深防禦，建議將其與操作系統沙箱結合使用（詳見 docs/comparison.md）。

項目結構

cmd/pipelock/          CLI 入口點
internal/
  cli/                 20 多個 Cobra 命令（run, check, generate, mcp, integrity, ...）
  config/              YAML 配置、驗證、默認值、熱重載（fsnotify）
  scanner/             9 層 URL 掃描管道 + 響應注入檢測
  audit/               結構化 JSON 日誌記錄（zerolog） + 事件發射分發
  proxy/               HTTP 代理：獲取、正向（CONNECT）、WebSocket、DNS 固定、TLS 攔截
  certgen/             ECDSA P-256 CA + 葉證書生成、緩存
  mcp/                 MCP 代理 + 雙向掃描 + 工具中毒檢測 + 調用鏈檢測
  killswitch/          緊急全拒絕（4 種激活源） + 端口隔離的 API
  emit/                事件發射（Webhook + Syslog 接收器）
  metrics/             Prometheus 指標 + JSON 統計信息
  normalize/           Unicode 歸一化（NFKC、易混淆字符、組合標記）
  integrity/           SHA256 文件完整性監控
  signing/             Ed25519 密鑰管理
  gitprotect/          Git 差異掃描，防止敏感信息提交
  hitl/                人工確認終端批准
  report/              從 JSONL 事件日誌生成 HTML/JSON 審計報告
  projectscan/         項目目錄掃描，用於審計命令
enterprise/            多代理功能（ELv2 許可，詳見 enterprise/LICENSE）
configs/               7 個預設配置文件
docs/                  指南、參考文檔、合規映射

測試指標

在本地運行 make test 進行驗證。性能數據請參考 docs/performance.md。原始基準測試數據請參考 docs/benchmarks.md。

獨立基準測試：agent-egress-bench（涵蓋 8 個類別共 72 種攻擊場景，工具中立）。

📄 許可證

Pipelock 核心採用 Apache License 2.0 許可。版權所有 2026 Joshua Waldrep。

多代理功能（按代理身份、預算和配置隔離）由 enterprise 構建標籤控制，並採用 Elastic License 2.0 (ELv2) 許可。主要實現位於 enterprise/ 目錄，構建標籤控制的集成代碼位於 cmd/ 和 internal/ 目錄。這些功能需要有效的企業許可證密鑰。

開源核心可以獨立運行，無需企業功能。

預構建的發佈工件（Homebrew、GitHub 發佈、Docker 鏡像）包含企業代碼，使用有效許可證密鑰即可激活。使用 go install 從源代碼構建或使用倉庫的 Dockerfile 構建將生成僅包含社區版的二進制文件。

請查看 LICENSE 獲取 Apache 2.0 許可證文本，查看 enterprise/LICENSE 獲取 ELv2 許可證文本。