airblackbox/gateway
GitHub: airblackbox/gateway
面向 AI 系统的「黑匣子」飞行记录仪，作为 OpenAI 兼容的反向代理，为每次 LLM 调用生成防篡改、可重放的审计记录。
Stars: 8 | Forks: 0
# AIR Blackbox Gateway
[](https://github.com/airblackbox/gateway/actions/workflows/ci.yml)
[](https://go.dev)
[](LICENSE)
[](https://opentelemetry.io)
[](https://github.com/airblackbox/python-sdk)
**你的 AI agent 刚刚发送了一封邮件、转移了资金，或者修改了生产数据。有人问道：*"确切地给我看看它看到了什么，以及它为什么要做出那个决定。"***
**你今天能回答这个问题吗？**
AIR Blackbox Gateway 是 AI 系统的“黑匣子”飞行记录仪。把它放在任何兼容 OpenAI 的 provider 前面，每一次 LLM 调用都会生成一个防篡改、可重放的审计记录 —— 且不会将敏感内容暴露给你的可观测性堆栈。
```
# 添加一行。每个 AI 决策现在都被记录。
from openai import OpenAI
import air
client = air.air_wrap(OpenAI())
```
15 个代码仓库。200+ 测试。每次推送都运行 CI。Apache-2.0 许可证。
## 5 分钟快速开始
**1. 启动堆栈**
```
git clone https://github.com/airblackbox/gateway.git
cd gateway
cp .env.example .env # add your OPENAI_API_KEY
docker compose up --build
```
**2. 安装 SDK**
```
pip install air-blackbox-sdk
```
**3. 记录一切**
```
from openai import OpenAI
import air
client = air.air_wrap(OpenAI())
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "What is a flight recorder?"}],
)
# x-run-id header = 您的审计追踪
# Prompts vaulted in your MinIO, not a third-party cloud
# HMAC-SHA256 chain = 防篡改记录
```
**兼容你的框架：**
```
# LangChain
from air.integrations.langchain import air_langchain_llm
llm = air_langchain_llm("gpt-4o-mini")
# CrewAI
from air.integrations.crewai import air_crewai_llm
llm = air_crewai_llm("gpt-4o-mini")
```
**4. 查看链路追踪** → [localhost:16686](http://localhost:16686) (Jaeger)
**5. 重放任何运行**
```
go run ./cmd/replayctl replay runs/
.air.json
```
## 为什么存在这个项目
Langfuse、Helicone 和 Datadog 回答的是 *"系统性能如何？"*
AIR 回答的是 **"到底发生了什么，我们能证明吗？"**
| | 可观测性工具 | AIR Blackbox Gateway |
|---|---|---|
| 仪表盘与延迟 | ✅ | ❌ (使用 Jaeger/Grafana) |
| 数据存储位置 | 他们的云端 | **你的** Vault (S3/MinIO) |
| 链路中的 PII | ❌ 原始内容暴露 | ✅ 仅包含 Vault 引用 |
| 防篡改记录 | ❌ | ✅ SHA-256 + HMAC 链 |
| 确定性重放 | ❌ | ✅ `replayctl` |
| 合规性报告 | ❌ | ✅ 22 项控制措施 (SOC 2 + ISO 27001) |
| 签名证据导出 | ❌ | ✅ HMAC 认证包 |
| Agent 护栏 | ❌ | ✅ 成本、循环、工具、PII |
AIR Blackbox 为 AI 系统提供防篡改审计链 —— 这是一种受证书透明度日志 启发的方法，应用于 agent 基础设施。它不是 Langfuse (6k+ 星)，不是 Helicone，也不是 LangSmith。它们做的是可观测性。我们做的是问责制。
## 适用人群
**平台工程师**，正在部署调用 LLM 的 agent。你需要记录每一个请求，但不能让 PII 泄露到可观测性堆栈中。把它放在你的 provider 前面 —— 无需修改代码。
**合规团队**，监管机构正在询问 *"给我看看 AI 做了什么"*。AIR 记录为你提供带有 SHA-256 校验和和签名证据包的结构化重建。
**初创公司 CTO**，知道 *"我们无法证明我们的 AI 做了什么"* 将阻碍企业交易、SOC 2 或保险。现在安装它，以免以后手忙脚乱。
**Agent 构建者**，正在超越聊天机器人，转向跨越数小时、调用工具并与生产数据交互的系统。你需要决策溯源、重放以及证明你的 agent 做了正确事情的能力 —— 或者一份清晰的记录，说明它在哪里没有做到。
## 工作原理
1. 你的 agent 向 gateway 发送一个兼容 OpenAI 的请求（只需更改 base URL）
2. gateway 分配一个 `run_id`，转发请求，捕获响应
3. Prompts 和 completions 被存入 MinIO (兼容 S3) 的 Vault 中 —— 链路追踪包含的是 **引用**，而非内容
4. 一个 `.air.json` 记录捕获完整的运行过程：vault 引用、model、tokens、计时、tool calls
5. OTel spans 流经 collector 管道 (normalize → vault → redact → export)
6. 之后：`replayctl` 重放运行并报告行为漂移
## 信任层
这是其他人都没做到的部分。
**审计链 (Audit Chain)** —— 每个代理的请求都会被追加到一条 HMAC-SHA256 链中。每个条目都链接到前一个条目的哈希值。修改任何记录，链条从该点向后都会断裂。这与证书透明度日志的完整性模型相同，但没有区块链的开销。
**合规性报告** —— gateway 根据涵盖 SOC 2（12 项控制）和 ISO 27001（10 项控制）的 22 项控制措施评估你的实时配置。控制措施通过或失败取决于实际启用的功能 —— vault、guardrails、analytics、audit chain。无需自我评估表格。Gateway 会自我评估。
**证据导出** —— `GET /v1/audit/export` 生成一个签名证据包：完整的审计链、合规性报告、时间范围、HMAC 证明。将其作为单个 JSON 文档交给你的审计员。该证明可以针对你的签名密钥进行独立验证。
| Endpoint | Method | Description |
|---|---|---|
| `/v1/audit` | GET | 链完整性 + 实时合规性评估 |
| `/v1/audit/export` | GET | 提供给监管机构的签名证据包 |
## 运维保障
AIR 是一个 **见证者，而非守门人**。它不会导致你的 AI 系统失败。
**非阻塞** —— Vault 无法访问？Gateway 仍然代理。你的 AI 永远不会因为记录失败而停止。
**有损安全** —— 丢失一条记录是可以接受的。丢失一个请求则不行。记录是尽力而为的；代理是得到保证的。
**自我降级** —— OTel Collector 宕机？Spans 被静默丢弃。文件系统已满？AIR 记录优雅地失败。记录警告，永不返回错误。
## 隐私与数据边界
你控制所有数据。你选择记录什么。
| Mode | What's Stored | Use Case |
|---|---|---|
| **Full vault** (default) | Prompts + completions in your MinIO | Complete reconstruction |
| **Metadata only** | Model, tokens, timing, run_id | Lightweight audit, no content |
| **Hash only** | SHA-256 of request/response | Prove a call happened without storing what was said |
| **Selective redaction** | Content with PII/PHI stripped | Healthcare, fintech, enterprise |
*"我们可以证明发生了什么，而无需暴露数据。"* 这就是让本产品在受监管行业中可行的原因。
## 生态系统
15 个仓库，全部经过测试，全部具备 CI/CD，全部采用 Apache-2.0 协议。
| Layer | Repos | What It Does |
|---|---|---|
| **Gateway** | `gateway` (this repo) | Proxy + vault + AIR records + guardrails + trust |
| **SDK** | [`python-sdk`](https://github.com/airblackbox/python-sdk) | Python integrations — OpenAI, LangChain, CrewAI |
| **Episode Ledger** | [`agent-episode-store`](https://github.com/airblackbox/agent-episode-store) | Groups AIR records into replayable task-level episodes |
| **Eval Harness** | [`eval-harness`](https://github.com/airblackbox/eval-harness) | Replays episodes, scores results, detects regressions |
| **Policy Engine** | [`agent-policy-engine`](https://github.com/airblackbox/agent-policy-engine) | Risk-tiered autonomy, runtime enforcement |
| **Collector** | [`genai-semantic-normalizer`](https://github.com/airblackbox/genai-semantic-normalizer), [`prompt-vault-processor`](https://github.com/airblackbox/prompt-vault-processor), [`otel-processor-genai`](https://github.com/airblackbox/opentelemetry-collector-processor-genai) | Normalize → vault → redact → metrics |
| **Platform** | [`air-platform`](https://github.com/airblackbox/air-platform) | Docker Compose orchestration + integration tests |
| **Replay** | [`agent-vcr`](https://github.com/airblackbox/agent-vcr), [`trace-regression-harness`](https://github.com/airblackbox/trace-regression-harness) | Record/replay agent runs, policy assertions on traces |
| **Governance** | [`mcp-policy-gateway`](https://github.com/airblackbox/mcp-policy-gateway), [`mcp-security-scanner`](https://github.com/airblackbox/mcp-security-scanner), [`agent-tool-sandbox`](https://github.com/airblackbox/agent-tool-sandbox), [`aibom-policy-engine`](https://github.com/airblackbox/aibom-policy-engine), [`runtime-aibom-emitter`](https://github.com/airblackbox/runtime-aibom-emitter) | Tool firewall, security scanning, sandboxing, AI bill of materials |
| **Trust** | `pkg/trust` (this repo) | HMAC audit chain, SOC 2 + ISO 27001 compliance, evidence export |
## 价值阶梯
```
Visibility (what happened)
→ Detection (something is wrong)
→ Prevention (stop it automatically)
→ Optimization (make it better)
→ Trust (prove it to regulators)
→ Autonomy (let the agent act, safely)
```
每一层都建立在下一层之上。你无法检测你看不见的东西。你无法预防你检测不到的东西。你无法信任你无法证明的东西。而没有信任，你就无法授予自主权。
## 已发布功能
| Version | Capability | Status |
|---|---|---|
| v0.1 | Recording, replay, vault, OTel pipeline, 8 providers | ✅ |
| v0.1 | Non-blocking proxy with streaming, auth, timeout safety | ✅ |
| v0.4 | Runaway agent kill-switch, cost guardrails, loop detection | ✅ |
| v0.5 | Policy enforcement, PII blocking, tool allowlists, HITL approval | ✅ |
| v0.6 | Cross-agent analytics, model routing, failure taxonomy | ✅ |
| v0.7 | HMAC-SHA256 audit chain, SOC 2 + ISO 27001 reporting, evidence export | ✅ |
| v0.8 | Python SDK (OpenAI, LangChain, CrewAI), CI/CD across all repos | ✅ |
## 下一步计划
| Phase | Timeline | Focus |
|---|---|---|
| Foundation | Q1–Q2 2026 | Episode model, durable state, pause/resume |
| Risk-Tiered Autonomy | Q3–Q4 2026 | Cost-of-error gating, approval workflows, sandbox replay |
| Multi-Agent Orchestration | Q1–Q2 2027 | Planner/executor/critic, escalation policies, shared state |
| External Trust Wedge | Q3–Q4 2027 | Trust layer as add-on, onboarding templates, incident runbooks |
| Enterprise Scale | 2028–2029 | Multi-tenant isolation, provenance search, SCIM provisioning |
## 配置
| Variable | Default | Description |
|---|---|---|
| `LISTEN_ADDR` | `:8080` | Gateway 监听地址 |
| `PROVIDER_URL` | `https://api.openai.com` | 上游 LLM provider |
| `VAULT_ENDPOINT` | `localhost:9000` | MinIO/S3 endpoint |
| `VAULT_ACCESS_KEY` | `minioadmin` | S3 access key |
| `VAULT_SECRET_KEY` | `minioadmin` | S3 secret key |
| `VAULT_BUCKET` | `air-runs` | S3 bucket name |
| `VAULT_USE_SSL` | `false` | S3 的 TLS |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `localhost:4317` | OTel collector gRPC |
| `RUNS_DIR` | `./runs` | AIR 记录目录 |
| `TRUST_SIGNING_KEY` | *(none)* | HMAC-SHA256 签名密钥 |
## AIR 记录格式
每次运行都会生成一个 `.air.json` 文件：
```
{
"version": "1.0.0",
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"trace_id": "abc123...",
"timestamp": "2025-02-14T10:30:00Z",
"model": "gpt-4o-mini",
"provider": "openai",
"request_vault_ref": "vault://air-runs/550e8400.../request.json",
"response_vault_ref": "vault://air-runs/550e8400.../response.json",
"request_checksum": "sha256:a1b2c3...",
"response_checksum": "sha256:d4e5f6...",
"tokens": { "prompt": 25, "completion": 142, "total": 167 },
"duration_ms": 1230,
"status": "success"
}
```
## 许可证
Apache-2.0。开源协议层将始终是 Apache-2.0。
采用路径：**开放协议 → 通用依赖 → 运维期望 → 合规要求。**
详情请参阅 [LICENSE](LICENSE)。有关未来的商业治理服务，请参阅 [商业附录](docs/COMMERCIAL_ADDENDUM.md)。标签：AI安全, AI治理, AI飞行记录仪, API集成, Chat Copilot, DevOps工具, DNS 反向解析, EVTX分析, GET参数, Go语言, HMAC校验, LangChain集成, LLM审计, MinIO, OpenAI兼容, OpenTelemetry, Python SDK, RAG运维, 中间件, 事件重放, 事故重建, 人工智能安全, 反向代理, 可观测性, 合规性, 提示词记录, 数据溯源, 日志审计, 漏洞探索, 用户代理, 程序破解, 请求拦截, 防篡改