driftsentry 0.1.0__py3-none-any.whl

driftsentry/__init__.py

@@ -0,0 +1,8 @@
+"""DriftSentry — Your infrastructure's immune system.
+
+Detect IaC drift, attribute blame, auto-remediate with PRs.
+Supports Terraform and OpenTofu.
+"""
+
+__version__ = "0.1.0"
+__app_name__ = "driftsentry"

driftsentry/attribution/__init__.py

@@ -0,0 +1 @@
+"""Drift attribution — attribute who caused drift using cloud audit logs."""

driftsentry/attribution/cloudtrail.py

@@ -0,0 +1,260 @@
+"""CloudTrail attributor — queries AWS CloudTrail to determine who caused drift.
+
+Looks up recent CloudTrail events for drifted resources to identify
+the IAM principal, API call, timestamp, and source IP.
+"""
+
+from __future__ import annotations
+
+import datetime
+import logging
+from typing import Any
+
+import boto3
+from botocore.exceptions import ClientError
+
+from driftsentry.core.models import DriftAttribution, DriftItem
+
+logger = logging.getLogger(__name__)
+
+# ─── Resource type to CloudTrail event mapping ──────────────────
+
+# Maps Terraform resource types to the CloudTrail event names that
+# could modify them. This is a best-effort mapping.
+RESOURCE_EVENT_MAP: dict[str, list[str]] = {
+    "aws_instance": [
+        "ModifyInstanceAttribute",
+        "RunInstances",
+        "TerminateInstances",
+        "StopInstances",
+        "StartInstances",
+    ],
+    "aws_security_group": [
+        "AuthorizeSecurityGroupIngress",
+        "AuthorizeSecurityGroupEgress",
+        "RevokeSecurityGroupIngress",
+        "RevokeSecurityGroupEgress",
+        "ModifySecurityGroupRules",
+        "UpdateSecurityGroupRuleDescriptionsIngress",
+        "UpdateSecurityGroupRuleDescriptionsEgress",
+        "CreateSecurityGroup",
+        "DeleteSecurityGroup",
+    ],
+    "aws_s3_bucket": [
+        "PutBucketPolicy",
+        "DeleteBucketPolicy",
+        "PutBucketAcl",
+        "PutBucketVersioning",
+        "PutBucketEncryption",
+        "DeleteBucketEncryption",
+        "PutBucketLogging",
+        "PutPublicAccessBlock",
+        "DeletePublicAccessBlock",
+    ],
+    "aws_iam_role": [
+        "UpdateAssumeRolePolicy",
+        "AttachRolePolicy",
+        "DetachRolePolicy",
+        "PutRolePolicy",
+        "DeleteRolePolicy",
+        "CreateRole",
+        "DeleteRole",
+    ],
+    "aws_iam_policy": [
+        "CreatePolicyVersion",
+        "SetDefaultPolicyVersion",
+        "DeletePolicyVersion",
+        "CreatePolicy",
+        "DeletePolicy",
+    ],
+    "aws_iam_user": [
+        "CreateUser",
+        "DeleteUser",
+        "AttachUserPolicy",
+        "DetachUserPolicy",
+    ],
+    "aws_db_instance": [
+        "ModifyDBInstance",
+        "DeleteDBInstance",
+        "CreateDBInstance",
+    ],
+    "aws_lambda_function": [
+        "UpdateFunctionConfiguration",
+        "UpdateFunctionCode",
+        "CreateFunction",
+        "DeleteFunction",
+        "PublishVersion",
+    ],
+    "aws_ecs_cluster": [
+        "CreateCluster",
+        "DeleteCluster",
+        "UpdateClusterSettings",
+    ],
+    "aws_ecs_service": [
+        "CreateService",
+        "UpdateService",
+        "DeleteService",
+    ],
+}
+
+# Console user agents
+CONSOLE_USER_AGENTS = [
+    "console.amazonaws.com",
+    "signin.amazonaws.com",
+    "Coral/Jakarta",
+    "Coral/Netty4",
+]
+
+
+class CloudTrailAttributor:
+    """Queries CloudTrail to attribute drift to specific IAM principals.
+
+    Uses CloudTrail's `lookup_events` API with resource-based filtering
+    to find who made changes to drifted resources.
+    """
+
+    def __init__(
+        self,
+        region: str = "us-east-1",
+        profile: str | None = None,
+        lookback_hours: int = 168,  # 7 days
+    ) -> None:
+        session_kwargs: dict[str, Any] = {"region_name": region}
+        if profile:
+            session_kwargs["profile_name"] = profile
+
+        session = boto3.Session(**session_kwargs)
+        self._cloudtrail = session.client("cloudtrail")
+        self._lookback_hours = lookback_hours
+
+    def attribute(self, drift_item: DriftItem) -> DriftAttribution | None:
+        """Find who caused drift for a given drift item.
+
+        Returns the most recent relevant CloudTrail event, or None
+        if no attribution could be made.
+        """
+        resource_id = drift_item.resource_id
+        resource_type = drift_item.resource_type
+
+        if not resource_id:
+            return None
+
+        # Get relevant event names for this resource type
+        event_names = RESOURCE_EVENT_MAP.get(resource_type, [])
+        if not event_names:
+            logger.debug(f"No event mapping for {resource_type}")
+            return None
+
+        # Query CloudTrail
+        events = self._lookup_events(resource_id, event_names)
+
+        if not events:
+            return None
+
+        # Return the most recent relevant event
+        event = events[0]
+        user_agent = event.get("userAgent", "")
+
+        return DriftAttribution(
+            principal=self._extract_principal(event),
+            event_name=event.get("eventName"),
+            event_time=event.get("eventTime"),
+            source_ip=event.get("sourceIPAddress"),
+            user_agent=user_agent,
+            is_console_change=any(ua in user_agent for ua in CONSOLE_USER_AGENTS),
+        )
+
+    def _lookup_events(
+        self,
+        resource_id: str,
+        event_names: list[str],
+    ) -> list[dict[str, Any]]:
+        """Query CloudTrail for events related to a resource."""
+        start_time = datetime.datetime.now(tz=datetime.UTC) - datetime.timedelta(
+            hours=self._lookback_hours
+        )
+
+        all_events: list[dict[str, Any]] = []
+
+        try:
+            # Look up by resource name/ID
+            paginator = self._cloudtrail.get_paginator("lookup_events")
+            for page in paginator.paginate(
+                LookupAttributes=[
+                    {
+                        "AttributeKey": "ResourceName",
+                        "AttributeValue": resource_id,
+                    }
+                ],
+                StartTime=start_time,
+                MaxResults=50,
+            ):
+                for event in page.get("Events", []):
+                    if event.get("EventName") in event_names:
+                        all_events.append(self._parse_event(event))
+
+        except ClientError as e:
+            logger.warning(f"CloudTrail lookup failed for {resource_id}: {e}")
+            return []
+
+        # Sort by time, most recent first
+        all_events.sort(key=lambda e: e.get("eventTime", ""), reverse=True)
+        return all_events
+
+    @staticmethod
+    def _parse_event(event: dict[str, Any]) -> dict[str, Any]:
+        """Parse a CloudTrail event into a standardized dict."""
+        import json
+
+        cloud_trail_event = event.get("CloudTrailEvent", "{}")
+        if isinstance(cloud_trail_event, str):
+            try:
+                detail = json.loads(cloud_trail_event)
+            except json.JSONDecodeError:
+                detail = {}
+        else:
+            detail = cloud_trail_event
+
+        return {
+            "eventName": event.get("EventName") or detail.get("eventName"),
+            "eventTime": event.get("EventTime"),
+            "sourceIPAddress": detail.get("sourceIPAddress"),
+            "userAgent": detail.get("userAgent", ""),
+            "userIdentity": detail.get("userIdentity", {}),
+            "requestParameters": detail.get("requestParameters", {}),
+        }
+
+    @staticmethod
+    def _extract_principal(event: dict[str, Any]) -> str:
+        """Extract a human-readable principal name from CloudTrail event."""
+        identity = event.get("userIdentity", {})
+
+        # Check for assumed role with session name
+        session_context = identity.get("sessionContext", {})
+        session_issuer = session_context.get("sessionIssuer", {})
+
+        arn = identity.get("arn", "")
+
+        # If it's an assumed role, show the role name and session name
+        if identity.get("type") == "AssumedRole":
+            role_name = session_issuer.get("userName", "")
+            # ARN format: arn:aws:sts::123456:assumed-role/RoleName/SessionName
+            parts = arn.split("/")
+            session_name = parts[-1] if len(parts) > 2 else ""
+            if session_name and role_name:
+                return f"{role_name}/{session_name}"
+            return str(role_name or arn)
+
+        # IAM user
+        if identity.get("type") == "IAMUser":
+            return str(identity.get("userName") or arn)
+
+        # Root account
+        if identity.get("type") == "Root":
+            return "root"
+
+        # AWS service
+        if identity.get("type") == "AWSService":
+            return str(identity.get("invokedBy") or "aws-service")
+
+        return str(arn or "unknown")

driftsentry/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package for DriftSentry."""

driftsentry/cli/main.py

@@ -0,0 +1,54 @@
+"""DriftSentry CLI — main entry point.
+
+Usage:
+    driftsentry scan --state-file terraform.tfstate
+    driftsentry report --format html --output drift-report.html
+    driftsentry remediate --mode both --create-pr
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from driftsentry import __version__
+from driftsentry.cli.remediate import remediate
+from driftsentry.cli.report import report
+from driftsentry.cli.scan import scan
+
+console = Console()
+
+app = typer.Typer(
+    name="driftsentry",
+    help=(
+        "🛡️ DriftSentry — Your infrastructure's immune system.\n\n"
+        "Detect IaC drift, attribute blame, auto-remediate with PRs.\n"
+        "Supports Terraform and OpenTofu."
+    ),
+    add_completion=True,
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+
+# Register sub-commands
+app.command(name="scan", help="Scan for infrastructure drift")(scan)
+app.command(name="report", help="Generate a drift report from the last scan")(report)
+app.command(name="remediate", help="Generate remediation artifacts and optionally create a PR")(
+    remediate
+)
+
+
+@app.command()
+def version() -> None:
+    """Show DriftSentry version."""
+    console.print(f"[bold cyan]DriftSentry[/] v{__version__}")
+
+
+@app.callback()
+def main_callback() -> None:
+    """DriftSentry — IaC Drift Detection & Auto-Remediation Engine."""
+    pass
+
+
+if __name__ == "__main__":
+    app()

driftsentry/cli/remediate.py

@@ -0,0 +1,195 @@
+"""Remediate command — generate remediation artifacts and optionally create PRs."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from driftsentry.cli.scan import get_last_scan_result
+from driftsentry.core.models import DriftResult, IaCTool, RemediationMode
+from driftsentry.remediation.generator import RemediationGenerator, RemediationOutput
+
+console = Console()
+
+
+def remediate(
+    input_file: str | None = typer.Option(
+        None,
+        "--input",
+        "-i",
+        help="Path to a saved scan result JSON file",
+    ),
+    mode: str = typer.Option(
+        "both",
+        "--mode",
+        "-m",
+        help="Remediation mode: import, revert, both",
+    ),
+    output_dir: str = typer.Option(
+        "./driftsentry-remediation",
+        "--output-dir",
+        "-o",
+        help="Directory to write remediation artifacts",
+    ),
+    iac_tool: str = typer.Option(
+        "terraform",
+        "--iac-tool",
+        help="IaC tool: terraform, opentofu",
+    ),
+    create_pr: bool = typer.Option(
+        False,
+        "--create-pr",
+        help="Create a GitHub PR with remediation code",
+    ),
+    github_repo: str | None = typer.Option(
+        None,
+        "--repo",
+        help="GitHub repo (owner/name) for PR creation",
+    ),
+    github_token: str | None = typer.Option(
+        None,
+        "--github-token",
+        help="GitHub token (or set GITHUB_TOKEN env var)",
+        envvar="GITHUB_TOKEN",
+    ),
+    base_branch: str = typer.Option(
+        "main",
+        "--base-branch",
+        help="Base branch for PRs",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Preview remediation without writing files",
+    ),
+    config_file: str | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Path to .driftsentry.yaml config file",
+    ),
+) -> None:
+    """Generate remediation artifacts for drifted resources.
+
+    Supports three modes:
+    - import: Generate terraform import commands for unmanaged resources
+    - revert: Generate revert plan for changed resources
+    - both: Generate both (default, configurable per-resource)
+
+    Examples:
+
+        driftsentry remediate --input scan-result.json --mode both
+
+        driftsentry remediate --mode import --iac-tool opentofu
+
+        driftsentry remediate --create-pr --repo myorg/infra
+    """
+    # Load result
+    result = _load_result(input_file)
+    if result is None:
+        console.print(
+            "[bold red]Error:[/] No scan result available. "
+            "Run [bold]driftsentry scan[/] first or use [bold]--input[/]."
+        )
+        raise typer.Exit(code=1)
+
+    if not result.has_drift:
+        console.print("[bold green]✅ No drift to remediate![/]")
+        return
+
+    # Generate remediation
+    generator = RemediationGenerator(
+        mode=RemediationMode(mode),
+        iac_tool=IaCTool(iac_tool),
+        output_dir=output_dir,
+        dry_run=dry_run,
+    )
+
+    output = generator.generate(result)
+
+    # Display summary
+    if dry_run:
+        console.print("[bold yellow]🏃 Dry run — no files written[/]\n")
+
+    if output.import_commands:
+        console.print(f"[bold]📥 Import commands:[/] {len(output.import_commands)}")
+        for cmd in output.import_commands[:5]:
+            console.print(f"  [dim]$ {cmd}[/]")
+        if len(output.import_commands) > 5:
+            console.print(f"  [dim]... and {len(output.import_commands) - 5} more[/]")
+        console.print()
+
+    if output.revert_items:
+        console.print(f"[bold]🔄 Revert items:[/] {len(output.revert_items)}")
+        for item in output.revert_items[:5]:
+            console.print(f"  [dim]{item['resource']} ({len(item['changes'])} changes)[/]")
+        console.print()
+
+    if output.deleted_resources:
+        console.print(f"[bold]🗑️  Deleted resources:[/] {len(output.deleted_resources)}")
+        for addr in output.deleted_resources[:5]:
+            console.print(f"  [dim]{addr}[/]")
+        console.print()
+
+    if not dry_run:
+        console.print(f"[green]✅ Remediation artifacts written to {output_dir}/[/]")
+        for f in sorted(output.files_created):
+            console.print(f"  [dim]• {f}[/]")
+
+    # Create PR if requested
+    if create_pr and not dry_run:
+        _create_pr(result, output, github_repo, github_token, base_branch)
+
+
+def _create_pr(
+    result: DriftResult,
+    remediation_output: RemediationOutput,
+    repo: str | None,
+    token: str | None,
+    base_branch: str,
+) -> None:
+    """Create a GitHub PR with remediation code."""
+    if not repo:
+        console.print("[bold red]Error:[/] --repo is required for PR creation")
+        raise typer.Exit(code=1)
+
+    if not token:
+        console.print(
+            "[bold red]Error:[/] GitHub token required. "
+            "Use --github-token or set GITHUB_TOKEN env var."
+        )
+        raise typer.Exit(code=1)
+
+    try:
+        from driftsentry.remediation.pr_creator import PRCreator
+
+        creator = PRCreator(
+            github_token=token,
+            repo=repo,
+            base_branch=base_branch,
+        )
+
+        pr_url = creator.create_pr(result, remediation_output)
+        console.print(f"\n[bold green]✅ Created PR:[/] {pr_url}")
+    except ImportError:
+        console.print("[bold red]Error:[/] PyGithub not installed. Run: pip install pygithub")
+        raise typer.Exit(code=1) from None
+    except Exception as e:
+        console.print(f"[bold red]Error creating PR:[/] {e}")
+        raise typer.Exit(code=1) from None
+
+
+def _load_result(input_file: str | None) -> DriftResult | None:
+    """Load a DriftResult from a file or the last scan."""
+    if input_file:
+        path = Path(input_file)
+        if not path.exists():
+            console.print(f"[bold red]Error not found:[/] {input_file}")
+            raise typer.Exit(code=1)
+        data = json.loads(path.read_text())
+        return DriftResult(**data)
+
+    return get_last_scan_result()

driftsentry/cli/report.py

@@ -0,0 +1,113 @@
+"""Report command — generate drift reports in various formats."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from driftsentry.cli.scan import get_last_scan_result
+from driftsentry.core.models import DriftResult
+from driftsentry.output.html import HTMLFormatter
+from driftsentry.output.json_fmt import JSONFormatter
+from driftsentry.output.markdown import MarkdownFormatter
+from driftsentry.output.table import TableFormatter
+
+console = Console()
+
+
+def report(
+    input_file: str | None = typer.Option(
+        None,
+        "--input",
+        "-i",
+        help="Path to a saved scan result JSON file (from driftsentry scan --save)",
+    ),
+    output_format: str = typer.Option(
+        "table",
+        "--format",
+        "-f",
+        help="Output format: table, json, html, markdown",
+    ),
+    output_file: str | None = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Path to write the report file (required for html/markdown)",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Show detailed attribute diffs",
+    ),
+) -> None:
+    """Generate a drift report from a saved scan result or the last scan.
+
+    Examples:
+
+        driftsentry report --format html --output drift-report.html
+
+        driftsentry report --input scan-result.json --format markdown --output report.md
+
+        driftsentry report --format json
+    """
+    # Load the result
+    result = _load_result(input_file)
+    if result is None:
+        console.print(
+            "[bold red]Error:[/] No scan result available. "
+            "Run [bold]driftsentry scan[/] first or use [bold]--input[/] "
+            "to load a saved result."
+        )
+        raise typer.Exit(code=1)
+
+    # Generate report
+    if output_format == "table":
+        formatter = TableFormatter(console=console, verbose=verbose)
+        formatter.render(result)
+
+    elif output_format == "json":
+        formatter_json = JSONFormatter(pretty=True)
+        if output_file:
+            with open(output_file, "w") as f:
+                formatter_json.render(result, output=f)
+            console.print(f"[green]✅ JSON report written to {output_file}[/]")
+        else:
+            formatter_json.render(result)
+
+    elif output_format == "html":
+        if not output_file:
+            output_file = "driftsentry-report.html"
+        formatter_html = HTMLFormatter()
+        formatter_html.render(result, output_path=output_file)
+        console.print(f"[green]✅ HTML report written to {output_file}[/]")
+
+    elif output_format == "markdown":
+        formatter_md = MarkdownFormatter()
+        if output_file:
+            formatter_md.render(result, output_path=output_file)
+            console.print(f"[green]✅ Markdown report written to {output_file}[/]")
+        else:
+            md = formatter_md.render(result)
+            console.print(md)
+
+    else:
+        console.print(f"[bold red]Error:[/] Unknown format: {output_format}")
+        raise typer.Exit(code=1)
+
+
+def _load_result(input_file: str | None) -> DriftResult | None:
+    """Load a DriftResult from a file or the last scan."""
+    if input_file:
+        path = Path(input_file)
+        if not path.exists():
+            console.print(f"[bold red]Error:[/] File not found: {input_file}")
+            raise typer.Exit(code=1)
+
+        data = json.loads(path.read_text())
+        return DriftResult(**data)
+
+    return get_last_scan_result()