Agent Security Gateway v0.1

项目简介

Agent Security Gateway v0.1 是一个插入在 Agent 工具调用意图与真实工具执行之间的最小安全控制层。

当前版本聚焦于最小闭环，完成：

• 工具白名单校验
• 参数边界校验
• allow / deny / failed 三条主路径
• 基于 request_id 的最小审计事件链

---

v0.1 范围

已实现

• Security Gateway -> Policy Engine -> Tool Runtime -> Audit Logger 最小主链路
• allow / deny / failed 三条路径
• request_id 驱动的请求追踪
• read_file 最小执行链
• http_fetch 最小策略边界校验
• pytest 覆盖核心场景

明确不做

• approval flow
• capability token
• 完整 egress control
• 多 Agent / 多租户
• 生产级持久化 / 回放 / 面板
• 完整 typed event schema

---

当前能力

支持工具

• read_file

  • 白名单校验
  • 路径边界校验
  • 最小执行链
  • 执行失败模拟

• http_fetch

  • URL 类型校验
  • scheme 校验
  • 私网 / loopback 目标拒绝
  • 域名白名单校验

主状态

RECEIVED -> NORMALIZED -> POLICY_CHECKING -> DENIED / ALLOWED -> EXECUTING -> SUCCEEDED / FAILED

说明：

• DENIED = 策略拒绝
• FAILED = 规范化或执行失败
• DENIED != FAILED

---

项目结构

.
├─ README.md
├─ VERSION_v0.1.md
├─ constants.py
├─ models.py
├─ agent_orchestrator.py
├─ security_gateway.py
├─ policy_engine.py
├─ tool_runtime.py
├─ audit_logger.py
├─ test_gateway_v01.py
└─ docs
   ├─ architecture.md
   ├─ test-matrix.md
   └─ events-and-errors.md

---

快速开始

安装依赖

pip install -r requirements.txt

运行测试

pytest -q

---

示例场景

deny

• 非白名单工具：delete_file
• 非法路径：/etc/passwd
• 私网目标：http://127.0.0.1/admin

allow

• 合法 read_file：/safe/demo.txt

failed

• args 非 dict
• read_file 执行失败：/safe/raise.txt

---

已知限制

• read_file 当前采用简化路径边界策略
• http_fetch 当前只做到策略层边界控制
• 审计为轻量存储
• 当前目标是最小安全控制闭环，不是完整平台

---

后续说明

v0.1 封口后，后续版本将在真实实现反馈基础上继续演进。