GovSafeAgent

面向政企场景的大模型智能体安全治理与评测平台

GovSafeAgent 为大模型 Agent 提供从输入检测、能力调度、模型访问、工具调用到审计评测的统一安全控制面。

平台围绕“可运行、可攻击、可拦截、可审计、可评测”构建闭环，支持桌面端交付、本地开发与可复现的分布式安全实验。

Important

当前版本是可运行、可验证的工程原型，不等同于已完成等保、密评或生产认证的商业产品。生产部署前仍需接入企业 IAM、KMS/HSM、WAF、SIEM、DLP、高可用数据层与组织安全流程。

文档导航

企业定位
核心能力
系统架构
快速开始
部署模式
配置说明
安全模型
API 概览
质量保障
运维与数据管理
项目结构
项目边界与路线图

企业定位

GovSafeAgent 将分散在模型、Agent、Skill、MCP 和审计系统中的安全策略收敛为统一治理链路。

企业挑战	GovSafeAgent 控制	交付价值
不可信输入进入 Agent 上下文	PromptShield-Gov 检测提示注入、越狱、知识投毒与敏感信息诱导	在规划和执行前完成风险分级与阻断
模型输出可直接驱动高风险动作	Model Gateway 将外部输出标记为不可信，并强制转换为严格 `AgentPlan`	防止模型绕过工具策略和执行边界
Skill、MCP 与第三方扩展来源复杂	SkillScan-Gov 静态扫描、仓库分类、风险校准和沙箱预检	将供应链风险前置到准入阶段
工具权限与参数缺少细粒度控制	MCP-Guard-Gov 基于角色、上下文、数据标签、任务图和一次性票据裁决	对每一次工具调用执行最小权限控制
多 Agent 链路难以追责	TraceAudit-Gov 使用 `trace_id` 固化签名事件链	支持租户隔离、证据导出、验证与回放
安全效果缺少统一度量	AgentSecEval-Gov 输出逐样例证据和五维归一化指标	支持回归门禁、基线管理和机制复算

适用场景

政务办公：文档处理、摘要生成、材料流转和外发审批。
知识服务：知识库问答、来源治理和间接提示注入检测。
流程办理：多步骤任务规划、权限校验和人工审批。
运维协同：工具调用控制、敏感路径保护和执行审计。

核心能力

能力域	主要组件	能力说明
输入安全	PromptShield-Gov	YAML 策略驱动的提示注入、越狱、知识投毒和敏感诱导检测
能力治理	Graphify-Gov、SafeRouter-Gov	能力图谱、Top-K 召回、结构化子任务 DAG、有界并发和 Audit fan-in
模型治理	Model Gateway	Provider 注册、协议适配、预算路由、隔离缓存、超时重试、熔断回退和成本指标
工具治理	MCP-Guard-Gov	按工具、参数、路径、域名、角色、数据标签和上下文执行策略裁决
扩展治理	SkillScan-Gov	对 Python、JavaScript、配置文件和 ZIP 包进行静态供应链扫描
沙箱治理	进程内沙箱、动态沙箱、Docker 沙箱	按风险等级选择隔离强度，并在能力安装前执行预检
审计治理	TraceAudit-Gov	SQLite 追加式事件日志、签名哈希链、租户视图、Markdown/JSON 导出和回放
安全评测	AgentSecEval-Gov	离线 smoke/full 基准、可信基线、逐样例证据和失败样例归档
任务运行	Task Runtime	三类舱壁、优先级、背压、幂等、超时重试、SSE、租约恢复和死信管理
管理控制台	Vue 3 + Tauri 2	Skill、MCP、Agent、模型、评测、审批、能力图谱与数据治理工作台

v0.5.0 重点更新

按业务线分发能力与策略，并对扩展仓库执行类型分类和差异化准入。
增加端到端风险分值校准，降低不同检测链路之间的分数偏移。
增加动态沙箱、Docker 沙箱和远程 MCP 网关的治理能力。
增加智能能力安装预检，以及 Python、Rust、Vue 全栈稳定性修复。

完整技术索引见项目技术地图和创新点索引。

系统架构

交付架构

flowchart TB
  USER["用户 / 安全运营人员"] --> SHELL["Tauri 2 桌面壳"]
  SHELL --> UI["Vue 3 管理控制台"]
  SHELL --> API["FastAPI Sidecar"]
  API --> CORE["SafeAgent 安全核心"]
  CORE --> DB[("SQLite / 本地证据与配置")]
  CORE --> EXT["受治理的模型 / Agent / MCP"]
  SHELL --> MAC["macOS DMG"]
  SHELL --> WIN["Windows MSI / EXE"]
  SHELL -. 暂缓发布 .-> LINUX["Linux AppImage / DEB"]

桌面应用自行启动本地 Sidecar，并绑定随机 loopback 端口。缓存、SQLite、评测结果和用户配置写入平台原生应用数据目录。

运行时安全链路

flowchart LR
  INPUT["用户输入 / 不可信文档"] --> SHIELD["PromptShield-Gov"]
  SHIELD -->|block / isolate| AUDIT["TraceAudit-Gov"]
  SHIELD -->|allow / approval| GRAPH["Graphify-Gov"]
  GRAPH --> ROUTER["SafeRouter-Gov"]
  MODEL["Model Gateway"] -->|不可信计划| ROUTER
  ROUTER --> AGENT["受控 Agent Runtime"]
  SKILL["Skill Registry / Executor"] --> AGENT
  AGENT --> GUARD["MCP-Guard-Gov"]
  GUARD -->|allow_with_log| TOOL["受控工具 / 模拟 MCP"]
  GUARD -->|require_approval| HUMAN["人工审批"]
  GUARD -->|block| AUDIT
  TOOL --> AUDIT
  HUMAN --> AUDIT
  AUDIT --> EVAL["AgentSecEval-Gov"]

安全决策统一为 allow、allow_with_log、mask_and_allow、require_approval 和 block。

外部模型、Dify 或通用工具型 Agent 只能提供不可信计划，不能直接调用 MCP Server，也不能绕过输入检测、工具守卫和审计节点。

快速开始

环境要求

依赖	版本	用途
Python	3.11.12	后端、安全核心与评测
uv	0.7.0 或更高	Python 解释器、依赖和虚拟环境管理
Node.js	22.12 或更高；CI 使用 24.3.0	Vue 控制台与桌面构建
Rust	1.97.1	Tauri 桌面端构建
Docker	可选	分布式队列、隔离和恢复实验

1. 获取并初始化项目

git clone https://github.com/YouYou-lj/GovSafeAgent.git
cd GovSafeAgent
./scripts/setup_uv_env.sh

脚本会将 uv 缓存、uv 管理的 Python 和虚拟环境分别放入仓库内的 .uv-cache/、.uv-python/ 和 .venv/。

Windows 使用以下命令：

.\scripts\setup_uv_env.ps1

2. 启动后端

./scripts/uv_run.sh uvicorn backend.main:app --reload --port 8000

业务 API 默认需要 Bearer 身份。生成一小时有效的本地管理员令牌：

./scripts/uv_run.sh python -m safeagent_gov.auth issue \
  --subject demo-admin \
  --tenant demo-government \
  --role admin \
  --ttl 3600

3. 启动管理控制台

cd frontend-vue
npm ci --ignore-scripts --no-audit --no-fund
npm run dev

启动完成后访问：

服务	地址
管理控制台	http://127.0.0.1:5173
OpenAPI 文档	http://127.0.0.1:8000/docs
健康检查	http://127.0.0.1:8000/health

将签发的令牌粘贴到控制台右上角身份入口，即可调用受保护的业务 API。

部署模式

模式	定位	依赖	状态
Tauri 桌面端	正式本地交付形态	本地 Sidecar、SQLite	macOS / Windows 支持
Web 开发模式	开发、调试和接口联调	FastAPI、Vue	支持
Docker Compose	论文复现、容器隔离和恢复实验	Docker、Redis、Dramatiq	可选
企业服务端	多租户、高可用集中部署	IAM、KMS、PostgreSQL、受管 Redis、WAF、SIEM	需二次建设

桌面端开发

./scripts/setup_uv_env.sh
cd frontend-vue && npm ci --ignore-scripts --no-audit --no-fund
cd ../desktop && npm ci --ignore-scripts --no-audit --no-fund
npm run dev

构建当前平台的原生安装包：

cd desktop
npm run build

当前开发版本：v0.5.0。版本号由 safeagent_gov/version.py 统一管理。

open release/mac/GovSafeAgent_0.5.0_aarch64.dmg

原生安装包不会提交到源码仓库。Tag 流水线只创建 Draft Release，正式发布前必须完成人工验收、平台签名和公证复核。

各平台构建方式见桌面端文档和发布目录说明。

Docker 研究复现

compose_file=research_technology/reproducibility/docker/docker-compose.yml
docker compose -f "$compose_file" up --build -d
docker compose -f "$compose_file" ps

默认拓扑仅向 loopback 暴露 Nginx ingress。FastAPI、Vue、Redis 和三类 Dramatiq Worker 位于内部网络，业务容器使用非 root、只读根文件系统、cap_drop: ALL 和资源限制。

停止服务不会删除命名卷：

docker compose -f "$compose_file" down

详细拓扑、Worker 隔离和调试叠加配置见部署说明。

配置说明

复制示例配置并按环境调整：

cp .env.example .env

环境变量	默认值	说明
`SAFEAGENT_API_URL`	`http://localhost:8000`	前端访问后端的基址
`SAFEAGENT_DB_PATH`	`backend/data/safeagent.db`	SQLite 数据库路径
`SAFEAGENT_MAX_UPLOAD_MB`	`10`	上传文件大小上限
`SAFEAGENT_API_RATE_LIMIT`	`120`	单个限流窗口内的请求上限
`SAFEAGENT_API_RATE_WINDOW_SECONDS`	`60`	限流窗口秒数
`SAFEAGENT_CORS_ORIGINS`	本地开发地址	精确允许的浏览器来源
`SAFEAGENT_TRUSTED_HOSTS`	本地主机名	允许的 HTTP Host
`SAFEAGENT_AUTH_SIGNING_SECRET`	本地生成	身份令牌签名密钥
`SAFEAGENT_AUDIT_SIGNING_SECRET`	本地生成	审计事件签名密钥
`SAFEAGENT_CAPABILITY_SECRET`	本地生成	能力票据签名密钥
`SAFEAGENT_EXTERNAL_AGENT_ENDPOINT`	空	可选的 planning-only 外部 Agent 地址

生产环境应为三类签名密钥分别注入至少 32 字节的独立随机值。CORS 或 Trusted Host 使用空值、通配值时，服务会失败关闭。

第三方模型 API Key 使用 AES-256-GCM 加密保存。Key 只进入对应服务的认证请求头，不进入提示词、请求正文、日志、审计或数据导出。

完整变量说明见示例环境文件和部署说明。

安全模型

设计原则

默认拒绝：策略、票据、审计或依赖不可用时，高风险动作不执行。
最小权限：工具调用绑定主体、租户、任务图、参数、数据标签和一次性能力票据。
不可信输出：模型与外部 Agent 输出必须通过严格 Schema 校验和统一安全节点。
证据优先：关键决策写入签名哈希链，并支持验证、导出和受控回放。
租户隔离：身份、审批、任务、审计和反馈查询均按签名租户过滤。
本地优先：默认 planner、smoke 评测和模拟工具可离线运行，不依赖商业模型。

已实现控制与生产接入项

安全域	当前控制	生产环境建议
身份与授权	签名 Bearer、角色依赖、服务端身份覆盖、租户过滤	对接 OIDC/IAM、MFA 和组织权限模型
密钥管理	独立密钥、`0600` 本地文件、密文完整性校验	接入 KMS/HSM、轮换和双密钥验证窗口
输入与上传	Schema 校验、大小限制、ZIP 有界解压、临时目录隔离	接入杀毒、内容拆弹和独立动态分析沙箱
网络与 API	精确 CORS、Trusted Host、安全响应头、身份限流	增加 TLS、WAF、集中式限流和 egress allowlist
工具执行	RBAC/ABAC、污点、任务图、审批、票据和重放保护	对真实 MCP Server 使用独立身份、mTLS 和资产准入
审计与留痕	敏感值摘要、签名哈希链、租户脱敏视图	接入 WORM、可信时间源、SIEM 和告警值班
依赖与构建	精确锁定、CycloneDX SBOM、固定镜像摘要、CI 门禁	增加镜像签名、在线 CVE 门禁和供应链证明
数据与恢复	SQLite 在线备份、完整性检查、SHA-256、拒绝覆盖恢复	使用加密备份、异地保留和定期灾备演练

Warning

仓库内 MCP Server 均为无副作用模拟器，不会真实发送邮件、删除文件、执行 Shell 命令或访问网页。允许的文件操作只映射到受控目录；agent_demo/data/secret 是阻断演示诱饵，不得存放真实敏感数据。

完整安全自审见工程安全自审。

API 概览

除 /、/health 和 OpenAPI 页面外，API 均要求 Authorization: Bearer <token>。

方法	路径	作用
`POST`	`/api/risk/detect`	检测输入风险并返回处置建议
`POST`	`/api/agent/run`	运行受控 Agent 安全链路
`POST`	`/api/router/plan`	生成结构化多 Agent 子任务 DAG
`POST`	`/api/tool/check`	对工具和参数执行策略试算
`POST`	`/api/mcp/call`	通过身份、任务图和一次性票据调用模拟 MCP
`POST`	`/api/mcp/scan`	离线扫描 MCP 描述与高风险能力
`POST`	`/api/skill/scan`	扫描 Skill 或扩展包
`GET/POST`	`/api/skills/*`	管理 Skill 注册表、执行和指标
`GET/POST`	`/api/model/*`	管理 Provider 并执行受治理的模型访问
`GET/POST`	`/api/tasks/*`	管理异步任务、SSE、指标和死信
`GET`	`/api/audit/{trace_id}`	查询、验证和导出完整证据链
`POST/GET`	`/api/eval/*`	运行评测、查询历史和管理可信基线
`GET/POST`	`/api/graphify/*`	构建、检索和验证能力图谱
`GET/POST`	`/api/policy/tool/*`	管理工具策略灰度、提升和回滚

请求与响应示例见API 规范。

质量保障

CI 对 Python、Vue、Tauri 配置、技术证据和文档执行统一质量门禁。Python 综合语句/分支覆盖率阈值为 85%。

后端与安全核心

./scripts/uv_run.sh python -m ruff check .
./scripts/uv_run.sh python -m pytest -q
./scripts/uv_run.sh python -m mypy \
  research_technology/mcp \
  safeagent_gov/graphify \
  safeagent_gov/router \
  safeagent_gov/skill_runtime \
  safeagent_gov/model_gateway \
  safeagent_gov/task_runtime

前端

cd frontend-vue
npm run lint
npm run typecheck
npm run test
npm run build

评测与仓库门禁

./scripts/uv_run.sh python research_technology/benchmarks/runners/run_all.py --profile public
./scripts/uv_run.sh python -m pytest -q tests/test_current_benchmark.py tests/test_graphify.py tests/test_agent_orchestration.py
./scripts/uv_run.sh python research_technology/benchmarks/runners/eval_model_gateway.py
./scripts/uv_run.sh python research_technology/benchmarks/runners/eval_task_runtime.py

./scripts/uv_run.sh python scripts/sync_project_version.py --check
./scripts/uv_run.sh python scripts/check_markdown_links.py
./scripts/uv_run.sh python scripts/check_repository_index.py
./scripts/uv_run.sh python scripts/generate_technical_manifest.py --check

公共评测只引用随仓库提供的 paper_fullstack_v1；不再依赖本地忽略或私有数据目录。

可复核的供应链证据包括CycloneDX SBOM和技术版本清单。

运维与数据管理

数据持久化

开发模式默认写入 backend/data/safeagent.db。
桌面模式写入平台原生应用数据目录，实际路径以“数据与隐私”页为准。
Compose 使用命名卷保存 Redis AOF、审计数据、受控输出和评测结果。

备份与恢复

项目使用 SQLite online backup API，并在复制前后执行 PRAGMA integrity_check 和 SHA-256 校验。

./scripts/uv_run.sh python scripts/backup_restore.py backup \
  --database backend/data/safeagent.db \
  --output /path/to/backup/safeagent.db

恢复操作只允许写入新路径，目标文件已存在时拒绝覆盖。完整流程见部署说明。

可观测性

当前版本提供任务池、模型网关、Skill 执行、路由、缓存、成本、时延、审计完整性和用户反馈指标。

生产环境建议将关键指标、审计事件和策略变更接入 OpenTelemetry、SIEM 或组织统一可观测平台。

项目结构

GovSafeAgent/
├── frontend-vue/         # Vue 3 / TypeScript 安全治理控制台
├── desktop/              # Tauri 2 壳、Sidecar 与跨平台构建
├── backend/              # FastAPI API、鉴权和数据访问
├── safeagent_gov/        # 安全契约、治理组件与任务运行时
├── agent_demo/           # LangGraph 场景编排与规划器适配
├── integrations/         # 外部 Agent 参考集成
├── configs/              # Graphify、MCP 与 Model Gateway 配置
├── research_technology/  # Skill、MCP、创新、基准、证据和论文材料
├── scripts/              # 环境、构建、备份和仓库门禁脚本
├── tests/                # 跨模块测试
└── release/              # 本地构建产物目录，不进入源码历史

skills/、mcp/、benchmarks/ 和 eval/ 是兼容导入入口，不保存第二份实现。

项目边界与路线图

当前边界

通用外部工具型 Agent 已完成真实 loopback HTTP 联调；OpenAI-compatible 和 Dify 适配仍以受控传输测试为主。
SQLite 和单节点 Redis 适合本地原型与研究复现，不代表跨机高可用。
当前评测结果证明仓库内机制与工程回归可复现，不代表开放世界攻击的泛化性能。
桌面端优先交付 macOS 与 Windows；Linux 保留目录和 CI 工作流，但暂未进入发布聚合。

企业化演进方向

对接政企 OIDC/IAM、MFA、KMS/HSM、DLP、WAF、SIEM 和可信知识库评分。
将 SQLite 迁移到 PostgreSQL，将 Redis 升级为受管服务或 Sentinel/Cluster。
增加 Kubernetes 部署、镜像签名、在线 SBOM/CVE 门禁和 WORM 审计存储。
对商业 LLM、Dify、OpenClaw 和真实 MCP Server 开展异构互操作与租户验收。
增加外部可信时间、策略审批流、组织级基线和持续攻防评测。

延伸文档

文档	内容
项目技术地图	模块、入口、证据与评审导航
部署说明	桌面、Web、Compose、密钥和备份恢复
API 规范	鉴权、请求、响应和接口边界
技术方案	总体技术设计与安全闭环
安全 Skill 索引	安全 Skill 能力与评测入口
MCP 模块	MCP 网关、策略和模拟 Server
跨平台架构	Tauri、Vue 与 Sidecar 的统一边界
演示脚本	正常任务、单点攻击与组合攻击演示
开源与使用说明	来源、二创边界和使用声明

贡献

欢迎通过 Issue 或 Pull Request 参与改进。提交前请确保：

变更范围清晰，并补充必要测试和文档。
Python 代码通过 Ruff、Mypy 和 Pytest 门禁。
Vue 代码通过 lint、typecheck、test 和 build。
不提交真实密钥、个人数据、运行数据库、安装包或私有评测集。
不复制第三方项目的受限代码、界面资产或未授权数据。

涉及安全边界的变更应同时说明威胁模型、失败行为、审计证据和回滚方式。

许可

本项目采用 Apache License 2.0（SPDX：Apache-2.0）。使用、修改和分发时请保留版权、许可与 NOTICE 相关声明。

第三方项目的参考范围和二创边界见开源与使用说明。

Name		Name	Last commit message	Last commit date
.github		.github
.qa		.qa
agent_demo		agent_demo
backend		backend
benchmarks		benchmarks
configs		configs
desktop		desktop
docs/release		docs/release
eval		eval
frontend-vue		frontend-vue
integrations		integrations
mcp		mcp
release		release
research_technology		research_technology
safeagent_gov		safeagent_gov
scripts		scripts
skills		skills
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.python-version		.python-version
.uv-version		.uv-version
CONTEXT.md		CONTEXT.md
LICENSE		LICENSE
OPEN_SOURCE_NOTICE.md		OPEN_SOURCE_NOTICE.md
PROJECT_MAP.md		PROJECT_MAP.md
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation