driftwatch-cli 0.1.0__tar.gz

driftwatch_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nitin Gupta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

driftwatch_cli-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: driftwatch-cli
+Version: 0.1.0
+Summary: CLI tool that detects Terraform infrastructure drift against live AWS, explains it with AI, and guides remediation.
+Author: Nitin Gupta
+License: MIT
+Project-URL: Homepage, https://github.com/hastagnitin/driftwatch
+Project-URL: Repository, https://github.com/hastagnitin/driftwatch
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: boto3>=1.34.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: groq>=0.4.0
+Requires-Dist: python-telegram-bot>=20.0
+Requires-Dist: psycopg2-binary>=2.9.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: moto[all]>=5.0.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# DriftWatch 🛡️
+
+**DriftWatch** is a production-ready CLI tool and automation engine that detects Terraform infrastructure drift against live AWS environments, explains the security and reliability impact using AI, and safely guides remediation.
+
+---
+
+## 🚀 Key Features
+
+- **Multi-Resource Drift Detection**: Continuously monitors and compares EC2 instances, S3 buckets, Security Groups, RDS databases, Lambda functions, and IAM roles against your Terraform state.
+- **Data-Driven Severity Scoring**: Evaluates changes dynamically at the attribute level (e.g. security group open ports vs description updates) to classify drifts as `CRITICAL`, `HIGH`, `MEDIUM`, or `LOW`.
+- **AI-Powered Risk Summaries**: Integrates with LLMs to provide plain-English security analysis and compliance impact assessments.
+- **Deterministic IaC Remediation**: Recommends safe, template-generated `terraform import` and `terraform apply` commands rather than hallucinated AI outputs.
+- **Guarded Auto-Remediation**: Pre-flight validation checks for EC2 (EBS verification, Spot skip, running state), RDS maintenance-window defaults, and explicit interactive confirmations.
+- **Multi-Channel Alerting**: Instant notifications via Telegram, Slack, and Email.
+- **CI/CD Quality Gate**: Built-in GitHub Actions integration to enforce zero-tolerance drift policies in pull requests.
+
+---
+
+## 🏛️ Architecture Overview
+
+```
+driftwatch/
+├── drift_engine/              # Core drift detection & reconciliation engine
+│   ├── aws_client.py         # Live AWS resource discovery (boto3)
+│   ├── core.py               # Diff evaluation & data-driven severity engine
+│   ├── database.py           # PostgreSQL scan history recorder
+│   ├── explain.py            # AI risk summaries & deterministic IaC templates
+│   ├── models.py             # Data models & attribute severity tables
+│   ├── notifications.py      # Alert dispatcher (Telegram, Slack, Email)
+│   ├── remediation.py        # Guarded auto-remediation handlers
+│   └── tf_parser.py          # Terraform state JSON parser
+├── driftwatch/               # CLI Entrypoint (Typer)
+│   └── cli.py                # Command definitions: scan, explain, remediate
+├── terraform/                # Example infrastructure and state configuration
+├── kubernetes/               # Kubernetes CronJob deployment
+└── tests/                    # Comprehensive unit tests with moto AWS mocks
+```
+
+---
+
+## 📋 Prerequisites
+
+- **Python**: `>= 3.10`
+- **AWS Credentials**: Configured via environment variables, IAM roles, or AWS CLI credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`).
+- **Terraform State File**: Local JSON state or remote state (`terraform.tfstate`).
+- **PostgreSQL** *(Optional)*: For persistent scan audit history.
+- **Groq API Key** *(Optional)*: `GROQ_API_KEY` for AI risk explanations.
+
+---
+
+## 📦 Installation
+
+### From Source (Local Development)
+```bash
+git clone https://github.com/hastagnitin/driftwatch.git
+cd driftwatch
+pip install -e .[dev]
+```
+
+---
+
+## ⚙️ Configuration
+
+Create a `.env` file in the root directory:
+
+```env
+AWS_DEFAULT_REGION=ap-south-1
+TF_STATE_PATH=terraform/terraform.tfstate
+
+# Optional: AI Risk Summaries
+GROQ_API_KEY=your_groq_api_key
+
+# Optional: Notifications
+SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
+TELEGRAM_BOT_TOKEN=your_telegram_bot_token
+TELEGRAM_CHAT_ID=your_telegram_chat_id
+
+# Optional: PostgreSQL Database
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=driftwatch
+DB_USER=postgres
+DB_PASSWORD=your_db_password
+```
+
+---
+
+## 💻 Usage & CLI Commands
+
+### 1. Scan for Drift
+Scan live AWS infrastructure against your Terraform state:
+```bash
+# Basic scan
+driftwatch scan --region ap-south-1 --state terraform/terraform.tfstate
+
+# Enforce CI Gate (fails build if CRITICAL drift is found)
+driftwatch scan --region ap-south-1 --fail-on CRITICAL
+```
+
+### 2. Explain Drift
+Generate AI risk analysis and deterministic IaC fix recommendations:
+```bash
+driftwatch explain sg-0123456789abcdef0 --region ap-south-1
+```
+
+### 3. Remediate Drift
+Safely remediate drifted resources back to IaC specifications:
+```bash
+# Dry run mode (default)
+driftwatch remediate sg-0123456789abcdef0 --region ap-south-1 --dry-run
+
+# Apply mode with interactive confirmation
+driftwatch remediate sg-0123456789abcdef0 --region ap-south-1 --apply
+```
+
+---
+
+## ⚠️ Security & Safety Guidelines
+
+> [!WARNING]
+> **Auto-Remediation Safety**:
+> - Automated drift remediation is intended for **Development** and **Staging** environments.
+> - In **Production**, DriftWatch enforces manual confirmation prompts (`confirm_action()`) and recommends template-generated `terraform apply` / `terraform import` workflows.
+> - RDS modifications default to maintenance windows (`ApplyImmediately=False`) to avoid unplanned reboots.
+
+---
+
+## 🧪 Testing
+
+Run the test suite with test coverage:
+```bash
+pytest tests/ -v --cov=drift_engine --cov=driftwatch --cov-report=term-missing
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

driftwatch_cli-0.1.0/README.md

@@ -0,0 +1,139 @@
+# DriftWatch 🛡️
+
+**DriftWatch** is a production-ready CLI tool and automation engine that detects Terraform infrastructure drift against live AWS environments, explains the security and reliability impact using AI, and safely guides remediation.
+
+---
+
+## 🚀 Key Features
+
+- **Multi-Resource Drift Detection**: Continuously monitors and compares EC2 instances, S3 buckets, Security Groups, RDS databases, Lambda functions, and IAM roles against your Terraform state.
+- **Data-Driven Severity Scoring**: Evaluates changes dynamically at the attribute level (e.g. security group open ports vs description updates) to classify drifts as `CRITICAL`, `HIGH`, `MEDIUM`, or `LOW`.
+- **AI-Powered Risk Summaries**: Integrates with LLMs to provide plain-English security analysis and compliance impact assessments.
+- **Deterministic IaC Remediation**: Recommends safe, template-generated `terraform import` and `terraform apply` commands rather than hallucinated AI outputs.
+- **Guarded Auto-Remediation**: Pre-flight validation checks for EC2 (EBS verification, Spot skip, running state), RDS maintenance-window defaults, and explicit interactive confirmations.
+- **Multi-Channel Alerting**: Instant notifications via Telegram, Slack, and Email.
+- **CI/CD Quality Gate**: Built-in GitHub Actions integration to enforce zero-tolerance drift policies in pull requests.
+
+---
+
+## 🏛️ Architecture Overview
+
+```
+driftwatch/
+├── drift_engine/              # Core drift detection & reconciliation engine
+│   ├── aws_client.py         # Live AWS resource discovery (boto3)
+│   ├── core.py               # Diff evaluation & data-driven severity engine
+│   ├── database.py           # PostgreSQL scan history recorder
+│   ├── explain.py            # AI risk summaries & deterministic IaC templates
+│   ├── models.py             # Data models & attribute severity tables
+│   ├── notifications.py      # Alert dispatcher (Telegram, Slack, Email)
+│   ├── remediation.py        # Guarded auto-remediation handlers
+│   └── tf_parser.py          # Terraform state JSON parser
+├── driftwatch/               # CLI Entrypoint (Typer)
+│   └── cli.py                # Command definitions: scan, explain, remediate
+├── terraform/                # Example infrastructure and state configuration
+├── kubernetes/               # Kubernetes CronJob deployment
+└── tests/                    # Comprehensive unit tests with moto AWS mocks
+```
+
+---
+
+## 📋 Prerequisites
+
+- **Python**: `>= 3.10`
+- **AWS Credentials**: Configured via environment variables, IAM roles, or AWS CLI credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`).
+- **Terraform State File**: Local JSON state or remote state (`terraform.tfstate`).
+- **PostgreSQL** *(Optional)*: For persistent scan audit history.
+- **Groq API Key** *(Optional)*: `GROQ_API_KEY` for AI risk explanations.
+
+---
+
+## 📦 Installation
+
+### From Source (Local Development)
+```bash
+git clone https://github.com/hastagnitin/driftwatch.git
+cd driftwatch
+pip install -e .[dev]
+```
+
+---
+
+## ⚙️ Configuration
+
+Create a `.env` file in the root directory:
+
+```env
+AWS_DEFAULT_REGION=ap-south-1
+TF_STATE_PATH=terraform/terraform.tfstate
+
+# Optional: AI Risk Summaries
+GROQ_API_KEY=your_groq_api_key
+
+# Optional: Notifications
+SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
+TELEGRAM_BOT_TOKEN=your_telegram_bot_token
+TELEGRAM_CHAT_ID=your_telegram_chat_id
+
+# Optional: PostgreSQL Database
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=driftwatch
+DB_USER=postgres
+DB_PASSWORD=your_db_password
+```
+
+---
+
+## 💻 Usage & CLI Commands
+
+### 1. Scan for Drift
+Scan live AWS infrastructure against your Terraform state:
+```bash
+# Basic scan
+driftwatch scan --region ap-south-1 --state terraform/terraform.tfstate
+
+# Enforce CI Gate (fails build if CRITICAL drift is found)
+driftwatch scan --region ap-south-1 --fail-on CRITICAL
+```
+
+### 2. Explain Drift
+Generate AI risk analysis and deterministic IaC fix recommendations:
+```bash
+driftwatch explain sg-0123456789abcdef0 --region ap-south-1
+```
+
+### 3. Remediate Drift
+Safely remediate drifted resources back to IaC specifications:
+```bash
+# Dry run mode (default)
+driftwatch remediate sg-0123456789abcdef0 --region ap-south-1 --dry-run
+
+# Apply mode with interactive confirmation
+driftwatch remediate sg-0123456789abcdef0 --region ap-south-1 --apply
+```
+
+---
+
+## ⚠️ Security & Safety Guidelines
+
+> [!WARNING]
+> **Auto-Remediation Safety**:
+> - Automated drift remediation is intended for **Development** and **Staging** environments.
+> - In **Production**, DriftWatch enforces manual confirmation prompts (`confirm_action()`) and recommends template-generated `terraform apply` / `terraform import` workflows.
+> - RDS modifications default to maintenance windows (`ApplyImmediately=False`) to avoid unplanned reboots.
+
+---
+
+## 🧪 Testing
+
+Run the test suite with test coverage:
+```bash
+pytest tests/ -v --cov=drift_engine --cov=driftwatch --cov-report=term-missing
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

driftwatch_cli-0.1.0/drift_engine/aws_client.py

@@ -0,0 +1,241 @@
+import sys
+import boto3
+from datetime import datetime, timedelta
+
+def fetch_live_ec2_instances(region: str) -> dict:
+    ec2 = boto3.client("ec2", region_name=region)
+    live = {}
+    try:
+        paginator = ec2.get_paginator("describe_instances")
+        for page in paginator.paginate():
+            for reservation in page.get("Reservations", []):
+                for instance in reservation.get("Instances", []):
+                    if instance.get("State", {}).get("Name") == "terminated":
+                        continue
+                    
+                    tags_list = instance.get("Tags", [])
+                    tags_dict = {t["Key"]: t["Value"] for t in tags_list if "Key" in t and "Value" in t}
+                    name = tags_dict.get("Name", "Unknown")
+                    
+                    sg_ids = []
+                    for sg in instance.get("SecurityGroups", []):
+                        if "GroupId" in sg:
+                            sg_ids.append(sg.get("GroupId"))
+                    sg_ids.sort()
+                    
+                    instance_id = instance["InstanceId"]
+                    live[instance_id] = {
+                        "type": "aws_instance",
+                        "name": name,
+                        "attributes": {
+                            "id": instance_id,
+                            "instance_type": instance.get("InstanceType"),
+                            "ami": instance.get("ImageId"),
+                            "tags": tags_dict,
+                            "vpc_security_group_ids": sg_ids
+                        },
+                    }
+    except Exception as e:
+        print(f"Failed to fetch aws_instance: {e}", file=sys.stderr)
+        return None
+    return live
+
+def fetch_live_s3_buckets(region: str) -> dict:
+    s3 = boto3.client("s3", region_name=region)
+    live = {}
+    try:
+        response = s3.list_buckets()
+        for bucket in response.get("Buckets", []):
+            bucket_name = bucket["Name"]
+            try:
+                tags_response = s3.get_bucket_tagging(Bucket=bucket_name)
+                tags_list = tags_response.get("TagSet", [])
+                tags_dict = {t["Key"]: t["Value"] for t in tags_list if "Key" in t and "Value" in t}
+                name = tags_dict.get("Name", bucket_name)
+            except Exception:
+                tags_dict = {}
+                name = bucket_name
+
+            live[bucket_name] = {
+                "type": "aws_s3_bucket",
+                "name": name,
+                "attributes": {
+                    "id": bucket_name,
+                    "bucket": bucket_name,
+                    "tags": tags_dict,
+                },
+            }
+    except Exception as e:
+        print(f"Failed to fetch aws_s3_bucket: {e}", file=sys.stderr)
+        return None
+    return live
+
+def fetch_live_security_groups(region: str) -> dict:
+    ec2 = boto3.client("ec2", region_name=region)
+    live = {}
+    try:
+        paginator = ec2.get_paginator("describe_security_groups")
+        for page in paginator.paginate():
+            for sg in page.get("SecurityGroups", []):
+                sg_id = sg["GroupId"]
+                sg_name = sg.get("GroupName", "")
+                
+                tags_list = sg.get("Tags", [])
+                tags_dict = {t["Key"]: t["Value"] for t in tags_list if "Key" in t and "Value" in t}
+                name_tag = tags_dict.get("Name", sg_name)
+                
+                ingress_rules = []
+                for perm in sg.get("IpPermissions", []):
+                    cidrs = [ip.get("CidrIp") for ip in perm.get("IpRanges", []) if ip.get("CidrIp")]
+                    if cidrs:
+                        ingress_rules.append({
+                            "from_port": perm.get("FromPort", 0),
+                            "to_port": perm.get("ToPort", 0),
+                            "protocol": perm.get("IpProtocol", "-1"),
+                            "cidr_blocks": cidrs
+                        })
+                
+                egress_rules = []
+                for perm in sg.get("IpPermissionsEgress", []):
+                    cidrs = [ip.get("CidrIp") for ip in perm.get("IpRanges", []) if ip.get("CidrIp")]
+                    if cidrs:
+                        egress_rules.append({
+                            "from_port": perm.get("FromPort", 0),
+                            "to_port": perm.get("ToPort", 0),
+                            "protocol": perm.get("IpProtocol", "-1"),
+                            "cidr_blocks": cidrs
+                        })
+                
+                live[sg_id] = {
+                    "type": "aws_security_group",
+                    "name": name_tag,
+                    "attributes": {
+                        "id": sg_id,
+                        "name": sg_name,
+                        "description": sg.get("Description", ""),
+                        "tags": tags_dict,
+                        "ingress": ingress_rules,
+                        "egress": egress_rules,
+                    },
+                }
+    except Exception as e:
+        print(f"Failed to fetch aws_security_group: {e}", file=sys.stderr)
+        return None
+    return live
+
+def fetch_live_rds_instances(region: str) -> dict:
+    rds = boto3.client("rds", region_name=region)
+    live = {}
+    try:
+        paginator = rds.get_paginator("describe_db_instances")
+        for page in paginator.paginate():
+            for db in page.get("DBInstances", []):
+                db_id = db.get("DBInstanceIdentifier")
+                if not db_id:
+                    continue
+                live[db_id] = {
+                    "type": "aws_db_instance",
+                    "name": db_id,
+                    "attributes": {
+                        "id": db_id,
+                        "identifier": db_id,
+                        "allocated_storage": db.get("AllocatedStorage"),
+                        "engine": db.get("Engine"),
+                        "engine_version": db.get("EngineVersion"),
+                        "instance_class": db.get("DBInstanceClass"),
+                        "multi_az": db.get("MultiAZ"),
+                    },
+                }
+    except Exception as e:
+        print(f"Failed to fetch aws_db_instance: {e}", file=sys.stderr)
+        return None
+    return live
+
+def fetch_live_lambda_functions(region: str) -> dict:
+    lambda_client = boto3.client("lambda", region_name=region)
+    live = {}
+    try:
+        paginator = lambda_client.get_paginator("list_functions")
+        for page in paginator.paginate():
+            for func in page.get("Functions", []):
+                func_name = func.get("FunctionName")
+                if not func_name:
+                    continue
+                live[func_name] = {
+                    "type": "aws_lambda_function",
+                    "name": func_name,
+                    "attributes": {
+                        "id": func_name,
+                        "function_name": func_name,
+                        "runtime": func.get("Runtime"),
+                        "handler": func.get("Handler"),
+                        "memory_size": func.get("MemorySize"),
+                        "timeout": func.get("Timeout"),
+                        "role": func.get("Role"),
+                    },
+                }
+    except Exception as e:
+        print(f"Failed to fetch aws_lambda_function: {e}", file=sys.stderr)
+        return None
+    return live
+
+def fetch_live_iam_roles(region: str) -> dict:
+    iam = boto3.client("iam", region_name=region)
+    live = {}
+    try:
+        paginator = iam.get_paginator("list_roles")
+        for page in paginator.paginate():
+            for role in page.get("Roles", []):
+                role_name = role.get("RoleName")
+                if not role_name:
+                    continue
+                if role_name.startswith("AWSServiceRoleFor") or role.get("Path", "").startswith("/aws-service-role/"):
+                    continue
+                
+                try:
+                    policies = iam.list_attached_role_policies(RoleName=role_name)
+                    attached_policies = sorted(
+                        p["PolicyArn"] for p in policies.get("AttachedPolicies", []) if "PolicyArn" in p
+                    )
+                except Exception:
+                    attached_policies = []
+                
+                live[role_name] = {
+                    "type": "aws_iam_role",
+                    "name": role_name,
+                    "attributes": {
+                        "id": role_name,
+                        "name": role_name,
+                        "path": role.get("Path", "/"),
+                        "arn": role.get("Arn", ""),
+                        "attached_policies": attached_policies
+                    }
+                }
+    except Exception as e:
+        print(f"Failed to fetch aws_iam_role: {e}", file=sys.stderr)
+        return None
+    return live
+
+def get_resource_cost(resource_id: str) -> float:
+    try:
+        client = boto3.client("ce", region_name="us-east-1")
+        
+        end_date = datetime.today().strftime("%Y-%m-%d")
+        start_date = (datetime.today() - timedelta(days=30)).strftime("%Y-%m-%d")
+        
+        response = client.get_cost_and_usage(
+            TimePeriod={"Start": start_date, "End": end_date},
+            Granularity="MONTHLY",
+            Metrics=["UnblendedCost"],
+            Filter={
+                "Dimensions": {
+                    "Key": "RESOURCE_ID",
+                    "Values": [resource_id]
+                }
+            }
+        )
+        
+        usd_cost = float(response["ResultsByTime"][0]["Total"]["UnblendedCost"]["Amount"])
+        return usd_cost
+    except Exception:
+        return 0.0