Peaky8linders/eu-ai-act-scanner
GitHub: Peaky8linders/eu-ai-act-scanner
该工具通过本地静态分析扫描代码库，检测并评估其与欧盟《AI法案》各条款要求的合规证据与缺口。
Stars: 3 | Forks: 0
# EU AI Act Scanner
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.python.org/downloads/)
-red)
**在一个仓库中以三种形式发布：**
1. 一个 **Claude Code 插件**，包含四个命令（`/ai-act-scan`、`/ai-act-scan-fix`、`/ai-act-article`、`/ai-act-incidents`）和 **13 项基于条款的技能**，涵盖分类、义务、部署者责任、GPAI、Annex IV、时间线、处罚以及真实事件 grounding。
2. 一个 **Python 库**（`from scanner import scan_project`），包含 **22 个分析器**，其中包括一个专门的 Article 50 透明度分析器和 7 个基于 Nannini 等人 (2026) 的 *AI Agents under EU Law* 的 agent 感知分析器——涵盖四个复合风险维度（级联、涌现、归因、时间）、AEPD 致命三角检测、runtime drift、监管边界分类以及工具权限最小化。
3. 一个 **MCP server**（`eu-ai-act-scan-mcp`），以便非 Claude-Code agent 可以通过 Model Context Protocol 调用扫描器并查询事件语料库。
每一条发现都 **基于真实事件**（v0.4 新增）：扫描器将其 gap 对应到内置的、经过审查层级的开源 [GenAI & Agentic AI Security Incidents 数据集](https://huggingface.co/datasets/emmanuelgjr/genai-incidents) 子集（CC-BY-4.0，7,725+ 起事件映射至 OWASP LLM Top 10 2025、OWASP Agentic (ASI) Top 10、NIST AI RMF 和 MITRE ATLAS）。一个 gap 不再只是“你没有 prompt 注入防御”，而是变成了“……而且这里是恰好利用了该 gap 的已记录事件，以及已发布的缓解措施。”详见[事件 grounding](#incident-grounding)。
## ⏳ 执法倒计时
EU AI Act 分阶段生效。**Digital Omnibus**（于 2026 年 6 月 29 日通过）将高风险的 Annex III 制度推迟至 **2027 年 12 月 2 日**——但故意**保持 Article 50 的透明度要求不变**，使其成为任何发布聊天机器人、生成合成内容或运行情绪/生物识别系统的人目前最紧迫的截止日期。
| 里程碑 | 条款 | 日期 | 状态 |
|---|---|---|---|
| 禁止的做法 | Art. 5 | 2025 年 2 月 2 日 | ✅ 已生效 |
| GPAI 模型义务 | Art. 53 / 55 | 2025 年 8 月 2 日 | ✅ 已生效 |
| **透明度** | Art. 50 | 2026 年 8 月 2 日 | ⏳ **T-20 天** |
| 高风险 (Annex III) | Art. 9-15 / 17 / 27 | 2027 年 12 月 2 日 | ⏳ T-507 天 |
_倒计时由 `scripts/update_readme_countdown.py` 生成于 2026-07-13（在 CI 中每周刷新）。Digital Omnibus 将高风险推迟到了 2027 年 12 月，但将 Article 50 留在了 2026 年 8 月 2 日。_
如果你的系统涉及生物识别、关键基础设施、教育、就业、基本服务、执法、移民或司法，那么高风险制度（2027 年 12 月）也在范围之内。大多数团队都不知道他们的代码目前对照法规处于什么状态。
**运行以下命令查看你距离生效的 Article 50 截止日期还有多远：**
```
from datetime import date
from scanner import scan_project
result = scan_project("./my-ai-project")
days_left = (date(2026, 8, 2) - date.today()).days # Article 50 transparency
print(f"T-{days_left} days to Article 50 transparency enforcement")
print(f"Overall compliance score: {result.overall_compliance_pct}%")
print()
print("Worst-scoring dimensions (fix these first):")
for dim_id, score in sorted(result.compliance_scores.items(), key=lambda x: x[1])[:5]:
print(f" [{score:>3}%] {dim_id}")
```
在一个中等合规水平的 RAG 应用上的输出示例：
```
T-20 days to Article 50 transparency enforcement
Overall compliance score: 47%
Worst-scoring dimensions (fix these first):
[ 12%] logging — Art. 12 automatic record-keeping
[ 25%] human_oversight — Art. 14 HITL gates + override hooks
[ 31%] fairness_testing — Art. 10(2)(f) disparate-impact tests
[ 44%] adversarial_robustness — Art. 15(3) prompt-injection defences
[ 48%] tech_docs — Art. 11 Annex IV technical file
```
每个 gap 都映射到特定的条款，因此合规官或法律顾问可以将其直接导入他们的质量管理体系或 Art. 43 合格性评估清单中，无需任何转换。
或者使用单行 Claude Code 版本：
```
/ai-act-scan ./my-app
```
这会运行相同的扫描，并用通俗易懂的英语讲述结果、引用条款，并通过 `/ai-act-scan-fix --top 3` 主动为最严重的 gap 提供修复任务建议。
## 为什么需要
EU AI Act（法规 2024/1689）于 2024 年 8 月生效。禁止的做法（Art. 5）和 GPAI 义务已经生效；Article 50 透明度要求将于 2026 年 8 月 2 日起适用；而高风险制度——由 Digital Omnibus 推迟——将于 2027 年 12 月 2 日起适用。大多数团队对其代码实际上展现的内容与法规要求之间的差异一无所知。
这个工具只做一件事：**扫描你的代码仓库，并揭示对照映射到 EU AI Act 条款的 23 个合规维度的证据和 gap，所有这些都基于利用了每类 gap 的真实事件**。它*不*替代合格性评估、法律审查或质量管理体系。它是所有这些之下的静态分析层。
## 扫描器检查什么
22 个专门的分析器，全部为确定性静态分析（默认不进行 LLM 调用）：
**基准分析器（14 个）：**
| 分析器 | 涵盖范围 | 条款 |
|---|---|---|
| `ai_frameworks` | PyTorch, TensorFlow, Hugging Face, OpenAI/Anthropic SDKs, LangChain | Art. 10, 11, 53 |
| `data_pipeline` | 训练数据处理、数据集加载、偏差测试 hooks | Art. 10 |
| `human_oversight` | HITL 门控、置信度阈值、批准门控、override hooks | Art. 14 |
| `security_controls` | 身份验证、限流、输入验证、RBAC | Art. 15 |
| `fairness_testing` | AIF360, Fairlearn, 差异影响测试 | Art. 10(2)(f) |
| `test_suite` | 针对 AI 代码的 pytest / unittest 覆盖率 | Art. 9, 15 |
| `logging_monitoring` | 结构化日志, MLflow, Prometheus, W&B | Art. 12, 15 |
| `documentation` | README, 模型卡片, docstrings | Art. 11, 13 |
| `configuration` | Dockerfile, `pyproject.toml`, CI 配置 | Art. 17 |
| `agent_cascade` | 多 agent 编排、工具使用 | Art. 15(4) |
| `adversarial_robustness` | ART, Foolbox, 护栏、prompt 注入防御 | Art. 15(3) |
| `terraform` | Terraform HCL — IAM, 网络、密钥处理 | Art. 15 |
| `cloudformation_k8s` | CloudFormation + Kubernetes 清单 | Art. 15 |
| `cicd_dockerfile` | GitHub Actions, GitLab CI, Dockerfile 安全 | Art. 17 |
**Agent 感知分析器（7 个），在 v0.3 中添加——基于 Nannini 等人 (2026)，[*AI Agents under EU Law*](https://arxiv.org/abs/2504.06255)：**
| 分析器 | 涵盖范围 | 复合风险维度 |
|---|---|---|
| `agent_inventory` | MCP, OpenAI Assistants v2, 浏览器 agent、代码解释器沙箱、动作动词分类法 | 归因 (论文 §10.4) |
| `privilege_minimization` | Prompt 作为控制的反模式、对模型输出直接 exec、长期凭证、OAuth 过度授权、权限注册表 | 级联 (OWASP Top 10 Agentic) |
| `runtime_drift` | 浮动模型 ID、内联 prompt、工具目录清单、Art. 3(23) 实质性修改程序 | 时间 (Art. 3(23)) |
| `regulatory_perimeter` | GDPR / Data Act / CRA / MDR / NIS2 触发器检测、Step-9 邻接构件 | 归因 (Art. 25) |
| `lethal_trifecta` | AEPD 规则 2 选 1 — 不受信任的输入 + 敏感数据 + 无 HITL 的自主状态更改 | 多重 |
| `model_typology` | 基础 / 生成式 / 决策支持 / 感知模型分类及 Annex 依据 | — |
| `cloud_deployment` | 特定于云提供商的控制和共享责任标志 | — |
发现结果被汇总到 **23 个合规维度**中（参见 [`scanner/kb.py`](scanner/kb.py)），来自四个 agent 感知分析器的 gap 发现会通过 [`scanner/data/agentic_taxonomy.py`](scanner/data/agentic_taxonomy.py) 和 [`scanner/data/role_obligations.py`](scanner/data/role_obligations.py) 自动打上其复合风险维度、威胁类别和适用运营者角色的标签。
## 事件 Grounding
一个规范性的 gap（“你没有 prompt 注入防御——Art. 15(4)”）很容易被敷衍过去。但一个*基于证据的* gap 则不然：“……而且这里是恰好利用了该 gap 的已记录事件，映射到 OWASP LLM01 + MITRE ATLAS AML.T0051，以及已发布的缓解措施。”这就是事件 grounding 的作用。
扫描器捆绑了开源的 **[GenAI & Agentic AI Security Incidents 数据集](https://huggingface.co/datasets/emmanuelgjr/genai-incidents)**（`emmanuelgjr/genai-incidents`，**CC-BY-4.0**）的一个精选的、经过审查层级的子集——这些真实世界和研究事件聚合自 AIID、OECD AIM、AIAAIC、MITRE ATLAS、AVID、MIT AI Risk Repository、NVD、GHSA、OSV、garak、promptfoo 等，并进行了去重。每个事件都带有其原生的分类体系：OWASP Top 10 for LLM Applications (2025)、OWASP Agentic (ASI) Top 10、NIST AI RMF 和 MITRE ATLAS 技术/战术，以及已记录的缓解措施和 CVE ID。
[`scanner/data/incident_crosswalk.py`](scanner/data/incident_crosswalk.py) 中的 crosswalk 将扫描器自己的词汇表——KB 维度、agentic 威胁类别和 EU AI Act 条款引用——映射到该事件分类体系。因此：
- **每个 gap 发现**都会得到一个 `related_incidents` 列表（利用了其类别的已记录事件）。
- **每次扫描结果**都带有 `incident_grounding`——得分最差的维度与真实事件配对。
- **Python/CLI/MCP API** 可以根据需要展示任何维度、条款或威胁类别的事件。
```
from scanner import incidents_for_dimension, incidents_for_article, incident_corpus_stats
for inc in incidents_for_article("art15", limit=3):
print(f"{inc.id} [{inc.severity}] {inc.title}")
print(f" OWASP-LLM {inc.owasp_llm} | MITRE {inc.mitre_atlas[:2]} | NIST {inc.nist_ai_rmf[:2]}")
if inc.mitigations:
print(f" mitigation: {inc.mitigations[0]}")
print(incident_corpus_stats()["count"], "incidents bundled, attribution:",
incident_corpus_stats()["license"])
```
或者通过 Claude Code / CLI：
```
/ai-act-incidents art15 # incidents for an article
/ai-act-incidents security # incidents for a KB dimension
/ai-act-incidents prompt_injection # incidents for an agentic threat category
```
```
eu-ai-act-scan --incidents art15 --limit 5 # JSON
eu-ai-act-scan ./my-app --markdown # scan report with a grounding section
```
**默认离线运行。** 捆绑的子集随 wheel 一起发布，不需要网络。完整的 7,725 起事件数据集仅需一步即可获取——`pip install genai-incidents` 或 `load_dataset("emmanuelgjr/genai-incidents")`——并且捆绑的快照由 [`scripts/sync_incident_corpus.py`](scripts/sync_incident_corpus.py)（`pip install eu-ai-act-scanner[sync]`）确定性地重新生成。事件 grounding 是**为你 Art. 9 风险管理和 Art. 72 上市后监测提供的证据输入——而非合规性结论。** 参见 [`eu-ai-act-incident-grounding`](skills/eu-ai-act-incident-grounding.md) 技能。
## 义务与运营者角色推断
只有当*你*承担该义务时，gap 才有意义。扫描器确定性地推断出被扫描的代码库占据了 EU AI Act 中的哪个/些角色——**provider**（你构建/训练/发布模型）、**deployer**（你使用别人的模型）、**GPAI provider**（你训练通用模型）——这些推断基于封闭词汇表的代码信号，不使用 LLM 也不联网。随后，每一个 **gap** 发现都会回填 `applicable_roles`：即实际上承担其条款义务的角色，这些角色取自[角色-义务注册表](scanner/data/role_obligations.py)。`ScanResult.inferred_roles` 带有项目级别的配置文件。
```
from scanner import scan_project
result = scan_project("./my-app")
print(result.inferred_roles) # e.g. ["provider"] — drives which obligations apply
```
## 自动化修复循环
`eu-ai-act-fix` 闭环运行：扫描 → 对 gap 排序 → 提出补救措施 →（可选）应用 → **重新扫描** → 仅在不导致任何退化的情况下保留修复 → 重复直到收敛。
```
eu-ai-act-fix ./my-app # safe dry-run: proposals only, nothing written
eu-ai-act-fix ./my-app --apply # write fixes, re-scan, revert any regression
eu-ai-act-fix ./my-app --top 5 --json # widen the gap set, machine-readable output
```
每个确定性的补救措施都会根据分析器自身的正向检测模式进行验证，因此在重新扫描时应用它可以明显提高分数。**回归防护** 是反脆弱的特性由于总分是跨维度平均的，添加一个文件可能会激活另一个分析器，一个“好”的修复可能会降低相邻维度的得分——所以每次应用的修复都会被重新扫描，并且**如果任何维度下降就会被回滚**。合规文档（`MODEL_CARD.md`、`DATA_CARD.md`）使用 `` 占位符进行构建——该循环绝不捏造监管声明。默认模式不写入任何内容；必须使用 `--apply` 才能修改代码树。
```
from scanner import run_fix_loop
res = run_fix_loop("./my-app", top_n=3, apply=False)
print(res.baseline_overall, "->", res.final_overall, f"({res.overall_delta:+})")
for p in res.proposals:
print(p.dimension, p.article, p.title)
```
## Claude Max 桥接（可选的 LLM）
扫描器是本地优先的，完全在没有 LLM 的情况下运行。当你*确实*想要可选的 LLM 辅助路径时（更丰富的文档评分、为没有确定性修复器的 gap 起草 LLM 修复），[Claude Max 桥接](scanner/llm_bridge.py) 会通过本地的 [Claude-Code 订阅包装器](https://github.com/)（兼容 Anthropic）路由它们，而不是使用按量计费的 API key——因此它们在你的 **Claude Max 订阅** 上运行。该包装器默认为 `http://127.0.0.1:8000`，也可以通过 Cloudflare tunnel 访问，用于远程/CI 环境。
```
export EU_AI_ACT_SCANNER_LLM=true # opt in
export EU_AI_ACT_SCANNER_LLM_BASE_URL=http://127.0.0.1:8000 # local wrapper (default)
# 或者，远程： https://wrapper. + EU_AI_ACT_SCANNER_LLM_API_KEY=...
export EU_AI_ACT_SCANNER_LLM_MODEL=claude-sonnet-4-6 # optional model override
eu-ai-act-scan --llm-status # report bridge config + probe wrapper /health
```
桥接**在构建上实现了优雅降级**——禁用的标志、缺失的 `anthropic` SDK 或无法访问的包装器都会退化为无效结果，并且永远不会阻止扫描。它移植了在 `regenold-eu-ai-act-rag` 系统中经过实战检验的多策略 JSON 提取器和结构截断启发式算法。
## 安装
### 作为 Claude Code 插件
```
# 来自 Claude Code
/plugin install Peaky8linders/eu-ai-act-scanner
```
然后在 Claude Code 内部的任何代码库上调用 `/ai-act-scan`。
### 作为 Python 包
```
git clone https://github.com/Peaky8linders/eu-ai-act-scanner
cd eu-ai-act-scanner
pip install -e .
```
或者（一旦发布）：
```
pip install eu-ai-act-scanner
```
### 作为 MCP server
对于非 Claude-Code agent（或任何 MCP 客户端），安装可选的 MCP extra 并运行服务器：
```
pip install "eu-ai-act-scanner[mcp]"
eu-ai-act-scan-mcp # stdio MCP server
```
使用内置的 [`.mcp.json`](.mcp.json) 将其注册到 MCP 客户端：
```
{ "mcpServers": { "eu-ai-act-scanner": { "command": "eu-ai-act-scan-mcp", "args": [] } } }
```
它暴露了七个工具：`scan_project`、`list_dimensions`、`get_article`、`incidents_for_dimension`、`incidents_for_threat`、`incidents_for_article` 和 `incident_corpus_stats`——与库和 CLI 使用相同的引擎。
## 用法
### 在 Claude Code 中（推荐）
```
/ai-act-scan ./my-app # full scan + narration + article cites
/ai-act-article art50 # Art. 50 transparency deep-dive
/ai-act-scan-fix --top 3 # propose fixes for the worst gaps
/ai-act-incidents art15 # real-world incidents for an article/dimension/threat
/ai-act-ask "..." # grounded Q&A over the bundled EU AI Act text
/ai-act-settings # view / set mode (deterministic | assisted)
```
该插件用通俗易懂的英语讲述输出，引用条款，并提供补救任务。一旦安装了插件，13 项内置技能（Art. 5 禁止、Art. 6 分类、FRIA、运营者角色、GPAI、Annex IV、时间线、处罚、事件 grounding 和三个元技能）即可自动调用——询问“这在 Art. 5 下被禁止吗？”、“Annex IV 里有什么？”或“哪些真实事件映射到此 gap？”，Claude 就会调用正确的技能。
### Article 50 示例
Article 50 透明度——聊天机器人披露、合成内容标记、deep-fakes、情绪/生物识别通知——将于 **2026 年 8 月 2 日起可执行**，这是 Digital Omnibus *没有*推迟的唯一一项义务。专门的 `article_50_transparency` 分析器检查所有四项职责：
```
/ai-act-scan ./my-chatbot
# art50-no-ai-disclosure (Art. 50(1)) — 没有“你正在与 AI 对话”提示的聊天界面
# art50-unmarked-synthetic (Art. 50(2)) — 没有 C2PA / 水印 的图像/音频生成
/ai-act-ask "What are a deployer's Article 50 duties for deepfakes?"
# 来自捆绑法规文本的引用解答 — Art. 50(3) 情感/生物识别, 50(4) deep-fake + AI-text
/ai-act-scan-fix --top 3
# 提出披露 / 标记修复，展示计划，仅应用你批准的内容
```
### 使用你自己的 Claude Code（辅助模式）
扫描默认 100% 本地且具有确定性。可以选择由**你自己的 Claude Code** 驱动进行更深入的扫描——无需 API key，无需包装器：
```
python -m scanner.cli --set mode=assisted # persist to .eu-ai-act-scanner.toml
python -m scanner.cli --set auto-apply=true # let it apply approved fixes too
```
在 `assisted` 模式下，命令使用宿主 Claude Code 会话在语义上审查发现结果，回答有根据的问题，并（在开启 `auto-apply` 的情况下）使用其自身的编辑工具应用修复。确定性评分仍然是客观的基准线。
### Python
```
from scanner import scan_project
result = scan_project("./my-ai-project")
print(f"Overall compliance: {result.overall_compliance_pct}%")
for dim_id, score in sorted(result.compliance_scores.items(), key=lambda x: x[1]):
print(f" {dim_id}: {score}%")
for gap in result.risk_indicators[:5]:
print(f" ! {gap}")
```
参见上方的[执行倒计时](#-enforcement-countdown)，获取一个可以直接运行的片段，它会根据紧急程度排序，展示你得分最差的维度。
## 输出结果代表什么
得分采用 0–100 分制：
- **0–29%**：明显的 gap，几乎没有证据
- **30–59%**：存在部分证据，有实质性 gap
- **60–79%**：有证据，可能需要补充文档
- **80–100%**：证据充分；仍需人工验证
**得分并不是合规结论。** 合规是一项法律决定，对于高风险系统需要进行合格性评估（Art. 43），对于其他风险层级则需要进行记录在案的自评估。此扫描器只负责揭示证据——由人（最好有法律顾问参与）得出结论。
## 它不能做什么
- **默认不进行 LLM 调用。** 纯本地静态分析。仅可选择开启：`assisted` 模式使用你自己的 Claude Code（`/ai-act-settings`），或无头 LLM 桥接（`EU_AI_ACT_SCANNER_LLM=true`）——除非你启用它们，否则均处于关闭状态。
- **无网络请求，无遥测。** 你的代码永远不会离开你的机器。事件语料库离线内置；只有 `scripts/sync_incident_corpus.py`（由维护者运行，从不在扫描时运行）会连接网络以重新生成它。
- **不进行风险层级分类。** 你的系统是高风险、有限风险还是最小风险，取决于用例（Art. 6 + Annex III）——这必须由人来决定。
- **不提供法律建议。** 请与法律顾问配合使用此工具，而不是替代法律顾问。
## 路线图
- **v0.1**：插件 + 库（2026 年 4 月）
- **v0.2**：面向法律从业者的 11 项基于条款的技能套件（2026 年 4 月）
- **v0.3**：根据 Nannini 等人 (2026) 制定的 7 个 agent 感知分析器 + 4 个新的合规维度 + 四维度复合风险分类法（2026 年 5 月）
- **v0.4**：真实世界事件 grounding（GenAI-incidents 语料库 crosswalk 到 OWASP LLM/ASI, NIST AI RMF, MITRE ATLAS）+ MCP server + `/ai-act-incidents` 命令（2026 年 6 月）
- **v0.6**：确定性运营者角色推断 + 自动化修复循环 + Claude Max 桥接（2026 年 6 月）
- **v0.7**：AI 系统范围门控——停止对非 AI 项目评分/修复（2026 年 7 月）
- **v0.8**：Article 50 透明度分析器 + 有根据的问答（`/ai-act-ask`）+ 辅助模式（`/ai-act-settings`）使用你自己的 Claude Code（当前版本，2026 年 7 月）
- **下一步**：baseline / diff 模式（扫描两次，仅报告发生变化的内容）；可选择开启实时的 `genai-incidents` 数据扩充
## 许可证
Apache-2.0。参见 [LICENSE](LICENSE)。
## 致谢
提取自 [CodexAI](https://antifragile-ai.net)——完整的 EU AI Act 合规平台。CodexAI 在此扫描器之上增加了风险分类、成熟度评分、路线图生成、Annex IV / FRIA / Art. 13 文档、跨框架映射和审计证据链。
事件 grounding 建立在由 Emmanuel G.（[`emmanuelgjr/genai-incidents`](https://huggingface.co/datasets/emmanuelgjr/genai-incidents)）创建的 **GenAI & Agentic AI Security Incidents** 数据集之上，采用 **CC-BY-4.0** 许可证，数据聚合自 AIID、OECD AIM、AIAAIC、MITRE ATLAS、AVID、MIT AI Risk Repository、NVD、GHSA、OSV、garak、promptfoo 等，并进行了去重。`scanner/data/incidents.json` 下捆绑的子集是一个精选的、经过审查层级的衍生品，用于离线 grounding；完整的数据集可通过 `pip install genai-incidents` 获取。感谢维护者让 AI 安全证据变得开放且可引用。
标签：AI安全, Chat Copilot, EU AI Act, LLM, MCP, Python, Unmanaged PE, 云安全监控, 合规检测, 安全专业人员, 文档结构分析, 无后门, 逆向工具, 静态分析