presidio-hardened-ikigov-assess

# presidio-hardened-ikigov-assess

🇬🇧 **English** · [🇩🇪 Deutsch](https://github.com/presidio-v/presidio-hardened-ikigov-assess/blob/main/README.de.md)

[![PyPI version](https://img.shields.io/pypi/v/presidio-hardened-ikigov-assess.svg)](https://pypi.org/project/presidio-hardened-ikigov-assess/)
[![Python](https://img.shields.io/pypi/pyversions/presidio-hardened-ikigov-assess.svg)](https://pypi.org/project/presidio-hardened-ikigov-assess/)
[![GitHub release](https://img.shields.io/github/v/release/presidio-v/presidio-hardened-ikigov-assess.svg)](https://github.com/presidio-v/presidio-hardened-ikigov-assess/releases)
[![Tests](https://github.com/presidio-v/presidio-hardened-ikigov-assess/actions/workflows/pytest.yml/badge.svg)](https://github.com/presidio-v/presidio-hardened-ikigov-assess/actions/workflows/pytest.yml)
[![CodeQL](https://github.com/presidio-v/presidio-hardened-ikigov-assess/actions/workflows/codeql.yml/badge.svg)](https://github.com/presidio-v/presidio-hardened-ikigov-assess/actions/workflows/codeql.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/presidio-v/presidio-hardened-ikigov-assess/badge)](https://scorecard.dev/viewer/?uri=github.com/presidio-v/presidio-hardened-ikigov-assess)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13748/badge)](https://www.bestpractices.dev/projects/13748)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

<!-- mcp-name: io.github.presidio-v/presidio-hardened-ikigov-assess -->

**IKI-Gov Assessment Tool** — operationalises the IKI-Gov-Referenzmodell (Integrated KI-Governance Reference Model) as a practical CLI tool for assessing AI use cases against a structured governance framework.

The IKI-Gov framework structures AI governance along a central lifecycle
(Kontext → Konzeption → Entwicklung → Freigabe → Betrieb → Anpassung → Außerbetriebnahme)
surrounded by six domains and measured across six dimensions (M1–M6) with six quality gates
(G0–G5).

Reference: Stantchev, V. *IKI-Gov-Referenzmodell* — Integrated KI-Governance Reference Model.

---

## The book

This tool implements the **IKI-Gov reference model**, introduced in the
Springer monograph by Vladimir Stantchev — published in two editions:

- **AI and IT Governance** (English) — Springer, Berlin; ISBN 978-3-662-74001-9; forthcoming 11 January 2027
- **KI und IT-Governance** (German) — Springer, Berlin; ISBN 978-3-662-74093-4; forthcoming 28 December 2026

The book works from classical IT governance (COBIT, ITIL, ISO/IEC 38500) toward AI
governance across ethics, law, risk, and data, then assembles IKI-Gov: the lifecycle,
six domains, six measurement dimensions (M1–M6), and six quality gates (G0–G5). The 25
checklist items scored here are drawn from the book's framework chapter and its
workshop/approval-gate appendix; the ISO/IEC 42001 and EU AI Act mappings follow its
orientation tables.

The book presents the model as a reasoned synthesis and a working heuristic for
orientation — not legal advice and not a conformity assessment. This tool holds the same
line (see the disclaimers on the `euaiact-gap` and `iso-gap` commands). Both editions are
now available for preorder from Springer (Berlin); the Springer catalogue page and DOI
will be added here once live.

---

## Installation

```bash
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]"
```

---

## Quick Start

```bash
# 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
```

### Example output

The worked example from the book (Anhang B, corrected proof), at a 100-column terminal:

```bash
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…)
```

The same answers at `--risk-class high` turn G2 into `BLOCKED — blocking (skips not permitted): D3`. `tests/test_book_example.py` pins this output; see [docs/book-compatibility.md](docs/book-compatibility.md).

---

## Checklist

25 items derived from the five appendix sections of the IKI-Gov framework:

| Prefix | Section | M-Dimension |
|--------|---------|-------------|
| S1–S5 | Strategie & Geschäftsfall | M1 Strategie & Ownership |
| D1–D5 | Daten, Recht & Ethik | M2 Datenqualität & Lineage |
| T1–T3 | Modell, Sicherheit & Technik | M3 Validierung & Fairness |
| T4–T5 | Modell, Sicherheit & Technik | M4 Sicherheit & Robustheit |
| O1–O5 | Betrieb, Monitoring & Aufsicht | M6 Betrieb, Drift & Vorfälle |
| I1–I5 | ISO/IEC 42001 Abgleich | M5 Compliance-Nachweise |

---

## Scoring

```
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)
```

Risk-class multipliers: `low` = 1.0 · `medium` = 1.5 · `high` = 2.0.
Skipped items are excluded from both numerator and denominator (conservative).

---

## Gates

| Gate | Lifecycle transition |
|------|---------------------|
| G0 | Kontext → Konzeption |
| G1 | Konzeption → Entwicklung |
| G2 | Entwicklung → Freigabe |
| G3 | Freigabe → Betrieb |
| G4 | Betrieb → Anpassung |
| G5 | Anpassung → Außerbetriebnahme |

**Status:** **OPEN** (all affirmed) · **PARTIAL** (some skipped, none denied) · **BLOCKED** (≥1 denied)

### Risk-class-aware thresholds (v0.3.0)

How skips are treated depends on the active risk class:

| Risk class | Skipped gate-critical items |
|------------|-----------------------------|
| `low` | forgiven — a gate with skips but no denials is **OPEN** |
| `medium` | tolerated — the gate is **PARTIAL** until they are affirmed |
| `high` | not permitted — skips **BLOCK** the gate (strict by default) |

`--strict` forces high-risk behaviour at any risk class. When a skip blocks a gate,
it is reported separately (`blocking_skips`) so the reason for a BLOCKED-not-PARTIAL
gate is explicit.

### CI exit codes

`--assert-gate Gn` exits with a status-specific code so pipelines can branch without
parsing output:

| Exit code | Meaning |
|-----------|---------|
| `0` | gate OPEN |
| `2` | gate PARTIAL |
| `3` | gate BLOCKED |
| `1` | general error (invalid input, gate mismatch) |

`--quiet` (`-q`) on `assess` and `gate` emits machine-readable JSON only.

---

## Regulatory-Content Packs (v0.16.0)

The ISO/IEC 42001 and EU AI Act mappings are versioned **content packs** behind a generic
coverage engine, so new frameworks are added as data:

```bash
iga content-list                              # built-in + external packs (versions, hashe