3mre0s/ai-firewall

# 本地 AI 防火墙 防止 Claude Code、Cursor 和 AI 编程代理意外将 API 密钥、`.env` 值、凭证、文件路径和个人数据发送给 LLM 提供商。 本地 AI 防火墙完全在您的机器上运行。它会在请求离开您的计算机之前，将检测到的机密信息替换为类型化的占位符，并在响应中于本地将其恢复。 - 仅限本地 - 无需账户 - 无托管网关 - 默认禁用遥测 - 机密映射仅保留在内存中 - 开源 [](#从源码构建) [](https://www.gnu.org/licenses/agpl-3.0) [](https://github.com/3mre0s/ai-firewall/actions/workflows/ci.yml) [](https://github.com/3mre0s/ai-firewall/releases/latest) [](https://github.com/3mre0s/ai-firewall/stargazers) [](https://goreportcard.com/report/github.com/3mre0s/ai-firewall)  ## 安全试用 ``` ai-firewall demo ``` 此操作完全在离线状态下运行，使用内置的合成凭证以及代理所用的相同 掩码引擎。它不需要 API 密钥、启动 代理、安装证书、更改环境变量或发送网络 请求。占位符映射仅存在于内存中，直到命令退出。 切勿将真实的 API 密钥、凭证、客户记录或私有仓库 内容粘贴到测试中。 ## 快速开始 显式代理模式是默认的首选体验。它不需要本地 CA ，并且不会拦截无关的 HTTPS 流量。 ### 1. 安装 从 [最新发布版本](../../releases/latest) 下载适合您平台的归档文件。Linux amd64 示例： ``` curl -LO https://github.com/3mre0s/ai-firewall/releases/latest/download/ai-firewall-linux-amd64.tar.gz curl -LO https://github.com/3mre0s/ai-firewall/releases/latest/download/checksums.txt sha256sum --check checksums.txt --ignore-missing tar -xzf ai-firewall-linux-amd64.tar.gz install -m 0755 ai-firewall "$HOME/.local/bin/ai-firewall" ``` Windows 用户应下载 `ai-firewall-windows-amd64.zip`，根据 `checksums.txt` 验证其 SHA-256 值，并将 `ai-firewall.exe` 放入 `PATH` 中。 ### 2. 启动防火墙 Claude Code Pro/Max 订阅用户可以保留客户端自身的 授权标头： ``` export FORWARD_API_KEY=none ai-firewall ``` 如果您使用 Anthropic API 密钥，请将其加载到您的 shell 中，并 通过防火墙传递，而无需在此命令中放入该值： ``` export FORWARD_API_KEY="$ANTHROPIC_API_KEY" ai-firewall ``` API 代理默认监听 `http://localhost:8080`。 ### 3. 通过代理启动 Claude Code 在第二个终端中： ``` export ANTHROPIC_BASE_URL=http://localhost:8080 claude ``` 有关验证、 清理和故障排除，请参阅详细的 [Claude Code 设置指南](docs/claude-code.md)。 ## 支持的工具 - **Claude Code:** 显式代理模式；支持订阅令牌透传。 - **Cursor 和 VS Code:** 使用内置的 [VS Code 扩展](extensions/vscode/README.md)。 - **Aider:** 请参阅 [Aider 集成指南](extensions/aider/README.md)。 - **Cline:** 请参阅 [Cline 集成指南](extensions/cline/README.md)。 - **Open WebUI:** 请参阅 [Open WebUI 集成指南](extensions/open-webui/README.md)。 - **其他客户端:** 将兼容 Anthropic 或 OpenAI 的 base URL 指向本地代理。 ## Cursor 和 VS Code 该扩展可以启动和停止防火墙，将提供商密钥存储在 编辑器的机密存储中，并复制代理环境变量供代理 终端使用。 ``` cd extensions/vscode npm install npm run package code --install-extension local-ai-firewall.vsix ``` 然后从命令面板运行这些命令： 1. `Local AI Firewall: Set API Key` 2. `Local AI Firewall: Start` 3. `Local AI Firewall: Copy Agent Env` 有关二进制文件发现和 开发设置，请参阅 [扩展 README](extensions/vscode/README.md)。 ## 工作原理 1. 您的 AI 工具向本地代理发送请求。 2. 防火墙扫描完整的请求主体以查找支持的模式。 3. 每个检测到的值都会被替换为类型化的占位符，例如 `[[OAI_KEY_A1B2C3D4E5F60718293A4B5C6D7E8F90]]`。 4. 占位符到机密的映射保留在内存保险库中。 5. 经过脱敏处理的请求将被转发到配置的提供商。 6. 在响应到达客户端之前，缓冲或 SSE 响应中的占位符将在本地恢复。 提供商收到的是经过脱敏处理的请求主体。身份验证标头仍会 到达提供商：显式模式要么注入 `FORWARD_API_KEY` ，要么在 `FORWARD_API_KEY=none` 时保留 客户端的标头。 ## 检测内容 当前注册表涵盖： - 常见开发者服务的 API 密钥和令牌 - 密码和机密分配，包括 shell 导出 - Unix 和 Windows 文件路径 - 电子邮件地址、信用卡号和 IBAN - 源代码中记录的经校验和验证的国家级标识符 检测是基于模式的，特意不将其表述为详尽无遗。请 参阅 [`patterns/patterns.go`](patterns/patterns.go) 了解真实来源。 ## 为什么信任它？ - 它在本地运行，不需要项目账户。 - 默认禁用遥测，并且需要在官方 发布二进制文件中明确选择加入。 - 提示内容不会发送到项目拥有的云服务。 - 占位符映射保留在进程内存中，并在正常 关闭时清除。 - 可以检查源代码并[在本地构建](#build-from-source)。 - 每个版本都包含涵盖所有平台归档和 VS Code 扩展的 `checksums.txt`。 - 透明的 MITM 模式是可选的，并且默认禁用。 - 信任边界和已知的权衡记录在 [THREAT_MODEL.md](THREAT_MODEL.md) 中。 在报告漏洞之前，请阅读 [SECURITY.md](SECURITY.md)。这些 属性降低了意外泄露的风险；它们并不能保证检测到每一个 机密。 ## 局限性 - 这不是沙盒，不能防御提示注入或 恶意模型输出。 - 它不能保护受感染的本地机器或以您的用户身份运行的另一个进程；这样的进程 可能会读取内存或本地凭证。 - 检测是基于模式的，可能会产生漏报。 - 合法内容可能会匹配某个模式并产生误报。 - 不支持、已编码、格式错误或被截断的凭证格式可能无法 被检测到。 - 仅扫描通过防火墙路由的流量。 - 透明的 MITM 模式会安装本地 CA，从而更改本地 信任模型；请保护其私钥，并在不再需要时将其卸载。 - 当新机密的字节跨越 SSE 数据块边界时，可能会遗漏流式响应中的新机密。请求作为完整主体进行扫描，并且 已知占位符的恢复使用滚动缓冲区。 有关完整的威胁模型，请参阅 [THREAT_MODEL.md](THREAT_MODEL.md)。 ## 高级：透明 MITM 模式 透明模式是可选的。它在本地终止配置的 AI 主机的 TLS ，并需要信任本地生成的 CA。 ``` export AI_FIREWALL_CA_PASSPHRASE="choose-a-strong-local-passphrase" ai-firewall install-ca export FORWARD_API_KEY=none export MITM_ENABLED=true ai-firewall ``` 将应用程序或系统 HTTP 代理指向 `http://localhost:8082`。在此 模式下，将扫描请求主体，同时客户端的身份验证标头将 原封不动地转发。 完成后移除 CA： ``` ai-firewall uninstall-ca ``` 如果未设置 `AI_FIREWALL_CA_PASSPHRASE`，私钥将存储为 未加密的 `0600` PEM 文件。在 启用此模式之前，请查阅 [THREAT_MODEL.md](THREAT_MODEL.md) 中特定于 MITM 的风险。 ## 配置 所有设置均为环境变量；无需配置文件。 | 变量 | 默认值 | 描述 | |---|---|---| | `FORWARD_API_KEY` | 必填 | 向上游注入的提供商密钥。使用 `none` 可保留客户端身份验证标头。 | | `UPSTREAM_URL` | `https://api.anthropic.com` | 上游提供商 base URL。 | | `FIREWALL_PORT` | `8080` | 显式 API 代理端口。 | | `PROVIDER_HINT` | 自动检测 | 可选的提供商适配器覆盖。 | | `VAULT_SIZE_LIMIT` | `200` | 内存中的最大占位符映射数。 | | `MASK_PATHS` | `true` | 掩码受支持的 Unix 和 Windows 路径。 | | `MASK_EMAILS` | `true` | 掩码电子邮件地址。 | | `LOG_LEVEL` | `info` | `silent`、`info` 或 `debug`。 | | `MITM_ENABLED` | `false` | 启用可选的透明代理。 | | `MITM_PORT` | `8082` | 透明代理端口。 | | `MITM_CERT_DIR` | `~/.ai-firewall` | 本地 CA 证书和密钥目录。 | | `AI_FIREWALL_CA_PASSPHRASE` | 未设置 | 加密持久化的 CA 私钥。 | | `ANALYTICS_OPT_IN` | `false` | 选择加入最少的发布遥测。 | 支持的命令： ``` ai-firewall Start the proxy server. ai-firewall demo Run the offline synthetic masking demo. ai-firewall install-ca Install the local MITM CA. ai-firewall uninstall-ca Remove the local MITM CA. ai-firewall version Print the build version. ai-firewall help Show usage. ``` ## 安全性 该防火墙旨在减少向 LLM 提供商的意外泄露， 而不是取代端点安全、CI 中的机密扫描或提供商端的 数据控制。 - 阅读[威胁模型](THREAT_MODEL.md)。 - 使用 [SECURITY.md](SECURITY.md) 报告漏洞。 - 将提供商凭证保留在您正常的机密管理工作流中。 - 在错误报告和测试中仅使用合成值。 - 本地 `/metrics` 和 `/dashboard` 端点会拒绝非环回客户端。 除非 `ANALYTICS_OPT_IN=true` 并且该二进制文件是 包含遥测构建密钥的官方版本，否则遥测不会发送任何内容。自行构建的二进制文件不会 发送遥测。提示内容、机密、路径和环境变量值不是 遥测字段。 ## 开发 ### 从源码构建 ``` git clone https://github.com/3mre0s/ai-firewall.git cd ai-firewall go build -trimpath -ldflags "-s -w" -o ai-firewall . ``` 在 Windows 上，使用 `-o ai-firewall.exe`。 ### 运行检查 ``` go test ./... go vet ./... ``` 有关贡献者和部署详细信息，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)、[ARCHITECTURE.md](ARCHITECTURE.md) 和 [DEPLOYMENT.md](DEPLOYMENT.md)。 ## 许可证 本地 AI 防火墙采用 [GNU Affero General Public License v3.0 或更高版本](LICENSE) 授权。有关 附加通知，请参阅 [NOTICE](NOTICE)。 商业许可咨询应通过 维护者的 GitHub 个人资料私下发送，而不是作为公开问题提出。

标签：AI网关代理, EVTX分析, Go, LLM安全防护, Ruby工具, 数据脱敏, 日志审计, 本地代理, 网络安全, 隐私保护