floatingsidewal/bulkhead

# Bulkhead **AI驱动开发工具的级联内容保护。** Bulkhead 检测并删除敏感内容 — PII、密钥、提示词注入和系统提示词泄露 — 在其通过 LLM 驱动功能泄露之前。它可以作为 VS Code 扩展、HTTP REST 服务器或 AI 编码助手的 MCP 服务器运行。 | | | |---|---| | **部署方式** | VS Code 扩展、HTTP REST 服务器、MCP 服务器、Docker | | **检测能力** | 13 个类别 154 种密钥模式、20+ 国家/地区 45+ 种 PII 实体类型、提示词注入、系统提示词泄露 | | **架构** | 三层级联分类器（regex、BERT、LLM） | | **测试** | 125 个测试，包括对抗性测试套件和性能基准测试 | ## Bulkhead 的独特之处 核心创新是**级联分类器** — 三个检测层逐步权衡速度与深度，因此昂贵的推理仅在实际需要的内容上运行。Regex 处理大部分内容（亚毫秒级，每次按键）。BERT 模型解析上下文实体，如名称和位置。LLM 消解真正困难的情况（"Jordan"是人名还是国家名？）。每个检测都携带完整的来源信息 — 哪一层标记的、置信度如何、以及原因。 检测模式本身移植自成熟的开源项目（参见[归属](#attribution)）。Bulkhead 的贡献在于级联架构、BERT 工作线程集成、LLM 消解层、多平台服务器架构，以及将它们联系在一起的去重逻辑。 ## 问题所在 每次使用 AI 编码助手时，编辑器的内容都会发送到 LLM。该内容可能包括： - **个人数据** — 社保号码、信用卡、电子邮件、电话号码、医疗 ID - **密钥** — API 密钥、令牌、数据库凭据、私钥 - **提示词注入** — 隐藏在代码注释或数据中的恶意指令 - **系统提示词泄露** — 试图提取你的 AI 工具配置 Bulkhead 位于你的代码和 AI 之间，在敏感内容泄露之前将其拦截。 ## Monorepo 结构 ``` bulkhead/ packages/ core/ @bulkhead/core Detection engine, guards, cascade, patterns vscode/ bulkhead VS Code extension server/ @bulkhead/server HTTP REST server + MCP server Dockerfile Multi-stage build (HTTP + MCP modes) docker-compose.yml HTTP and MCP service definitions ``` ## 工作原理 Bulkhead 使用**级联分类器** — 三个检测层在速度和深度之间权衡： | 层级 | 速度 | 检测内容 | 运行时机 | |-------|-------|----------------|--------------| | **Regex** | 亚毫秒级 | 结构化 PII（社保号码、信用卡、IBAN）、密钥（AWS 密钥、令牌）、注入模式 | 每次按键（防抖后） | | **BERT** | 20-50毫秒 | 名称、地点、组织 — Regex 无法捕获的上下文实体 | 按需"深度扫描"或 `/v1/scan/model` | | **LLM** | 500毫秒-2秒 | 模糊情况（"'Jordan'是人还是国家？"） | 仅针对 BERT 层无法解决的约 5-10% 的检测 | 每个检测都携带**来源信息** — 哪一层标记的、置信度如何、以及是已确认还是需要审核。 ## 检测内容 ### PII（20+ 国家/地区 45+ 种实体类型） 模式移植自 [Microsoft Presidio](https://github.com/microsoft/presidio)，带有校验和验证（Luhn、IBAN mod-97、Verhoeff）和上下文感知评分。 - **通用：** 信用卡、电子邮件、IBAN、IP 地址、MAC 地址、电话号码、URL、加密钱包、日期 - **美国：** 社保号码、驾照、护照、银行账户、ITIN、Medicare (MBI)、NPI、ABA 路由、DEA 执照 - **英国：** NHS 号码、NINO、护照、邮政编码、车辆登记 - **欧盟：** 西班牙 NIF/NIE、意大利税务代码/增值税/驾照/护照/身份证、波兰 PESEL、芬兰 PIC、瑞典 personnummer、德国税务 ID/护照 - **亚太：** 新加坡 NRIC/UEN、澳大利亚 ABN/ACN/TFN/Medicare、印度 PAN/Aadhaar/车辆/选民/护照、韩国 RRN/护照、泰国 TNIN - **非洲：** 尼日利亚 NIN ### 密钥（13 个类别 154 种模式） 模式来源于 HAI-Guardrails、GitLeaks 和公开提供商文档。 - **云服务：** AWS、Azure、GCP - **源代码管理：** GitHub、GitLab、Bitbucket - **CI/CD：** Jenkins、CircleCI、Travis CI、Drone - **通讯：** Slack、Twilio、SendGrid、Mailgun - **支付：** Stripe、Square、PayPal - **数据库：** 连接字符串、Redis、MongoDB - **基础设施：** Terraform、Vault、Consul - **SaaS：** Jira、Confluence、Datadog、New Relic - **AI/ML：** OpenAI、Anthropic、HuggingFace、Cohere - **认证：** Auth0、Okta、Firebase、Clerk、Supabase - **CDN/托管：** Cloudflare、Netlify、Vercel、Heroku - **社交：** Twitter、Facebook、LinkedIn - **通用：** JWT、私钥、高熵字符串 ### 提示词注入 16 种 regex 模式 + 针对已知攻击短语的启发式相似度匹配。检测："忽略之前的指令"、角色扮演攻击、DAN 模式、越狱尝试。 ### 系统提示词泄露 7 种 regex 模式 + 启发式匹配。检测："揭示你的系统提示词"、"重复上述所有内容"、提取技术。 ## 快速开始 ### 从源码安装 ``` git clone https://github.com/your-org/bulkhead.git cd bulkhead npm install npm run build ``` ### VS Code 扩展 1. 在 VS Code 中打开 `bulkhead/` 文件夹 2. 按 `F5` 启动扩展开发主机 3. 打开任意文件 — Bulkhead 自动扫描编辑内容（regex 层，防抖） 4. 使用命令面板： - `Bulkhead: Scan File` — regex 扫描 - `Bulkhead: Deep Scan` — regex + BERT + LLM 级联 ### HTTP REST 服务器 ``` # 开发 cd packages/server && npm run dev # 生产 npm run build && node packages/server/dist/main.js # 使用 API key 认证 BULKHEAD_API_KEY=my-secret-key node packages/server/dist/main.js ``` ``` # 扫描文本 curl -X POST http://localhost:3000/v1/scan \ -H "Content-Type: application/json" \ -d '{"text": "My SSN is 123-45-6789"}' # 扫描和编辑 curl -X POST http://localhost:3000/v1/redact \ -H "Content-Type: application/json" \ -d '{"text": "My SSN is 123-45-6789"}' ``` ### MCP 服务器（Claude Code） 添加到项目根目录的 `.mcp.json`： ``` { "mcpServers": { "bulkhead": { "command": "npx", "args": ["tsx", "packages/server/src/mcp/index.ts"] } } } ``` ### MCP 服务器（GitHub Copilot CLI） 添加到 `.github/copilot/mcp.json`： ``` { "mcpServers": { "bulkhead": { "command": "npx", "args": ["tsx", "packages/server/src/mcp/index.ts"] } } } ``` ### Docker ``` # HTTP 服务器在端口 3000 docker compose up bulkhead # MCP 服务器在 stdio docker compose run --rm -i bulkhead-mcp ``` ### 作为库使用 ``` import { GuardrailsEngine, PiiGuard, SecretGuard } from "@bulkhead/core"; const engine = new GuardrailsEngine(); engine.addGuard(new PiiGuard()); engine.addGuard(new SecretGuard()); const results = await engine.analyze("Email: john@example.com, Key: AKIAIOSFODNN7EXAMPLE"); // results[0].detections -> [{ entityType: "EMAIL_ADDRESS", source: "regex", disposition: "confirmed", ... }] // results[1].detections -> [{ entityType: "AWS_ACCESS_KEY", source: "regex", disposition: "confirmed", ... }] ``` ## 配置 ### VS Code 设置 | 设置 | 默认值 | 描述 | |---------|---------|-------------| | `bulkhead.enabled` | `true` | 主开关 | | `bulkhead.debounceMs` | `500` | 编辑后自动扫描的延迟 | | `bulkhead.guards.pii.enabled` | `true` | PII 检测 | | `bulkhead.guards.secret.enabled` | `true` | 密钥检测 | | `bulkhead.guards.injection.enabled` | `true` | 提示词注入检测 | | `bulkhead.cascade.modelEnabled` | `false` | 启用 BERT 模型（首次使用下载约 29MB） | | `bulkhead.cascade.escalationThreshold` | `0.75` | BERT 置信度低于此值时检测升级到 LLM | | `bulkhead.cascade.contextSentences` | `3` | 发送给 LLM 进行消解的上下文句子数 | ### 环境变量（服务器） | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `BULKHEAD_PORT` | `3000` | HTTP 服务器端口 | | `BULKHEAD_HOST` | `0.0.0.0` | HTTP 服务器绑定地址 | | `BULKHEAD_LOG_LEVEL` | `info` | 日志级别：`info`、`warn`、`error`、`silent` | | `BULKHEAD_API_KEY` |（无）| 认证 API 密钥。设置后，所有 `/v1/*` 路由需要 `X-API-Key` 头 | | `BULKHEAD_CORS_ORIGIN` |（禁用）| CORS 来源。设置为 `*` 或特定来源以启用 | | `BULKHEAD_MAX_BODY_SIZE` | `1048576` | 最大请求体大小（字节，默认 1MB） | | `BULKHEAD_GUARDS_PII_ENABLED` | `true` | 启用 PII 防护 | | `BULKHEAD_GUARDS_SECRET_ENABLED` | `true` | 启用密钥防护 | | `BULKHEAD_GUARDS_INJECTION_ENABLED` | `true` | 启用注入防护 | | `BULKHEADASCADE_MODEL_ENABLED` | `false` | 启用 BERT 模型作为第二层 | | `BULKHEAD_CASCADE_MODEL_ID` | `gravitee-io/bert-small-pii-detection` | HuggingFace 模型 ID | | `BULKHEAD_CASCADE_ESCALATION_THRESHOLD` | `0.75` | LLM 升级的 BERT 置信度阈值 | | `BULKHEAD_LLM_PROVIDER` | `none` | LLM 提供商：`openai`、`anthropic`、`custom` | | `BULKHEAD_LLM_API_KEY` |（无）| LLM 提供商的 API 密钥 | | `BULKHEAD_LLM_ENDPOINT` |（无）| 自定义 LLM 提供商的端点 URL | ## 测试 ``` npm test # Run all 125 tests npm run test:watch # Watch mode (core package) npm run lint # Type-check all packages ``` 测试套件包括[对抗性测试套件](test/adversarial/)，涵盖规避技术、抗误报能力、混合威胁文档、带 ASCII 柱状图的性能基准测试，以及一个同时触发所有威胁类型的"厨房水槽"文档。 ## 文档 - [架构](docs/architecture.md) — 级联分类器设计、组件图、入口点 - [部署](docs/deployment.md) — 五种部署场景及配置示例 - [API 参考](docs/api.md) — HTTP 端点、MCP 工具、环境变量 - [防护](docs/guards.md) — 防护实现细节 - [模式](docs/patterns.md) — 检测模式参考 - [测试](docs/testing.md) — 测试策略和对抗性测试套件 - [操作指南](docs/how-to.md) — 使用指南 ## 归属 Bulkhead 的检测模式和防护架构源自两个开源项目。级联分类器、BERT 集成、LLM 消解、VS Code 扩展、服务器架构和去重逻辑均为独立开发。详见 [ATTRIBUTION.md](ATTRIBUTION.md) 和原始版权声明 [NOTICES](NOTICES)。 - **[Microsoft Presidio](https://github.com/microsoft/presidio)**（MIT）— PII 检测模式、校验和算法、实体分类法 - **[HAI-Guardrails](https://github.com/presidio-oss/hai-guardrails)**（MIT）— 防护架构、检测策略、安全模式 ## 贡献 参见 [CONTRIBUTING.md]( 获取指南。 ## 许可证 [MIT](LICENSE)

标签：AI安全, API密钥保护, BERT模型, Chat Copilot, DLP, Docker容器, GDPR合规, MCP服务器, meg, MITM代理, NLP安全, PII保护, REST API, VS Code扩展, 个人信息保护, 代码隐私保护, 信息安全, 凭证保护, 命名实体识别, 实体识别, 对抗攻击, 开发工具安全, 攻击面发现, 敏感信息检测, 文本分类, 正则表达式匹配, 系统提示泄漏, 级联分类器, 自动化攻击, 请求拦截, 隐私合规