preflight-engine 0.1.0__py3-none-any.whl

preflight/engine.py

@@ -0,0 +1,115 @@
+"""Analysis engine: Coordinates parsing, rule evaluation, scoring, and policy enforcement."""
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+from preflight.models import (
+    AnalysisResult,
+    Environment,
+    Finding,
+    PlanSummary,
+    PolicyEvaluation,
+    ResourceChange,
+)
+from preflight.plan import parse_plan_file, parse_plan_json
+from preflight.policy import PolicyEvaluator
+from preflight.redaction import redact_sensitive_data
+from preflight.rules import Rule, get_default_rules
+from preflight.rules.base import RuleContext
+from preflight.scoring import aggregate_resource_risks
+
+
+class PreflightEngine:
+    """Core analysis engine orchestrating infrastructure change evaluation."""
+
+    def __init__(self, rules: list[Rule] | None = None) -> None:
+        self.rules = rules if rules is not None else get_default_rules()
+
+    def analyze_file(
+        self,
+        plan_path: str | Path,
+        environment: Environment = Environment.PRODUCTION,
+        policy_evaluator: PolicyEvaluator | None = None,
+    ) -> AnalysisResult:
+        """Run analysis directly on a plan file."""
+        resource_changes, summary = parse_plan_file(plan_path)
+        identifier = "<stdin>" if str(plan_path) == "-" else str(plan_path)
+        return self._run_analysis(
+            plan_path=identifier,
+            resource_changes=resource_changes,
+            summary=summary,
+            environment=environment,
+            policy_evaluator=policy_evaluator,
+        )
+
+    def analyze_json(
+        self,
+        json_content: str,
+        plan_identifier: str = "<stdin>",
+        environment: Environment = Environment.PRODUCTION,
+        policy_evaluator: PolicyEvaluator | None = None,
+    ) -> AnalysisResult:
+        """Run analysis on an in-memory JSON string."""
+        resource_changes, summary = parse_plan_json(json_content)
+        return self._run_analysis(
+            plan_path=plan_identifier,
+            resource_changes=resource_changes,
+            summary=summary,
+            environment=environment,
+            policy_evaluator=policy_evaluator,
+        )
+
+    def _run_analysis(
+        self,
+        plan_path: str,
+        resource_changes: list[ResourceChange],
+        summary: PlanSummary,
+        environment: Environment,
+        policy_evaluator: PolicyEvaluator | None,
+    ) -> AnalysisResult:
+        context = RuleContext(environment=environment)
+        all_findings: list[Finding] = []
+
+        # Evaluate rules against each resource change
+        for resource in resource_changes:
+            for rule in self.rules:
+                findings = rule.evaluate(resource, context)
+                for f in findings:
+                    # Sanitize details using defensive redaction
+                    f.details = redact_sensitive_data(f.details)
+                    all_findings.append(f)
+
+        # Sort findings deterministically (by severity descending, score descending, address ascending, rule ID ascending)
+        all_findings.sort(
+            key=lambda x: (-x.severity.level, -x.calculated_score, x.resource_address, x.rule_id)
+        )
+
+        # Score and aggregate risks
+        resources, overall_score, overall_category, highest_res = aggregate_resource_risks(
+            resources=resource_changes,
+            findings=all_findings,
+            environment=environment,
+        )
+
+        # Evaluate deployment policy
+        if policy_evaluator is None:
+            policy_evaluator = PolicyEvaluator()
+        policy_result: PolicyEvaluation = policy_evaluator.evaluate(
+            findings=all_findings,
+            overall_risk_score=overall_score,
+        )
+
+        timestamp = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+        return AnalysisResult(
+            plan_path=plan_path,
+            environment=environment,
+            summary=summary,
+            resources=resources,
+            findings=all_findings,
+            overall_risk_score=overall_score,
+            overall_risk_category=overall_category,
+            highest_contributing_resource=highest_res,
+            policy_evaluation=policy_result,
+            timestamp=timestamp,
+        )

preflight/github.py

@@ -0,0 +1,124 @@
+"""GitHub PR comment integration using the GitHub REST API."""
+
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+from typing import Any
+
+from preflight import __version__
+from preflight.reporting import PR_COMMENT_MARKER
+
+
+class GitHubApiError(Exception):
+    """Raised when GitHub API operations fail."""
+
+
+def parse_pr_number_from_ref(ref: str) -> int | None:
+    """Extract PR number from refs like 'refs/pull/123/merge' or '123/merge'."""
+    match = re.search(r"pull/(\d+)/", ref)
+    if match:
+        return int(match.group(1))
+    match = re.match(r"^(\d+)$", ref.strip())
+    if match:
+        return int(match.group(1))
+    return None
+
+
+def resolve_github_context(
+    repo: str | None = None,
+    pr: int | None = None,
+    token: str | None = None,
+) -> tuple[str, int, str]:
+    """Resolve repository, pull request number, and token from options or environment."""
+    resolved_repo = repo or os.environ.get("GITHUB_REPOSITORY")
+    if not resolved_repo or "/" not in resolved_repo:
+        raise GitHubApiError(
+            "GitHub repository not specified. Pass '--repo owner/repo' or set GITHUB_REPOSITORY."
+        )
+
+    resolved_pr = pr
+    if resolved_pr is None:
+        pr_env = os.environ.get("PR_NUMBER")
+        if pr_env and pr_env.isdigit():
+            resolved_pr = int(pr_env)
+        elif "GITHUB_REF" in os.environ:
+            resolved_pr = parse_pr_number_from_ref(os.environ["GITHUB_REF"])
+
+    if resolved_pr is None:
+        raise GitHubApiError(
+            "Pull request number not specified. Pass '--pr <number>' or set PR_NUMBER / GITHUB_REF in CI."
+        )
+
+    resolved_token = token or os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    if not resolved_token:
+        raise GitHubApiError("GitHub token not found. Pass '--token <token>' or set GITHUB_TOKEN.")
+
+    return resolved_repo, resolved_pr, resolved_token
+
+
+def _github_request(
+    url: str,
+    token: str,
+    method: str = "GET",
+    payload: dict[str, Any] | None = None,
+) -> Any:
+    """Execute an authenticated HTTP request against GitHub's REST API."""
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github+json",
+        "User-Agent": f"Preflight-Engine/{__version__}",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    data = json.dumps(payload).encode("utf-8") if payload is not None else None
+    req = urllib.request.Request(url, data=data, headers=headers, method=method)
+
+    try:
+        with urllib.request.urlopen(req) as resp:
+            content = resp.read().decode("utf-8")
+            return json.loads(content) if content else {}
+    except urllib.error.HTTPError as exc:
+        err_msg = exc.read().decode("utf-8", errors="replace")
+        raise GitHubApiError(f"GitHub API error ({exc.code} {exc.reason}): {err_msg}") from exc
+    except urllib.error.URLError as exc:
+        raise GitHubApiError(f"Network error connecting to GitHub API: {exc.reason}") from exc
+
+
+def post_or_update_pr_comment(
+    repo: str,
+    pr_number: int,
+    token: str,
+    comment_body: str,
+    marker: str = PR_COMMENT_MARKER,
+) -> dict[str, Any]:
+    """Publish a sticky PR comment, updating an existing comment if a marker is present."""
+    comments_url = f"https://api.github.com/repos/{repo}/issues/{pr_number}/comments"
+
+    # 1. Search for existing sticky comment with our marker
+    existing_comments = _github_request(f"{comments_url}?per_page=100", token, method="GET")
+    existing_comment_id: int | None = None
+
+    if isinstance(existing_comments, list):
+        for comment in existing_comments:
+            body = comment.get("body", "")
+            if marker in body:
+                existing_comment_id = int(comment["id"])
+                break
+
+    # 2. Update existing comment or create a new one
+    if existing_comment_id is not None:
+        patch_url = f"https://api.github.com/repos/{repo}/issues/comments/{existing_comment_id}"
+        resp = _github_request(patch_url, token, method="PATCH", payload={"body": comment_body})
+        return {
+            "action": "updated",
+            "comment_id": existing_comment_id,
+            "url": resp.get("html_url", ""),
+        }
+    else:
+        resp = _github_request(comments_url, token, method="POST", payload={"body": comment_body})
+        return {
+            "action": "created",
+            "comment_id": resp.get("id"),
+            "url": resp.get("html_url", ""),
+        }

preflight/models.py

@@ -0,0 +1,274 @@
+"""Domain models for Preflight infrastructure change risk analysis."""
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+
+class Environment(StrEnum):
+    DEVELOPMENT = "development"
+    STAGING = "staging"
+    PRODUCTION = "production"
+
+    @classmethod
+    def from_str(cls, value: str) -> "Environment":
+        normalized = value.strip().lower()
+        if normalized in ("dev", "development"):
+            return cls.DEVELOPMENT
+        if normalized in ("stage", "staging"):
+            return cls.STAGING
+        if normalized in ("prod", "production"):
+            return cls.PRODUCTION
+        raise ValueError(f"Unknown environment '{value}'. Valid: development, staging, production.")
+
+
+class ActionType(StrEnum):
+    CREATE = "create"
+    UPDATE = "update"
+    DELETE = "delete"
+    REPLACE = "replace"
+    READ = "read"
+    NOOP = "no-op"
+    UNKNOWN = "unknown"
+
+    @classmethod
+    def from_terraform_actions(cls, actions: list[str]) -> "ActionType":
+        if not actions:
+            return cls.NOOP
+        if actions == ["create"]:
+            return cls.CREATE
+        if actions == ["update"]:
+            return cls.UPDATE
+        if actions == ["delete"]:
+            return cls.DELETE
+        if actions == ["read"]:
+            return cls.READ
+        if actions == ["no-op"]:
+            return cls.NOOP
+        if sorted(actions) == ["create", "delete"]:
+            return cls.REPLACE
+        return cls.UNKNOWN
+
+
+class Severity(StrEnum):
+    LOW = "low"
+    MODERATE = "moderate"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+    @property
+    def level(self) -> int:
+        levels = {
+            Severity.LOW: 1,
+            Severity.MODERATE: 2,
+            Severity.HIGH: 3,
+            Severity.CRITICAL: 4,
+        }
+        return levels[self]
+
+    def __ge__(self, other: object) -> bool:
+        if not isinstance(other, Severity):
+            return NotImplemented
+        return self.level >= other.level
+
+    def __gt__(self, other: object) -> bool:
+        if not isinstance(other, Severity):
+            return NotImplemented
+        return self.level > other.level
+
+    def __le__(self, other: object) -> bool:
+        if not isinstance(other, Severity):
+            return NotImplemented
+        return self.level <= other.level
+
+    def __lt__(self, other: object) -> bool:
+        if not isinstance(other, Severity):
+            return NotImplemented
+        return self.level < other.level
+
+    @classmethod
+    def from_str(cls, value: str) -> "Severity":
+        normalized = value.strip().lower()
+        for member in cls:
+            if member.value == normalized:
+                return member
+        raise ValueError(f"Unknown severity '{value}'. Valid: low, moderate, high, critical.")
+
+
+class RiskCategory(StrEnum):
+    LOW = "low"
+    MODERATE = "moderate"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+    @classmethod
+    def from_score(cls, score: float) -> "RiskCategory":
+        if score < 25.0:
+            return cls.LOW
+        if score < 50.0:
+            return cls.MODERATE
+        if score < 75.0:
+            return cls.HIGH
+        return cls.CRITICAL
+
+
+@dataclass(frozen=True)
+class RiskFactors:
+    change_impact: float = 0.0
+    security_exposure: float = 0.0
+    reversibility: float = 0.0
+    environment_criticality: float = 0.0
+    uncertainty: float = 0.0
+
+    def to_dict(self) -> dict[str, float]:
+        return {
+            "change_impact": round(self.change_impact, 2),
+            "security_exposure": round(self.security_exposure, 2),
+            "reversibility": round(self.reversibility, 2),
+            "environment_criticality": round(self.environment_criticality, 2),
+            "uncertainty": round(self.uncertainty, 2),
+        }
+
+
+@dataclass
+class Finding:
+    rule_id: str
+    rule_name: str
+    severity: Severity
+    resource_address: str
+    resource_type: str
+    action: ActionType
+    what_changed: str
+    why_it_matters: str
+    remediation: str
+    risk_factors: RiskFactors
+    calculated_score: float
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "rule_id": self.rule_id,
+            "rule_name": self.rule_name,
+            "severity": self.severity.value,
+            "resource_address": self.resource_address,
+            "resource_type": self.resource_type,
+            "action": self.action.value,
+            "what_changed": self.what_changed,
+            "why_it_matters": self.why_it_matters,
+            "remediation": self.remediation,
+            "risk_factors": self.risk_factors.to_dict(),
+            "calculated_score": round(self.calculated_score, 1),
+            "details": self.details,
+        }
+
+
+@dataclass
+class ResourceChange:
+    address: str
+    mode: str
+    type: str
+    name: str
+    provider_name: str
+    raw_actions: list[str]
+    action: ActionType
+    module_address: str | None = None
+    before: dict[str, Any] | None = None
+    after: dict[str, Any] | None = None
+    after_unknown: dict[str, Any] | None = None
+    replace_paths: list[Any] | None = None
+    before_sensitive: Any = None
+    after_sensitive: Any = None
+
+
+@dataclass
+class ResourceRisk:
+    resource_address: str
+    resource_type: str
+    action: ActionType
+    risk_score: float
+    risk_category: RiskCategory
+    risk_factors: RiskFactors
+    findings: list[Finding] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "resource_address": self.resource_address,
+            "resource_type": self.resource_type,
+            "action": self.action.value,
+            "risk_score": round(self.risk_score, 1),
+            "risk_category": self.risk_category.value,
+            "risk_factors": self.risk_factors.to_dict(),
+            "findings_count": len(self.findings),
+            "findings": [f.to_dict() for f in self.findings],
+        }
+
+
+@dataclass
+class PlanSummary:
+    total_resources: int = 0
+    to_create: int = 0
+    to_update: int = 0
+    to_delete: int = 0
+    to_replace: int = 0
+    to_read: int = 0
+    to_noop: int = 0
+    unknown_actions: int = 0
+    has_unknown_values: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "total_resources": self.total_resources,
+            "to_create": self.to_create,
+            "to_update": self.to_update,
+            "to_delete": self.to_delete,
+            "to_replace": self.to_replace,
+            "to_read": self.to_read,
+            "to_noop": self.to_noop,
+            "unknown_actions": self.unknown_actions,
+            "has_unknown_values": self.has_unknown_values,
+        }
+
+
+@dataclass
+class PolicyEvaluation:
+    blocked: bool
+    blocking_reasons: list[str] = field(default_factory=list)
+    fail_on_severity: Severity | None = None
+    blocked_rule_ids: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "blocked": self.blocked,
+            "blocking_reasons": self.blocking_reasons,
+            "fail_on_severity": self.fail_on_severity.value if self.fail_on_severity else None,
+            "blocked_rule_ids": self.blocked_rule_ids,
+        }
+
+
+@dataclass
+class AnalysisResult:
+    plan_path: str
+    environment: Environment
+    summary: PlanSummary
+    resources: list[ResourceRisk]
+    findings: list[Finding]
+    overall_risk_score: float
+    overall_risk_category: RiskCategory
+    highest_contributing_resource: str | None
+    policy_evaluation: PolicyEvaluation
+    timestamp: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "plan_path": self.plan_path,
+            "timestamp": self.timestamp,
+            "environment": self.environment.value,
+            "overall_risk_score": round(self.overall_risk_score, 1),
+            "overall_risk_category": self.overall_risk_category.value,
+            "highest_contributing_resource": self.highest_contributing_resource,
+            "summary": self.summary.to_dict(),
+            "policy_evaluation": self.policy_evaluation.to_dict(),
+            "findings_count": len(self.findings),
+            "findings": [f.to_dict() for f in self.findings],
+            "resources": [r.to_dict() for r in self.resources],
+        }

preflight/plan.py

@@ -0,0 +1,165 @@
+"""Input layer: Read, validate, and normalize Terraform plan JSON."""
+
+import json
+import sys
+from pathlib import Path
+
+from preflight.models import ActionType, PlanSummary, ResourceChange
+
+
+class PlanParseError(Exception):
+    """Raised when a Terraform plan file cannot be read or parsed."""
+
+
+def parse_plan_file(plan_path: str | Path) -> tuple[list[ResourceChange], PlanSummary]:
+    """Read and validate a Terraform plan JSON file or stdin stream."""
+    path_str = str(plan_path)
+    if path_str == "-":
+        if hasattr(sys.stdin, "isatty") and sys.stdin.isatty():
+            raise PlanParseError(
+                "Standard input is an interactive terminal. Pipe data in via '|' "
+                "(e.g., terraform show -json tfplan | preflight analyze -) or specify a plan file path."
+            )
+        try:
+            content = sys.stdin.read()
+        except OSError as exc:
+            raise PlanParseError(f"Failed to read from standard input: {exc}") from exc
+        if not content.strip():
+            raise PlanParseError("Standard input is empty.")
+        return parse_plan_json(content)
+
+    path = Path(plan_path)
+    if not path.exists():
+        raise PlanParseError(f"Plan file not found: '{path}'. Ensure the path is correct.")
+    if path.is_dir():
+        raise PlanParseError(f"Plan path '{path}' is a directory, not a file.")
+
+    try:
+        content = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as exc:
+        raise PlanParseError(f"File '{path}' is not valid UTF-8 text: {exc}") from exc
+    except OSError as exc:
+        raise PlanParseError(f"Failed to read file '{path}': {exc}") from exc
+
+    return parse_plan_json(content)
+
+
+def parse_plan_json(json_content: str) -> tuple[list[ResourceChange], PlanSummary]:
+    """Parse raw JSON string representation of a Terraform plan."""
+    if not json_content.strip():
+        raise PlanParseError("Plan file is empty.")
+
+    try:
+        data = json.loads(json_content)
+    except json.JSONDecodeError as exc:
+        raise PlanParseError(
+            f"Invalid JSON syntax at line {exc.lineno}, column {exc.colno}: {exc.msg}"
+        ) from exc
+
+    if not isinstance(data, dict):
+        raise PlanParseError(
+            f"Unsupported plan format: expected JSON object at root, got {type(data).__name__}."
+        )
+
+    # Validate Terraform plan signature (must have format_version or resource_changes or planned_values)
+    is_tf_plan = any(
+        k in data
+        for k in ("format_version", "terraform_version", "resource_changes", "planned_values")
+    )
+    if not is_tf_plan:
+        raise PlanParseError(
+            "JSON structure does not appear to be a Terraform plan. "
+            "Ensure you generated it via 'terraform show -json <tfplan>'."
+        )
+
+    raw_changes = data.get("resource_changes", [])
+    if not isinstance(raw_changes, list):
+        raise PlanParseError(
+            f"'resource_changes' must be an array, got {type(raw_changes).__name__}."
+        )
+
+    resource_changes: list[ResourceChange] = []
+    summary = PlanSummary(total_resources=len(raw_changes))
+
+    for idx, item in enumerate(raw_changes):
+        if not isinstance(item, dict):
+            raise PlanParseError(f"resource_changes[{idx}] is not an object.")
+
+        address = str(item.get("address", f"resource_{idx}"))
+        mode = str(item.get("mode", "managed"))
+        res_type = str(item.get("type", "unknown"))
+        name = str(item.get("name", "unknown"))
+        provider_name = str(item.get("provider_name", "unknown"))
+        module_address = item.get("module_address")
+
+        change = item.get("change")
+        if not isinstance(change, dict):
+            actions = ["unknown"]
+            before = None
+            after = None
+            after_unknown = None
+            replace_paths = None
+            before_sensitive = None
+            after_sensitive = None
+        else:
+            raw_actions = change.get("actions", [])
+            actions = (
+                [str(a) for a in raw_actions] if isinstance(raw_actions, list) else ["unknown"]
+            )
+            before = change.get("before") if isinstance(change.get("before"), dict) else None
+            after = change.get("after") if isinstance(change.get("after"), dict) else None
+            after_unknown = (
+                change.get("after_unknown")
+                if isinstance(change.get("after_unknown"), dict)
+                else None
+            )
+            replace_paths = (
+                change.get("replace_paths")
+                if isinstance(change.get("replace_paths"), list)
+                else None
+            )
+            before_sensitive = change.get("before_sensitive")
+            after_sensitive = change.get("after_sensitive")
+
+        action_type = ActionType.from_terraform_actions(actions)
+
+        # Update summary counts
+        match action_type:
+            case ActionType.CREATE:
+                summary.to_create += 1
+            case ActionType.UPDATE:
+                summary.to_update += 1
+            case ActionType.DELETE:
+                summary.to_delete += 1
+            case ActionType.REPLACE:
+                summary.to_replace += 1
+            case ActionType.READ:
+                summary.to_read += 1
+            case ActionType.NOOP:
+                summary.to_noop += 1
+            case ActionType.UNKNOWN:
+                summary.unknown_actions += 1
+
+        if after_unknown and any(v for v in after_unknown.values()):
+            summary.has_unknown_values = True
+
+        resource_changes.append(
+            ResourceChange(
+                address=address,
+                module_address=str(module_address) if module_address else None,
+                mode=mode,
+                type=res_type,
+                name=name,
+                provider_name=provider_name,
+                raw_actions=actions,
+                action=action_type,
+                before=before,
+                after=after,
+                after_unknown=after_unknown,
+                replace_paths=replace_paths,
+                before_sensitive=before_sensitive,
+                after_sensitive=after_sensitive,
+            )
+        )
+
+    return resource_changes, summary