AgentLock
An adversarially benchmarked reference implementation for pre-action agent authorization
Your AI agent needs a login screen. AgentLock is that login screen.
## 问题
所有主流的 AI agent 框架 —— LangChain、CrewAI、AutoGen 等 —— 都将工具调用视为受信任的函数调用，**没有身份验证，没有范围限制，也没有访问控制**。
```
{
"name": "send_email",
"description": "Sends an email to a recipient",
"parameters": { "to": "string", "subject": "string", "body": "string" }
}
```
这个工具会向**任何人**发送电子邮件，包含**任何内容**，在**任何时间**，出于**任何理由**，由能够与该 agent 通信的**任何用户** —— 或攻击者 —— 发起。
这相当于给计算机上的每个应用程序都赋予了完整的 root 访问权限，并寄希望于它行为规矩。
## 解决方案
AgentLock 为每个工具添加了一个 `permissions` 块。其中两个字段提供了直接的价值。完整的规范涵盖了所有内容。
```
pip install agentlock
```
### 5 分钟内保护你的第一个工具
```
from agentlock import AuthorizationGate, AgentLockPermissions
gate = AuthorizationGate()
# 定义权限 — 默认拒绝
gate.register_tool("send_email", AgentLockPermissions(
risk_level="high",
requires_auth=True,
allowed_roles=["account_owner", "admin"],
rate_limit={"max_calls": 5, "window_seconds": 3600},
data_policy={
"output_classification": "contains_pii",
"prohibited_in_output": ["ssn", "credit_card"],
"redaction": "auto",
},
))
# 每次调用都经过 gate
result = gate.authorize(
"send_email",
user_id="alice",
role="account_owner",
parameters={"to": "bob@company.com", "subject": "Q3 Report"},
)
if result.allowed:
output = gate.execute("send_email", my_send_func, token=result.token,
parameters={"to": "bob@company.com", "subject": "Q3 Report"})
else:
print(result.denial)
# {"status": "denied", "reason": "insufficient_role", ...}
```
### 或使用装饰器
```
from agentlock import AuthorizationGate, agentlock
gate = AuthorizationGate()
@agentlock(gate, risk_level="high", allowed_roles=["admin"])
def send_email(to: str, subject: str, body: str) -> str:
return f"Email sent to {to}"
# 使用 auth context 调用
send_email(to="bob@co.com", subject="Hi", body="Hello",
_user_id="alice", _role="admin")
```
## 核心原则
| 原则 | 含义 |
|-----------|--------------|
| **默认拒绝** | 未定义权限 = 拒绝。始终如此。 |
| **工具级强制执行** | 每个工具强制执行自身的权限。 |
| **身份绑定访问** | 每次调用均与已验证的身份绑定。Agent 无法自行断言身份。 |
| **最小权限** | 特定操作所需的最低访问权限。 |
| **框架无关** | 核心部分零框架依赖。 |
| **可审计** | 每次调用都会生成审计记录。无一例外。 |
## Schema
符合 AgentLock 规范的工具通过添加 `agentlock` 块来扩展标准定义：
```
{
"name": "send_email",
"description": "Sends an email to a recipient",
"parameters": { "to": "string", "subject": "string", "body": "string" },
"agentlock": {
"version": "1.0",
"risk_level": "high",
"requires_auth": true,
"allowed_roles": ["account_owner", "admin"],
"scope": {
"data_boundary": "authenticated_user_only",
"max_records": 1,
"allowed_recipients": "known_contacts_only"
},
"rate_limit": { "max_calls": 5, "window_seconds": 3600 },
"data_policy": {
"output_classification": "contains_pii",
"prohibited_in_output": ["ssn", "credit_card"],
"redaction": "auto"
},
"audit": { "log_level": "full", "retention_days": 90 },
"human_approval": { "required": false }
}
}
```
### 风险等级
| 等级 | 描述 | 默认行为 |
|-------|-------------|-----------------|
| `none` | 只读，非敏感 | 自动允许，最小化日志记录 |
| `low` | 只读，潜在敏感 | 身份验证后自动允许，标准日志记录 |
| `medium` | 写操作，范围受限 | 身份验证 + 范围检查 + 完整日志记录 |
| `high` | 向外部系统写入或涉及 PII | 身份验证 + 范围 + 速率限制 + 完整日志记录 |
| `critical` | 涉及财务、破坏性或批量操作 | 身份验证 + 审批 + 完整日志记录 |
## 三层强制执行
```
┌──────────────────────────────────────────────┐
│ Layer 1: Agent (Conversation) │
│ - Reads/writes messages │
│ - Decides which tool to call │
│ - CANNOT authenticate, see credentials, │
│ or access backends │
├──────────────────────────────────────────────┤
│ Layer 2: Authorization Gate (AgentLock) │
│ - Validates permissions │
│ - Verifies identity, role, scope │
│ - Enforces rate limits │
│ - Issues single-use execution tokens │
│ - Generates audit records │
├──────────────────────────────────────────────┤
│ Layer 3: Tool Execution (Infrastructure) │
│ - Validates token │
│ - Executes within scoped boundaries │
│ - Enforces data policy / redaction │
│ - Token is single-use, time-limited │
└──────────────────────────────────────────────┘
```
**关键约束：** Agent 永远不会接收到执行 token。Layer 2 直接传递给 Layer 3。Agent 仅获取结果。
## 安全提示
AgentLock 负责对工具调用进行授权。它不对用户进行身份验证。Web 框架集成（FastAPI、Flask）信任上游 header 中的身份。请将其部署在经过身份验证的 API 网关或反向代理之后。
## 安全加固
AgentLock 假定授权网关运行在受信任的计算环境中。以下建议可加强生产环境部署中的强制执行边界：
- 将网关部署在与 agent 不同的独立机器或容器上。被攻破的 agent 无法篡改其无法访问的网关。
- Agent 应通过经过身份验证的 API 与网关通信，而不是通过共享内存或本地函数调用。
- 网关主机应仅运行网关服务，以保持最小的攻击面。
- 应用标准的基础设施安全措施：加密传输、受限的网络访问、操作系统级的审计日志。
## 框架集成
AgentLock 是框架无关的。为以下流行框架提供可选集成：
```
pip install agentlock[langchain] # LangChain
pip install agentlock[crewai] # CrewAI
pip install agentlock[autogen] # AutoGen
pip install agentlock[mcp] # Model Context Protocol
pip install agentlock[fastapi] # FastAPI
pip install agentlock[flask] # Flask
pip install agentlock[crypto] # Ed25519 signed receipts
pip install agentlock[all] # Everything
```
### LangChain
```
from agentlock.integrations.langchain import AgentLockToolWrapper
protected_tool = AgentLockToolWrapper(
tool=my_langchain_tool,
gate=gate,
permissions=AgentLockPermissions(risk_level="high", allowed_roles=["admin"]),
)
```
### FastAPI
```
from agentlock.integrations.fastapi import AgentLockMiddleware, require_agentlock
app = FastAPI()
app.add_middleware(AgentLockMiddleware, gate=gate)
@app.post("/api/send-email")
async def send_email(request: Request, auth=Depends(require_agentlock(gate, "send_email"))):
...
```
## CLI
```
agentlock init # Generate starter tool definition
agentlock validate tool.json # Validate against schema
agentlock inspect tool.json # Display permissions summary
agentlock schema # Print JSON schema
agentlock audit --tool send_email # Query audit logs
```
## AgentLock 防范的内容
基于实证研究：涵盖 35 个类别的多轮对抗性攻击测试，并在多个前沿 AI 模型上进行了测试。
| 攻击类别 | 防范措施 |
|----------------|-----------|
| Prompt injection | 网关处的确定性权限强制执行，辅以内容扫描 |
| 社会工程学 | 通过密码学手段验证身份，而非通过对话 |
| 数据泄露 | max_records + rate_limit + data_boundary |
| 权限提升 | 每次调用均检查 Role |
| 工具滥用 | Scope 约束 + 速率限制 |
| Token 重放 | 一次性、时间限制、绑定特定操作 |
| Agent 冒充 | 带外身份验证 |
| 记忆中毒 | 记忆网关（allowed_writers + prohibited_content），在网关处强制执行 |
**深度防御。** 对抗性和合法的工具请求在语义上可能完全相同，因此没有扫描器能捕获所有攻击。这就是授权网关处于首要位置的原因：它提供了确定性的保证 —— 无论请求的措辞如何，超出身份声明权限的调用都会被拒绝。内容扫描和自适应 prompt 加固是加速器，而不是基础：它们提高了对那些落在 agent *允许范围内* 的攻击的拦截率，而这正是网关无法单独掌控的区域。两层机制都很重要，我们自己的基准测试也证明了这一点：自适应 prompt 加固 —— 一个内容检测层 —— 是促使 v1.2 在受控管理员配置上的通过率从 30.2% 跃升至 57.1% 的最大单一因素，它正是叠加在网关之上的。网关使得未经授权的操作在结构上变得不可能；而扫描则缩小了网关从未被设计去覆盖的残余攻击面。
## v1.1：记忆与上下文权限
AgentLock v1.1 将工具级别的权限扩展到涵盖 agent 的 **context window** 和 **记忆**。并非所有的上下文都是同等重要的 —— 系统 prompt 和网络搜索结果不应对 agent 的行为拥有相同的权限。
### Context 权限
每一个上下文条目都会根据来源进行分类，并被赋予一个权限级别：
```
from agentlock import (
AuthorizationGate, AgentLockPermissions,
ContextPolicyConfig, TrustDegradationConfig, DegradationTrigger,
ContextSource, DegradationEffect,
)
gate = AuthorizationGate()
gate.register_tool("web_search", AgentLockPermissions(
risk_level="low",
requires_auth=True,
allowed_roles=["analyst"],
context_policy=ContextPolicyConfig(
trust_degradation=TrustDegradationConfig(
enabled=True,
triggers=[
DegradationTrigger(
source=ContextSource.WEB_CONTENT,
effect=DegradationEffect.REQUIRE_APPROVAL,
),
],
),
),
))
```
一旦网络搜索结果进入 context，所有后续的工具调用都需要人工审批。信任度在单次会话内会逐渐衰减，且绝不会提升 —— 只有开启新的会话才能恢复完全信任。
### 记忆访问控制
```
from agentlock import MemoryPolicyConfig, MemoryWriter, MemoryPersistence
gate.register_tool("assistant", AgentLockPermissions(
risk_level="medium",
requires_auth=True,
allowed_roles=["user"],
memory_policy=MemoryPolicyConfig(
persistence=MemoryPersistence.SESSION,
allowed_writers=[MemoryWriter.SYSTEM, MemoryWriter.USER],
prohibited_content=["credentials", "pii"],
require_write_confirmation=True,
),
))
```
### 来源追踪
每一次对 context 的写入都会生成一条 `ContextProvenance` 记录，其中包含来源、权限级别、写入者身份、时间戳和内容哈希。审计记录现在包含 `trust_ceiling`、`context_provenance_ids` 和 `memory_operation` 字段。
## v1.2：自适应加固与新的决策类型
AgentLock v1.2 增加了四项功能，以此弥合授权与运行时防御之间的差距。
### 自适应 Prompt 加固
当网关检测到可疑活动时，它会为 agent 的系统 prompt 生成防御性指令。一个前 LLM prompt 扫描器会在模型处理用户消息之前对其进行分析，从而能够在攻击的第一轮就实现加固。四个信号检测器（速度、工具组合、响应回显、prompt 扫描）共同汇入一个单调递增的会话风险评分中。
### 五种决策类型
v1.0/v1.1 支持 ALLOW 和 DENY。v1.2 新增了三种：
| 决策 | 时机 | 效果 |
|----------|------|--------|
| **ALLOW** | 调用已获授权 | 签发 token，工具正常执行 |
| **DENY** | 调用未获授权 | 无 token，返回结构化拒绝 |
| **MODIFY** | 调用已获授权，但输出必须经过转换 | 签发 token，LLM 查看输出前剔除其中的 PII |
| **DEFER** | 上下文存在歧义，网关无法做出决定 | 挂起操作，通过人工审查或超时解决 |
| **STEP_UP** | 会话状态表明风险升高 | 暂停操作，需要人工审批 |
### MODIFY：输出转换
```
gate.register_tool("query_database", AgentLockPermissions(
risk_level="high",
requires_auth=True,
allowed_roles=["admin", "support"],
modify_policy=ModifyPolicyConfig(
enabled=True,
transformations=[
TransformationConfig(field="output", action="redact_pii"),
TransformationConfig(
field="to", action="restrict_domain",
config={"allowed_domains": ["company.com"]},
),
],
),
))
result = gate.authorize("query_database", user_id="alice", role="admin")
# result.decision == DecisionType.MODIFY
# result.modify_output_fn 在 LLM 查看之前从 tool 输出中剥离 PII
output = gate.execute("query_database", db_func, token=result.token,
modify_output_fn=result.modify_output_fn)
# output: {'name': 'Jane Doe', 'email': '[REDACTED:email]', 'ssn': '[REDACTED:ssn]'}
```
工具依然会执行。管理员依然能得到答案。但是 PII 永远不会进入 LLM 的 context 中，从而避免了被 injection 攻击武器化。
### 签名回执 (AARM R5)
每个授权决策都可以生成一份经过密码学签名的回执，无需访问网关即可进行离线验证。被篡改的回执将无法通过签名验证。
```
from agentlock import AuthorizationGate, ReceiptSigner, ReceiptVerifier
signer = ReceiptSigner(signing_method="ed25519")
gate = AuthorizationGate(receipt_signer=signer)
result = gate.authorize("query_database", user_id="alice", role="admin")
# result.receipt 是一个带有 Ed25519 签名的 SignedReceipt
verifier = ReceiptVerifier(signing_method="ed25519", verify_key=signer.verify_key_bytes)
assert verifier.verify(result.receipt) # True
```
当未安装 PyNaCl 时，HMAC-SHA256 可作为备选方案。通过 `pip install agentlock[crypto]` 安装对 Ed25519 的支持。
### 哈希链上下文 (AARM R2)
上下文条目构成了一条防篡改的仅追加链。每个条目都包含前一个条目的哈希值。修改任何条目都会使其后的所有条目失效。
```
gate.notify_context_write(session_id, source=ContextSource.TOOL_OUTPUT,
content_hash="abc123...")
valid, broken_at = gate.context_tracker.verify_context_chain(session_id)
# 如果完好无损则为 (True, None)，如果被篡改则为 (False, index)
```
## 基准测试
AgentLock 会针对一套已发布的对抗性测试套件进行测试，其结果 —— 包括性能退步 —— 都是公开的。这正是关键所在：安全声明应当是可证伪的并带有版本标记。两项测试活动的完整文档均记录在 [docs/benchmark.md](docs/benchmark.md) 中。
- **五阶段演进 (v1.0 → v1.1.2)** 针对运行在 Gemini 2.5 Flash-Lite 上的 LangChain agent。Injection 失败次数从 73 次（无保护）降至 12 次；PII 泄漏从 3 次降至 0 次。报告并未掩盖挫折：v1.1 在追求提升 injection 防御时破坏了 PII 保护（100/A → 0/F），而 v1.1.1 在恢复 PII 防御时导致了 injection 退步（6 → 21 次失败）。v1.1.2 解耦了这两个过滤管线，并同时稳住了两者。
- **受控管理员配置 (v1.2.x)** 针对 Grok 进行，其中合法的管理员凭证能通过所有的身份验证和角色检查 —— 从而将行为和结构防御与 RBAC 隔离开来。通过率：30.2%（仅权限） → 81.3%（自适应加固 + MODIFY/DEFER/STEP_UP） → 99.5%（v1.2.1）。
### 各模块得分（五阶段，v1.0 → v1.1.2）
| 模块 | 无 AgentLock | v1.0 | v1.1 | v1.1.1 | v1.1.2 |
|--------|--------------|------|------|--------|--------|
| PII 检测 | 65/D | 100/A | 0/F | 100/A | 100/A |
| Injection | 56% / F | 89% / B | 96.3% / A | 88.6% / B | 93.4% / B |
| 数据流 | 97/A | 74/C | 97/A | 97/A | 97/A |
| YARA 检测 | 0/F | 40/F | 60/D | 0/F | 60/D |
| 合规性 | 7/F | 15/F | 7/F | 0/F | 0/F |
| **权限** | **45/F** | **60/D** | **45/F** | **45/F** | **45/F** |
**关于 45/F 的权限得分（这是一个已知且有明确范围的差距 —— 并未被隐藏）。** 权限模块在 v1.1–v1.1.2 中的得分停留在 45/F，它值得一个诚实的解释。它**并不**衡量网关是否强制执行了权限 —— 网关是确定性地执行权限的，这恰恰是 injection 进展和其他每一行数据所证明的。它衡量的是 *agent 的回复* 能否抵御权限和角色侦察：比如枚举工具名称、确认账户层级结构是否存在、在探查时泄露表名。这些正是属于模型层信息泄露行为（SP、EBE 和 RE 类别），它们占据了 v1.1.2 剩余 12 次 injection 失败中的 9 次。Middleware 可以拦截请求或对输出进行脱敏，但它无法阻止一个“乐于助人”的模型去*承认*系统 prompt 或受限层级的客观存在。解决之道不在于更多的过滤 —— 而是需要进行系统 prompt 加固，指示模型去回避而不是去确认。
这正是 v1.2 自适应 prompt 加固所补充的能力，而 v1.2.1 的受控管理员测试运行结果 —— 在系统 prompt 提取、基于错误的提取和拒绝耗尽方面均达到了 100/A —— 就是该方法有效的证据。合规性行得分较低也出于类似原因：它评估的是参考 agent 尚未生成的合规证明和报告工件；合规报告模板已列入 v2.0 的路线图。这两个分数都没有被掩盖 —— 它们都在带有明确计划的路线图上。
v1.2 测试套件是在此 repo 中编写和评分的；针对外部套件（如 AgentDojo 等）的测试已在计划中。
## AgentLock 的对比
行动前授权领域现在有了几个重量级的参与者。此表格基于截至 2026 年 7 月各项目的主要来源（repo、规范说明、论文）构建。如果某项能力无法通过主要来源进行核实，则会被标记为 *不明确* (❓)，而不是假定其不存在。
| 能力 | AgentLock | MS AGT | OAP | NeMo | AgentMint |
|---|:---:|:---:|:---:|:---:|:---:|
行动前授权网关
1 | ✅ | ✅ | ✅ | ❌ | ⚠️ |
| 会话级复合行为评分
2 | ✅ | ❓ | ❌ | ❌ | ❌ |
| 超出允许/拒绝之外的决策类型
3 | ✅ | ✅ | ⚠️ | ⚠️ | ❌ |
| 包含退步数据的已发布对抗性基准测试
4 | ✅ | ❌ | ⚠️ | ❌ | ❌ |
| 会话内的信任度衰减
5 | ✅ | ❓ | ❌ | ❌ | ❌ |
| Ed25519 签名回执
6 | ✅ | ✅ | ❓ | ❌ | ✅ |
| 哈希链防篡改审计
7 | ✅ | ✅ | ✅ | ❌ | ✅ |
| 框架集成（数量）
8 | 6 | ~19 | ~7 | 1 | 5 |
| OWASP 映射覆盖率
9 | ✅ | ✅ | ❓ | ❓ | ⚠️ |
| 语言 SDK（数量）
10 | 1 | 5 | 1 | 1 | 2 |
图例： ✅ 具备 · ⚠️ 部分具备 · ❌ 不具备 · ❓ 不明确（无法从主要来源确认）。
1. **行动前授权网关。** OAP 将此映射到其 PAA-2 控制项。NeMo 拥有内容/对话护栏，而不是身份/范围授权。AgentMint 在回执中记录了 scope，但其重点是事后行动（公证）。
2. **会话级复合行为评分。** AgentLock 会对会话内的调用*序列*进行评分（例如：速率激增 + 可疑工具组合会触发 `rapid_exfil` 复合规则）。在 MS AGT 的规范中没有记录此项；在其他项目中均缺失。
3. **超出允许/拒绝之外的决策类型。** AgentLock：ALLOW/DENY/MODIFY/DEFER/STEP_UP。MS AGT：allow/warn/deny/escalate/transform（直接的同类对标）。OAP：allow/deny/escalate（指定了 escalate 但在参考实现中未实现）。NeMo：仅拒绝/更改内容，不涉及授权决策。AgentMint：二进制 `in_policy`。
4. **包含退步数据的已发布对抗性基准测试。** AgentLock：v1.0→v1.1.2 的五阶段演进加上 v1.2 受控管理员配置。MS AGT：其文档声明暂未发布任何基准。OAP：Vault CTF，单一配置，而非跨版本比较。NeMo：仅有 garak 示例扫描。AgentMint：一致性向量已推迟。
5. **会话内的信任度衰减。** AgentLock：单调、按会话计算。MS AGT：一个 0–1000 的信任评分，声称在博客文章中会衰减，但在规范中未作定义。在其他项目中均缺失。
6. **Ed25519 签名回执。** AgentLock：Ed25519，带有 HMAC-SHA256 回退。MS AGT：基于 RFC 8785 (JCS) 的单次调用 Ed25519，did:mesh 身份。OAP：颁发可验证护照，但无法确认是否进行了 Ed25519 回执签名。AgentMint：具备。
7. **哈希链防篡改审计。** AgentLock：哈希链上下文 (AARM R2)。MS AGT：Merkle / SHA-256 审计链。OAP：防篡改日志 (PAA-4)。NeMo：仅限遥测 / OpenTelemetry，非密码学链。AgentMint：在规范中定义，尽管目前的参考验证器仅检查签名。
8. **框架集成。** AgentLock：LangChain, CrewAI, AutoGen, MCP, FastAPI, Flask。MS AGT (~19)：Semantic Kernel, AutoGen, LangGraph, CrewAI, OpenAI Agents SDK, MCP 等。OAP (~7)：LangChain, CrewAI, Cursor, Claude Code, n8n 等。NeMo：LangChain。AgentMint：LangChain, CrewAI, OpenAI Agents SDK, MCP, Google ADK。
9. **OWASP 映射覆盖率。** AgentLock：OWASP LLM Top 10 以及下方的 Agentic (ASI) 和 MCP 映射。MS AGT：声称 10/10 覆盖 Agentic Top 10（自述）。OAP：未发布编号映射。NeMo：仅有第三方映射，无官方版本。AgentMint：引用了 OWASP Agentic 目录，但未发布带编号的映射。
10. **语言 SDK。** AgentLock：Python。MS AGT (5)：Python, TypeScript, .NET, Rust, Go。OAP：JavaScript/TypeScript (npm)。NeMo：Python。AgentMint (2)：Python 生产者 + Go 验证者。
**客观地看待这些对比。** Microsoft 的 Agent Governance Toolkit 在分发范围和密码学层面上领先于 AgentLock：大约 19 个框架集成对比我们的 6 个，五种语言 SDK 对比我们的一种，一个 MCP 安全网关，单次调用 Ed25519 回执，以及 Merkle 链审计日志。它还推出了一个五项决策模型（allow/warn/deny/escalate/transform），这正是我们的直接对标对象 —— 我们的决策类型是**与 AGT 持平，而非胜过它**。Ed25519 签名回执和哈希链审计同样正成为基本门槛，而非差异化优势：AGT 和 AgentMint 都已支持这些功能。
AgentLock 真正狭隘且有防御价值的优势在于两点：
1. **一份包含自身性能退步的已发布对抗性基准测试。** AGT 自己的文档声明它尚未发布攻击成功率基准，并警告不要相信归属于它的第三方百分比数据。OAP 报告的是单一配置的 CTF，而不是跨版本比较。AgentLock 公布了完整的 v1.0→v1.1.2 演进过程，*包括* v1.1 的 PII 破坏和 v1.1.1 的 injection 退步，以及 v1.2 受控管理员测试运行。这个表格中没有其他人展示过他们的挫折。我们做到了。
2. **会话级复合行为评分。** AgentLock 会对会话内的调用*序列*进行评分 —— 例如：速率激增结合可疑工具组合会触发 `rapid_exfil` 复合规则，而这两个信号单独出现时都不会触发。这不同于单一的标量信任评分，而且在其他任何项目的主要来源中均未见诸文档。
这就是我们诚实的立场：一个更小、单一语言的参考实现，其优势在于严谨性和行为分析，而非分发规模。
## 标准一致性
AgentLock 定位为**新兴的行动前授权共识的参考实现 —— 而非相互竞争的标准。** 随着独立的规范逐渐趋同于同一个理念（在工具调用执行*之前*进行确定性授权），AgentLock 旨在成为这些控制项的具体且可测试的实例。
### Open Agent Passport (OAP) 行动前控制
OAP (Uchibeke, arXiv:2603.20953) 定义了五项行动前授权控制，即 PAA-1 到 PAA-5。AgentLock 实现了全部五项：
| OAP 控制项 | 需求 | AgentLock |
|---|---|---|
| **PAA-1** | 机器可读的策略，规定允许哪些工具调用、在何种条件下、处于何种保证级别 | 每个工具配备 `AgentLockPermissions` 块（包含 risk_level, allowed_roles, scope, data_policy） |
| **PAA-2** | 在每次工具调用前同步执行策略的平台级 hook，独立于模型运作 | `AuthorizationGate.authorize()` 在 `execute()` 之前运行；agent 永远不会接收到 token |
| **PAA-3** | 将 agent 绑定到已授权 scope 的可验证凭证 | 一次性、绑定 SHA-256 参数的执行 token + Ed25519 签名回执（能力绑定；非 W3C VC 格式） |
| **PAA-4** | 包含所有授权决策的防篡改审计日志 | 完整审计记录 + 哈希链上下文 (AARM R2) |
| **PAA-5** | 在缺乏有效决策时默认拒绝 | 默认拒绝是核心原则：无权限 = 拒绝 |
### OWASP Agentic 应用 Top 10 (ASI, 2026)
AgentLock 并未声称达到 10/10 的完全覆盖。它映射到了工具授权层实际能够强制执行的类别：
| ID | 类别 | AgentLock 覆盖范围 |
|---|---|---|
| **ASI01** | Agent 目标劫持 | 一旦不可信内容进入，即触发 Injection 过滤器 + 信任度衰减 |
| **ASI02** | 工具误用与漏洞利用 | 按工具划分的权限、scope 限制、速率限制 |
| **ASI03** | 身份与权限滥用 | 每次调用均检查 Role；agent 无法自我提权 |
| **ASI06** | 记忆与上下文中毒 | 记忆网关 (allowed_writers, prohibited_content) + 上下文权限 |
| **ASI09** | 人机信任利用 | 针对升高风险的 STEP_UP / 人工审批网关 |
| **ASI10** | 流氓 Agent | 会话级复合评分 + 单调递增的信任度衰减 |
超出授权层范围的包括：ASI04（供应链）、ASI05（意外代码执行）、ASI07（Agent 间通信）、ASI08（级联故障）。Agent 间授权已列入 v1.2+ 的路线图。
### OWASP MCP Top 10 (2025)
AgentLock 解决了 10 项 MCP 风险中的 8 项：
| ID | 类别 | AgentLock 覆盖范围 |
|---|---|---|
| **MCP01** | Token 管理不善与机密暴露 | 带外身份验证；凭证绝不会进入对话 |
| **MCP02** | 通过范围蔓延引发权限提升 | 每个工具声明 scope，由网关验证 |
| **MCP03** | 工具投毒 | Injection 过滤器递归检查嵌套参数 |
| **MCP05** | 命令注入与执行 | Injection 过滤器阻止命令注入 payload |
| **MCP06** | 通过上下文 Payload 进行的 Prompt Injection | 上下文权限 + Injection 过滤器 |
| **MCP07** | 身份验证与授权不足 | 核心功能：默认拒绝授权网关 |
| **MCP08** | 缺乏审计与遥测 | 每次调用都会生成审计记录；哈希链上下文 |
| **MCP10** | 上下文注入与过度分享 | 信任度衰减 + 数据策略输出限制 |
未涉及内容：MCP04（供应链 / 依赖篡改）和 MCP09（影子 MCP 服务器）属于部署基础设施层面的问题，不在授权层的职责范围内。
### 其他框架
| 标准 | 覆盖范围 |
|----------|----------|
| **OWASP LLM Top 10 (2025)** | LLM01 Prompt Injection, LLM05 不安全的输出, LLM06 过度授权 |
| **NIST AI RMF (AI 100-1)** | Govern, Map, Measure, Manage 功能 |
| **NIST SP 800-53 Rev. 5** | AC, AU, IA, SI 控制族 |
| **MITRE ATLAS** | AML.T0051 Prompt Injection, AML.T0054 越狱 |
| **欧盟 AI 法案** | 透明度（审计）、人类监督（审批）、风险分类 |
## 路线图
| 版本 | 重点 |
|---------|-------|
| **v1.0** | 核心 schema、工具权限、强制执行架构 |
| **v1.1** | 记忆/上下文权限、信任度衰减、来源追踪 |
| **v1.2** | 自适应加固、MODIFY/DEFER/STEP_UP 决策、签名回执、哈希链上下文（847 项测试） |
| **v1.3** | 输出目标控制、数据流策略 |
| **v2.0** | 执行范围、行为策略、异常检测、合规模板 |
## 贡献
欢迎踊跃贡献。请先开一个 issue 讨论您希望做出的更改。
```
git clone https://github.com/webpro255/agentlock.git
cd agentlock
pip install -e ".[dev]"
pytest
```
## 许可证
Apache 2.0 —— 详见 [LICENSE](LICENSE)。
## 作者
**David Grice** —— [agentlock.dev](https://agentlock.dev)
直到最近，AI 工具一直是现代计算中唯一缺乏权限模型的可编程系统访问类别。AgentLock 正致力于填补这一空白。