driftwatch-cli 0.1.0__py3-none-any.whl

drift_engine/notifications.py

@@ -0,0 +1,114 @@
+import os
+import smtplib
+import requests
+from email.mime.text import MIMEText
+from email.mime.multipart import MIMEMultipart
+
+def _format_drift_results(drift_results: list, include_ai: bool = True) -> list:
+    lines = []
+    for result in drift_results:
+        lines.append(
+            f"[{result.drift_type.value}] {result.resource_type}: "
+            f"{result.resource_name} ({result.resource_id})"
+        )
+        if result.diff:
+            for attr, values in result.diff.items():
+                lines.append(
+                    f"    - {attr}: Expected '{values['terraform']}', "
+                    f"Found '{values['live']}'"
+                )
+        if include_ai and getattr(result, "ai_analysis", ""):
+            lines.append(f"    - AI Analysis: {result.ai_analysis}")
+        lines.append("")
+    return lines
+
+def send_telegram_alert(message: str):
+    bot_token = os.environ.get("TELEGRAM_BOT_TOKEN")
+    chat_id = os.environ.get("TELEGRAM_CHAT_ID")
+    
+    if not bot_token or not chat_id:
+        print("Telegram credentials missing in environment variables.")
+        return
+        
+    url = f"https://api.telegram.org/bot{bot_token}/sendMessage"
+    payload = {
+        "chat_id": chat_id,
+        "text": message
+    }
+    
+    try:
+        response = requests.post(url, json=payload, timeout=15)
+        response.raise_for_status()
+        print("Telegram alert sent successfully.")
+    except Exception as e:
+        print(f"Failed to send Telegram alert: {e}")
+
+def send_slack_alert(webhook_url: str, drift_results: list):
+    if not webhook_url:
+        return
+
+    message_lines = ["*DriftWatch Alert: Infrastructure Drift Detected!*"]
+    message_lines.extend(_format_drift_results(drift_results))
+
+    payload = {"text": "\n".join(message_lines)}
+    
+    try:
+        response = requests.post(webhook_url, json=payload, timeout=15)
+        response.raise_for_status()
+        print("Slack alert sent successfully.")
+    except Exception as e:
+        print(f"Failed to send Slack alert: {e}")
+
+def send_email_alert(smtp_server: str, smtp_port: int, sender_email: str, sender_password: str, recipient_email: str, drift_results: list):
+    if not all([smtp_server, sender_email, sender_password, recipient_email]):
+        return
+
+    msg = MIMEMultipart()
+    msg['From'] = sender_email
+    msg['To'] = recipient_email
+    msg['Subject'] = "DriftWatch Alert: Infrastructure Drift Detected"
+
+    body_lines = ["DriftWatch has detected changes in your infrastructure:\n"]
+    body_lines.extend(_format_drift_results(drift_results))
+
+    msg.attach(MIMEText("\n".join(body_lines), 'plain'))
+
+    try:
+        server = smtplib.SMTP(smtp_server, smtp_port, timeout=15)
+        server.starttls()
+        server.login(sender_email, sender_password)
+        server.send_message(msg)
+        server.quit()
+        print("Email alert sent successfully.")
+    except Exception as e:
+        print(f"Failed to send Email alert: {e}")
+
+def process_alerts(drift_results: list):
+    if not drift_results:
+        return
+        
+    slack_webhook = os.environ.get("SLACK_WEBHOOK_URL")
+    smtp_server = os.environ.get("SMTP_SERVER", "smtp.gmail.com")
+    smtp_port = int(os.environ.get("SMTP_PORT", 587))
+    sender_email = os.environ.get("SENDER_EMAIL")
+    sender_password = os.environ.get("SENDER_PASSWORD")
+    recipient_email = os.environ.get("RECIPIENT_EMAIL")
+    bot_token = os.environ.get("TELEGRAM_BOT_TOKEN")
+    chat_id = os.environ.get("TELEGRAM_CHAT_ID")
+
+    if slack_webhook:
+        send_slack_alert(slack_webhook, drift_results)
+    
+    if sender_email and sender_password and recipient_email:
+        send_email_alert(smtp_server, smtp_port, sender_email, sender_password, recipient_email, drift_results)
+
+    if bot_token and chat_id:
+        message_lines = ["DriftWatch Alert Summary:"]
+        message_lines.extend(_format_drift_results(drift_results, include_ai=False))
+            
+        telegram_message = "\n".join(message_lines)
+        
+        if len(telegram_message) > 4000:
+            telegram_message = telegram_message[:4000] + "\n...[TRUNCATED]"
+            
+        send_telegram_alert(telegram_message)

drift_engine/remediation.py

@@ -0,0 +1,273 @@
+import os
+import boto3
+
+def get_environment_tag(tags):
+    if not tags:
+        return 'unknown'
+    if isinstance(tags, dict):
+        value = tags.get('Environment')
+        return value.lower() if value else 'unknown'
+    for tag in tags:
+        if isinstance(tag, dict) and tag.get('Key') == 'Environment':
+            return tag.get('Value').lower()
+    return 'unknown'
+
+def confirm_action(action_desc: str, env: str = 'unknown', is_disruptive: bool = False) -> bool:
+    if env in ['dev', 'staging']:
+        print(f"[*] [{env.upper()}] Auto-approving: {action_desc}")
+        return True
+
+    print(f"[!] [{env.upper()}] Protection Active. Manual action required.")
+    if is_disruptive:
+        print("[!] WARNING: This is a disruptive action -> Downtime risk!")
+
+    while True:
+        choice = input(f"⚠️ {action_desc}. Proceed? (y/n): ").strip().lower()
+        if choice in ['y', 'yes']:
+            return True
+        elif choice in ['n', 'no']:
+            return False
+        print("Invalid input. Please enter 'y' or 'n'.")
+
+def remediate_ec2_instance_type(region: str, instance_id: str, expected_type: str, env: str):
+    ec2 = boto3.client('ec2', region_name=region)
+    try:
+        desc = ec2.describe_instances(InstanceIds=[instance_id])
+        reservations = desc.get('Reservations', [])
+        if not reservations or not reservations[0].get('Instances'):
+            print(f"❌ EC2 instance {instance_id} not found.")
+            return
+        instance_info = reservations[0]['Instances'][0]
+        
+        if instance_info.get('RootDeviceType') != 'ebs':
+            print(f"❌ Cannot modify instance {instance_id}: Root device is not EBS-backed (found: {instance_info.get('RootDeviceType')}).")
+            return
+            
+        if instance_info.get('InstanceLifecycle') == 'spot':
+            print(f"❌ Cannot modify instance {instance_id}: Spot instances do not support instance type modification.")
+            return
+
+        state = instance_info.get('State', {}).get('Name')
+        if state not in ['running', 'stopped']:
+            print(f"❌ Cannot modify instance {instance_id}: Instance state is '{state}'. Must be 'running' or 'stopped'.")
+            return
+    except Exception as e:
+        print(f"❌ Pre-flight check failed for EC2 {instance_id}: {e}")
+        return
+
+    if not confirm_action(f"Change EC2 {instance_id} instance type to {expected_type}", env, True):
+        print(f"⏭️  Skipped remediation for EC2 {instance_id}")
+        return
+
+    was_running = (state == 'running')
+    stopped = False
+    try:
+        if was_running:
+            print(f"Stopping instance {instance_id} for remediation...")
+            ec2.stop_instances(InstanceIds=[instance_id])
+            waiter = ec2.get_waiter('instance_stopped')
+            waiter.wait(InstanceIds=[instance_id])
+            stopped = True
+            
+        print(f"Modifying instance type to {expected_type}...")
+        ec2.modify_instance_attribute(
+            InstanceId=instance_id,
+            InstanceType={'Value': expected_type}
+        )
+        
+        if was_running:
+            print(f"Restarting instance {instance_id}...")
+            ec2.start_instances(InstanceIds=[instance_id])
+            stopped = False
+            
+        print(f"✅ [REMEDIATED] Successfully remediated {instance_id} back to {expected_type}")
+    except Exception as e:
+        print(f"❌ Failed to remediate EC2 {instance_id}: {e}")
+        if stopped:
+            try:
+                print(f"Attempting to restart EC2 {instance_id} after failed remediation...")
+                ec2.start_instances(InstanceIds=[instance_id])
+            except Exception as restart_error:
+                print(f"❌ Failed to restart EC2 {instance_id}: {restart_error}")
+
+def remediate_security_group(region: str, sg_id: str, diff_data: dict, env: str):
+    ec2 = boto3.client('ec2', region_name=region)
+    
+    if "ingress" in diff_data:
+        expected_ingress = diff_data["ingress"].get("terraform", [])
+        live_ingress = diff_data["ingress"].get("live", [])
+        
+        print(f"Checking Security Group {sg_id} for Ingress drift...")
+        for live_rule in live_ingress:
+            if live_rule not in expected_ingress:
+                from_p = live_rule.get('from_port')
+                to_p = live_rule.get('to_port')
+                is_ssh = (from_p == 22 or to_p == 22 or (isinstance(from_p, int) and isinstance(to_p, int) and from_p <= 22 <= to_p))
+                if is_ssh:
+                    print("⚠️ CAUTION: Rule being revoked includes SSH (Port 22). Active connections may be terminated.")
+                if confirm_action(f"Revoke unauthorized Inbound rule (Port {from_p}) in {sg_id}", env, is_ssh):
+                    try:
+                        ec2.revoke_security_group_ingress(GroupId=sg_id, IpPermissions=[{
+                            'IpProtocol': live_rule['protocol'], 'FromPort': live_rule['from_port'], 'ToPort': live_rule['to_port'],
+                            'IpRanges': [{'CidrIp': c} for c in live_rule.get('cidr_blocks', []) if c]
+                        }])
+                        print(f"✅ [REMEDIATED] Removed unauthorized Inbound Rule from {sg_id}")
+                    except Exception as e:
+                        print(f"❌ Failed to revoke Inbound rule: {e}")
+
+        for exp_rule in expected_ingress:
+            if exp_rule not in live_ingress:
+                if confirm_action(f"Restore missing IaC Inbound rule (Port {exp_rule.get('from_port')}) in {sg_id}", env, False):
+                    try:
+                        ec2.authorize_security_group_ingress(GroupId=sg_id, IpPermissions=[{
+                            'IpProtocol': exp_rule['protocol'], 'FromPort': exp_rule['from_port'], 'ToPort': exp_rule['to_port'],
+                            'IpRanges': [{'CidrIp': c} for c in exp_rule.get('cidr_blocks', []) if c]
+                        }])
+                        print(f"✅ [REMEDIATED] Restored missing Inbound Rule to {sg_id}")
+                    except Exception as e:
+                        print(f"❌ Failed to restore Inbound rule: {e}")
+
+    if "egress" in diff_data:
+        expected_egress = diff_data["egress"].get("terraform", [])
+        live_egress = diff_data["egress"].get("live", [])
+        
+        print(f"Checking Security Group {sg_id} for Egress drift...")
+        for live_rule in live_egress:
+            if live_rule not in expected_egress:
+                if confirm_action(f"Revoke unauthorized Outbound rule (Port {live_rule.get('from_port')}) in {sg_id}", env, False):
+                    try:
+                        ec2.revoke_security_group_egress(GroupId=sg_id, IpPermissions=[{
+                            'IpProtocol': live_rule['protocol'], 'FromPort': live_rule['from_port'], 'ToPort': live_rule['to_port'],
+                            'IpRanges': [{'CidrIp': c} for c in live_rule.get('cidr_blocks', []) if c]
+                        }])
+                        print(f"✅ [REMEDIATED] Removed unauthorized Outbound Rule from {sg_id}")
+                    except Exception as e:
+                        print(f"❌ Failed to revoke Outbound rule: {e}")
+
+        for exp_rule in expected_egress:
+            if exp_rule not in live_egress:
+                if confirm_action(f"Restore missing IaC Outbound rule (Port {exp_rule.get('from_port')}) in {sg_id}", env, False):
+                    try:
+                        ec2.authorize_security_group_egress(GroupId=sg_id, IpPermissions=[{
+                            'IpProtocol': exp_rule['protocol'], 'FromPort': exp_rule['from_port'], 'ToPort': exp_rule['to_port'],
+                            'IpRanges': [{'CidrIp': c} for c in exp_rule.get('cidr_blocks', []) if c]
+                        }])
+                        print(f"✅ [REMEDIATED] Restored missing Outbound Rule to {sg_id}")
+                    except Exception as e:
+                        print(f"❌ Failed to restore Outbound rule: {e}")
+
+    if "description" in diff_data:
+        print(f"⚠️  Description drift detected for {sg_id}. SG descriptions cannot be updated dynamically in AWS EC2 API. Please update via Terraform.")
+
+def remediate_s3_bucket(bucket_name: str, diff_data: dict, env: str):
+    s3 = boto3.client('s3')
+    
+    if "tags" in diff_data:
+        expected_tags = diff_data["tags"].get("terraform", {})
+        if confirm_action(f"Restore IaC tags for S3 Bucket '{bucket_name}'", env, False):
+            try:
+                tag_set = [{'Key': k, 'Value': v} for k, v in expected_tags.items()]
+                s3.put_bucket_tagging(Bucket=bucket_name, Tagging={'TagSet': tag_set})
+                print(f"✅ [REMEDIATED] Successfully restored tags for {bucket_name}")
+            except Exception as e:
+                print(f"❌ Failed to restore S3 tags: {e}")
+                
+    if "bucket" in diff_data:
+        print(f"⚠️  Bucket name drift detected for {bucket_name}. S3 buckets cannot be renamed. Please recreate via Terraform.")
+
+def remediate_rds_instance(region: str, db_id: str, diff_data: dict, env: str, apply_immediately: bool = False):
+    rds = boto3.client('rds', region_name=region)
+    updates = {}
+    
+    if "instance_class" in diff_data:
+        updates['DBInstanceClass'] = diff_data["instance_class"]["terraform"]
+    if "allocated_storage" in diff_data:
+        updates['AllocatedStorage'] = diff_data["allocated_storage"]["terraform"]
+        
+    if updates:
+        mode_desc = "immediately (may force reboot)" if apply_immediately else "during next maintenance window"
+        if confirm_action(f"Modify RDS {db_id} ({mode_desc}) with configs: {updates}", env, apply_immediately):
+            try:
+                updates['ApplyImmediately'] = apply_immediately
+                rds.modify_db_instance(DBInstanceIdentifier=db_id, **updates)
+                print(f"✅ [REMEDIATED] Initiated RDS modification for {db_id} (ApplyImmediately={apply_immediately}).")
+            except Exception as e:
+                print(f"❌ Failed to remediate RDS {db_id}: {e}")
+
+def remediate_lambda_function(region: str, func_name: str, diff_data: dict, env: str):
+    lam = boto3.client('lambda', region_name=region)
+    updates = {}
+    
+    if "runtime" in diff_data:
+        updates['Runtime'] = diff_data["runtime"]["terraform"]
+    if "handler" in diff_data:
+        updates['Handler'] = diff_data["handler"]["terraform"]
+    if "memory_size" in diff_data:
+        updates['MemorySize'] = diff_data["memory_size"]["terraform"]
+    if "timeout" in diff_data:
+        updates['Timeout'] = diff_data["timeout"]["terraform"]
+    
+    if updates:
+        if confirm_action(f"Modify Lambda {func_name} with {updates}", env, False):
+            try:
+                lam.update_function_configuration(FunctionName=func_name, **updates)
+                print(f"✅ [REMEDIATED] Successfully modified Lambda {func_name}")
+            except Exception as e:
+                print(f"❌ Failed to remediate Lambda {func_name}: {e}")
+
+def remediate_iam_role(role_name: str, diff_data: dict, env: str):
+    iam = boto3.client('iam')
+    expected_policies = diff_data.get("attached_policies", {}).get("terraform", [])
+    live_policies = diff_data.get("attached_policies", {}).get("live", [])
+
+    print(f"Checking IAM Role {role_name} for unauthorized policies...")
+    for live_policy in live_policies:
+        if live_policy not in expected_policies:
+            if confirm_action(f"Detach unauthorized policy '{live_policy}' from Role '{role_name}'", env, False):
+                try:
+                    iam.detach_role_policy(RoleName=role_name, PolicyArn=live_policy)
+                    print(f"✅ [REMEDIATED] Successfully detached {live_policy} from {role_name}")
+                except Exception as e:
+                    print(f"❌ Failed to detach policy from {role_name}: {e}")
+
+    for exp_policy in expected_policies:
+        if exp_policy not in live_policies:
+            if confirm_action(f"Attach missing IaC policy '{exp_policy}' to Role '{role_name}'", env, False):
+                try:
+                    iam.attach_role_policy(RoleName=role_name, PolicyArn=exp_policy)
+                    print(f"✅ [REMEDIATED] Successfully attached {exp_policy} to {role_name}")
+                except Exception as e:
+                    print(f"❌ Failed to attach policy to {role_name}: {e}")
+
+def process_remediation(drift_results: list):
+    region = os.environ.get("AWS_DEFAULT_REGION", "ap-south-1")
+    for result in drift_results:
+        attrs = result.live_attributes or result.tf_attributes or {}
+        tags = attrs.get('tags', {})
+        env = get_environment_tag(tags)
+
+        if result.drift_type.value == "MODIFIED":
+            print(f"\n--- Drift Detected: {result.resource_type} ({result.resource_id}) ---")
+            
+            if result.resource_type == "aws_instance" and "instance_type" in result.diff:
+                expected_type = result.diff["instance_type"]["terraform"]
+                remediate_ec2_instance_type(region, result.resource_id, expected_type, env)
+            
+            elif result.resource_type == "aws_security_group":
+                remediate_security_group(region, result.resource_id, result.diff, env)
+
+            elif result.resource_type == "aws_s3_bucket":
+                remediate_s3_bucket(result.resource_id, result.diff, env)
+                
+            elif result.resource_type == "aws_db_instance":
+                remediate_rds_instance(region, result.resource_id, result.diff, env, apply_immediately=False)
+                
+            elif result.resource_type == "aws_lambda_function":
+                remediate_lambda_function(region, result.resource_id, result.diff, env)
+
+            elif result.resource_type == "aws_iam_role":
+                remediate_iam_role(result.resource_id, result.diff, env)
+                
+        elif result.drift_type.value in ["MISSING", "UNMANAGED"]:
+            print(f"\n--- {result.drift_type.value} Resource Detected: {result.resource_type} ({result.resource_id}) ---")
+            print(f"⚠️  Auto-remediation for {result.drift_type.value} resources is not executed directly. Please review the suggested Terraform template/import commands to reconcile.")

drift_engine/tf_parser.py

@@ -0,0 +1,70 @@
+import json
+
+def load_terraform_state(state_path: str) -> dict:
+    try:
+        with open(state_path) as f:
+            state = json.load(f)
+    except FileNotFoundError:
+        print(f"Error: Terraform state file not found at '{state_path}'")
+        return {}
+    except json.JSONDecodeError:
+        print(f"Error: Terraform state file at '{state_path}' is corrupted or invalid JSON.")
+        return {}
+        
+    resources = {}
+    
+    for resource in state.get("resources", []):
+        r_type = resource["type"]
+        
+        if r_type == "archive_file":
+            continue
+            
+        for instance in resource.get("instances", []):
+            attrs = instance.get("attributes", {})
+            
+            if r_type == "aws_iam_role_policy_attachment":
+                role_name = attrs.get("role")
+                policy_arn = attrs.get("policy_arn")
+                if role_name and policy_arn:
+                    if role_name not in resources:
+                        resources[role_name] = {
+                            "type": "aws_iam_role", 
+                            "name": role_name, 
+                            "attributes": {"id": role_name, "name": role_name, "attached_policies": []}
+                        }
+                    if "attached_policies" not in resources[role_name]["attributes"]:
+                        resources[role_name]["attributes"]["attached_policies"] = []
+                    resources[role_name]["attributes"]["attached_policies"].append(policy_arn)
+                    resources[role_name]["attributes"]["attached_policies"].sort()
+                continue
+
+            resource_id = attrs.get("id")
+            
+            tags = attrs.get("tags", {})
+            if tags and tags.get("Name"):
+                name = tags.get("Name")
+            elif r_type == "aws_lambda_function":
+                name = attrs.get("function_name", "Unknown")
+            elif r_type == "aws_db_instance":
+                name = attrs.get("identifier", "Unknown")
+            elif r_type == "aws_iam_role":
+                name = attrs.get("name", "Unknown")
+                if "attached_policies" not in attrs:
+                    attrs["attached_policies"] = []
+            else:
+                name = "Unknown"
+            
+            if resource_id:
+                if resource_id in resources and r_type == "aws_iam_role":
+                    existing_policies = resources[resource_id]["attributes"].get("attached_policies", [])
+                    attrs["attached_policies"] = sorted(set(
+                        attrs.get("attached_policies", []) + existing_policies
+                    ))
+                    
+                resources[resource_id] = {
+                    "type": r_type, 
+                    "name": name, 
+                    "attributes": attrs
+                }
+                
+    return resources

driftwatch/cli.py

@@ -0,0 +1,194 @@
+import os
+import typer
+import boto3
+from datetime import datetime
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from drift_engine.core import detect_drift, get_severity
+from drift_engine.aws_client import get_resource_cost
+from drift_engine.explain import get_drift_explanation, get_deterministic_remediation_suggestion
+from drift_engine.models import DriftType
+from drift_engine.notifications import process_alerts
+from drift_engine.database import save_drift_to_db
+from drift_engine.remediation import process_remediation
+
+app = typer.Typer(help="DriftWatch CLI - Detect, Explain, and Remediate Terraform Infrastructure Drift.")
+
+SEVERITY_RANK = {"LOW": 0, "MEDIUM": 1, "HIGH": 2, "CRITICAL": 3}
+
+def _resolve_region(region: str = None) -> str:
+    actual_region = region or os.environ.get("AWS_DEFAULT_REGION")
+    if not actual_region:
+        try:
+            actual_region = boto3.Session().region_name
+        except Exception:
+            actual_region = None
+    return actual_region
+
+def _run_scan(state_path: str, region: str) -> tuple:
+    os.environ["TF_STATE_PATH"] = state_path
+    os.environ["AWS_DEFAULT_REGION"] = region
+    return detect_drift(state_path, region)
+
+def _render_report(results: list, total_scanned: int) -> tuple[str, int, int]:
+    current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    typer.echo("=== DRIFTWATCH SCAN REPORT ===")
+    typer.echo(f"Scan time: {current_time} | Resources scanned: {total_scanned}\n")
+
+    if not results:
+        typer.secho("No drift detected. Infrastructure matches IaC.", fg=typer.colors.GREEN)
+        return "LOW", 0, 0
+
+    highest_severity_found = "LOW"
+    crit_count = 0
+    high_count = 0
+
+    for r in results:
+        severity = get_severity(r.resource_type, r.drift_type, r.diff)
+
+        if SEVERITY_RANK.get(severity, 0) > SEVERITY_RANK.get(highest_severity_found, 0):
+            highest_severity_found = severity
+
+        if severity == "CRITICAL":
+            crit_count += 1
+            color = typer.colors.RED
+        elif severity == "HIGH":
+            high_count += 1
+            color = typer.colors.YELLOW
+        else:
+            color = typer.colors.BLUE
+
+        typer.secho(f"[{r.drift_type.value}] {r.resource_type}: {r.resource_id}", fg=color, bold=True)
+        ai_text = ""
+
+        if r.drift_type == DriftType.UNMANAGED and r.resource_type == "aws_instance":
+            cost = "{:,.2f}".format(get_resource_cost(r.resource_id))
+            inst_type = r.live_attributes.get("instance_type", "unknown")
+            typer.echo(f"  Type: {inst_type} (created manually in console)")
+            typer.echo(f"  Severity: {severity} | Cost: +${cost}/month (untracked)")
+            ai_text = get_drift_explanation(r.resource_type, r.resource_id, r.live_attributes, r.drift_type.value)
+        elif r.diff:
+            typer.echo(f"  Severity: {severity}")
+            for attr, vals in r.diff.items():
+                typer.echo(f"  Attribute: {attr}")
+                typer.echo(f"  Terraform: {vals.get('terraform')}")
+                typer.echo(f"  Live AWS:  {vals.get('live')}")
+            ai_text = get_drift_explanation(r.resource_type, r.resource_id, r.diff, r.drift_type.value)
+        else:
+            typer.echo(f"  Severity: {severity}")
+            ai_text = get_drift_explanation(r.resource_type, r.resource_id, {"status": "missing"}, r.drift_type.value)
+
+        if ai_text:
+            typer.echo(f"  AI Analysis: {ai_text}\n")
+            r.ai_analysis = ai_text
+        else:
+            typer.echo("\n")
+
+    typer.echo(f"Total drift found: {len(results)} resources  |  CRITICAL: {crit_count}  HIGH: {high_count}\n")
+    return highest_severity_found, crit_count, high_count
+
+def _dispatch_alerts(results: list):
+    process_alerts(results)
+    save_drift_to_db(results)
+
+def _check_gate(highest_severity_found: str, fail_on: str = None):
+    if fail_on and SEVERITY_RANK.get(highest_severity_found, 0) >= SEVERITY_RANK.get(fail_on.upper(), 0):
+        typer.secho(
+            f"\nBUILD FAILED: highest severity found is {highest_severity_found} (gate: {fail_on.upper()})",
+            fg=typer.colors.RED, bold=True,
+        )
+        raise typer.Exit(code=1)
+
+@app.command()
+def scan(
+    state: str = typer.Option("terraform/terraform.tfstate", help="Path to Terraform state file."),
+    region: str = typer.Option(None, help="Target AWS region."),
+    fail_on: str = typer.Option(None, help="Severity threshold to trigger non-zero exit code.")
+):
+    """Scan infrastructure against Terraform state and identify drift."""
+    actual_region = _resolve_region(region)
+    if not actual_region:
+        typer.secho("No AWS region found. Pass --region or set AWS_DEFAULT_REGION.", fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+    typer.echo(f"Scanning AWS Infrastructure in {actual_region}...\n")
+    try:
+        results, total_scanned = _run_scan(state, actual_region)
+        highest_severity, _, _ = _render_report(results, total_scanned)
+        
+        if results:
+            _dispatch_alerts(results)
+            typer.echo("Tip: run 'driftwatch remediate <resource_id>' to fix a specific resource.\n")
+            
+        _check_gate(highest_severity, fail_on)
+    except typer.Exit:
+        raise
+    except Exception as e:
+        typer.secho(f"Error during execution: {e}", fg=typer.colors.RED)
+        raise typer.Exit(code=1)
+
+@app.command()
+def explain(
+    resource_id: str,
+    state: str = typer.Option("terraform/terraform.tfstate", help="Path to Terraform state file."),
+    region: str = typer.Option(None, help="Target AWS region.")
+):
+    """Explain the security/operational impact of detected drift using AI and suggest IaC fixes."""
+    actual_region = _resolve_region(region)
+    if not actual_region:
+        typer.secho("No AWS region found. Pass --region or set AWS_DEFAULT_REGION.", fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+    typer.echo(f"Fetching current drift state for {resource_id} in {actual_region}...")
+    results, _ = _run_scan(state, actual_region)
+    match = [r for r in results if r.resource_id == resource_id]
+    
+    if not match:
+        typer.secho(f"No current drift found for {resource_id}.", fg=typer.colors.YELLOW)
+        raise typer.Exit(code=1)
+        
+    r = match[0]
+    diff_data = r.diff if r.diff else r.live_attributes
+    
+    typer.echo("Generating AI Risk Analysis...")
+    ai_text = get_drift_explanation(r.resource_type, r.resource_id, diff_data, r.drift_type.value)
+    typer.echo(f"\nAI Risk Analysis:\n{ai_text}\n")
+    
+    deterministic_remediation = get_deterministic_remediation_suggestion(r.resource_type, r.resource_id, diff_data, r.drift_type.value)
+    typer.echo(f"Recommended IaC Remediation Command:\n{deterministic_remediation}\n")
+
+@app.command()
+def remediate(
+    resource_id: str,
+    state: str = typer.Option("terraform/terraform.tfstate", help="Path to Terraform state file."),
+    region: str = typer.Option(None, help="Target AWS region."),
+    dry_run: bool = typer.Option(True, "--dry-run/--apply", help="Dry run mode (default) or apply changes."),
+):
+    """Safely reconcile live infrastructure back to Terraform state."""
+    actual_region = _resolve_region(region)
+    if not actual_region:
+        typer.secho("No AWS region found. Pass --region or set AWS_DEFAULT_REGION.", fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+    results, _ = _run_scan(state, actual_region)
+    match = [r for r in results if r.resource_id == resource_id]
+
+    if not match:
+        typer.secho(f"No current drift found for {resource_id}. Run 'driftwatch scan' first.", fg=typer.colors.YELLOW)
+        raise typer.Exit(code=1)
+
+    r = match[0]
+    typer.secho(f"[{r.drift_type.value}] {r.resource_type}: {r.resource_id}", bold=True)
+    for attr, vals in (r.diff or {}).items():
+        typer.echo(f"  {attr}: terraform={vals.get('terraform')}  live={vals.get('live')}")
+
+    if dry_run:
+        typer.secho("\n[DRY RUN] No changes made. Re-run with --apply to remediate.", fg=typer.colors.BLUE)
+        return
+
+    process_remediation(match)
+
+if __name__ == "__main__":
+    app()