admina-framework 0.9.0__py3-none-any.whl

admina/domains/compliance/cross_regulation.py

@@ -0,0 +1,314 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Admina — cross-regulation control matrix (base).
+
+A small, hand-curated mapping that shows which common operational
+controls satisfy obligations across the three frameworks Admina
+already covers in OSS: EU AI Act, NIS2, GDPR.
+
+The matrix is **base coverage only** — twelve controls that show up
+in essentially every operational compliance program. Full
+sector-specific mappings (ISO 27001 ↔ NIS2 ↔ AI Act, NIST AI RMF ↔
+ISO 42001, etc.) are out of scope for this release. Contributions
+are welcome (see CONTRIBUTING.md).
+
+Use cases:
+  - Show "if you implement X, you also satisfy obligations from N
+    different regulations" so the operator can plan once and report
+    multiple times.
+  - Drive a simple consolidated checklist in the dashboard.
+  - Power the JSON / CSV / Markdown export for stakeholders that
+    want to see all three regimes at a glance.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Each entry: control id → {title, description, mappings}
+# `mappings` is keyed by regulation; value is a short list of
+# article references AND a one-liner explaining the link.
+CROSS_REGULATION_MATRIX: dict[str, dict[str, Any]] = {
+    "risk_assessment": {
+        "title": "Documented risk assessment",
+        "description": (
+            "Periodic identification, evaluation and prioritisation of "
+            "risks to the organisation's data, systems, and (where "
+            "applicable) AI outputs."
+        ),
+        "mappings": {
+            "eu_ai_act": [
+                {"ref": "Art. 9", "note": "Risk management system for high-risk AI"},
+            ],
+            "nis2": [
+                {"ref": "Art. 21(2)(a)", "note": "Risk analysis and security policy"},
+            ],
+            "gdpr": [
+                {"ref": "Art. 35", "note": "DPIA when processing is likely to result in high risk"},
+                {"ref": "Art. 32(1)", "note": "Security appropriate to risk"},
+            ],
+        },
+    },
+    "incident_handling": {
+        "title": "Incident detection, response, and reporting",
+        "description": (
+            "Documented incident handling: detection, classification, "
+            "internal response, post-mortem, regulator notification "
+            "where required."
+        ),
+        "mappings": {
+            "eu_ai_act": [
+                {"ref": "Art. 62", "note": "Reporting of serious incidents"},
+            ],
+            "nis2": [
+                {"ref": "Art. 21(2)(b)", "note": "Incident handling"},
+                {"ref": "Art. 23", "note": "24h early warning + 72h notification + 1-month report"},
+            ],
+            "gdpr": [
+                {"ref": "Art. 33", "note": "Personal data breach notification within 72h"},
+                {"ref": "Art. 34", "note": "Communication to data subjects"},
+            ],
+        },
+    },
+    "encryption_in_transit_and_at_rest": {
+        "title": "Encryption in transit and at rest",
+        "description": "TLS for transport, encryption-at-rest for stored data.",
+        "mappings": {
+            "eu_ai_act": [
+                {"ref": "Art. 15(4)", "note": "Cybersecurity of high-risk systems"},
+            ],
+            "nis2": [
+                {"ref": "Art. 21(2)(h)", "note": "Cryptography policies and procedures"},
+            ],
+            "gdpr": [
+                {"ref": "Art. 32(1)(a)", "note": "Pseudonymisation and encryption"},
+            ],
+        },
+    },
+    "access_control_mfa": {
+        "title": "Access control + MFA for privileged operations",
+        "description": (
+            "Role-based access control, MFA for admin and remote "
+            "access, joiner/mover/leaver process."
+        ),
+        "mappings": {
+            "eu_ai_act": [
+                {"ref": "Art. 15(4)", "note": "Cybersecurity measures"},
+            ],
+            "nis2": [
+                {"ref": "Art. 21(2)(i)", "note": "Access control + asset management"},
+                {"ref": "Art. 21(2)(j)", "note": "Multi-factor authentication"},
+            ],
+            "gdpr": [
+                {"ref": "Art. 32(1)(b)", "note": "Confidentiality and integrity"},
+            ],
+        },
+    },
+    "logging_and_audit_trail": {
+        "title": "Tamper-evident logging and audit trail",
+        "description": (
+            "Append-only event log with chain integrity (hashes or "
+            "signatures), enabling after-the-fact reconstruction of "
+            "decisions and access."
+        ),
+        "mappings": {
+            "eu_ai_act": [
+                {"ref": "Art. 12", "note": "Record-keeping for high-risk systems"},
+            ],
+            "nis2": [
+                {"ref": "Art. 21(2)(b)", "note": "Incident handling — supports investigation"},
+            ],
+            "gdpr": [
+                {"ref": "Art. 30", "note": "Records of processing activities"},
+                {"ref": "Art. 5(2)", "note": "Accountability principle"},
+            ],
+        },
+    },
+    "data_minimisation_and_retention": {
+        "title": "Data minimisation and defined retention",
+        "description": (
+            "Collect only what is necessary; delete or anonymise when "
+            "the retention period is reached."
+        ),
+        "mappings": {
+            "eu_ai_act": [
+                {"ref": "Art. 10(3)", "note": "Quality and relevance of training/validation data"},
+            ],
+            "nis2": [],  # no direct NIS2 obligation
+            "gdpr": [
+                {"ref": "Art. 5(1)(c)", "note": "Data minimisation"},
+                {"ref": "Art. 5(1)(e)", "note": "Storage limitation"},
+            ],
+        },
+    },
+    "third_party_risk_management": {
+        "title": "Third-party / supply-chain risk management",
+        "description": (
+            "Inventory of suppliers and processors, risk assessment, "
+            "contractual security clauses, incident-notification clauses."
+        ),
+        "mappings": {
+            "eu_ai_act": [
+                {"ref": "Art. 25", "note": "Obligations along the AI value chain"},
+            ],
+            "nis2": [
+                {"ref": "Art. 21(2)(d)", "note": "Supply chain security"},
+            ],
+            "gdpr": [
+                {"ref": "Art. 28", "note": "Processor contractual obligations"},
+                {"ref": "Art. 44-49", "note": "International transfers"},
+            ],
+        },
+    },
+    "human_oversight": {
+        "title": "Human oversight of automated decisions",
+        "description": (
+            "A human reviewer can intervene, override, or audit "
+            "decisions made by an automated system."
+        ),
+        "mappings": {
+            "eu_ai_act": [
+                {"ref": "Art. 14", "note": "Human oversight of high-risk AI"},
+            ],
+            "nis2": [],
+            "gdpr": [
+                {"ref": "Art. 22", "note": "Right not to be subject to solely automated decisions"},
+            ],
+        },
+    },
+    "transparency_and_information": {
+        "title": "Transparency to end users / data subjects",
+        "description": (
+            "Users and data subjects are informed about purpose, "
+            "logic, and consequences of processing — including AI "
+            "interactions."
+        ),
+        "mappings": {
+            "eu_ai_act": [
+                {"ref": "Art. 13", "note": "Transparency for high-risk AI"},
+                {"ref": "Art. 50", "note": "Transparency for chatbots / synthetic content"},
+            ],
+            "nis2": [],
+            "gdpr": [
+                {"ref": "Art. 12-14", "note": "Information to data subjects"},
+            ],
+        },
+    },
+    "training_and_awareness": {
+        "title": "Staff training and security awareness",
+        "description": "Annual training, phishing drills, role-specific awareness.",
+        "mappings": {
+            "eu_ai_act": [
+                {"ref": "Art. 4", "note": "AI literacy"},
+            ],
+            "nis2": [
+                {"ref": "Art. 21(2)(g)", "note": "Cyber hygiene + cybersecurity training"},
+            ],
+            "gdpr": [
+                {"ref": "Art. 39(1)(b)", "note": "DPO awareness-raising / training"},
+            ],
+        },
+    },
+    "business_continuity": {
+        "title": "Business continuity and disaster recovery",
+        "description": ("Backup strategy, disaster recovery plan, regular tests."),
+        "mappings": {
+            "eu_ai_act": [
+                {"ref": "Art. 15(4)", "note": "Resilience of high-risk AI"},
+            ],
+            "nis2": [
+                {
+                    "ref": "Art. 21(2)(c)",
+                    "note": "Business continuity, backup, DR, crisis management",
+                },
+            ],
+            "gdpr": [
+                {
+                    "ref": "Art. 32(1)(c)",
+                    "note": "Ability to restore availability and access in a timely manner",
+                },
+            ],
+        },
+    },
+    "documentation_and_accountability": {
+        "title": "Documentation of decisions and accountability",
+        "description": (
+            "Documented evidence that compliance measures are in place and operate as intended."
+        ),
+        "mappings": {
+            "eu_ai_act": [
+                {"ref": "Art. 11", "note": "Technical documentation for high-risk systems"},
+            ],
+            "nis2": [
+                {"ref": "Art. 21(2)(f)", "note": "Effectiveness assessment"},
+            ],
+            "gdpr": [
+                {"ref": "Art. 5(2)", "note": "Accountability principle"},
+                {"ref": "Art. 24", "note": "Responsibility of the controller"},
+            ],
+        },
+    },
+}
+
+
+REGULATIONS: tuple[str, ...] = ("eu_ai_act", "nis2", "gdpr")
+
+
+def coverage_summary() -> dict[str, Any]:
+    """Aggregate counts that can drive a compact dashboard widget.
+
+    Returns the total number of controls and, for each regulation,
+    how many controls touch it (i.e. have at least one mapping).
+    """
+    total = len(CROSS_REGULATION_MATRIX)
+    by_reg: dict[str, int] = {r: 0 for r in REGULATIONS}
+    for ctrl in CROSS_REGULATION_MATRIX.values():
+        for reg in REGULATIONS:
+            if ctrl["mappings"].get(reg):
+                by_reg[reg] += 1
+    return {
+        "total_controls": total,
+        "regulations": list(REGULATIONS),
+        "controls_per_regulation": by_reg,
+    }
+
+
+def to_markdown() -> str:
+    """Render the matrix as a stand-alone Markdown table.
+
+    Used by the reporting export endpoint when the operator picks
+    `format=markdown`. The frontend can show the same data as an
+    HTML table without re-implementing it.
+    """
+    lines = [
+        "# Cross-regulation control matrix",
+        "",
+        "Base coverage of operational controls across EU AI Act, NIS2, and GDPR.",
+        "",
+        "| Control | EU AI Act | NIS2 | GDPR |",
+        "|---|---|---|---|",
+    ]
+    for ctrl_id, ctrl in CROSS_REGULATION_MATRIX.items():
+        cells = []
+        for reg in REGULATIONS:
+            refs = ctrl["mappings"].get(reg) or []
+            if refs:
+                cells.append(", ".join(r["ref"] for r in refs))
+            else:
+                cells.append("—")
+        lines.append(
+            f"| **{ctrl['title']}**<br/>_{ctrl_id}_ | {cells[0]} | {cells[1]} | {cells[2]} |"
+        )
+    return "\n".join(lines) + "\n"

admina/domains/compliance/eu_ai_act.py

@@ -0,0 +1,367 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Admina — EU AI Act Compliance Engine — Compliance domain
+Automated risk classification, gap analysis, and compliance reporting.
+"""
+
+import logging
+from datetime import UTC, datetime
+
+logger = logging.getLogger("admina.eu_ai_act")
+
+# ── EU AI Act application timeline (Art. 113, Regulation 2024/1689) ─────────
+# Reflects the "AI Act Omnibus" agreement reached by Council and Parliament
+# on 7 May 2026 (Omnibus VII), which postponed several high-risk deadlines
+# and added a new Art. 5 prohibition (NCII / synthetic CSAM).
+#
+# Sources:
+#   - Reg. (EU) 2024/1689 (original AI Act)
+#   - Council/Parliament press release 2026-05-07 (Omnibus VII agreement)
+EU_AI_ACT_DEADLINES: dict[str, str] = {
+    # Art. 5 prohibitions — already in force
+    "prohibitions": "2025-02-02",
+    # GPAI obligations Art. 50-55 — already in force
+    "gpai_obligations": "2025-08-02",
+    # Art. 50 transparency for synthetic content (watermarking).
+    # Omnibus reduced the grace period 6m → 3m; new effective date below.
+    "transparency_synthetic_content": "2026-12-02",
+    # NEW Art. 5 prohibition: non-consensual intimate imagery + synthetic CSAM
+    "prohibitions_ncii_csam": "2026-12-02",
+    # Annex III high-risk (employment, education, biometrics, scoring, …)
+    # Postponed from 2 Aug 2026 → 2 Dec 2027 by Omnibus VII.
+    "high_risk_annex_iii": "2027-12-02",
+    # National AI regulatory sandboxes (Art. 57)
+    # Postponed from 2 Aug 2026 → 2 Aug 2027 by Omnibus VII.
+    "national_sandboxes": "2027-08-02",
+    # Annex I high-risk (medical devices, toys, regulated products)
+    # Postponed from 2 Aug 2027 → 2 Aug 2028 by Omnibus VII.
+    "high_risk_annex_i": "2028-08-02",
+    # Latest applicable date — overall "full application" reference
+    "full_application": "2028-08-02",
+}
+
+# Primary deadline used in dashboards / countdowns / single-value APIs.
+# Annex III is the most relevant for the typical Admina user (it covers
+# employment, scoring, education, biometrics — the bulk of operational AI).
+EU_AI_ACT_ENFORCEMENT_DEADLINE: str = EU_AI_ACT_DEADLINES["high_risk_annex_iii"]
+
+
+# ── Risk Classification Keywords ─────────────────────────────────────────────
+# Source: EU AI Act Annex III + Art. 5 prohibited practices (Reg. 2024/1689,
+# as amended by the Omnibus VII agreement of 7 May 2026).
+# Update these when the Commission publishes delegated acts extending Annex III.
+
+UNACCEPTABLE_RISK_KEYWORDS = [
+    "social scoring",
+    "social credit",
+    "real-time biometric",
+    "mass surveillance",
+    "subliminal manipulation",
+    # Added by Omnibus VII (effective 2 Dec 2026):
+    "non-consensual intimate imagery",
+    "non-consensual deepfake",
+    "synthetic csam",
+    "ai-generated child sexual abuse",
+    "deepfake nudification",
+    "nudifier",
+]
+
+HIGH_RISK_KEYWORDS = [
+    "credit scor",
+    "recruitment",
+    "hiring",
+    "law enforcement",
+    "critical infrastructure",
+    "healthcare",
+    "medical",
+    "education",
+    "migration",
+    "border",
+    "judicial",
+    "biometric",
+    "financial",
+    "trading",
+    "insurance",
+]
+
+HIGH_RISK_SENSITIVE_DATA = ["health", "biometric", "financial", "criminal", "genetic"]
+
+LIMITED_RISK_KEYWORDS = [
+    "chatbot",
+    "conversational",
+    "content generation",
+    "emotion recognition",
+    "deepfake",
+    "synthetic media",
+]
+
+
+# EU AI Act Risk Categories
+RISK_CATEGORIES = {
+    "unacceptable": {
+        "level": 4,
+        "description": "Prohibited AI practices",
+        "examples": [
+            "social scoring",
+            "real-time biometric identification",
+            "manipulation of vulnerable groups",
+            "non-consensual intimate imagery / synthetic CSAM (Omnibus VII, effective 2 Dec 2026)",
+        ],
+        "action": "PROHIBITED — Must not deploy",
+    },
+    "high": {
+        "level": 3,
+        "description": "High-risk AI systems requiring conformity assessment",
+        "examples": [
+            "credit scoring",
+            "recruitment",
+            "law enforcement",
+            "critical infrastructure",
+            "healthcare diagnostics",
+        ],
+        "action": "Requires conformity assessment, logging, human oversight",
+    },
+    "limited": {
+        "level": 2,
+        "description": "Limited risk with transparency obligations",
+        "examples": ["chatbots", "emotion recognition", "deepfakes", "content generation"],
+        "action": "Must inform users they are interacting with AI",
+    },
+    "minimal": {
+        "level": 1,
+        "description": "Minimal or no risk",
+        "examples": ["spam filters", "inventory management", "video game AI"],
+        "action": "No specific obligations, voluntary codes of conduct",
+    },
+}
+
+# Compliance requirements for high-risk systems
+HIGH_RISK_REQUIREMENTS = {
+    "risk_management": {
+        "name": "Risk Management System",
+        "article": "Art. 9",
+        "checks": [
+            "Documented risk management process",
+            "Risk identification and analysis",
+            "Risk mitigation measures implemented",
+            "Residual risk assessment completed",
+        ],
+    },
+    "data_governance": {
+        "name": "Data Governance",
+        "article": "Art. 10",
+        "checks": [
+            "Training data quality measures",
+            "Data bias examination",
+            "Data provenance documentation",
+            "Privacy impact assessment",
+        ],
+    },
+    "technical_documentation": {
+        "name": "Technical Documentation",
+        "article": "Art. 11",
+        "checks": [
+            "System description and purpose",
+            "Development process documentation",
+            "Performance metrics documented",
+            "Limitations and risks documented",
+        ],
+    },
+    "record_keeping": {
+        "name": "Record Keeping / Logging",
+        "article": "Art. 12",
+        "checks": [
+            "Automatic event logging enabled",
+            "Log retention period defined (min 6 months)",
+            "Logs include traceability data",
+            "Tamper-proof logging mechanism",
+        ],
+    },
+    "transparency": {
+        "name": "Transparency",
+        "article": "Art. 13",
+        "checks": [
+            "Instructions for use provided",
+            "Capabilities and limitations documented",
+            "Human oversight measures described",
+            "Performance characteristics disclosed",
+        ],
+    },
+    "human_oversight": {
+        "name": "Human Oversight",
+        "article": "Art. 14",
+        "checks": [
+            "Human oversight interface exists",
+            "Override mechanism available",
+            "Escalation procedures defined",
+            "Monitoring dashboards operational",
+        ],
+    },
+    "accuracy_robustness": {
+        "name": "Accuracy, Robustness, Cybersecurity",
+        "article": "Art. 15",
+        "checks": [
+            "Accuracy metrics defined and monitored",
+            "Robustness testing performed",
+            "Cybersecurity measures implemented",
+            "Adversarial attack resistance tested",
+        ],
+    },
+}
+
+
+class EUAIActCompliance:
+    """
+    Automated EU AI Act compliance checking and reporting.
+    """
+
+    def __init__(self):
+        self.assessments: list[dict] = []
+
+    def classify_risk(self, system_description: str, use_case: str, data_types: list[str]) -> dict:
+        """
+        Classify an AI system's risk level under the EU AI Act.
+        """
+        description_lower = system_description.lower()
+        use_case_lower = use_case.lower()
+
+        # Check for unacceptable risk indicators
+        if any(
+            kw in description_lower or kw in use_case_lower for kw in UNACCEPTABLE_RISK_KEYWORDS
+        ):
+            return {
+                "risk_category": "unacceptable",
+                **RISK_CATEGORIES["unacceptable"],
+            }
+
+        # Check for high-risk indicators
+        high_risk_score = 0
+        if any(kw in description_lower or kw in use_case_lower for kw in HIGH_RISK_KEYWORDS):
+            high_risk_score += 2
+        if any(dt in HIGH_RISK_SENSITIVE_DATA for dt in [d.lower() for d in data_types]):
+            high_risk_score += 1
+
+        if high_risk_score >= 2:
+            return {
+                "risk_category": "high",
+                **RISK_CATEGORIES["high"],
+            }
+
+        # Check for limited risk
+        if any(kw in description_lower or kw in use_case_lower for kw in LIMITED_RISK_KEYWORDS):
+            return {
+                "risk_category": "limited",
+                **RISK_CATEGORIES["limited"],
+            }
+
+        return {
+            "risk_category": "minimal",
+            **RISK_CATEGORIES["minimal"],
+        }
+
+    def gap_analysis(self, risk_category: str, current_compliance: dict[str, list[bool]]) -> dict:
+        """
+        Perform gap analysis for a high-risk AI system.
+        current_compliance: {requirement_key: [True/False for each check]}
+        """
+        if risk_category not in ("high", "unacceptable"):
+            return {
+                "applicable": False,
+                "message": f"Full gap analysis not required for {risk_category}-risk systems",
+            }
+
+        gaps = []
+        total_checks = 0
+        passed_checks = 0
+
+        for req_key, req_info in HIGH_RISK_REQUIREMENTS.items():
+            checks = current_compliance.get(req_key, [False] * len(req_info["checks"]))
+            for i, (check_desc, is_met) in enumerate(zip(req_info["checks"], checks)):
+                total_checks += 1
+                if is_met:
+                    passed_checks += 1
+                else:
+                    gaps.append(
+                        {
+                            "requirement": req_info["name"],
+                            "article": req_info["article"],
+                            "check": check_desc,
+                            "status": "NOT_MET",
+                        }
+                    )
+
+        compliance_score = round(passed_checks / max(total_checks, 1) * 100, 1)
+
+        result = {
+            "applicable": True,
+            "compliance_score": compliance_score,
+            "total_checks": total_checks,
+            "passed_checks": passed_checks,
+            "gaps": gaps,
+            "gap_count": len(gaps),
+            "status": "COMPLIANT" if compliance_score == 100 else "GAPS_FOUND",
+            "enforcement_deadline": EU_AI_ACT_ENFORCEMENT_DEADLINE,
+            "assessed_at": datetime.now(UTC).isoformat(),
+        }
+
+        self.assessments.append(result)
+        return result
+
+    def generate_report(self, system_name: str, classification: dict, gap_result: dict) -> dict:
+        """Generate a compliance report summary."""
+        return {
+            "report_title": f"EU AI Act Compliance Report — {system_name}",
+            "generated_at": datetime.now(UTC).isoformat(),
+            "system_name": system_name,
+            "risk_classification": classification,
+            "gap_analysis": gap_result,
+            "recommendations": self._generate_recommendations(gap_result),
+            "next_steps": [
+                "Address all identified gaps before enforcement deadline",
+                "Schedule conformity assessment if high-risk",
+                "Establish ongoing monitoring and review process",
+                "Appoint AI compliance officer",
+            ],
+        }
+
+    def _generate_recommendations(self, gap_result: dict) -> list[str]:
+        recs = []
+        if not gap_result.get("applicable"):
+            return ["Continue voluntary best practices"]
+
+        gap_areas = set(g["requirement"] for g in gap_result.get("gaps", []))
+        if "Record Keeping / Logging" in gap_areas:
+            recs.append(
+                "PRIORITY: Enable Admina Forensic Black Box for tamper-proof logging (Art. 12)"
+            )
+        if "Human Oversight" in gap_areas:
+            recs.append(
+                "PRIORITY: Configure escalation policies and human-in-the-loop workflows (Art. 14)"
+            )
+        if "Accuracy, Robustness, Cybersecurity" in gap_areas:
+            recs.append("Enable Anti-Injection Firewall and Loop Breaker for robustness (Art. 15)")
+        if "Transparency" in gap_areas:
+            recs.append("Document agent capabilities and limitations in system registry (Art. 13)")
+        if "Data Governance" in gap_areas:
+            recs.append("Enable PII Redaction and configure data governance policies (Art. 10)")
+
+        return recs if recs else ["All requirements met — maintain compliance posture"]
+
+    def get_stats(self) -> dict:
+        return {
+            "total_assessments": len(self.assessments),
+            "enforcement_deadline": EU_AI_ACT_ENFORCEMENT_DEADLINE,
+        }