"""Compliance framework control definitions and helpers."""

from __future__ import annotations

from enum import StrEnum


class Framework(StrEnum):
    SOC2 = "soc2"
    CIS = "cis"
    OWASP_CICD = "owasp_cicd"
    ISO27001 = "iso27001"


# ---------------------------------------------------------------------------
# SOC 2 Trust Service Criteria (relevant subset)
# ---------------------------------------------------------------------------
SOC2_CONTROLS: dict[str, str] = {
    "CC1.2": "Board Oversight — management demonstrates commitment to integrity",
    "CC6.1": "Logical Access Controls — restrict access to authorised users",
    "CC6.2": "Access Provisioning — manage user access lifecycle",
    "CC6.3": "Access Modification — modify access based on role changes",
    "CC6.6": "System Boundaries — restrict external access",
    "CC6.7": "Data Encryption — protect data in transmission and at rest",
    "CC7.1": "System Monitoring — detect and monitor security events",
    "CC7.2": "Security Monitoring — evaluate and respond to security incidents",
    "CC8.1": "Change Management — authorise and test changes before deployment",
}

# ---------------------------------------------------------------------------
# CIS Controls / GitLab / Software Supply Chain (relevant subset)
# ---------------------------------------------------------------------------
CIS_CONTROLS: dict[str, str] = {
    "CIS-GitLab-1.1": "Ensure branch protection is enabled on default branch",
    "CIS-GitLab-1.2": "Ensure merge request approvals are required",
    "CIS-GitLab-1.3": "Ensure commit signing is enforced",
    "CIS-GitLab-2.1": "Ensure CI/CD variables are masked",
    "CIS-GitLab-2.2": "Ensure CI/CD variables are protected",
    "CIS-GitLab-2.3": "Avoid hardcoded secrets in CI configuration",
    "CIS-GitLab-3.1": "Ensure SAST is configured in CI pipeline",
    "CIS-GitLab-3.2": "Ensure secret detection is configured in CI pipeline",
    "CIS-GitLab-3.3": "Ensure dependency scanning is configured",
    "CIS-GitLab-3.4": "Ensure container scanning is configured",
    "CIS-GitLab-4.1": "Pin Docker images to digest",
    "CIS-GitLab-4.2": "Avoid privileged runner mode",
    "CIS-SSCS-1": "Software Supply Chain — verify integrity of third-party components",
    "CIS-SSCS-2": "Software Supply Chain — pin dependency versions",
}

# ---------------------------------------------------------------------------
# OWASP CI/CD Security Top 10
# ---------------------------------------------------------------------------
OWASP_CICD_CONTROLS: dict[str, str] = {
    "CICD-SEC-1": "Insufficient Flow Control Mechanisms — uncontrolled pipeline triggers",
    "CICD-SEC-2": "Inadequate Identity and Access Management — overprivileged pipeline jobs",
    "CICD-SEC-3": "Dependency Chain Abuse — unpinned or tampered third-party packages/images",
    "CICD-SEC-4": "Poisoned Pipeline Execution (PPE) — untrusted code runs in CI context",
    "CICD-SEC-5": (
        "Insufficient Pipeline-Based Access Controls"
        " — secrets accessible without protection"
    ),
    "CICD-SEC-6": "Insufficient Credential Hygiene — credentials exposed in CI environment",
    "CICD-SEC-7": "Insecure System Configuration — misconfigured runners or pipeline environment",
    "CICD-SEC-8": "Ungoverned Usage of Third-Party Services — untrusted external CI resources",
    "CICD-SEC-9": "Improper Artifact Integrity Validation — unverified build artifacts",
    "CICD-SEC-10": (
        "Insufficient Logging and Visibility"
        " — missing or suppressed security stage output"
    ),
}

# ---------------------------------------------------------------------------
# ISO 27001:2022 Annex A Controls (relevant subset)
# ---------------------------------------------------------------------------
ISO27001_CONTROLS: dict[str, str] = {
    "A.5.14": "Information transfer — secure transfer policies",
    "A.8.2":  "Privileged access rights — restrict and control",
    "A.8.3":  "Information access restriction",
    "A.8.4":  "Access to source code",
    "A.8.8":  "Management of technical vulnerabilities",
    "A.8.9":  "Configuration management",
    "A.8.20": "Network security controls",
    "A.8.24": "Use of cryptography",
    "A.8.25": "Secure development lifecycle",
    "A.8.26": "Application security requirements",
    "A.8.29": "Security testing in development and acceptance",
    "A.8.32": "Change management",
    "A.9.4.3": "Password management systems — no hardcoded credentials",
}


def describe_control(framework: Framework, control_id: str) -> str:
    """Return human-readable description for a control ID, or the ID itself."""
    mapping = {
        Framework.SOC2: SOC2_CONTROLS,
        Framework.CIS: CIS_CONTROLS,
        Framework.OWASP_CICD: OWASP_CICD_CONTROLS,
        Framework.ISO27001: ISO27001_CONTROLS,
    }
    return mapping[framework].get(control_id, control_id)
