JKasteele/ai-act-companion

# AI Act Companion [](https://github.com/JKasteele/ai-act-companion/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org/) [](https://github.com/astral-sh/ruff) [](https://huggingface.co/spaces/JesseKasteele/ai-act-companion) AI Act Companion 帮助您针对 AI 系统运行结构化的 AI 风险评估，使其符合 **EU AI Act**（法规 (EU) 2024/1689）和 **NIST AI RMF** 的要求，并生成配套的文档。它完全在您本地的机器上运行。  ## 为什么选择它？ 大多数开源的 EU AI Act 仓库要么是静态检查表，要么是重量级的平台。本项目专注于免费工具中少见的三个方面： - **可解释且带引用。** 每个结论都会告诉您是*哪个* Article/Annex 驱动的以及*为什么*——这是一个可溯源的、确定性的规则引擎，而不是黑盒。 - **经过测试。** 分类器附带了一套单元测试套件（每个风险层级都有黄金测试用例），因此合规性逻辑是*经过验证的，而非凭感觉*。 - **本地且私密，诚实的 AI。** 可选的 AI 辅助功能在本地运行（通过 Ollama）或通过粘贴到您自己的 LLM 流程中——并且**绝不**替您做决定：根据设计，强制要求人工干预（human-in-the-loop）审查（符合 EU AI Act Art. 14 的精神）。 - **Claude 原生。** 以 **Claude Code 插件**形式提供：MCP server 将确定性引擎作为工具暴露出来，而一项技能（skill）负责编排完整的人工干预评估。Claude 充当交互界面；经过审计的规则引擎依然是唯一事实来源。请参阅[在 Claude Code 中使用](#use-inside-claude-code)。 - **不仅仅是合规，更是安全视角。** 将系统映射到 **OWASP Top 10 for LLM Applications (2025)** 和 **MITRE ATLAS**，并关联到 EU AI Act Art. 15 和 NIST AI RMF——这种治理与安全交叉的视角通常只存在于商业工具中。请参阅[AI 安全视角](#ai-security-lens)。 - **从发现结果到红队测试计划。** 将安全视角转化为用于*已授权的*紫队演练的、优先级排序的、**感知架构的**对抗性**测试计划**——每个测试用例都根据相同的确定性严重程度进行优先级排序，并可追溯到它所验证的控制措施。它是一种规划辅助工具（不包含漏洞载荷），而不是攻击工具。请参阅[红队测试计划](#red-team-test-plan)。 - **……再回到防御控制目录。** 蓝队的镜像：根据风险*实施*的控制措施，按相同的严重程度确定优先级，每项都指明了验证它的红队测试——*先实施，后测试*。此外，还提供了一个针对数据层（训练数据、提示词、检索、embeddings、遥测）的 **OWASP GenAI 数据安全**视角（DSGAI01–21），基于 EU AI Act Art. 10。请参阅[控制目录与数据安全](#control-catalogue--data-security)。 ## 两种使用方式 一个确定性引擎（经过审计的规则分类器 + 报告生成器）位于两个可互换的前端之下——选择适合您工作流程的那一个： ``` flowchart TB A["🔒 Local web app
(privacy-first)"] B["⚡ Claude Code plugin
(MCP)"] E["Deterministic engine
classifier · reports · knowledge
= ground truth"] O["Risk tier + cited articles
risk · DPIA · bias · security · FRIA · techdoc
compliance · monitoring · framework-matrix
red-team plan · control catalogue · data security"] A -->|"optional local AI:
Ollama or paste-into-your-own-LLM"| E B -->|"Claude is the interface
& narrative author"| E E --> O ``` | | 🔒 本地 Web 应用 | ⚡ Claude Code 插件 | |---|---|---| | **界面** | 您机器上的浏览器 UI | Claude Code (聊天) | | **AI 辅助** | 本地 Ollama，或粘贴到您自己的 LLM | Claude Code 本身，通过 MCP 工具 | | **隐私** | 完全本地化——数据绝不离开您的设备 | 使用您现有的 Claude Code 会话 | | **最适用于** | 注重隐私 / 离线 / 无订阅 | 如果您已经习惯使用 Claude Code | | **设置** | [快速开始](#quickstart) | [在 Claude Code 中使用](#use-inside-claude-code) | 无论选择哪种方式，**风险层级和引用均仅来自确定性引擎**——AI 绝不决定结果，并且强制要求人工干预审查。该引擎也可以通过 [CLI](#cli) 进行无头（headless）驱动。 ## 截图 | 分类结果 | 感知架构的严重程度 | 红队测试计划（攻击） | |---|---|---| |  |  |  | | 控制目录（防御） | OWASP GenAI 数据安全 | CSF 2.0 / ISO 27001 矩阵 | |---|---|---| |  |  |  | | 合规追踪器 + 罚款 | AI 辅助（人工干预） | | |---|---|---| |  |  | | ## 它的功能 1. **信息采集问卷**，用于描述 AI 系统（目的、领域、用户、数据、自主性，以及针对 Art. 5/6/50 和 GPAI 的筛查问题）。 2. **基于规则的 EU AI Act 分类器**，确定性地将答案映射到风险层级——**禁止 / 高 / 有限 / 最小**——并附带推理过程和相关条款/附录（articles/annexes），包括 Art. 6(3) 豁免的细微差别。 3. 根据结果**生成文档**： - AI 风险评估报告 - DPIA 骨架（GDPR Art. 35，关联到 AI Act） - 偏见审计检查表 - AI 安全评估（OWASP LLM Top 10 + MITRE ATLAS，包含感知架构的严重程度和 NIST CSF 2.0 / ISO 27001 矩阵） - FRIA 骨架（基本权利影响评估，Art. 27） - Annex IV 技术文档骨架（Art. 11） - 包含 Art. 99 处罚风险的义务与合规追踪器 - 上市后监控计划（Art. 72） - 框架整合矩阵（NIST CSF 2.0 / ISO 27001:2022） - 感知架构的红队测试计划（已授权的紫队范围界定） - 防御控制目录（要实施的控制，每一个都交叉链接到验证它的红队测试） - OWASP GenAI 数据安全评估（DSGAI01–21，数据层视角） 全部映射到 EU AI Act + NIST AI RMF，可导出为 **Markdown** 和 **PDF**（通过浏览器的打印为 PDF 功能）。 4. **可选的 AI 层**（人工干预）：将自由文本的系统描述转换为草拟的答案和叙述性章节草稿——输出始终是供您审查的草稿；它永远不会被自动分类、提交或存储。 ## 技术栈 - **后端：** Python + FastAPI（基于规则的核心，无需 AI） - **前端：** 原生 HTML/CSS/JS（无构建步骤） - **存储：** `data/` 中的 JSON 文件 - **PDF：** 浏览器打印为 PDF（零依赖） ## 快速开始 ``` # 1. 虚拟环境 + 依赖 python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1 pip install -e ".[dev]" # or: pip install -r requirements.txt # 2. 运行服务器 uvicorn app.main:app --reload # 3. 打开 http://127.0.0.1:8000 ``` 点击 **"Load example"** 获取一个合成的高风险示例，或者加载 `examples/` 中的其中一个文件。 ### Docker ``` docker build -t ai-act-companion . docker run --rm -p 8000:8000 -v "$PWD/data:/app/data" ai-act-companion ``` ## 在 Claude Code 中使用 AI Act Companion 也是一个 **Claude Code 插件**。一个 MCP server (`mcp_server.py`) 将确定性引擎作为工具暴露出来 (`classify_ai_system`, `generate_report`, `get_questionnaire`, …)，而 `ai-act-assessment` 技能（skill）驱动一个完整的人工干预评估——Claude 负责收集信息并撰写叙述，但**风险层级和引用仅来自引擎**，并且未经您的确认，任何内容都不会被保存。 ``` pip install -e ".[mcp]" # install the MCP dependency ``` **选项 A —— 直接打开仓库。** 项目作用域内的 `.mcp.json` 会自动注册服务器；在 Claude Code 提示时批准它，然后问： *"为我的简历筛选系统运行一次 EU AI Act 评估。"* **选项 B —— 作为插件安装**（在任何项目中都有效）： ``` /plugin marketplace add JKasteele/ai-act-companion /plugin install ai-act-companion@ai-act-companion ``` 然后通过 `/ai-act-companion:ai-act-assessment` 调用该技能，或者直接描述一个系统，让 Claude 自动拾取它。 ## CLI 基于相同引擎的可脚本化入口点（由 MCP server 使用，本身也很方便）： ``` ai-act questionnaire # print the intake schema ai-act classify --answers examples/hiring_cv_screening.json cat answers.json | ai-act classify --answers - # read from stdin ai-act classify --answers a.json --save # persist + print id ai-act report --answers a.json --type dpia --out dpia.md ai-act list ``` （`ai-act` 通过 `pip install -e .` 安装；或者运行 `python -m app.cli …`。） ## 测试与验证 ``` pytest # or: python tests/test_classifier.py ruff check . # lint ``` 该套件包括一项 **25 个用例的黄金集准确度评估** （`tests/test_accuracy.py` 针对 `examples/golden_set.json`，准确率为 100%——预期层级由独立的监管推理标记），以及一套**对抗性红队测试套件** （`tests/test_red_team.py`），证明提示词注入 / 越狱（jailbreak）输入无法改变确定性的风险层级。 请参阅 **[DESIGN.md](DESIGN.md)** 了解架构和设计原理 （确定性引擎 + LLM 界面 + 人工干预安全模式）。 ## 项目结构 ``` ai-act-companion/ ├── app/ │ ├── main.py FastAPI app + endpoints │ ├── cli.py scriptable CLI over the engine │ ├── questionnaire.py intake definition (single source of truth) │ ├── classifier.py rule-based EU AI Act classifier │ ├── reports.py report generators (risk/DPIA/bias/security/FRIA/techdoc/compliance/monitoring/framework-matrix/redteam/controls/datasec/stride/incident/modelcard) │ ├── security.py AI security lens + architecture-aware severity │ ├── redteam.py architecture-aware red-team test-plan generator │ ├── controls.py defensive control-catalogue generator (blue-team mirror) │ ├── data_security.py OWASP GenAI Data Security lens (DSGAI01–21) │ ├── stride.py STRIDE threat model (reuses the architecture-aware severity) │ ├── incident.py serious-incident helper (Art. 3(49) + Art. 73 deadlines) │ ├── modelcard.py Model Card generator (Mitchell et al., 2019; Art. 13) │ ├── scan.py repository AI-usage scanner (EU AI Act relevance flag) │ ├── storage.py JSON persistence │ ├── models.py pydantic models │ ├── knowledge/ EU AI Act, NIST AI RMF, ISO 42001, AI security, red-team, controls, GenAI data security, monitoring, CSF/ISO 27001 as data │ └── llm/ optional local/manual AI assist (web app) ├── mcp_server.py MCP server (Claude Code tools over the engine) ├── skills/ Claude Code skill (ai-act-assessment playbook) ├── .claude-plugin/ plugin.json + marketplace.json ├── .mcp.json project-scoped MCP registration ├── static/ frontend (index.html, app.js, style.css, print.css) ├── examples/ synthetic example assessments ├── data/ saved assessments (JSON, gitignored) └── tests/ classifier tests ``` ## API | 方法 | 路径 | 描述 | |---|---|---| | GET | `/api/questionnaire` | 问卷定义 | | POST | `/api/assess` | 分类并存储 | | GET | `/api/assessments` | 列出已存储的评估（清单） | | GET | `/api/portfolio` | 清单汇总（层级分布、待办义务、Art. 50） | | GET | `/api/assessments/{id}` | 完整的评估（JSON 导出） | | DELETE | `/api/assessments/{id}` | 删除某项评估 | | GET | `/api/export.csv` | 作为 CSV 登记表的清单 | | GET | `/api/assessments/{id}/report?type=risk\|dpia\|bias\|security\|fria\|techdoc\|compliance\|monitoring\|framework-matrix\|redteam\|controls\|datasec\|stride\|incident\|modelcard` | 报告 | | GET | `/api/ai/status` | AI 层状态（提供商、模型、可达性） | | POST | `/api/ai/prefill` | 自由文本 → 草拟答案（或用于手动模式的提示词） | | POST | `/api/ai/parse` | 粘贴回的 LLM 答案 → 验证后的草稿 | | POST | `/api/ai/narrative` | 针对单个叙述字段的草稿文本 | ## AI 层（可选） AI 层是**可选的**且**提供商可插拔**的（`app/llm/`）。通过 `.env` 进行配置（参见 `.env.example`）： | `LLM_PROVIDER` | 行为 | |---|---| | `ollama` *（默认）* | 通过 Ollama 的本地模型。私密，免费。 | | `manual` | 应用程序会生成一个提示词，您将其粘贴到**自己**的 LLM 会话中（例如 Claude）；然后您将 JSON 答案粘贴回来。无需 API 密钥。 | | `none` | 关闭 AI 层（仅基于规则）。 | **硬性保证（人工干预）：**所有 AI 输出均为*草稿*。它只用于预填问卷，绝不会自动分类、提交或存储。答案会根据 schema 进行验证——未知字段和无效选项会被明显忽略。 ## AI 安全视角 治理和安全是互补的，但免费工具很少将它们联系起来。 AI Act Companion 增加了一个**安全视角**：根据系统的回答，它会推导出适用的 **OWASP Top for LLM Applications (2025)** 项目，并为每个项目提供相关的 **MITRE ATLAS** 技术、EU AI Act 控制措施（主要是 Art. 15——其第 5 段明确指出了数据/模型投毒、对抗样本、模型逃逸和机密性攻击）、NIST AI RMF 子类别（基于 **MEASURE 2.7**）以及缓解措施。 它显示在结果视图中，作为一个 `security` 报告 （`ai-act report --type security`），以及通过 `classify_ai_security` MCP 工具。 该视角具有适应性：非生成式 ML 系统仍会映射到信息披露、投毒和供应链相关项，而暴露的 LLM 还会额外映射到提示词注入、系统提示词泄露和错误信息。 **感知架构的严重程度。**每个适用项都会获得一个确定性的严重程度（Critical / High / Medium / Low），它是根据一小部分结构化的架构上下文字段计算得出的——例如，*提示词注入在此处属于 Critical，因为 LLM 是唯一的访问控制边界，并且 API 是可读写的*——并附有一行说明决定性字段的理由。严重程度是这些字段的纯函数，因此精心构造的自由文本无法改变它（由红队测试套件覆盖）。 **框架桥梁。**安全报告（以及一个独立的 `framework-matrix` 报告）包含一个**框架集成矩阵**，它将发现结果与 **NIST CSF 2.0** 和 **ISO/IEC 27001:2022**（仅限公开的控制名称）相对齐——这些是安全审查人员和 ISMS 审计师实际使用的框架。 ### 红队测试计划 安全视角回答了*哪些* AI 风险适用及其严重程度；而**红队测试计划**将其转化为*如何对其进行测试*。从相同的结构化答案中，它会生成一个优先级排序的、**感知架构的**对抗性测试用例目录，用于界定*已授权的*紫队演练范围。每个测试用例都包含一个目标、它所针对的 MITRE ATLAS 技术、前置条件、方法论、通过/失败（成功）标准、蓝队应该看到的**检测与日志**记录，以及它所验证的 EU AI Act / NIST 控制措施。 两个特性使其不仅仅是一个普通的检查表： - **感知架构的优先级排序。**测试用例的优先级*即是*其父级 OWASP 风险的感知架构的严重程度，并且条件测试受限于架构——例如，只有在提示词中对所有用户数据强制执行访问控制时，才会出现 **Critical** 的*跨租户数据访问*测试，并且只有在系统摄取不受信任的内容时才会出现*间接（检索内容）注入*测试。与分类器具有相同的不变性：自由文本无法添加、丢弃或重新设定测试的优先级。 - **这是一个计划，而不是攻击工具。**它**不包含可用的漏洞载荷**——仅包含测试设计——并且不执行任何操作。它是用于已授权测试的辅助工具，不是扫描器，也不能替代真正的红队。 它作为 **Red-team plan** 报告选项卡、`ai-act report --type redteam` 以及通过 `generate_red_team_plan` MCP 工具（结构化） / `generate_report`（Markdown）显示。 ### 控制目录与数据安全 另外两个视角完善了紫队的全貌： - **防御控制目录** —— 红队计划的蓝队镜像。对于范围内的每项 OWASP 风险，它列出了**要实施的控制**（它是什么，它能防止什么，如何验证它）、NIST CSF 2.0 / ISO 27001:2022 锚点以及 EU AI Act / NIST AI RMF 参考。一项控制的优先级*即是*它所缓解的风险的感知架构的严重程度（与红队计划使用的数字相同），条件控制受限于与攻击*相同*的架构条件，并且每项控制都指明了**验证它的红队测试用例**——将这两份报告变成一个循环：*实施控制，然后运行证明它有效的测试。*作为 **Control catalogue** 选项卡、`ai-act report --type controls` 以及 `generate_control_catalog` MCP 工具显示。 - **OWASP GenAI 数据安全视角** —— LLM Top 10 视角在数据层的补充。它将系统映射到 21 项 **OWASP GenAI 数据安全**风险（DSGAI01–21，来自 2026 v1.0 指南），涵盖训练/微调数据、提示词、检索上下文、embeddings、遥测和输出。相关性在信息采集过程中是确定性的；每个适用风险都会交叉映射到 OWASP LLM Top 10、**EU AI Act Art. 10（数据治理）**、GDPR 和 NIST AI RMF。作为 **Data security** 选项卡、`ai-act report --type datasec` 以及 `assess_data_security` MCP 工具显示。 ### STRIDE、事件、模型卡与清单汇总 Tier 3 套件完善了生命周期： - **STRIDE 威胁模型** —— 跨越六个 STRIDE 类别的系统，由相同的安全架构答案驱动。四个类别重用了安全视角的**感知架构的严重程度**（因此 STRIDE 和 OWASP 视图在构建上保持一致）；“欺骗”和“否认”根据身份验证和日志记录进行评分。**STRIDE 威胁模型**选项卡 / `--type stride`。 - **严重事件助手** —— 一个针对四个 **Art. 3(49)** 分支的决策辅助工具，返回具有约束力的 **Art. 73** 报告截止日期（15 / 2 / 10 天），外加一份填写式事件报告。**Serious incident** 选项卡 / `--type incident`。 - **模型卡** (Mitchell et al., 2019) —— 一项透明度工件（**Art. 13**），根据信息采集表预填。**Model card** 选项卡 / `--type modelcard`。 - **清单汇总** —— 跨越所有已保存的评估：风险层级分布、按日期即将到期的义务，以及 Art. 50 披露列（在仪表板、`/api/portfolio` 和 CSV 登记表中）。 该工具还有自己的 [THREAT_MODEL.md](THREAT_MODEL.md) —— 包括应用于其*自身* AI 层的 OWASP LLM Top 10 —— 以及 [SECURITY.md](SECURITY.md) 策略；`bandit` 和 `pip-audit` 在 CI 中运行。 ## 用作 CI 检查（GitHub Action） 尽早发现 AI 系统：捆绑的 **EU AI Act 相关性扫描** action 会标记出某个仓库是否似乎使用了 AI/ML（依赖清单、源码导入、模型工件），并指向值得检查的条款。这是一个确定性的相关性标志——不进行任何模型调用，也不进行分类——并将 Markdown 摘要写入作业/PR。 ``` # .github/workflows/ai-act.yml name: EU AI Act relevance on: [pull_request] jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: JKasteele/ai-act-companion@v0.7.0 with: path: . # fail-on-detect: "true" # optional: turn the scan into a gate ``` 在本地运行：`ai-act scan .`（或 `--json`）。示例输出会列出找到的库、任何模型文件，以及需要考虑的 EU AI Act 问题（Art. 2/5/6/10/50）。 ## 法律依据 引用在 `app/knowledge/` 中被建模为数据。分类器会针对每个结论引用具体的条款/附录： - **Art. 5** —— 被禁止的实践 - **Art. 6 + Annex I/III** —— 高风险（包括 Art. 6(3) 豁免） - **Art. 50** —— 透明度义务 - **Chapter V (Art. 51–55)** —— 通用人工智能 (GPAI) - **Art. 11 + Annex IV** —— 技术文档 - **Art. 72** —— 上市后监控 - **Art. 99 / 101** —— 行政罚款（面临处罚风险的模块） - **OWASP LLM Top 10 (2025) + MITRE ATLAS** —— 安全视角、红队测试计划与控制目录 - **OWASP GenAI 数据安全 (2026, v1.0)** —— 数据层视角（DSGAI01–21），基于 Art. 10 - **NIST AI RMF 1.0** —— GOVERN / MAP / MEASURE / MANAGE 交叉映射 - **ISO/IEC 42001:2023** —— AI 管理体系交叉映射（分析对齐） - **NIST CSF 2.0 + ISO/IEC 27001:2022** —— 安全框架集成矩阵（分析对齐） ## 路线图 - [x] 基于规则、带引用的 EU AI Act 分类器（禁止 / 高 / 有限 / 最小） - [x] 风险评估 + DPIA 骨架 + 偏见审计检查表，映射到 NIST AI RMF - [x] 可选的 AI 层（Ollama + 手动提示词提供商），强制要求人工干预 - [x] 单元测试 + CI + Docker - [x] **Claude Code 插件** —— MCP server + 技能 + CLI（Claude 作为界面，引擎作为事实来源） - [x] **AI 安全视角** —— 发现结果映射到 OWASP LLM Top 10 (2025) + MITRE ATLAS - [x] 工具自身的威胁模型 (`THREAT_MODEL.md`) + 在 CI 中运行 `bandit`/`pip-audit` - [x] EUR-Lex / AI Act Explorer 深度链接 + 分阶段的适用性时间表 (Art. 113) - [x] 基本权利影响评估 (FRIA, Art. 27) 生成器 - [x] AI 系统清单（仪表板）+ CSV 登记表和 JSON 导出/导入 - [x] ISO/IEC 42001 交叉映射（在风险评估报告中） - [x] Annex IV 技术文档生成器 (Art. 11) - [x] 包含 Art. 99 罚款风险的义务与合规追踪器 - [x] AI 安全视角的**感知架构的严重程度** (Critical/High/Medium/Low) - [x] 上市后监控计划 (Art. 72)，基于 NIST AI 800-4 构建结构 - [x] **NIST CSF 2.0 + ISO/IEC 27001:2022** 框架集成矩阵 - [x] **感知架构的红队测试计划** (OWASP LLM Top 10 + MITRE ATLAS，已授权的紫队范围界定) - [x] **防御控制目录** —— 蓝队的镜像，每项控制均由红队测试验证 - [x] **OWASP GenAI 数据安全视角** (DSGAI01–21) —— 数据层的补充，基于 EU AI Act Art. 10 - [x] **STRIDE 威胁模型** —— 六个类别，重用感知架构的严重程度 (Art. 15) - [x] **严重事件助手** —— Art. 3(49) 分支 + Art. 73 报告截止日期 + 报告模板 - [x] **模型卡生成器** (Mitchell et al., 2019) —— 透明度工件 (Art. 13)，根据信息采集表预填 - [x] **清单汇总** —— 层级分布、按日期到期的义务、Art. 50 披露列 - [x] **ISO/IEC 42001 Annex A 控制映射** —— 全部 38 项 Annex A 控制措施，每项都锚定到其最相关的 EU AI Act 条款（在风险报告中） - [x] **现场演示** (Hugging Face Spaces) + **EU AI Act 截止日期倒计时** + 刷新的 UI - [x] **静态示例报告库** —— 真实的生成工件，可在 GitHub 上查看 - [x] **仓库 AI 使用扫描器** —— `ai-act scan` + 一个能够在任何代码库中标记 EU AI Act 相关性的 GitHub Action ## 许可证 MIT —— 见 [LICENSE](LICENSE)。

标签：AI风险缓解, AI风险评估, Claude Code插件, DPIA隐私影响评估, EU AI Act, MCP, Python, 合规与审计, 无后门, 请求拦截, 逆向工具