preflight-engine 0.1.0__py3-none-any.whl

preflight/rules/generic.py

@@ -0,0 +1,298 @@
+"""Provider-neutral detection rules for Terraform plans."""
+
+from preflight.models import (
+    ActionType,
+    Finding,
+    ResourceChange,
+    RiskFactors,
+    Severity,
+)
+from preflight.rules.base import Rule, RuleContext
+from preflight.scoring import score_finding
+
+# Types typically representing stateful or persistent resources where forced recreation is high-risk
+STATEFUL_PATTERNS = (
+    "db",
+    "database",
+    "cluster",
+    "instance",
+    "volume",
+    "disk",
+    "bucket",
+    "table",
+    "storage",
+    "queue",
+    "topic",
+)
+
+
+class GenericResourceDeletionRule(Rule):
+    rule_id = "GEN-DEL-001"
+    name = "Resource Deletion"
+    description = "Detects resource deletion in the Terraform plan."
+    default_severity = Severity.HIGH
+
+    def evaluate(self, resource: ResourceChange, context: RuleContext) -> list[Finding]:
+        if resource.action != ActionType.DELETE:
+            return []
+
+        base_factors = RiskFactors(
+            change_impact=4.0,
+            security_exposure=1.0,
+            reversibility=4.5,
+            uncertainty=0.0,
+        )
+        resolved_factors, score = score_finding(base_factors, context.environment)
+
+        return [
+            Finding(
+                rule_id=self.rule_id,
+                rule_name=self.name,
+                severity=self.default_severity,
+                resource_address=resource.address,
+                resource_type=resource.type,
+                action=resource.action,
+                what_changed=f"Resource '{resource.address}' ({resource.type}) is scheduled for permanent deletion.",
+                why_it_matters=(
+                    "Deleting infrastructure resources destroys active configuration, "
+                    "removes state, and can sever dependencies for other services."
+                ),
+                remediation=(
+                    "Verify this deletion is intended. Ensure dependent workloads have been migrated "
+                    "or decommissioned before applying the change."
+                ),
+                risk_factors=resolved_factors,
+                calculated_score=score,
+                details={"raw_actions": resource.raw_actions},
+            )
+        ]
+
+
+class GenericResourceReplacementRule(Rule):
+    rule_id = "GEN-REP-001"
+    name = "Resource Replacement"
+    description = "Detects resource recreation caused by immutable attribute modifications."
+    default_severity = Severity.HIGH
+
+    def evaluate(self, resource: ResourceChange, context: RuleContext) -> list[Finding]:
+        if resource.action != ActionType.REPLACE:
+            return []
+
+        replace_paths = [str(p) for p in (resource.replace_paths or [])]
+        paths_desc = f" due to changes in: {', '.join(replace_paths)}" if replace_paths else ""
+
+        base_factors = RiskFactors(
+            change_impact=4.0,
+            security_exposure=2.0,
+            reversibility=4.0,
+            uncertainty=1.0,
+        )
+        resolved_factors, score = score_finding(base_factors, context.environment)
+
+        return [
+            Finding(
+                rule_id=self.rule_id,
+                rule_name=self.name,
+                severity=self.default_severity,
+                resource_address=resource.address,
+                resource_type=resource.type,
+                action=resource.action,
+                what_changed=(
+                    f"Resource '{resource.address}' ({resource.type}) will be destroyed and recreated{paths_desc}."
+                ),
+                why_it_matters=(
+                    "Resource replacement involves destroying the existing instance before or after creating a new one. "
+                    "This causes IP/endpoint changes, state resets, and temporary downtime."
+                ),
+                remediation=(
+                    "Review the attributes triggering replacement in 'replace_paths'. Consider if changes can be performed "
+                    "with zero-downtime blue/green patterns or by updating mutable fields in-place."
+                ),
+                risk_factors=resolved_factors,
+                calculated_score=score,
+                details={"replace_paths": replace_paths, "raw_actions": resource.raw_actions},
+            )
+        ]
+
+
+class GenericUnknownActionRule(Rule):
+    rule_id = "GEN-ACT-001"
+    name = "Unknown Change Action"
+    description = "Detects unsupported or unrecognized action sequences in plan."
+    default_severity = Severity.HIGH
+
+    def evaluate(self, resource: ResourceChange, context: RuleContext) -> list[Finding]:
+        if resource.action != ActionType.UNKNOWN:
+            return []
+
+        base_factors = RiskFactors(
+            change_impact=3.0,
+            security_exposure=2.0,
+            reversibility=3.0,
+            uncertainty=5.0,
+        )
+        resolved_factors, score = score_finding(base_factors, context.environment)
+
+        return [
+            Finding(
+                rule_id=self.rule_id,
+                rule_name=self.name,
+                severity=self.default_severity,
+                resource_address=resource.address,
+                resource_type=resource.type,
+                action=resource.action,
+                what_changed=(
+                    f"Resource '{resource.address}' contains unrecognized action sequence: {resource.raw_actions}."
+                ),
+                why_it_matters=(
+                    "Preflight cannot deterministically predict the lifecycle behavior of unrecognized Terraform actions."
+                ),
+                remediation=(
+                    "Inspect the plan manually using 'terraform show' to confirm the exact operation being performed."
+                ),
+                risk_factors=resolved_factors,
+                calculated_score=score,
+                details={"raw_actions": resource.raw_actions},
+            )
+        ]
+
+
+class GenericUnknownValuesRule(Rule):
+    rule_id = "GEN-UNK-001"
+    name = "Unknown Computed Values"
+    description = "Detects unknown values that hinder reliable pre-deployment risk assessment."
+    default_severity = Severity.MODERATE
+
+    def evaluate(self, resource: ResourceChange, context: RuleContext) -> list[Finding]:
+        # Only evaluate on resources being created or updated
+        if resource.action not in (ActionType.CREATE, ActionType.UPDATE, ActionType.REPLACE):
+            return []
+
+        if not resource.after_unknown:
+            return []
+
+        # Filter out standard read-only computed attributes generated by Terraform
+        BENIGN_COMPUTED = {
+            "id",
+            "arn",
+            "created_at",
+            "updated_at",
+            "version_id",
+            "tags_all",
+            "owner_id",
+        }
+        unknown_keys = [
+            k
+            for k, v in resource.after_unknown.items()
+            if (
+                v is True
+                or (isinstance(v, dict) and any(v.values()))
+                or (isinstance(v, list) and len(v) > 0)
+            )
+            and k not in BENIGN_COMPUTED
+        ]
+
+        if not unknown_keys:
+            return []
+
+        # If after is extensively unknown
+        is_extensively_unknown = len(unknown_keys) > 5
+
+        base_factors = RiskFactors(
+            change_impact=2.0 if is_extensively_unknown else 1.0,
+            security_exposure=2.0 if is_extensively_unknown else 1.0,
+            reversibility=1.0,
+            uncertainty=4.5 if is_extensively_unknown else 3.0,
+        )
+        resolved_factors, score = score_finding(base_factors, context.environment)
+
+        return [
+            Finding(
+                rule_id=self.rule_id,
+                rule_name=self.name,
+                severity=self.default_severity,
+                resource_address=resource.address,
+                resource_type=resource.type,
+                action=resource.action,
+                what_changed=(
+                    f"Resource '{resource.address}' has {len(unknown_keys)} attribute(s) computed at apply time: "
+                    f"{', '.join(unknown_keys[:5])}{'...' if len(unknown_keys) > 5 else ''}."
+                ),
+                why_it_matters=(
+                    "Unknown computed values cannot be statically verified prior to deployment. "
+                    "Rules inspecting these fields may not identify exposure until after application."
+                ),
+                remediation=(
+                    "Where possible, provide explicit values rather than depending on dynamic interpolation "
+                    "for sensitive security or routing parameters."
+                ),
+                risk_factors=resolved_factors,
+                calculated_score=score,
+                details={"unknown_attributes": unknown_keys[:10]},
+            )
+        ]
+
+
+class GenericDestructiveChangeRule(Rule):
+    rule_id = "GEN-DST-001"
+    name = "Destructive Stateful Resource Change"
+    description = "Detects destructive changes to stateful storage, compute, or database resources."
+    default_severity = Severity.HIGH
+
+    def evaluate(self, resource: ResourceChange, context: RuleContext) -> list[Finding]:
+        if resource.action not in (ActionType.DELETE, ActionType.REPLACE):
+            return []
+
+        type_lower = resource.type.lower()
+        NON_STATEFUL_SUFFIXES = (
+            "_policy",
+            "_rule",
+            "_attachment",
+            "_association",
+            "_public_access_block",
+            "_metric",
+            "_alarm",
+        )
+        if any(type_lower.endswith(suffix) for suffix in NON_STATEFUL_SUFFIXES):
+            return []
+
+        is_stateful = any(pattern in type_lower for pattern in STATEFUL_PATTERNS)
+        if not is_stateful:
+            return []
+
+        base_factors = RiskFactors(
+            change_impact=4.5,
+            security_exposure=1.5,
+            reversibility=4.5,
+            uncertainty=1.0,
+        )
+        resolved_factors, score = score_finding(base_factors, context.environment)
+
+        action_desc = (
+            "replacement (recreation)" if resource.action == ActionType.REPLACE else "deletion"
+        )
+
+        return [
+            Finding(
+                rule_id=self.rule_id,
+                rule_name=self.name,
+                severity=self.default_severity,
+                resource_address=resource.address,
+                resource_type=resource.type,
+                action=resource.action,
+                what_changed=(
+                    f"Stateful resource '{resource.address}' ({resource.type}) is scheduled for {action_desc}."
+                ),
+                why_it_matters=(
+                    "Stateful resources store persistent data or maintain state. Destroying or recreating them "
+                    "risks unrecoverable data loss and prolonged downtime."
+                ),
+                remediation=(
+                    "Verify that data snapshots exist, ensure deletion protection settings are reviewed, "
+                    "and double-check whether replacement can be avoided."
+                ),
+                risk_factors=resolved_factors,
+                calculated_score=score,
+                details={"stateful_type": resource.type, "action": resource.action.value},
+            )
+        ]

preflight/rules/kubernetes.py

@@ -0,0 +1,264 @@
+"""K8S specific detection rules"""
+
+from typing import Any
+
+from preflight.models import (
+    ActionType,
+    Finding,
+    ResourceChange,
+    RiskFactors,
+    Severity,
+)
+from preflight.rules.base import Rule, RuleContext
+from preflight.scoring import score_finding
+
+K8S_WORKLOAD_TYPES = {
+    "kubernetes_deployment",
+    "kubernetes_deployment_v1",
+    "kubernetes_daemonset",
+    "kubernetes_daemon_set",
+    "kubernetes_daemon_set_v1",
+    "kubernetes_stateful_set",
+    "kubernetes_stateful_set_v1",
+    "kubernetes_job",
+    "kubernetes_job_v1",
+    "kubernetes_cron_job",
+    "kubernetes_cron_job_v1",
+    "kubernetes_pod",
+    "kubernetes_pod_v1",
+    "kubernetes_replication_controller",
+    "kubernetes_replication_controller_v1",
+}
+
+K8S_BINDING_TYPES = {
+    "kubernetes_cluster_role_binding",
+    "kubernetes_cluster_role_binding_v1",
+    "kubernetes_role_binding",
+    "kubernetes_role_binding_v1",
+}
+
+
+def _is_truthy(val: Any) -> bool:
+    if isinstance(val, bool):
+        return val
+    if isinstance(val, str):
+        return val.strip().lower() in ("true", "1", "yes")
+    return False
+
+
+def _check_container_list(containers: Any) -> list[str]:
+    violations: list[str] = []
+    if isinstance(containers, dict):
+        containers = [containers]
+    if not isinstance(containers, list):
+        return violations
+
+    for c in containers:
+        if not isinstance(c, dict):
+            continue
+        c_name = c.get("name") or "unnamed"
+        sec_ctx = c.get("security_context") or c.get("securityContext")
+        if isinstance(sec_ctx, list) and sec_ctx:
+            sec_ctx = sec_ctx[0]
+        if isinstance(sec_ctx, dict) and _is_truthy(sec_ctx.get("privileged")):
+            violations.append(f"container '{c_name}' has privileged=true")
+
+    return violations
+
+
+def _find_k8s_workload_violations(data: Any) -> list[str]:
+    violations: list[str] = []
+
+    def _traverse(node: Any) -> None:
+        if isinstance(node, dict):
+            if _is_truthy(node.get("host_network")) or _is_truthy(node.get("hostNetwork")):
+                violations.append("hostNetwork is enabled")
+            if _is_truthy(node.get("host_pid")) or _is_truthy(node.get("hostPID")):
+                violations.append("hostPID is enabled")
+            if _is_truthy(node.get("host_ipc")) or _is_truthy(node.get("hostIPC")):
+                violations.append("hostIPC is enabled")
+
+            for key in ("container", "containers", "init_container", "init_containers"):
+                if key in node:
+                    violations.extend(_check_container_list(node[key]))
+
+            for v in node.values():
+                if isinstance(v, (dict, list)):
+                    _traverse(v)
+        elif isinstance(node, list):
+            for item in node:
+                if isinstance(item, (dict, list)):
+                    _traverse(item)
+
+    _traverse(data)
+
+    seen: set[str] = set()
+    deduped: list[str] = []
+    for v in violations:
+        if v not in seen:
+            seen.add(v)
+            deduped.append(v)
+    return deduped
+
+
+def _check_helm_release(after: dict[str, Any]) -> list[str]:
+    violations: list[str] = []
+    set_blocks = after.get("set") or []
+    if isinstance(set_blocks, list):
+        for item in set_blocks:
+            if not isinstance(item, dict):
+                continue
+            name = str(item.get("name", "")).lower()
+            val = item.get("value")
+            if not _is_truthy(val):
+                continue
+            if "privileged" in name:
+                violations.append(f"helm value '{item.get('name')}' enables privileged mode")
+            elif "hostnetwork" in name:
+                violations.append(f"helm value '{item.get('name')}' enables hostNetwork")
+
+    values_raw = after.get("values")
+    if isinstance(values_raw, list):
+        for raw in values_raw:
+            if not isinstance(raw, str):
+                continue
+            raw_lower = raw.lower()
+            if "privileged: true" in raw_lower:
+                violations.append("helm values contains privileged: true")
+            if "hostnetwork: true" in raw_lower:
+                violations.append("helm values contains hostNetwork: true")
+
+    return violations
+
+
+class KubernetesWorkloadSecurityRule(Rule):
+    rule_id = "K8S-SEC-001"
+    name = "Kubernetes Workload Privileged or Host Access"
+    description = "Detects Kubernetes pods and workloads running in privileged mode or with host network/PID/IPC namespaces."
+    default_severity = Severity.HIGH
+
+    def evaluate(self, resource: ResourceChange, context: RuleContext) -> list[Finding]:
+        if resource.action == ActionType.DELETE or not resource.after:
+            return []
+
+        violations: list[str] = []
+
+        if resource.type in K8S_WORKLOAD_TYPES or resource.type.startswith("kubernetes_"):
+            violations.extend(_find_k8s_workload_violations(resource.after))
+        elif resource.type == "helm_release":
+            violations.extend(_check_helm_release(resource.after))
+
+        if not violations:
+            return []
+
+        base_factors = RiskFactors(
+            change_impact=3.5,
+            security_exposure=5.0,
+            reversibility=1.0,
+            uncertainty=0.5,
+        )
+        resolved_factors, score = score_finding(base_factors, context.environment)
+
+        return [
+            Finding(
+                rule_id=self.rule_id,
+                rule_name=self.name,
+                severity=self.default_severity,
+                resource_address=resource.address,
+                resource_type=resource.type,
+                action=resource.action,
+                what_changed=(
+                    f"Kubernetes workload '{resource.address}' enables privileged or host access: "
+                    f"{'; '.join(violations)}."
+                ),
+                why_it_matters=(
+                    "Privileged containers and host namespace sharing compromise node boundary isolation, "
+                    "enabling container breakout, host filesystem tampering, and cluster-wide node takeover."
+                ),
+                remediation=(
+                    "Disable privileged container mode (privileged = false) and avoid hostNetwork, hostPID, "
+                    "or hostIPC unless strictly required by node-level daemon plugins."
+                ),
+                risk_factors=resolved_factors,
+                calculated_score=score,
+                details={"violations": violations},
+            )
+        ]
+
+
+class KubernetesClusterAdminBindingRule(Rule):
+    rule_id = "K8S-RBAC-001"
+    name = "Kubernetes ClusterRoleBinding to cluster-admin"
+    description = (
+        "Detects RoleBindings and ClusterRoleBindings granting superuser cluster-admin privileges."
+    )
+    default_severity = Severity.CRITICAL
+
+    def evaluate(self, resource: ResourceChange, context: RuleContext) -> list[Finding]:
+        if resource.action == ActionType.DELETE or not resource.after:
+            return []
+
+        if resource.type not in K8S_BINDING_TYPES:
+            return []
+
+        role_ref = resource.after.get("role_ref")
+        if isinstance(role_ref, list) and role_ref:
+            role_ref = role_ref[0]
+
+        if not isinstance(role_ref, dict):
+            return []
+
+        role_name = str(role_ref.get("name", "")).strip()
+        if role_name.lower() != "cluster-admin":
+            return []
+
+        subjects = resource.after.get("subject") or resource.after.get("subjects") or []
+        if isinstance(subjects, dict):
+            subjects = [subjects]
+        subject_descs: list[str] = []
+        if isinstance(subjects, list):
+            for s in subjects:
+                if isinstance(s, dict):
+                    s_kind = s.get("kind", "Subject")
+                    s_name = s.get("name", "unnamed")
+                    s_ns = s.get("namespace")
+                    if s_ns:
+                        subject_descs.append(f"{s_kind}:{s_ns}/{s_name}")
+                    else:
+                        subject_descs.append(f"{s_kind}:{s_name}")
+
+        subjects_str = ", ".join(subject_descs) if subject_descs else "unspecified subjects"
+
+        base_factors = RiskFactors(
+            change_impact=4.0,
+            security_exposure=5.0,
+            reversibility=2.0,
+            uncertainty=0.5,
+        )
+        resolved_factors, score = score_finding(base_factors, context.environment)
+
+        return [
+            Finding(
+                rule_id=self.rule_id,
+                rule_name=self.name,
+                severity=self.default_severity,
+                resource_address=resource.address,
+                resource_type=resource.type,
+                action=resource.action,
+                what_changed=(
+                    f"RBAC binding '{resource.address}' binds subject(s) [{subjects_str}] "
+                    f"to superuser role 'cluster-admin'."
+                ),
+                why_it_matters=(
+                    "The cluster-admin role grants unconditional control over every API resource across all "
+                    "namespaces in the cluster. Misconfigurations allow lateral movement and full cluster compromise."
+                ),
+                remediation=(
+                    "Define least-privilege Roles or ClusterRoles granting only the specific API groups, "
+                    "resources, and verbs needed by the workload or user."
+                ),
+                risk_factors=resolved_factors,
+                calculated_score=score,
+                details={"role": role_name, "subjects": subject_descs},
+            )
+        ]

preflight/scoring.py

@@ -0,0 +1,140 @@
+"""Explainable risk scoring engine for Terraform infrastructure changes."""
+
+from preflight.models import (
+    Environment,
+    Finding,
+    ResourceChange,
+    ResourceRisk,
+    RiskCategory,
+    RiskFactors,
+)
+
+# Factor weights (sum to 100)
+WEIGHT_CHANGE_IMPACT = 30.0
+WEIGHT_SECURITY_EXPOSURE = 25.0
+WEIGHT_REVERSIBILITY = 20.0
+WEIGHT_ENVIRONMENT_CRITICALITY = 15.0
+WEIGHT_UNCERTAINTY = 10.0
+
+# Environment criticality mappings (0 to 5)
+ENV_CRITICALITY_SCORES: dict[Environment, float] = {
+    Environment.DEVELOPMENT: 1.0,
+    Environment.STAGING: 3.0,
+    Environment.PRODUCTION: 5.0,
+}
+
+
+def calculate_factor_score(
+    change_impact: float,
+    security_exposure: float,
+    reversibility: float,
+    environment_criticality: float,
+    uncertainty: float,
+) -> float:
+    """Calculate normalized risk score (0 to 100) from 5 factors scored 0 to 5.
+
+    Formula: Σ(weight * factor_score / 5.0)
+    """
+    ci = max(0.0, min(5.0, change_impact))
+    se = max(0.0, min(5.0, security_exposure))
+    rev = max(0.0, min(5.0, reversibility))
+    ec = max(0.0, min(5.0, environment_criticality))
+    unc = max(0.0, min(5.0, uncertainty))
+
+    score = (
+        (WEIGHT_CHANGE_IMPACT * ci / 5.0)
+        + (WEIGHT_SECURITY_EXPOSURE * se / 5.0)
+        + (WEIGHT_REVERSIBILITY * rev / 5.0)
+        + (WEIGHT_ENVIRONMENT_CRITICALITY * ec / 5.0)
+        + (WEIGHT_UNCERTAINTY * unc / 5.0)
+    )
+    return round(score, 1)
+
+
+def score_finding(
+    factors: RiskFactors,
+    environment: Environment,
+) -> tuple[RiskFactors, float]:
+    """Calculate the score for a single finding with environment context."""
+    env_crit = ENV_CRITICALITY_SCORES.get(environment, 5.0)
+    resolved_factors = RiskFactors(
+        change_impact=factors.change_impact,
+        security_exposure=factors.security_exposure,
+        reversibility=factors.reversibility,
+        environment_criticality=env_crit,
+        uncertainty=factors.uncertainty,
+    )
+    score = calculate_factor_score(
+        change_impact=resolved_factors.change_impact,
+        security_exposure=resolved_factors.security_exposure,
+        reversibility=resolved_factors.reversibility,
+        environment_criticality=resolved_factors.environment_criticality,
+        uncertainty=resolved_factors.uncertainty,
+    )
+    return resolved_factors, score
+
+
+def aggregate_resource_risks(
+    resources: list[ResourceChange],
+    findings: list[Finding],
+    environment: Environment,
+) -> tuple[list[ResourceRisk], float, RiskCategory, str | None]:
+    """Aggregate findings per resource and compute resource and plan-level risk.
+
+    The initial release assigns the maximum resource-level risk score as the
+    overall plan risk score.
+    """
+    findings_by_resource: dict[str, list[Finding]] = {}
+    for finding in findings:
+        findings_by_resource.setdefault(finding.resource_address, []).append(finding)
+
+    env_crit = ENV_CRITICALITY_SCORES.get(environment, 5.0)
+    resource_risks: list[ResourceRisk] = []
+    max_score = 0.0
+    highest_contributing_resource: str | None = None
+
+    for res in resources:
+        res_findings = findings_by_resource.get(res.address, [])
+        if res_findings:
+            # Resource risk factors take the maximum component across its findings
+            max_ci = max(f.risk_factors.change_impact for f in res_findings)
+            max_se = max(f.risk_factors.security_exposure for f in res_findings)
+            max_rev = max(f.risk_factors.reversibility for f in res_findings)
+            max_unc = max(f.risk_factors.uncertainty for f in res_findings)
+
+            res_factors = RiskFactors(
+                change_impact=max_ci,
+                security_exposure=max_se,
+                reversibility=max_rev,
+                environment_criticality=env_crit,
+                uncertainty=max_unc,
+            )
+            res_score = calculate_factor_score(max_ci, max_se, max_rev, env_crit, max_unc)
+        else:
+            res_factors = RiskFactors(
+                change_impact=0.0,
+                security_exposure=0.0,
+                reversibility=0.0,
+                environment_criticality=env_crit,
+                uncertainty=0.0,
+            )
+            res_score = 0.0
+
+        res_category = RiskCategory.from_score(res_score)
+        resource_risk = ResourceRisk(
+            resource_address=res.address,
+            resource_type=res.type,
+            action=res.action,
+            risk_score=res_score,
+            risk_category=res_category,
+            risk_factors=res_factors,
+            findings=res_findings,
+        )
+        resource_risks.append(resource_risk)
+
+        if res_score > max_score:
+            max_score = res_score
+            highest_contributing_resource = res.address
+
+    overall_category = RiskCategory.from_score(max_score)
+    return resource_risks, max_score, overall_category, highest_contributing_resource