jagmarques/asqav-compliance

Governance for AI agents. Audit trails, policy enforcement, and compliance.

Website | Docs | SDK Guide | Compliance

# Compliance Scanner **面向 AI 代理的 CI/CD 合规扫描器。** 在每次拉取请求时捕获 AI 代理代码中的治理漏洞——审计追踪、策略执行、人工监督等。映射 EU AI Act、DORA 和 ISO 42001 的要求。 可以把它看作“AI 合规领域的 Dependabot”。 ## 快速开始 将以下内容添加到 `.github/workflows/ai-governance.yml` 中即可： ``` name: AI Agent Governance on: [pull_request] jobs: compliance: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: jagmarques/asqav-compliance@v1 with: github-token: ${{ secrets.GITHUB_TOKEN }} ``` 该 action 会在每次 PR 时扫描 AI 代理框架的使用情况，并将合规报告作为评论发布。 ## 数据处理 此 GitHub Action 完全在您仓库的 CI runner 内部运行。它读取拉取请求差异中的更改文件，执行静态模式匹配，并通过 GitHub API 将生成的 Markdown 报告作为 PR 评论发布。该 Action 不会将您的代码、prompt 或代理上下文传输到 Asqav 云端或任何第三方服务。 如果您在运行时单独使用 `asqav` Python SDK 或 `@asqav/sdk`，它们有各自的数据处理方式。默认情况下，两个 SDK 都会自动检测 Asqav 云端（`*.asqav.com`），并应用仅哈希模式以实现符合 GDPR 的数据最小化，仅发送哈希值和一个小型元数据包（action_type、agent_id、session_id、model_name、tool_name）。对于自托管部署，SDK 会将完整上下文发送到您控制的服务器。您可以在每次调用时进行覆盖： ``` import { init } from '@asqav/sdk'; await init({ apiKey: 'sk_...', baseUrl: 'https://api.asqav.com', mode: 'hash-only' }); ``` 有关指纹规范和一致性向量，请参阅 SDK 仓库中的 [docs/fingerprint-spec.md](https://github.com/jagmarques/asqav-sdk/blob/main/docs/fingerprint-spec.md)。 ## 示例输出 当 action 运行时，它会在您的 PR 上直接发布如下报告： ``` ## AI Agent 治理报告 | Metric | Value | |-------------------------|--------------------------------| | Compliance Score | 60/100 | | Agent files scanned | 3 | | Frameworks detected | langchain, openai, crewai | ### 治理检查 | Category | Status | Details | |----------------------|--------|------------------------------| | Audit Trail | PASS | 3/3 files covered | | Policy Enforcement | PASS | 3/3 files covered | | Revocation Capability| GAP | 2/3 files missing coverage | | Human Oversight | GAP | 3/3 files missing coverage | | Error Handling | PASS | 3/3 files covered | ### 建议 - Revocation Capability: Add a kill switch or revocation mechanism so agents can be disabled in an emergency. - Human Oversight: Add human-in-the-loop approval flows for high-risk agent actions. ``` 每个漏洞都包含具有可操作性的建议以及文档链接。 ## 检查内容 扫描器会评估每个导入 AI 代理框架的 Python 文件的五个治理类别： | 类别 | 检查目标 | |----------|-------------------| | **Audit Trail** | 日志记录、`asqav.sign()`、审计日志、操作记录 | | **Policy Enforcement** | 速率限制、范围限制、操作门控、超时 | | **Revocation Capability** | 紧急停止开关、熔断器、紧急停止机制 | | **Human Oversight** | Human-in-the-loop 流程、审批关卡、人工审查步骤 | | **Error Handling** | 代理调用周围的 try/except 块 | ### 监管映射 这些检查符合以下法规的要求： - **EU AI Act** - 第 14 条（人工监督），第 15 条（准确性/鲁棒性） - **DORA** - ICT 风险管理、事件响应、运营韧性 - **ISO 42001** - AI 管理体系控制与治理 ## 输入 | 输入项 | 描述 | 必需 | 默认值 | |-------|-------------|----------|---------| | `github-token` | 用于发布 PR 评论的 GitHub token | 是 | `${{ github.token }}` | | `scan-path` | 扫描路径（相对于仓库根目录） | 否 | `.`（整个仓库） | | `fail-on-gaps` | 如果发现治理漏洞，则使检查失败 | 否 | `false` | ## 输出 | 输出项 | 描述 | |--------|-------------| | `score` | 合规分数 (0-100) | | `agent-files` | 找到的代理文件数量 | | `gaps` | 治理漏洞总数 | | `report` | 完整的 Markdown 报告 | ## 高级用法 ### 阻止不符合合规要求的 PR ``` - uses: jagmarques/asqav-compliance@v1 id: scan with: github-token: ${{ secrets.GITHUB_TOKEN }} scan-path: 'src/agents' fail-on-gaps: 'true' - name: Print score run: echo "Compliance score: ${{ steps.scan.outputs.score }}/100" ``` ### 在矩阵配置中与其他检查一起使用 ``` jobs: compliance: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: jagmarques/asqav-compliance@v1 id: governance with: github-token: ${{ secrets.GITHUB_TOKEN }} fail-on-gaps: 'true' tests: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: pytest ``` ## 评分 5 个类别每个最多贡献 20 分。分数与通过每项检查的代理文件百分比成正比。 | 分数 | 含义 | |-------|---------| | 80-100 | 治理态势良好 | | 50-79 | 需要解决部分漏洞 | | 0-49 | 存在重大治理漏洞 | ## 支持的框架 开箱即用，支持 10 个 AI 代理框架： - [LangChain](https://langchain.com/) / [LlamaIndex](https://www.llamaindex.ai/) / [Haystack](https://haystack.deepset.ai/) - [CrewAI](https://crewai.com/) / [AutoGen](https://microsoft.github.io/autogen/) / [Smol Agents](https://huggingface.co/docs/smolagents/) - [OpenAI](https://platform.openai.com/) / [Anthropic](https://anthropic.com/) / [Google Generative AI](https://ai.google.dev/) - [Semantic Kernel](https://learn.microsoft.com/semantic-kernel/) ## 相关项目 | 项目 | 描述 | |---------|-------------| | [asqav-sdk](https://github.com/jagmarques/asqav-sdk) | 用于 AI 代理治理的 Python SDK——审计追踪、策略执行、签名 | | [asqav-mcp](https://github.com/jagmarques/asqav-mcp) | 用于 AI 代理治理的 MCP server——通过 Model Context Protocol 进行策略检查与合规 | 使用 SDK 进行运行时治理。使用此 action 进行 CI/CD 合规检查。使用 MCP 进行 AI 原生工具集成。 ## 许可证 [MIT](LICENSE)

标签：AI代理治理, CI/CD合规扫描, DevSecOps, DORA, EU AI Act, GitHub Action, ISO 42001, Lerna, PR自动检查, Python, 上游代理, 云安全监控, 人工智能监管, 人机协作监管, 代码审查, 合规报告, 安全与合规自动化, 审计追踪, 开源, 无后门, 欧盟人工智能法案, 策略执行, 自动化合规检查, 自动化攻击, 软件供应链安全, 远程方法调用, 逆向工具, 防御加固, 静态分析