akdur/agent-skill-assurance-lab

# Agent Skill Assurance Lab 在被信任并应用于接近生产的操作工作流之前，为 Agent Skills、MCP 工具接口和 AI 自动化捆绑包提供证据驱动的保障。 本仓库是一个供应商中立的合成参考实现。它不使用真实的客户数据、云凭证、特定于雇主的系统、专有图表或私有实现工件。 ## 执行摘要 Agent 的能力越来越多地以可复用的 skill 文件夹、MCP 服务器、脚本和工具 schema 的形式出现。最棘手的问题不是“agent 能否运行它？”，而是“平台团队能否证明此功能能做什么、它可能会触碰到什么，以及是否应该允许其在接近生产环境的工作流中使用？” 本实验室将该审查过程转化为可重复的证据： - 包清单 - 能力与效果图 - 默认拒绝策略决策 - 合成测试套件运行结果 - Markdown 审查报告 - 用于 CI 的 SARIF 扫描结果 - 演示保障信封和本地证明 所有操作均在本地使用合成测试套件运行。不需要 LLM 密钥、云账户、实时网络或外部服务。 ## 快速开始 ``` python3 -m pip install -e . assure scan examples/skills/risky-cleanup ``` 预期输出： ``` REVIEW risky-cleanup | effects=file_write,subprocess | findings=1 ``` 运行完整的本地验证： ``` python3 -m unittest PYTHONPATH=src python3 -m agent_skill_assurance_lab scan examples/skills/risky-cleanup --run-id local-smoke node tools/render-diagrams.mjs ``` ## 主要架构图 这些是专为 GitHub、LinkedIn Featured 和招聘人员审查设计的作品集级别图表。它们是从源代码控制的 JSON 生成的已提交 SVG 资产，而不是 Mermaid 截图。 [](docs/architecture/architecture-board.svg) [](docs/architecture/sequence-board.svg) 查看全尺寸：[架构图](docs/architecture/architecture-board.svg) · [时序图](docs/architecture/sequence-board.svg) ## 架构图集 这些是存放于 `docs/diagrams/source/` 下、从源代码控制的 JSON 生成的已提交 SVG 架构资产。 | 图表 | 用途 | | --- | --- | | [端到端架构图](docs/architecture/architecture-board.svg) | 密集型架构图，展示了触发器、路由、保障阶段、数据/证据流、共享证据存储、外部系统、治理、输出信封和设计原则。 | | [时序架构图](docs/architecture/sequence-board.svg) | 时间感知时序图，展示了扫描初始化、并行/静态分析阶段、策略决策、测试套件执行、报告生成、SARIF 发布、重试/回退行为和最终结果。 | | [C4 上下文图](docs/architecture/c4-context.svg) | 展示了保障实验室与平台工程师、skill 包、CI 和证据消费者之间的关系。 | | [C4 容器图](docs/architecture/c4-container.svg) | 展示了内部组件：包读取器、图构建器、策略编译器、测试套件、证据写入器和 CLI。 | | [保障时序图](docs/architecture/assurance-sequence.svg) | 展示了从包输入到证据输出的扫描生命周期。 | | [信任边界图](docs/architecture/trust-boundaries.svg) | 展示了不可信的包内容在何处与策略和证据生成隔离。 | | [证据图](docs/architecture/evidence-map.svg) | 展示了生成的工件及其如何支持审计、CI 和人工审查。 |      ## 组件职责 | 组件 | 职责 | 输出 | | --- | --- | --- | | 包读取器 | 读取 `SKILL.md`、脚本、引用、资产、元数据和合成 MCP/工具声明。 | `SkillPackage` 模型 | | 能力图构建器 | 推导读取、写入、子进程、网络目的地、凭证提示和审批用语。 | `capability-graph.json` | | 策略编译器 | 应用 `personal`、`team` 或 `production-adjacent` 的默认拒绝配置文件。 | 允许、审查或拒绝决策 | | 测试套件 | 评估合成安全、有风险和恶意的包，而无需执行包脚本。 | 确定性测试结果 | | 证据写入器 | 写入机器可读和人类可读的证据。 | JSON、Markdown、SARIF | | 图表渲染器 | 将 JSON 图表源转换为精美的 SVG，用于 GitHub 和 LinkedIn 可见的文档。 | `docs/architecture/*.svg` | ## 时序流程 1. 操作员运行 `assure scan `。 2. 包读取器将文件和元数据规范化为包模型。 3. 图构建器推导声明和推断的效果。 4. 策略编译器应用所选的策略配置文件。 5. 测试套件记录确定性的可安装性和安全检查。 6. 证据写入器在 `artifacts/runs//` 下输出工件。 7. CLI 返回用于 CI 或人工审查的简明决策。 ## 示例测试套件 | 测试套件 | 意图 | 接近生产环境的决策 | 原因 | | --- | --- | --- | --- | | `safe-status-report` | 本地合成报告 | 允许 | 无写入，无网络，无凭证提示。 | | `risky-cleanup` | 审批门控的清理工作流 | 审查 | 文件写入和子进程效果需要人工审查。 | | `malicious-exfiltration` | 合成的机密/网络滥用 | 拒绝 | 凭证和外部网络指标超出了策略限制。 | ## 证据工件 扫描会写入： ``` artifacts/runs// assurance-envelope.json capability-graph.json findings.sarif review.md skillbom.json ``` 保障信封包含合成的 ROI 字段： - 人工审查基准分钟数 - 自动审查分钟数 - 阻止的不安全效果 - 最小权限增量 - 策略决策和原因代码 ## 安全模型 - 测试套件脚本经过检查但未被执行。 - 不进行实时网络调用。 - 不需要或读取任何机密。 - 结果是确定性的，适合 CI。 - 演示签名材料仅用于说明，不用于生产环境 PKI。 ## 仓库布局 ``` src/agent_skill_assurance_lab/ Python implementation examples/skills/ Synthetic safe/risky/malicious fixtures tests/ Unit and fixture tests docs/diagrams/source/ Source of truth for architecture diagrams docs/architecture/ Generated SVG architecture diagrams tools/render-diagrams.mjs Dependency-free SVG renderer .github/workflows/ci.yml Test, smoke, and diagram freshness checks ``` ## 主要 SRE 信号 本仓库展示了 AI 自动化治理、MCP/Skills 生态感知、CI 证据、供应链风格的审查、最小权限思维以及由策略支持的操作安全性。

标签：AI Agent安全, MCP协议, MITM代理, 云安全监控, 安全合规, 文档结构分析, 策略引擎, 网络代理, 网络安全挑战, 自定义脚本, 逆向工具, 静态分析