cwellbournewood/aegis
GitHub: cwellbournewood/aegis
面向 LLM 应用的开源 prompt injection 防御网关，通过五个组合层在 agent 与模型之间提供基于密码学证明和权限授权的结构性安全防护。
Stars: 2 | Forks: 0
# AEGIS
**用于注入安全的认证执行网关。**
*Scvtvm contra iniectionem.*
这是一个个人项目，旨在探索当您将 prompt injection 视为一个结构性问题，而不是内容分类问题时，会发生什么。五个组合层——三个结构层，两个概率层——位于您的 agent 和模型之间。
位于 `/aegis/dashboard` 的操作控制台：左侧为五个层 (I–V)，中间为实时决策流，右侧为所选请求的完整投票明细。哈希链完整性持续验证中。
## 为什么存在这个项目
LLM 接收的是单一的 token 流。系统指令、用户输入、检索到的文档和工具输出之间的边界是由应用层强制执行的约定，而不是由模型强制执行的。基于过滤自然语言的防御可以被足够有创造力的自然语言所绕过。
我想看看基于加密来源证明和权限授权构建的防御在代码中究竟是什么样子。AEGIS 就是这个探索的结果。其贡献在于组合方式；没有任何一个单独的想法是新颖的。
## 五个组合层
| | 层 | 类型 | 作用 |
|---|---|---|---|
| **I** | **CCPT** | 结构层 | 每个上下文块都封装在绑定来源和信任级别的 HMAC 签名信封中 |
| **II** | **Lattice** | 结构层 | Bell-LaPadula 信息流规则。L0/L1 内容无法授权工具调用 |
| **III** | **Anchor** | 概率层 | 对用户的请求进行嵌入；检查提议的操作是否存在语义漂移 |
| **IV** | **Canary** | 概率层 | 系统提示词中的诱饵 honeytoken 指令；其泄露是高置信度的攻击证据 |
| **V** | **Capability** | 结构层 | 工具调用需要模型无法伪造的加密且受参数约束的 token |
决策引擎根据可配置的策略，综合每层的 ALLOW/WARN/BLOCK 投票。每个决策都记录在哈希链的、仅追加的审计日志中。
## Sidecar 部署
```
Your agent
↓
AEGIS proxy (5 layers)
↓
LLM provider
```
将您现有的 OpenAI、Anthropic 或 Google 客户端指向 AEGIS 代理 URL，或者使用 AEGIS SDK 进行 capability 铸造和意图声明。
## 安装
尚未在 PyPI / npm 上发布。有两种等效的安装方式。
**pip 从源码安装**（在本地提供 CLI 和 Python SDK；支持 bash、zsh、cmd 和 PowerShell）：
```
pip install git+https://github.com/cwellbournewood/aegis@main
aegis genkey > .aegis-master-key
aegis up --port 8080
```
`aegis up` 会自动检测工作目录中的 `./.aegis-master-key`。要使用不同的路径，请设置 `AEGIS_MASTER_KEY_FILE=/path/to/key`（或者使用 `AEGIS_MASTER_KEY=` 直接内联传递密钥）。
**容器**（无需安装 Python）：
```
docker run -d --name aegis -p 8080:8080 \
-e AEGIS_MASTER_KEY="$(openssl rand -hex 32)" \
ghcr.io/cwellbournewood/aegis:1.0.0
```
为了获得更高质量的漂移检测：
```
pip install 'aegis-guard[embed] @ git+https://github.com/cwellbournewood/aegis@main'
```
TypeScript SDK（从源码构建）：
```
git clone https://github.com/cwellbournewood/aegis
cd aegis/sdk-ts && npm install && npm run build
# 然后：执行 npm link，或者打包并安装生成的 tarball
```
## 快速入门
当代理运行在 `:8080` 时，通过 SDK 将 Anthropic 客户端指向它：
```
from aegis.sdk import AegisClient
import anthropic
aegis = AegisClient(base_url="http://localhost:8080")
session = aegis.session.create(
user_intent="summarize my latest invoice email",
upstream="anthropic",
)
session.capabilities.mint(
"read_email",
constraints={"folder": {"kind": "eq", "value": "inbox"}},
)
claude = anthropic.Anthropic(base_url=session.proxy_url, api_key="sk-ant-...")
resp = claude.messages.create(
model="claude-sonnet-4-5",
max_tokens=512,
messages=[{"role": "user", "content": "summarize my latest invoice email"}],
extra_body={"aegis": {"session_id": session.session_id, "capability_tokens": session.capability_tokens()}},
)
```
对于 Claude Code、Cursor 或其他使用 MCP 的 agent，还需要封装您的 MCP 服务器：
```
claude mcp add github "aegis mcp-wrap --policy strict -- npx @modelcontextprotocol/server-github"
```
完整的部署案例请参见 [docs/QUICKSTART.md](docs/QUICKSTART.md)。
## 命令行界面 (CLI)
```
aegis up # start the proxy
aegis down # stop a running proxy (PID file, or --port fallback)
aegis status # health, version, uptime
aegis logs tail | show | query --since 1h --decision BLOCK | export
aegis sessions list | show
aegis policy validate | show | explain --decision-id
aegis verify # verify hash chain + tip pointer
aegis bench # adversarial corpus benchmark
aegis bench-perf # latency / throughput
aegis genkey # 32-byte hex master key
aegis mcp-wrap -- # wrap an MCP server
```
## 配置
```
mode: balanced # strict | balanced | permissive
flows:
- { from: L0, to: tool_call, decision: BLOCK }
- { from: L1, to: tool_call, decision: WARN }
- { from: L2, to: tool_call, decision: ALLOW, require: [capability_token] }
- { from: L3, to: tool_call, decision: ALLOW }
anchor:
threshold_balanced: 0.22
threshold_strict: 0.40
embedder: { kind: hashing, dim: 384 }
canary:
enabled: true
count: 3
capability:
default_ttl_seconds: 600
nonce_store: { kind: memory } # or redis for multi-replica HA
log_path: ./aegis-decisions.log
```
完整的带有注释的默认配置请见 [`aegis/policies/default.yaml`](aegis/policies/default.yaml)。
| 变量 | 用途 |
|---|---|
| `AEGIS_MASTER_KEY` | 十六进制编码的 32 字节主密钥（用于通过 HKDF 派生每次会话密钥的根） |
| `AEGIS_MASTER_KEY_FILE` | 包含主密钥的文件路径 |
| `AEGIS_POLICY_PATH` | 策略 YAML 的路径 |
| `AEGIS_ANTHROPIC_URL` / `AEGIS_OPENAI_URL` / `AEGIS_GOOGLE_URL` | 覆盖上游 URL |
| `AEGIS_DRY_RUN=1` | 不向上游转发；返回合成响应 |
## 支持的提供商
| 提供商 | 传输格式 |
|---|---|
| Anthropic Claude 3.5+ / Claude 4 | Messages API + streaming |
| OpenAI GPT-4o / GPT-4.1 / GPT-5 | Chat Completions + streaming |
| Google Gemini 1.5+ / 2.x | `generateContent` |
尚未支持开放权重模型、Ollama 和 vLLM。
## 性能
| 指标 | 测量值（空闲，哈希嵌入器） |
|---|---|
| 增加的 p50 延迟 | 0.07 ms (简单) / 0.10 ms (1 次工具调用) / 0.25 ms (4 次工具调用) |
| 增加的 p99 延迟 | 0.13 ms / 0.28 ms / 0.49 ms |
| 吞吐量 | >12,000 req/s |
| Token 开销 | ~80 tokens / session |
以上数据来自 Windows 本地机器上的 `aegis bench-perf`。CI 断言的回归测试在每次提交时以 3 倍余量运行。
## 对抗性基准测试
针对内置的对抗样本语料库运行 `aegis bench --mode balanced`：
```
| category | attempts | blocked | warned | allowed | block rate |
|-------------+----------+---------+--------+---------+------------|
| direct | 4 | 4 | 0 | 0 | 100.0% |
| indirect | 8 | 7 | 0 | 1 | 87.5% |
| memory | 3 | 3 | 0 | 0 | 100.0% |
| multi-agent | 2 | 2 | 0 | 0 | 100.0% |
| benign | 4 | 0 | 0 | 4 | 0.0% |
```
唯一被允许的间接案例是一个显式测试，用于验证当 capability 和意图一致时，策略能正确放行来自 L2 的工具调用。良性语料库在 `balanced` 模式下的误报率为零。完整的输出和严格模式的运行结果位于 [docs/proof/](docs/proof/)。
## 流式处理
```
POST /v1/anthropic/messages/stream
POST /v1/openai/chat/completions/stream
```
每个数据块在到达时都会进行 canary 扫描。泄露会在违规数据块到达客户端之前触发一个即时的 `aegis_blocked` SSE 事件。流结束时运行完整的流水线。
## 可观测性
`GET /metrics` 返回 Prometheus 展示格式的内容，包含按上游和决策统计的请求计数器、每层投票计数、canary 泄露计数器、capability 生命周期计数器、端到端及每关卡的延迟直方图，以及活跃会话和日志条目的仪表盘。
`GET /aegis/dashboard` 是一个单页操作 UI：实时决策流、拦截率迷你图、每层的 ALLOW/BLOCK 柱状图以及最常被拦截的工具。
## 安全属性
这些是可以从源码和测试中验证的技术属性：
- HMAC 密钥通过 HKDF-SHA256 从主密钥为每次会话派生。
- 决策日志是仅追加且哈希链式的。`aegis verify ` 端到端检查完整性。
- 模型 API 密钥不会被持久化；它们被直接传递给上游提供商。
- CCPT 信封在内容到达模型之前被剥离。
- Canary token 每次会话都是加密随机的，并具有多种模板变体。
- Capability token 默认为一次性使用且具有时间限制。
- 所有密码学均使用经过审查的库（Python 的 `cryptography`，TS 的 `node:crypto`）。
## AEGIS 不是什么
- 它不是一个模型。没有对齐，也没有 RLHF。
- 它不是一个 WAF。仅检查 LLM API 路径。
- 它不能替代最小权限工具设计；它是对其的补充。
- 它不是零漏报。目标是在将误报保持在可控范围内的同时，大幅提高攻击者的成本。
## 供应链验证
每个标记的发布版本都提供了一个多架构镜像、一个 cosign 无密钥签名、一个 SLSA 构建来源证明以及一个 SPDX SBOM。
```
# 验证镜像是否由此仓库的 release workflow 构建。
cosign verify ghcr.io/cwellbournewood/aegis:1.0.0 \
--certificate-identity-regexp='https://github.com/cwellbournewood/aegis/.+' \
--certificate-oidc-issuer=https://token.actions.githubusercontent.com
# 验证 SLSA provenance。
gh attestation verify --owner cwellbournewood \
oci://ghcr.io/cwellbournewood/aegis:1.0.0
```
SBOM (SPDX) 作为附件发布在每次的 GitHub Release 中，并作为 cosign SBOM 证明附加在镜像上。
## 文档
- [快速入门](docs/QUICKSTART.md)：包含可直接复制粘贴代码的三个部署案例
- [谁应该使用它](docs/WHO_SHOULD_USE.md)：适用性检查
- [接口](docs/INTERFACES.md)：终端用户、SDK、CLI、仪表盘、审计日志
- [架构](docs/ARCHITECTURE.md)：五个层、决策流水线及实现
- [操作指南](docs/OPERATOR.md)：部署、调优、可观测性
- [贡献](CONTRIBUTING.md)：代码风格、评估标准
标签：AEGIS, AI安全, Chat Copilot, CISA项目, HMAC, LLM安全网关, LLM应用防火墙, meg, Streamlit, 信任边界, 信息安全, 大语言模型安全, 密码学验证, 开源安全工具, 提示词注入防御, 智能体安全, 机密管理, 模型无关, 深度防御, 结构化安全, 网关开发, 能力令牌, 自定义请求头, 蜜标, 访问控制, 语义漂移检测, 请求拦截, 逆向工具, 逆向工程平台