presidio-hardened-ikigov-assess

presidio-hardened-ikigov-assess

🇬🇧 英语 · 🇩🇪 德语

IKI-Gov 评估工具 — 将 IKI-Gov-Referenzmodell（集成式 AI 治理参考模型）转化为实用的 CLI 工具，用于依据结构化治理框架评估 AI 用例。

IKI-Gov 框架围绕核心生命周期构建 AI 治理 （Kontext → Konzeption → Entwicklung → Freigabe → Betrieb → Anpassung → Außerbetriebnahme）， 涵盖六个领域，并通过六个维度（M1–M6）和六个质量关卡 （G0–G5）进行衡量。

参考文献：Stantchev, V. IKI-Gov-Referenzmodell — 集成式 AI 治理参考模型。

---

本书

此工具实现了 IKI-Gov 参考模型，该模型首次发表于 Vladimir Stantchev 的 Springer 专著，并分别推出两个版本：

• AI and IT Governance（英文）— Springer，柏林；ISBN 978-3-662-74001-9；预计于 2027 年 1 月 11 日出版
• KI und IT-Governance（德文）— Springer，柏林；ISBN 978-3-662-74093-4；预计于 2026 年 12 月 28 日出版

本书从经典 IT 治理（COBIT、ITIL、ISO/IEC 38500）出发，探讨伦理、法律、风险和数据领域的 AI 治理，随后构建出 IKI-Gov：生命周期、六个领域、六个测量维度（M1–M6）和六个质量关卡（G0–G5）。此处评分的 25 个检查清单项取自本书的框架章节及其研讨会／审批关卡附录；ISO/IEC 42001 和 EU AI Act 的映射则遵循书中的导向表。

本书将该模型定位为经过推理的综合成果和用于指引方向的实用启发式方法，而非法律建议或合规性评估。此工具也遵循同样的原则（请参阅 euaiact-gap 和 iso-gap 命令中的免责声明）。两个版本现已开放 Springer（柏林）预订。Springer 目录页面和 DOI 上线后将在此处补充。

---

安装

pip install presidio-hardened-ikigov-assess

# With dependency CVE checking
pip install "presidio-hardened-ikigov-assess[audit]"

# With Ed25519 public-key evidence verification
pip install "presidio-hardened-ikigov-assess[crypto]"

---

快速入门

# Parameter-driven assessment
iga assess --use-case "fraud-scoring" --risk-class high --lang en \
    --affirm S1,S2,S3,D1,D2,T1,T4,O1,I1

# Interactive wizard (step-by-step)
iga assess --interactive --lang de --risk-class high --use-case "kredit-scoring"

# Gate readiness check
iga gate --gate G2 --risk-class high \
    --affirm S1,S2,S3,D1,D2,T1,T4,O1,I1 --lang en

# CI pipeline gate assertion (exit 0 OPEN / 2 PARTIAL / 3 BLOCKED)
iga gate --gate G1 --risk-class high --affirm S1,S2,D1,D2 --assert-gate G1

# Strict mode: skipped gate-critical items count as blocking
iga gate --gate G2 --risk-class high --affirm S1,S2 --skip D3 --strict --assert-gate G2

# Machine-readable JSON (scriptable, no progress bars)
iga assess --affirm S1,S2,S3 --quiet
iga gate --gate G0 --affirm S1,S2 --skip S3 --quiet

# Export report to Markdown (stdout)
iga report --use-case "fraud-scoring" --risk-class high \
    --affirm S1,S2,S3,D1,D2,T1 --format markdown

# Export report to JSON
iga report --use-case "fraud-scoring" --affirm S1,S2 --format json

# Write the report to a file (Markdown or JSON)
iga report --use-case "fraud-scoring" --affirm S1,S2,T4 --output audit/fraud-scoring.md
iga report --use-case "fraud-scoring" --affirm S1,S2 -f json -o fraud-scoring.json

# ISO/IEC 42001 clause-level coverage gap analysis
iga iso-gap --use-case "fraud-scoring" --risk-class high --affirm S1,S2,S3,I1,I2
iga iso-gap --affirm S2,S3,I1,I2 --quiet   # machine-readable JSON

# EU AI Act high-risk obligations (Art. 9–18, 72) — high-risk systems only
iga euaiact-gap --use-case "fraud-scoring" --affirm S1,S2,S3,S4,S5,D1,D5
iga euaiact-gap --affirm S1,S2 --quiet

# Persist assessments and view the portfolio (SQLite at ~/.iga/assessments.db)
iga assess --use-case "fraud-scoring" --risk-class high --affirm S1,S2,S3 --save
iga list                                   # table of saved assessments
iga portfolio                              # aggregated M1–M6 + blocked gates
iga trend --use-case "fraud-scoring"       # delta vs the previous saved run
iga delete --use-case "fraud-scoring"      # hard-delete

# List saved assessments (persistence in v0.6.0)
iga list

输出示例

在 100 列终端中运行本书中的完整示例（附录 B，校正后的校样）：

iga assess --use-case fraud-scoring --risk-class medium --lang en \
  --affirm S1,S2,S3,S4,S5,D1,D2,D4,D5,T1,T2,T3,T4,O1,O2,O3,I1 --skip D3

IKI-Gov Assessment — fraud-scoring  [risk: MEDIUM]

Measurement Dimensions
  M1  Strategie & Ownership                ██████████  100.0 %
  M2  Data Quality & Lineage               ██████████  100.0 %
  M3  Validation & Fairness                ██████████  100.0 %
  M4  Security & Robustness                █████░░░░░   50.0 %
  M5  Compliance Evidence                  ██░░░░░░░░   20.0 %
  M6  Operations, Drift & Incidents        ██████░░░░   60.0 %
────────────────────────────────────────────────────────────────────────────────────────────────────
       Overall maturity                     ███████░░░   71.7 %
       Evidence: 0 verified, 0 evidence-backed of 17 affirmed items; 0 asserted and not counted.

Gate Readiness
  G0  OPEN
  G1  OPEN
  G2  PARTIAL  — skipped: D3
  G3  BLOCKED  — blocking: T5 (A security review of the model…)
  G4  BLOCKED  — blocking: O4 (An incident response and change…), O5 (An audit log — capturing
model…), I2 (Roles and responsibilities for AI…)
  G5  BLOCKED  — blocking: O5 (An audit log — capturing model…), I2 (Roles and responsibilities for
AI…), I3 (An AI risk register per ISO/IEC 42001…), I4 (The AI system lifecycle is documented…), I5
(An internal audit of AI governance…)

将风险等级设为 --risk-class high 并使用相同答案时，G2 将变为 BLOCKED — blocking (skips not permitted): D3。tests/test_book_example.py 会固定此输出；请参阅 docs/book-compatibility.md。

---

清单

源自 IKI-Gov 框架五个附录部分的 25 个条目：

前缀	部分	M 维度
S1–S5	战略与业务案例	M1 战略与所有权
D1–D5	数据、法律与伦理	M2 数据质量与血缘
T1–T3	模型、安全与技术	M3 验证与公平性
T4–T5	模型、安全与技术	M4 安全与稳健性
O1–O5	运营、监控与监督	M6 运营、漂移与事件
I1–I5	ISO/IEC 42001 对照	M5 合规证据

---

评分

score_m(dim) = sum(weight_i for affirmed items in dim)
               / sum(weight_i for non-skipped items in dim) × 100

overall = arithmetic mean(M1, M2, M3, M4, M5, M6)

风险类别乘数：low = 1.0 · medium = 1.5 · high = 2.0。 跳过的条目不计入分子和分母（保守处理）。

---

阶段关卡

阶段关卡	生命周期转换
G0	上下文 → 概念设计
G1	概念设计 → 开发
G2	开发 → 批准
G3	批准 → 运营
G4	运营 → 调整
G5	调整 → 停用

状态： OPEN（全部确认） · PARTIAL（部分跳过，未拒绝任何项） · BLOCKED（≥1 项被拒绝）

考虑风险类别的阈值（v0.3.0）

如何处理跳过项取决于当前风险类别：

风险类别	跳过的阶段关卡关键条目
low	予以豁免——存在跳过项但没有拒绝项的阶段关卡为 OPEN
medium	可容忍——在这些条目得到确认之前，阶段关卡为 PARTIAL
high	不允许——跳过项会使阶段关卡 BLOCKED（默认采用严格模式）

--strict 会在任何风险类别下强制采用高风险行为。如果跳过项导致阶段关卡被阻止， 系统会单独报告（blocking_skips），以明确说明阶段关卡为何为 BLOCKED 而非 PARTIAL。

CI 退出代码

--assert-gate Gn 会根据状态返回对应的退出代码，使流水线无需解析输出即可分支处理：

退出代码	含义
0	阶段关卡为 OPEN
2	阶段关卡为 PARTIAL
3	阶段关卡为 BLOCKED
1	一般错误（输入无效、阶段关卡不匹配）

assess 和 gate 上的 --quiet（-q）仅输出机器可读的 JSON。

---

监管内容包（v0.16.0）

ISO/IEC 42001 和 EU AI Act 映射采用版本化的内容包，并由通用覆盖引擎提供支持，因此新增框架只需作为数据添加：

iga content-list                              # built-in + external packs (versions, hashes)
iga framework-gap --framework iso42001 --affirm S1,S2,D1
iga framework-gap --framework euaiact --risk-class high --affirm S1,S2,D5 --quiet
iga framework-gap --framework nist-ai-rmf --affirm S1,S2,S3   # NIST AI RMF (Govern/Map/Measure/Manage)

内容包会将每个目标（条款/条文）映射到可作为其证据的清单条目或阶段关卡。 将 JSON 内容包放入 IGA_CONTENT_PATH（或 ~/.iga/content/）即可添加或覆盖框架；如果外部内容包与内置内容包具有相同的 framework_id，则以外部内容包为准。旧版 iso-gap / euaiact-gap 命令保持不变。

ISO/IEC 42001 覆盖情况

iga iso-gap 会将评估映射到 ISO/IEC 42001 条款级覆盖情况。每个条款组（第 4–10 条及附录 A 控制措施）都会报告为已覆盖（所有映射的清单条目均已确认）、部分覆盖或存在缺口，并列出覆盖不完整条款中尚未完成的条目：

ISO/IEC 42001 Coverage Gap Analysis — fraud-scoring  [risk: HIGH]

  4   Context of the organization      PARTIAL    (1/2)  — Outstanding items: S4
  5   Leadership                       COVERED    (4/4)
  8   Operation                        GAP        (0/13) — Outstanding items: D1, D2, …
  A   Annex A (Controls)               GAP        (0/12) — Outstanding items: …

跳过和拒绝的条目均视为未确认（不计入覆盖）。条目→条款矩阵源自 IKI-Gov 定位表 （tab:framework-iso42001-matrix），并集中定义在 checklist.ISO_CLAUSES_BY_ITEM 中。 使用 --quiet 可输出机器可读的 JSON。

---

EU AI Act（高风险系统）

iga euaiact-gap 会将阶段关卡就绪情况映射到 EU AI Act 对高风险系统的义务（第 9–18 条，以及上市后监控第 72 条）。根据生成相应证据的阶段关卡的就绪情况，每条条文都会报告为 OPEN / PARTIAL / BLOCKED：

EU AI Act High-Risk Compliance Gap — fraud-scoring  [risk: HIGH]

  Art. 9   Risk management system     G0, G1, G2, G4   PARTIAL  — G2 BLOCKED, G4 BLOCKED
  Art. 10  Data and data governance   G1               OPEN
  Art. 11  Technical documentation    G2, G3           BLOCKED  — G2/G3 BLOCKED

阶段关卡→条文映射根据 IKI-Gov 手册逐字转录 （tab:framework-euaiact-gates，并根据 2026 年 10 月的校样更正：G4 引用第 9 条及第 72 条，G5 引用第 18 条和第 17 条），并存放于 euaiact.EU_AI_ACT_ARTICLE_GATES。 该命令仅适用于高风险系统（对低风险/中风险系统会返回警告）；--quiet 会输出 JSON。

此工具不构成法律建议或合规性评估。

---

持久化与组合

iga assess --save 会将评估结果持久化到本地 SQLite 数据库 ~/.iga/assessments.db（可通过 IGA_DB_PATH 环境变量覆盖）。组合命令可跨已保存的用例运行：

命令	用途
iga list	列出所有已保存评估的表格（用例、风险、总体结果、时间戳）
iga portfolio	汇总每个用例最新评估的 M1–M6 平均值和总体成熟度，并统计各关卡处于 BLOCKED 状态的用例数量
iga trend --use-case X	显示两个已保存运行结果之间的各维度变化（▲/▼/=）、总体成熟度变化和关卡状态转换（最新与上一次运行的对比，或 --from/--to 时间范围）
iga delete --use-case X	永久删除某个用例的所有已保存评估

list 和 portfolio 支持使用 --quiet 输出 JSON。数据库只会存储你提供的内容（用例名称、风险类别、语言、答案/分数/关卡）；数据库文件会以 0600 权限创建，~/.iga 目录则会以 0700 权限创建。delete 会永久删除数据；不会保留软删除日志。

---

外部证据

声明可由对等的 presidio-hardened-* 控制项（首个生成方：presidio-hardened-ai）发出的签名证据提供支持，从而将项目从自我声明升级为有证据支持，或通过本地信任库进行密码学验证。验证采用失败即关闭策略：缺失、格式错误或签名错误都不会被视为已验证。

# Affirm items from an evidence document, verifying signatures against a trust store
iga assess --use-case "fraud-scoring" --risk-class high \
    --evidence evidence.json --trust trust.json

# Fail-closed: ONLY items whose reference verifies against --trust count.
# Bare --affirm / wizard answers are recorded as "asserted" and do not count.
iga assess --use-case "fraud-scoring" --risk-class high \
    --affirm S1,S2 --evidence evidence.json --trust trust.json --require-evidence

# Verify a document on its own (exit 0 only if every reference verifies)
iga verify-evidence --evidence evidence.json --trust trust.json

--require-evidence 表示仅接受证据（v0.26.0）

所有需要答案的命令均可使用 --require-evidence：assess、 gate、report、export、certify、framework-gap、iso-gap、euaiact-gap、 classify assess，以及 iga_assess_with_evidence MCP 工具。启用该标志后，只有 --evidence 中的引用通过 --trust 验证的项目才会被计为肯定。没有此类引用的 --affirm（或向导）答案属于已声明：系统会记录该答案、在 stderr 中列出其名称、 在每种输出中显示为 asserted (not counted)，并且不会将其计入分数或关卡。若未提供 --evidence、未提供 --trust、信任存储为空、签名者未知、密钥错误或签名遭篡改，则 没有任何内容能通过验证，也不会有任何内容被计入。跳过的项目仍保持跳过状态。

在 v0.26.0 之前，此标志仅筛选 --evidence 输入。 单独的 --affirm 仍会计入， 且未提供 --evidence 时根本不会读取此标志，因此对全部 25 个项目运行 --require-evidence --trust '{}'，会报告 100 %，且每个关卡都为 OPEN。参见 SECURITY.md 和 CHANGELOG.md（0.26.0，Security）。

现在，无论由哪些标志生成，每种输出都会标记各个项目：每条已肯定和已声明的记录始终包含 单项 provenance（self | evidence | evidence-verified）；JSON 包含 answers.asserted 和 evidence_coverage （require_evidence、asserted_not_counted）；关卡和差距 JSON 包含 evidence 区块； Markdown 报告在分数下方有 Evidence 列和摘要行；签名导出清单也会在签名字节中包含 相同的 evidence 区块，因此数据包本身会说明其数字所依据的内容。

证据文档是生成方提供的 EvidenceRef JSON：

{
  "schema": "presidio-hardened/evidence-ref@1",
  "use_case": "fraud-scoring",
  "evidence": [
    {
      "item_id": "D1",
      "source": "presidio-hardened-ai",
      "source_version": "0.2.0",
      "ledger_ref": "pai-ledger:seq/0",
      "content_hash": "abc123def456",
      "signer": "presidio-hardened-ai",
      "signature": "2e7af6d2…",
      "claimed_at": "2026-06-08T00:00:00+00:00"
    }
  ]
}

信任存储将每位签名者映射到其密钥。条目可以是裸 HMAC 密钥（向后兼容），也可以是 声明算法和密钥材料的对象：

{
  "presidio-hardened-ai": "shared-hmac-secret",
  "peer-control": { "alg": "ed25519", "public_key": "<64-hex-char public key>" }
}

轮换密钥时，public_key（或 HMAC 的 key）可以是一个列表——如果签名与列表中 任一密钥匹配，就能通过验证，因此在重叠窗口期间，新密钥可以与旧密钥并行使用；移除存储 中的密钥即可撤销：

{
  "peer-control": { "alg": "ed25519", "public_key": ["<new public key>", "<retiring key>"] }
}

Ed25519（RFC 8032）公钥验证让验证方只需持有公钥（无需与生成方共享密钥），且需要 [crypto] 额外依赖。签名针对规范化的 {content_hash, signer} 消息生成；签名者密钥仅从 本地信任存储解析（不使用网络）。证据引用包含哈希和不透明的账本 URI，绝不包含个人身份 信息（PII）。由于该消息不包含项目名称，因此将一条已签名引用用于多个项目时，所有项目 都无法通过验证：每份证据仅支持一个项目。

与更广泛套件的关系： ikigov-assess 是治理的主干，用于使用来自同级 presidio-hardened-* 控制项的证据。跨仓库概览（该系列如何协同运作以及端到端演示）请参阅 presidio-hardened-* 套件架构 （位于 presidio-hardened-ai 中）。

---

Gate 证书（v0.23.0）

Gate 证书（presidio-hardened/gate-certificate@1）让证书本身成为证明。如今，Gate 决策（OPEN / PARTIAL / BLOCKED）之所以可信，是因为它由 iga 计算得出。证书则颠倒了这一点：它是一种紧凑的签名制品，任何第三方都可以针对信任存储在本地验证，无需运行 ikigov-assess，也无需使用评估数据库——这与集中式策略决策点（Cedar / Zanzibar 类）形成对比；在后者中，判定之所以可信，是因为服务返回了该结果。这是计算法理学项目的产品化形式（Stantchev，arXiv 2026）：本地验证、信任链路中不包含引擎、默认失败关闭。

证书包含自身的依据：充分肯定集合（对每个 Gate 项分别记录 affirmed / skipped / denied）、任何内嵌的 evidence-ref 原文，以及决策谓词输入——Gate 的项目 ID、风险类别、生效的严格标志和谓词内容哈希——因此，验证者仅凭证书即可重新计算决策，并将其与声明进行比较。

# Emit a signed gate certificate after evaluating a gate
iga certify --gate G2 --use-case "fraud-scoring" --risk-class high \
    --affirm S1,S2,D1,D2,D3,D4,D5,T1,T2,T3 \
    --evidence evidence.json --trust trust.json \
    --issuer "presidio-assessor" --sign-alg ed25519 \
    --sign-key-file issuer.key --output cert.json

# Verify locally against a trust store — no DB, no engine, fail-closed
iga verify-certificate --certificate cert.json --trust trust.json

向 iga certify 提供 --evidence 时，必须同时提供 --trust，且每个 evidence-ref 都必须通过验证后才能嵌入；任何一个 ref 验证失败都会中止签发。随后，验证会独立执行五项检查，每项都有不同的失败原因： 未知架构 → unknown-schema；签发者签名（分离式签名，针对证书去掉 signature 字段后的规范化字节）→ bad-signature / unknown-issuer；谓词身份 → predicate-content-mismatch；根据验证者的信任存储重新验证每个内嵌的 evidence-ref → evidence-ref-failure；以及根据内嵌的谓词输入重新计算决策，并与声明比较 → decision-mismatch。验证只读取证书和信任存储。

规范化与签名沿用 evidence-ref 和 workshop manifest 所使用的系列约定：规范 JSON 为 UTF-8 编码的 json.dumps(sort_keys=True, separators=(",", ":"), ensure_ascii=False)，并使用 SHA-256 计算哈希；签发者签名使用 HMAC-SHA256 或 Ed25519（RFC 8032），并从与 evidence-ref 相同的信任存储结构中解析。

声明范围（不夸大其词）： Gate 证书证明，在声明的谓词以及内嵌的肯定集合 / 证据条件下，Gate 决策重新计算后与声明值一致。它并不能证明底层控制措施有效，也不能证明证据所述的现实世界主张属实。

血缘、有效期、依据与等级（v0.26.0）

四个新增的可选字段，均位于已签名内容中，因此 v0.26.0 之前的证书仍可照常验证：

• parents（--parent <hex>，可重复）——ADR-0002 溯源父项：此决策所依据证据的内容哈希，通常是 eai-classification@1 文档和研讨会清单。该字段包含在签名中，因此签发后无法改写血缘；它通过构造确保无环；为空时省略。解析父项由使用方负责，而非验证器。
• not_after（--valid-days N）——有效期上限。此格式有意仅通过过期来撤销：没有撤销列表、累加器或协调机制。超过有效期后，验证器会失败关闭（expired）；verify-certificate --at <UTC> 可按指定时刻验证，使检查可复现。未设置上限则永不过期。
• grounding——确认项集合中最弱的依据等级：如果任何已确认的门槛项都没有内嵌证据引用，则为 self，否则为 evidence-verified。由具名签署者进行自我证明，并不代表已证明的等级，而是一种未绑定的声明。验证器会重新计算该值（grounding-mismatch），并且 --min-grounding evidence-verified 会对任何自我证明项失败关闭（grounding-below-minimum）。
• 保障等级——证据文档现在可以是 evidence-ref@2（presidio-evidence ADR-0003）；引用声明的 assurance_tier（attested | optimistic | zk，默认值为 attested）仅在 @2 下有效，并会原样保留在证书中。这是一项声明：验证器会重新检查引用的签名，但不会验证欺诈证明或 zk 证明；它会报告所声明的最弱等级，因此 --min-evidence-tier 可以要求最低等级（evidence-tier-below-minimum）；没有内嵌引用的证书也无法满足该最低等级要求（no-evidence-for-tier-floor）。证书自身的 assurance_tier 只能是 attested；声明任何其他等级的证书都会被拒绝（unsupported-assurance-tier），从而避免将未来的 zk 门槛证书误认为是此验证器能够检查的证书。

证书标识（v0.29.0）

certificate_content_hash(cert) 返回证书的标识：对签发者签名所用的规范字节（去掉 signature 后的文档）计算 SHA-256，并以小写十六进制表示。下游载荷会根据家族证据契约，将此哈希放入其 parents 中，以标识准许其通过的门槛决策。该哈希不包含签名块，因此重新签名后哈希不变；任何签名内容的改动都会改变哈希。framework_content_hash 用于标识其下所有证书共享的门槛规则，不是父项。该标识不说明证书是否有效；请先验证证书。

from presidio_ikigov_assess.certificate import certificate_content_hash, verify_certificate

result = verify_certificate(cert, trust)
if result.ok:
    parent = certificate_content_hash(cert)

---

MCP 服务

该评估引擎也可作为 模型上下文协议 服务使用，让兼容 MCP 的大模型 Agent 和客户端能够将 IKI-Gov 评估作为工具运行。

# Install with the MCP extra (requires Python 3.10+ and the mcp 2.x SDK)
pip install "presidio-hardened-ikigov-assess[mcp]"

# Run the server over stdio
iga-mcp

它已列入 MCP Registry，名称为 io.github.presidio-v/presidio-hardened-ikigov-assess；注册表客户端可通过 uvx --from "presidio-hardened-ikigov-assess[mcp]" presidio-hardened-ikigov-assess 启动它，该命令运行的服务与 iga-mcp 相同。

在 MCP 客户端（例如 Claude Desktop）中添加以下配置即可注册：

{
  "mcpServers": {
    "iki-gov-assess": {
      "command": "iga-mcp"
    }
  }
}

工具

工具	用途
iga_framework_info	描述模型：生命周期阶段、维度 M1–M6、关卡 G0–G5、章节、风险类别（de/en）
iga_list_checklist	返回全部 25 项检查清单条目，包含 ID、文本、维度、关卡和章节
iga_assess	根据已确认/跳过的条目 ID 评估用例 → M1–M6 得分、整体成熟度、关卡就绪情况
iga_assess_with_evidence	根据签名的 EvidenceRef 文档评估用例，并通过信任库验证签名（HMAC 或 Ed25519）
iga_check_gate	评估单个关卡 G0–G5 的就绪情况，并列出阻塞/跳过的条目
iga_iso_gap	将已确认的条目映射至 ISO/IEC 42001 条款覆盖情况（已覆盖 / 部分覆盖 / 存在差距）
iga_euaiact_gap	映射至《欧盟 AI 法案》第 9–18、72 条高风险义务（OPEN / PARTIAL / BLOCKED）

所有工具共用 CLI 的输入验证和输出清理，返回与 iga report --format json 相同的结构化 JSON 架构，并遵循每个会话的滥用防护机制（超出限制时返回工具错误，而非终止服务）。

---

证据包导出（v0.15.0）

导出签名的、可供审计的评估包，并在之后进行验证：

# Write report.md + report.json + manifest.json (sha256 of each artifact + framework hash).
# Seal the manifest with an HMAC key read from a file (kept off argv / shell history).
iga export --use-case fraud-scoring --risk-class high --affirm S1,S2,D1 \
    --bundle audit/fraud-scoring/ --sign-key-file ~/.iga/seal.key

# Re-hash artifacts against the manifest (and check the optional HMAC seal).
iga verify-bundle --bundle audit/fraud-scoring/ --sign-key-file ~/.iga/seal.key

manifest.json 会对每个工件进行内容哈希，并记录一个 framework_content_hash，用于固定生成评估结果的检查清单及 ISO/欧盟 AI 法案映射，因此后续的任何修改都会被 verify-bundle 检测到。使用 --zip 生成 .zip 文件。（PDF 渲染和公钥清单签名暂缓实现；哈希清单 + 可选 HMAC 密封是完整性基线。）

密封密钥依次从 --sign-key-file <path>（首选）、--sign-key <key>（内联；请避免使用——密钥会显示在 shell 历史记录和进程列表中），然后是 $IGA_SIGN_KEY 环境变量中读取。export 和 verify-bundle 必须使用同一来源。

分类器桥接（eai-classification/v1）

v0.20.0 — 企业 AI 分类框架与 IKI-Gov 评估引擎之间，与生成方无关的互操作层。

该桥接接受任何符合 eai-classification/v1 架构的生成方所提供的文档——包括研究用 eai-classificator 工具、合作伙伴调查工具，或手工编写的 JSON。该架构以模型为基础（6×6 矩阵：类型 T1–T6 × 自主级别 L1–L6），而非以任何特定工具的输出格式为基础。

分类文档示例

{
  "schema": "eai-classification/v1",
  "producer": {"tool": "eai-classificator", "version": "1.0.0"},
  "use_cases": [
    {
      "id": "fraud-scoring",
      "type": "T1",
      "level": "L4",
      "name": {"de": "Betrugserkennung", "en": "Fraud Scoring"},
      "confidence": 0.92,
      "tags": ["finance", "high-risk"]
    },
    {
      "id": "customer-chat",
      "type": "T4",
      "level": "L3",
      "ecosystem": true
    }
  ]
}

L6 / 生态系统机制： L6 级别是非序数的生态系统/多系统协调叠加层。在任何 L1–L5 用例上设置 "ecosystem": true，表示其参与多系统协调机制——解析器会将有效单元格级别标准化为 L6，并保留 base_level 作为记录。 level=L6 与 ecosystem=false 同时出现时构成矛盾，将被拒绝。

导入分类文档

# Human table: use case, cell, risk presumption, strict, obligations, note
iga classify ingest --file classification.json --lang de

# Machine JSON: includes pack content_hash and producer echo
iga classify ingest --file classification.json --quiet

根据分类文档运行配置评估

# Resolve the selected use case's profile, then run the full assess pipeline
iga classify assess \
    --file classification.json \
    --select fraud-scoring \
    --affirm S1,S2,D1,D2,T1 \
    --lang de \
    --quiet \
    --save

# The profile's risk_class and strict flag are pre-set from the classification
# pack. --strict may further tighten; profile strict=true cannot be loosened.

classify assess 命令会复用完整的现有处理流程（compute_scores、evaluate_all_gates、render_json、store.save_assessment、log_security_event），并记录 iga-classify-assess 安全事件，其中包括单元格 ID 和配置包的 content_hash。

分类配置包覆盖

内置包（eai-classification-default，DRAFT 语义）会自动加载。若要覆盖它，请将带有 "pack_kind": "classification-profile" 的 JSON 文件放入 IGA_CONTENT_PATH（默认为 ~/.iga/content/）。该文件必须涵盖全部 36 个单元格；若包的 framework_id 相同，则会覆盖内置包。

{
  "pack_kind": "classification-profile",
  "framework_id": "eai-classification-default",
  "version": "my-org-1.0",
  "profiles": {
    "T1.L1": {"risk_presumption": "low", "strict": false,
               "obligations": ["iso42001", "euaiact"],
               "notes": {"en": "Minimal oversight required."}},
    "T1.L2": { "..." : "..." }
  }
}

ContentPacks（监管框架差距映射）与 ProfilePacks 可共存于同一目录；加载器会根据 pack_kind 区分二者。

面向外部生产方的 JSON Schema

schemas/eai-classification.v1.schema.json（仓库根目录）提供了一份 JSON Schema draft/2020-12 定义，合作方生产方可用它进行发布前验证。Python 解析器 classification.py 是权威来源；jsonschema 并非项目声明的依赖项。

---

Workshop Mode（T-B3/T-B4）

iga workshop run 是实时的客户研讨会工具：在连接投影仪的笔记本电脑上运行此命令，指定一份分类文档，它便会以大幅面、高对比度的富文本输出呈现每个用例，同时将每个用例的交付材料（“Übergabeunterlage”）写入磁盘。整个流程（投影呈现加材料生成）目标为每个用例耗时不足 2 分钟。从 v0.22.0 开始，建议采用客户锚定的保管模式：客户使用在自有硬件上生成的密钥为清单签名，presidio 则以评估方身份在单独的证明文档中共同签名。

支持离线运行

Workshop Mode 专为与外界隔离的客户现场而设计。它会明确绕过启动时的 CVE／依赖项检查（pip-audit 需要网络访问；在隔离现场运行时会卡住、超时，并发出嘈杂的“无法得出结论”警告）。检测到 workshop 子命令时会自动绕过依赖项检查；无需添加 --no-dep-check 标志。通过在会议前于创始人的计算机上运行 pip-audit，维持安全防护水平。

示例

# Generate leave-behind artifacts for all use cases in a classification document,
# in German (default), writing to ./workshop-out/<date>/.
iga workshop run \
    --file classification.json \
    --lang de

# Generate for selected use cases only.
iga workshop run \
    --file medical.json \
    --select infusion-pump-dosing \
    --select surgical-robotics \
    --out /tmp/workshop-2026/

# Pre-populate answers (assessor filled a form earlier).
iga workshop run \
    --file classification.json \
    --answers answers.json

# Quiet: write artifacts only, no projector output.
iga workshop run --file classification.json --quiet

answers.json 格式如下：

{
  "fraud-scoring": {
    "affirm": ["S1", "S2", "S3", "D1", "D2"],
    "skip":   ["I4", "I5"]
  }
}

每个用例的材料布局

workshop-out/<date>/<use_case_id>/
  report.de.md       Markdown leave-behind (localised)
  report.json        Full assessment JSON + classification provenance block
  sign.py            Standalone customer owner signer
  SIGNING.md         Bilingual signing-ceremony runbook
  assessor.pub       Presidio assessor public key, when supplied/derived
  manifest.json      Content-hashed manifest (presidio-hardened/workshop-leavebehind@1)
  manifest.sig       Ed25519 detached signature (UNSIGNED marker if no key provided)
  attestation.json   Optional presidio assessor attestation envelope
  attestation.content.json

manifest.json 记录：工具版本、单元格 ID、风险类别、语言、配置包内容哈希、每份材料的 SHA-256，以及材料是否已签名。

客户所有者签名与 presidio 证明

在客户硬件上生成客户所有者密钥对。私钥以 0600 模式创建；仅将公钥交给 presidio，以加入本次合作的信任库：

iga workshop keygen --out customer-key.hex --signer "ACME GmbH"

iga workshop run 写入交付材料后，客户以所有者身份为清单签名：

iga workshop sign \
    --dir workshop-out/2026-07-04/infusion-pump-dosing/ \
    --key customer-key.hex \
    --signer "ACME GmbH"

随后，Presidio 以评估方身份对客户签名的清单共同签名。该证明是单独的 workshop-attestation@1 证据文档，并绑定到清单哈希：

iga workshop attest \
    --dir workshop-out/2026-07-04/infusion-pump-dosing/ \
    --engagement hc-workshop-2026-001 \
    --sign-key ~/.iga/workshop-assessor.key \
    --signer presidio-hardened-ikigov-assess

验证交付材料（客户侧）

客户验证其所有者签名，并在需要时验证 presidio 评估方证明：

# Verify the artifact in the infusion-pump-dosing/ directory.
iga workshop verify \
    --dir workshop-out/2026-07-04/infusion-pump-dosing/ \
    --pubkey <customer-public-key>

# Require a valid presidio attestation bound to the manifest.
iga workshop verify \
    --dir workshop-out/2026-07-04/infusion-pump-dosing/ \
    --pubkey <customer-public-key> \
    --require-attestation \
    --attestation-pubkey <presidio-assessor-public-key>

# Machine-readable JSON result.
iga workshop verify \
    --dir workshop-out/2026-07-04/infusion-pump-dosing/ \
    --pubkey <customer-public-key> \
    --quiet

如果所有材料哈希和签名均通过验证，则退出码为 0；否则为 1（失败关闭）。未签名的交付材料也会验证失败，因为仅哈希匹配无法证明文件由谁生成；传入 --allow-unsigned 可仅接受哈希一致性。只有在签名验证通过时，JSON 结果中的 authenticated 才为 true。

命名委托链（v0.23.0）

客户签名 → 清单哈希 → presidio 证明这一谱系以显式的委托链形式呈现：由一系列有序的命名链接组成，每个链接都说明其 role、signer、所签名的内容 signs，以及其引用的哈希 reference。--show-chain 会逐个检查链中的链接，并为每个链接提供不同的失败原因（owner-sig-invalid、owner-key-mismatch、assessor-missing-key，以及所有证明原因，例如 attests-manifest-mismatch）；--require-chain 还会在不存在所有者链接时失败关闭。此功能仅为增补且由现有数据派生——验证时会根据现有所有者区块、manifest.sig 和证明组装委托链，因此 v0.23.0 之前生成的清单（不含链）仍可照常验证。

iga workshop verify \
    --dir workshop-out/2026-07-04/infusion-pump-dosing/ \
    --pubkey <customer-public-key> \
    --attestation-pubkey <presidio-assessor-public-key> \
    --show-chain --quiet

---

安全性

完整的安全策略请参见 SECURITY.md。

工具内置的安全控制：

• 对所有 CLI 参数进行输入验证（类型、范围、允许列表）
• 对报告输出中所有用户提供的字符串进行 HTML 转义
• 在 ~/.iga/security.log 中记录结构化安全事件日志（不记录内容，仅记录结构化元数据）
• 启动时通过 pip-audit 检查 CVE（使用 --no-dep-check 禁用；iga --version 会跳过检查，因此可离线查看已安装版本）
• 会话速率限制（默认：100 次评估；可通过 IGA_MAX_ASSESSMENTS 覆盖）

项目供应链：OpenSSF Best Practices 银级认证和 OpenSSF Scorecard（当前评分见顶部徽章）。对 main 的更改需要另一位审阅者批准；发布标签均已签名；每次发布都会通过 OIDC Trusted Publishing 发布到 PyPI，并附带来源证明和 CycloneDX SBOM；解析器经过模糊测试（Atheris）。

---

路线图

版本	主题	状态
v0.1.0	MVP — 交互式与参数驱动评估、M1–M6 评分、双语	已发布
v0.2.0	MCP 服务 — Agent 可访问的评估引擎（iga-mcp）	已发布
v0.3.0	优化关卡就绪度、CI 退出码 0/2/3、--strict 标志	已发布
v0.4.0	将报告导出到文件（--output），包含各项答案	已发布
v0.5.0	ISO/IEC 42001 条款级差距映射（iga iso-gap）	已发布
v0.6.0	组合模式：持久化、list、portfolio、delete	已发布
v0.7.0	成熟度趋势：已保存运行结果之间的差异（iga trend）	已发布
v0.8.0	高风险系统的 EU AI Act 关卡→条款映射（iga euaiact-gap）	已发布
v0.13.0	基于外部证据的确认：iga assess --evidence / verify-evidence + iga_assess_with_evidence（首个证据生成方：presidio-hardened-ai）	已发布
v0.14.0	公钥（Ed25519）证据验证：信任库 {alg, public_key} 条目 + verify_ref 分发（[crypto] extra）	已发布
v0.20.0	分类器桥接（eai-classification/v1）、36 单元配置包、iga classify	已发布
v0.21.0 T-B3	iga workshop — 离线客户研讨会工具、Ed25519 签名的会后材料、workshop verify	已发布
v0.21.0 T1.4	完整的德语本地化：所有运行时输出均通过 t()，--lang de 下没有仅英文的标记	已发布
v0.22.0 T-B4	研讨会证据自主权：客户所有者签名、独立签名器、presidio 评估方证明	已发布
v0.23.0 T-B5	关卡证书：签名的 gate-certificate@1、iga certify / iga verify-certificate、签发时和验证时的证据引用验证、命名研讨会委派链	已发布
v0.24.0	维护：覆盖率引导的模糊测试（fuzz extra、Atheris）、JSON 边界处的失败关闭防护、将 mcp 限定在 2.0 以下以修复 [mcp] extra	已发布
v0.25.0	iga --version；移植到 mcp 2.x SDK（MCPServer，extra 现在需要 mcp>=2,<3）；OrgAuthMiddleware 拒绝非 HTTP ASGI 作用域，而非转发它们	已发布
v0.26.0 S-1	安全：--require-evidence 在所有位置均采用失败关闭策略；未经证实的确认标记为 asserted、予以展示但绝不计入；每种输出都会标明已提供证据 / 已声明 / 未处理	已发布
v0.26.0 T-B6	证书沿袭关系（parents、ADR-0002）、有效期（not_after）、grounding、evidence-ref@2 保证等级均会显示，并附带验证器最低要求	已发布
v0.27.0	**安全：**2026-09 审计整改（GHSA-376h-xg26-xf2j）：一条证据引用仅能验证一个条目，证书签发方绑定到签名者，限定捆绑包路径范围，设置每个组织的远程速率窗口	已发布
v0.28.0	书籍内容一致性（Anhang B）：通过测试固定的示例、修正的 [risk: …] 标头、euaiact-gap 遵循修正后的关卡→条款表（Art. 18、72）；docs/book-compatibility.md	已发布
v0.29.0	关卡证书身份采用 certificate_content_hash（ADR-0006），以便证据生成方在 parents 中注明准入关卡决策；[mcp] 需要 mcp>=2.2 才能使用远程服务	已发布
v0.29.1	**安全：**信任条目的 public_key 绝不会被用作 HMAC 密钥（GHSA-3c6h-3546-fqmm）；将 certifi、opentelemetry-api 和 filelock 锁定到高于最新公告所涉及的版本	已发布

完整版本讨论日志：PRESIDIO-REQ.md

计划中（未来 12 个月）

方向性规划；计划中或正在进行的工作，并非承诺：

• 下一步 — 扩大框架差距覆盖范围（随着实施法案陆续出台，完善 ISO/IEC 42001 并更新 EU AI Act），并增加为 assess --evidence / 关卡证书流程提供证据的生成方。
• 评估中 — 推进可复现构建和逐文件来源追踪，以满足 OpenSSF 金级标准。

---

开发

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint and format
ruff format .
ruff check . --fix

---

许可证

MIT。请参阅 LICENSE。

---

SDLC

此仓库遵循 PRESIDIO 加固系列 SDLC 的开源基线 （报告 · PDF）。 为此基线衡量的控制项及任何尚未解决的差距，详见适用性矩阵中对应的行。

---

治理、架构与安全

• 治理 — 角色、决策流程和项目延续性。
• 架构 — 组件、处理流程和信任边界。
• 保障案例 — 安全声明及其各自的证据。
• 安全政策 — 受支持的版本以及如何报告漏洞。
• 贡献指南 · 行为准则 · 版本管理