airblackbox/airblackbox

# AIR Blackbox [](https://pypi.org/project/air-blackbox/) [](https://pypi.org/project/air-blackbox/) [](LICENSE) [](https://airblackbox.ai) [-purple)](https://csrc.nist.gov/pubs/fips/204/final) [](https://github.com/airblackbox/airblackbox) **面向自主 AI 智能体的飞行记录仪。录制、重放、执行、审计，并提供后量子签名的证据。** 一次代理替换。全面覆盖。本地运行。 ``` # 之前 client = OpenAI(base_url="https://api.openai.com/v1") # 之后，代码中的其余部分保持不变 client = OpenAI( base_url="http://localhost:8080/v1", default_headers={"X-Gateway-Key": "your-key"} ) ``` 现在，每一次 LLM 调用都会生成一条经过签名的、防篡改的、可重放的审计记录。无需更改 SDK。无需重构。不影响性能。 ## 为什么现在需要后量子技术 市场上其他的 AI 审计追踪工具都使用 HMAC 或 RSA 进行签名。在您当前生成的记录的保留期内，这两种算法都将被量子计算机破解。EU AI Act 第 12 条要求您将这些日志至少保留六个月，甚至更长。监管机构如果接受在保留期结束前即可被破解的签名，将自担风险。您不应该冒这个险。 AIR Blackbox 使用 **ML-DSA-65 (FIPS 204 / Dilithium3)**（NIST 标准化的后量子签名方案）对每条记录进行签名。密钥在本地生成，并且永远不会离开您的机器。您今天生成的证据在 2035 年及以后依然可验证且不可伪造。 ## 您将获得什么 **后量子审计链**，每次调用都会生成一条经过 ML-DSA-65 签名、HMAC-SHA256 链式链接的 `.air.json` 记录，并异步写入。篡改一条记录，其后的所有记录都将失效。符合 FIPS 204 标准，抗量子安全，本地签名。 **证据包**，一条命令即可将审计链、扫描结果和 ML-DSA-65 签名打包成一个自我验证的 `.air-evidence` ZIP 压缩包。审计员只需运行 `python verify.py`，即可在两秒内获得通过/失败（PASS/FAIL）的结果。他们无需进行 pip install，无需网络连接，也不需要托管的云服务。 **EU AI Act 差距分析**，针对第 9、10、11、12、13、14 和 15 条进行 51 项以上的检查。可映射至 ISO 42001、NIST AI RMF 和 Colorado SB 24-205。一次扫描，四个框架，一份报告。 **PII 与注入扫描**，在提示词到达模型之前，检测横跨 5 种攻击类别的 20 种加权模式。灵敏度可配置。自动拦截。 **重放**，从审计链中加载任何过去的 episode，验证签名，并带时间戳重放每一个步骤。无需猜测即可进行事件重建。 **框架信任层**，为 LangChain、CrewAI、OpenAI Agents SDK、Anthropic、AutoGen、Google ADK 和 Haystack 提供开箱即用的封装器。相同的审计链，原生集成。 ## 快速入门 ``` pip install air-blackbox # 运行你的首次 gap analysis，适用于任何 Python AI 项目 air-blackbox comply --scan . -v # 查找隐藏在 helpers 和 utilities 中未声明的 model calls air-blackbox discover # 回放任何已录制的 episode air-blackbox replay # 生成已签名的 evidence package，用于审计或监管机构审查 air-blackbox export ``` **Claude Code 插件**，对于常驻编辑器的开发者来说，这是最快的途径： ``` /plugin marketplace add airblackbox/air-blackbox-plugin /plugin install air-blackbox@air-blackbox ``` **全栈** (Gateway + Episode Store + Policy Engine + observability)： ``` git clone https://github.com/airblackbox/air-platform.git cd air-platform cp .env.example .env # add OPENAI_API_KEY make up # running in ~8 seconds ``` - 追踪: `localhost:16686` (Jaeger) - 指标: `localhost:9091` (Prometheus) - Episode: `localhost:8081` (Episode Store API) ## 它如何融入您的技术栈 ``` Your Agent │ ▼ AIR Gateway ← swap base_url here │ ├── PII + injection scan (before prompt reaches model) ├── HMAC audit record (async, zero latency impact) └── ML-DSA-65 signing (keys never leave your machine) │ ▼ LLM Provider ← OpenAI / Anthropic / Azure / local │ ▼ AIR Record ← tamper-evident .air.json │ ▼ Evidence Bundle ← self-verifying .air-evidence ZIP ``` 适用于任何与 OpenAI 兼容的 API。无论提供商是谁，格式和集成都保持一致。 ## 为什么不直接记录所有日志？ 您可能已经有了日志记录。但日志记录无法解决以下问题： **防篡改能力**，任何对日志存储具有写权限的人都可以更改记录。HMAC 链使得更改可以被检测到。ML-DSA-65 签名可以证明是谁在何时签署了记录，并且能够在具有密码学意义的量子计算机到来后依然存活。 **提示词重建**，大多数日志记录只捕获响应，而不捕获完整的提示词上下文、工具调用和中间推理过程。AIR 会记录完整的 episode。 **合规结构**，EU AI Act 第 12 条要求防篡改日志必须具备特定的保留期限和审计访问保证。原始日志无法满足这一点。但证据包可以。 **机密信息泄露到追踪中**，每一个构建自己的日志记录系统的团队，最终都会在其可观测性后端中发现凭证。AIR 会在写入任何记录之前剥离 API 密钥并进行金库加密。 ## 运行时控制，air-gate 和 air-controls `air-blackbox` 会在您发布代码前对其进行扫描。另外两个姊妹包则负责处理您的智能体在上线*之后*的操作。 ### air-gate，人机回溯 (Human-in-the-Loop) 门控 在智能体发送电子邮件、删除该文件或执行该 SQL 之前，`air-gate` 会暂停，检查策略，可选择通过 Slack 询问人类，并将该决定签署到防篡改的审计链中。只需 12 行 Python 代码即可满足 EU AI Act 第 14 条 (人工监督) 的要求。 ``` pip install air-gate ``` ``` from air_gate import GateClient gate = GateClient() # local mode, zero config result = gate.check( agent_id="support-bot", action_type="email", action="send_email", payload={"to": "customer@example.com", "body": "..."}, ) if result["decision"] == "auto_allowed": send_the_email() elif result["decision"] == "blocked": log.warning("Blocked by policy:", result["reason"]) # MEDIUM/HIGH-risk actions 将暂停，直到有人在 Slack 中批准 # 随时验证完整的 audit chain assert gate.verify() ``` 亮点： - **风险分层的 YAML 策略**，针对每种操作类型提供 `auto_allow`、`require_approval`、`block` 设置 - **Slack 审批流程**，人工可通过手机审批，回调 URL 会将结果传回给智能体 - **PII 自动脱敏**，涵盖五个垂直领域（通用、金融/PCI-DSS、医疗/HIPAA、法律、招聘/EEOC）的 25 个以上类别 - **LangChain 和 OpenAI 函数工具封装器**，实现一键集成 - **库或服务器模式**，`GateClient()` 实现零配置，FastAPI + Slack 机器人用于团队工作流 完整仓库：[airblackbox/air-gate](https://github.com/airblackbox/air-gate) ### air-controls，运行时可视化 您的智能体每天要做出数千项决定。`air-controls` 是让这些决定变得清晰可见的仪表盘。操作时间轴、单次调用成本、风险评分、紧急终止开关。使用与 `air-blackbox` 相同的 HMAC 审计链。 ``` pip install air-controls ``` ``` # LangChain from air_controls import ControlsCallback cb = ControlsCallback(agent_name="sales-bot") chain.invoke({"input": "..."}, config={"callbacks": [cb]}) # CrewAI from air_controls import CrewMonitor mon = CrewMonitor(agent_name="research-crew") mon.run(crew) # 任何 OpenAI / Anthropic agent from air_controls import monitor @monitor(agent_name="my-bot") def process_customer(query): return openai.chat.completions.create(...) ``` ``` air-controls status # live dashboard of all agents air-controls events sales-bot # event timeline for one agent air-controls pause sales-bot # kill switch air-controls verify # verify audit chain integrity ``` 本地优先。SQLite 支持存储。无需云服务。无需数据回传。 完整仓库：[airblackbox/air-controls](https://github.com/airblackbox/air-controls)，并在 [air-controls-mcp](https://github.com/airblackbox/air-controls-mcp) 提供了用于 Cursor、Claude Code 和 Windsurf 的 MCP 服务器。 ## 各组件如何组合 ``` Build time Runtime ─────────────────── ──────────────────────── air-blackbox ──────────┐ ┌──── air-controls (scan code, │ │ (monitor what agents do, find gaps, │ │ action timeline, cost, export evidence) │ │ kill switch) │ │ │ │ │ │ escalates to │ │ ▼ │ │ air-gate │ │ (pause dangerous actions, │ │ human approval, Slack) │ │ ▼ ▼ Shared HMAC-SHA256 audit chain Shared ML-DSA-65 post-quantum signatures Shared .air-evidence bundle format All four deployable as one Docker Compose stack: air-platform (make up, 8 seconds to full stack) ``` ## 完整生态系统 `air-blackbox` 是扫描器和入口点。其他一切都是对它的扩展。 | 包 | 阶段 | 功能描述 | |---|---|---| | **[air-blackbox](https://github.com/airblackbox/airblackbox)** | 构建时 | EU AI Act 扫描器，51 项以上检查，ML-DSA-65 签名的证据包（本仓库） | | [air-trust](https://github.com/airblackbox/air-trust) | 构建 + 运行时 | 加密原语和信任层封装器（见仓库） | | [air-controls](https://github.com/airblackbox/air-controls) | 运行时 | 实时智能体可视化、时间轴、成本、紧急终止开关 | | [air-gate](https://github.com/airblackbox/air-gate) | 运行时 | 执行前带有 Slack 审批的人机回溯 (human-in-the-loop) 门控 | | [air-platform](https://github.com/airblackbox/air-platform) | 部署 | 一条命令启动的 Docker Compose 全栈 | | [air-blackbox-mcp](https://github.com/airblackbox/air-blackbox-mcp) | IDE | 用于 Claude Desktop、Cursor、Claude Code 的 MCP 服务器 | | [air-controls-mcp](https://github.com/airblackbox/air-controls-mcp) | IDE | 用于运行时智能体可视化的 MCP 服务器 | | [air-blackbox-plugin](https://github.com/airblackbox/air-blackbox-plugin) | IDE | Claude Code 插件（扫描器的斜杠命令） | | [compliance-action](https://github.com/airblackbox/compliance-action) | CI | GitHub Action，在每个 PR 上运行合规性检查 | | [otel-prompt-vault](https://github.com/airblackbox/otel-prompt-vault) | 基础设施 | OTel 处理器：将敏感内容卸载到外部存储 | | [otel-collector-genai](https://github.com/airblackbox/otel-collector-genai) | 基础设施 | OTel 处理器：脱敏、成本/Token 指标、循环检测 | | [otel-semantic-normalizer](https://github.com/airblackbox/otel-semantic-normalizer) | 基础设施 | OTel 处理器：将 LLM 属性规范化为 `gen_ai.*` 模式 | 您可以安装其中任何一个。当您需要时，它们可以无缝组合。 ## 验证背书 - **Julian Risch** (deepset, Haystack 维护者)，在 LinkedIn 和 [GitHub issue #10810](https://github.com/deepset-ai/haystack/issues/10810) 上进行了公开背书；并在 38 分钟内做出了回复 - **Piero Molino** (Ludwig 维护者)，在 issue 开启后的几小时内，合并了由 AIR 扫描结果驱动的 EU AI Act 合规性更改 - **arXiv AEGIS** (2026 年 3 月)，独立研究人员发布了用于 AI 智能体治理的相同拦截层架构 - **McKinsey State of AI Trust 2026**，将信任基础设施列为关键的自主 AI 类别 - 已被收录至 [EthicalML/awesome-artificial-intelligence-regulation](https://github.com/EthicalML/awesome-artificial-intelligence-regulation) 和 [GenAI-Gurus/awesome-eu-ai-act](https://github.com/GenAI-Gurus/awesome-eu-ai-act) ## 对比分析 | | AIR Blackbox | 文档生成器 (ArcKit 等) | 托管扫描器 (ark-forge 等) | |---|---|---|---| | 扫描实际代码 | ✅ | ❌ (根据提示生成文档) | ✅ | | 带有凭证的执行前门控 | ✅ **air-gate** | ❌ | ❌ | | 后量子签名 (ML-DSA-65) | ✅ FIPS 204 | ❌ | ❌ | | HMAC 审计链 | ✅ 本地，自我验证 | ❌ | 部分 (通常是托管的) | | 所有内容均在本地运行 | ✅ | ✅ | ❌ | | MCP 服务器 + Claude Code 插件 | ✅ | 部分 | ❌ | | 定价 | 免费且开源，Apache 2.0 | 免费 (仅限文档) | 免费额度 + 付费签名 | **使用文档生成器**来处理 RFP（需求建议书）、商业案例和治理委员会的文书工作。 **使用 AIR Blackbox** 向审计员证明您的 AI 系统实际执行了哪些操作，并保证这些证明在量子计算机到来后依然能够通过验证。 ## 理念 **AIR 是一名见证者，而不是守门人，除非您要求它这么做。** - **非阻塞**，录制或门控故障绝不会中断生产流程 - **容许丢失**，丢弃审计记录是可以接受的；而丢弃用户请求则不可接受 - **自我降级**，如果收集器发生故障，spans 会静默丢弃；只记录警告，从不返回错误 您无法检测到您看不见的东西。您无法阻止您检测不到的东西。您无法信任您无法证明的东西。AIR Blackbox 是使证明成为可能的那个层级，无论是今天还是量子时代之后。 ## 许可证 Apache-2.0，[airblackbox.ai](https://airblackbox.ai) *这不是一项经认证的合规性测试。它是一个用于识别潜在差距的起点。* 如果这能帮助您为 EU AI Act 的执行做好准备，请[给本仓库加星](https://github.com/airblackbox/airblackbox)，这有助于其他团队发现它。

标签：AI合规扫描, AI治理, API网关, Dilithium, DNS 解析, EU AI Act, FIPS 204, LLM审计, ML-DSA-65, OpenAI代理, pip install, Python包, 不可抵赖性, 企业合规, 信任层, 合规自动化, 后量子密码学, 审计日志, 本地代理, 用户代理, 网络安全, 网络安全, 网络安全标准, 自动驾驶代理, 自定义请求头, 记录与重放, 请求拦截, 逆向工具, 量子安全, 防篡改, 隐私保护, 隐私保护, 零代码集成, 黑匣子