LegionForge/LegionForge-Guardian
GitHub: LegionForge/LegionForge-Guardian
LLM 智能体框架的确定性安全 Sidecar，通过模式匹配和哈希验证在工具调用前拦截提示注入、工具篡改和能力滥用等威胁。
Stars: 0 | Forks: 0
# legionforge-guardian
**LLM 智能体框架的确定性安全 Sidecar。**
[](LICENSE)
[](https://www.python.org)
[](https://pypi.org/project/legionforge-guardian)
## 问题所在
LLM 智能体可能会遭受 prompt 注入，被诱骗调用危险工具，并被诱导泄露数据——所有这些都仅仅通过自然语言即可实现。大多数框架没有安全层。少数有的则依赖另一个 LLM 来评估请求，这意味着检查器本身也可能被注入。
## Guardian 的功能
Guardian 是一个 FastAPI sidecar（端口 9766），在任何工具调用执行之前运行 **七项确定性检查**。不使用 LLM。不使用启发式算法。仅通过模式匹配、哈希验证和加密验证——做出无法被 prompt 注入的决策。
将其部署在任何智能体框架之前。如果 Guardian 发出停止指令，工具就不会运行。
## 七项检查
| # | 检查项 | 拦截内容 |
|---|---|---|
| 0 | **Task token ACL** | JWT 范围权限集之外的工具 |
| 1 | **Tool registry** | 未注册的工具；已吊销的工具（10秒传播） |
| 2 | **Capability boundary** | 禁止的行为：`register_tool`、`spawn_agent_direct`、`escalate_scope` 及其他 5 项 |
| 3 | **Destructive pattern detection** | 9 个正则表达式家族：凭证探测、Shell 注入、批量数据窃取、数据暂存、侦察、权限提升等 |
| 4 | **Sequence contracts** | 偏离注册智能体 Playbook 的工具调用序列 |
| 5 | **Hash integrity** | 注册以来描述或 Schema 哈希发生变化的工具（篡改检测） |
| 6 | **Adaptive rules** | 从数据库热加载的规则——无需重新部署即可阻断/记录/沙箱化 |
所有检查按顺序运行。首次失败即立即停止或进入沙箱。无 LLM 调用。
## 快速开始（Docker Compose — 30 秒）
```
git clone https://github.com/LegionForge/LegionForge-Guardian
cd LegionForge-Guardian
# 启动 Guardian + 其自带的 PostgreSQL (init.sql 自动运行)
GUARDIAN_DB_PASSWORD=changeme docker compose up -d
# 验证其正在运行
curl http://localhost:9766/health
# {"status": "ok", "service": "guardian", "version": "4.0.0"}
```
## Python SDK
```
from legionforge_guardian import guardian_check
# 在你的 agent 中执行任何 tool 调用之前：
result = await guardian_check(
tool_name="web_search",
tool_input={"query": "latest AI news"},
agent_state={"agent_id": "researcher", "run_id": "abc123"},
)
if not result["allowed"]:
# Guardian says halt or sandbox — do not execute the tool
raise SecurityError(result["reason"])
```
或者直接使用客户端类：
```
from legionforge_guardian.sdk.client import GuardianClient
client = GuardianClient(url="http://localhost:9766")
result = await client.check(
tool_name="file_write",
tool_input={"path": "/etc/crontab", "content": "..."},
agent_state={"agent_id": "worker", "run_id": "xyz"},
)
# → allowed=False, tier="halt", threat_type="SYSTEM_PATH_PROBE"
```
SDK 是 **故障安全 (fail-safe)** 的：网络错误或超时会返回一个合成的停止响应。
Guardian 故障绝不会静默允许工具执行。
## 框架集成
### LangGraph
```
from legionforge_guardian.sdk.client import GuardianClient
guardian = GuardianClient()
class SecureToolNode:
async def __call__(self, state):
tool_call = state["messages"][-1].tool_calls[0]
result = await guardian.check(
tool_name=tool_call["name"],
tool_input=tool_call["args"],
agent_state={"agent_id": state["agent_id"], "run_id": state["run_id"]},
)
if not result["allowed"]:
return {"messages": [ToolMessage(content=f"BLOCKED: {result['reason']}")]}
# execute the tool normally
...
```
### AutoGen
```
async def guardian_hook(sender, recipient, messages, config):
for msg in messages:
if msg.get("tool_calls"):
for call in msg["tool_calls"]:
result = await guardian.check(call["function"]["name"], call["function"]["arguments"], {})
if not result["allowed"]:
raise ValueError(f"Guardian blocked: {result['reason']}")
return messages, config
```
### 通用（任何框架）
```
# 在执行 tool 之前，POST 到 /check：
curl -s -X POST http://localhost:9766/check \
-H "Authorization: Bearer $GUARDIAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"tool_id": "web_search",
"action": "invoke",
"args": {"query": "..."},
"agent_id": "my_agent",
"run_id": "run_001",
"sequence_so_far": []
}'
# {"allowed": true, "tier": "allow", "reason": "All checks passed", "confidence": 1.0}
```
## API 参考
### `POST /check` — 强制执行热路径
当 `GUARDIAN_REQUIRE_AUTH=true` 时，需要 `Authorization: Bearer `。
**请求：**
```
{
"tool_id": "web_search",
"action": "invoke",
"args": {"query": "internal admin panel credentials"},
"agent_id": "researcher_agent",
"run_id": "run_abc123",
"sequence_so_far": ["web_search"],
"task_token": null
}
```
**响应：**
```
{
"allowed": false,
"tier": "halt",
"reason": "Destructive pattern 'CREDENTIAL_PROBE' detected in tool args",
"threat_type": "DESTRUCTIVE_PATTERN",
"confidence": 1.0
}
```
`tier` 值：`"allow"` | `"sandbox"` | `"halt"`
### `POST /report` — 异步威胁事件摄取
从您的应用程序发送威胁事件以进行审计日志记录。
### `GET /rules` — 只读缓存视图
返回当前加载的工具注册表、序列契约和自适应规则。
需要认证。
### `GET /health` — 存活检查
始终无需认证。由 Docker healthcheck 使用。
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `GUARDIAN_DB_HOST` | `localhost` | PostgreSQL 主机 |
| `GUARDIAN_DB_PORT` | `5432` | PostgreSQL 端口 |
| `GUARDIAN_DB_NAME` | `guardian` | 数据库名称 |
| `GUARDIAN_DB_USER` | `guardian` | 数据库用户 |
| `GUARDIAN_DB_PASSWORD` | *(必填)* | 数据库密码 |
| `TASK_TOKEN_SECRET` | *(启用认证时必填)* | /check 和 /rules 的 Bearer token |
| `GUARDIAN_REQUIRE_AUTH` | `true` | 仅在本地开发时设置为 `false` |
| `GUARDIAN_HOST` | `127.0.0.1` | 绑定地址（见下方说明） |
| `GUARDIAN_PORT` | `9766` | 监听端口 |
**生产环境提示：** Guardian 默认为 `127.0.0.1`（仅限 localhost）。在 Docker 中运行时，设置 `GUARDIAN_HOST=0.0.0.0` 以允许容器的端口映射工作。
切勿公开暴露 Guardian 的端口——它必须只能由智能体进程访问。
**安全提示：** 当 `GUARDIAN_REQUIRE_AUTH=true` 时，必须设置 `TASK_TOKEN_SECRET`。
如果需要认证但未配置密钥，Guardian 将以 503 拒绝请求。
在生产环境中使用 Secrets Manager（Vault、AWS Secrets Manager、macOS Keychain），而不是纯环境变量。
## 数据库设置
Guardian 需要两个表。针对任何 PostgreSQL 14+ 实例运行 `init.sql`：
```
psql $GUARDIAN_DB_URL -f init.sql
```
如果您是与 LegionForge 一起部署，Guardian 使用 LegionForge 的现有表。
针对 LegionForge 数据库运行 `init.sql` 是安全的——所有语句都使用 `CREATE TABLE IF NOT EXISTS`。
## 架构
```
Your Agent Framework
│
▼ (before every tool call)
┌───────────────────┐
│ Guardian /check │ ← FastAPI, localhost:9766
│ │
│ Check 0: Token │
│ Check 1: Registry│
│ Check 2: Caps │ ← In-memory caches, refreshed every 10s
│ Check 3: Patterns│
│ Check 4: Sequence│
│ Check 5: Hash │
│ Check 6: Rules │ ← Hot-reloaded from DB
│ │
└───────────────────┘
│
▼ (if allowed)
Tool executes
```
**设计原则：**
- **热路径中无 LLM。** 每个决策都是确定且可审计的。
- **故障安全 (Fail-safe)。** 网络错误或超时 → 合成停止。Guardian 故障永远不会静默允许工具执行。
- **故障闭锁 (Fail-closed)。** 未知工具被拒绝。新异序列被沙箱化。认证配置错误返回 503，而不是 200。
- **内存热路径。** 注册表 + 规则在启动时缓存，每 10 秒刷新一次。
数据库延迟不在关键路径上。
- **防篡改审计日志。** 每个检查结果上的 SHA-256 哈希链。
可离线验证。
### 为什么不使用基于 LLM 的检查器？
评估另一个 LLM 输出的 LLM 本身也可能遭受 Prompt 注入。如果正在被评估的智能体已被攻陷，其输出可能包含操纵检查器的指令。确定性模式匹配无法被 Prompt 注入。
安全边界必须在 LLM 的影响范围之外。
## 安全
参阅 [SECURITY.md](SECURITY.md) 了解威胁模型、Guardian 不防范的内容以及漏洞报告说明。
## 测试对抗
Guardian 已针对 24 种对抗性攻击函数进行了验证，涵盖：
Prompt 注入、凭证探测、SSRF、路径遍历、Shell 注入、权限提升、数据窃取、工具篡改和序列契约违规。结果：在干净的 LegionForge 部署上 **0 次绕过**。
复现：在 LegionForge monorepo 中运行 `make test-pentest`。
## 许可证
MIT — 详见 [LICENSE](LICENSE)。
[LegionForge](https://github.com/LegionForge/LegionForge) 项目的一部分。
由 [Jp Cruz](https://github.com/jp-cruz) 构建。
标签：AV绕过, DNS 反向解析, FastAPI, HTTP工具, LLM 安全, Self-hosted, 人工智能安全, 合规性, 哈希完整性, 审计日志, 工具调用安全, 提示词注入防护, 数据防泄露, 权限控制, 模式匹配, 测试用例, 确定性检测, 网络安全, 网络安全审计, 自动化资产收集, 请求拦截, 越权防护, 运行时保护, 逆向工具, 防御侧车, 隐私保护