add readme

local-app/python-tools/cross-organization/purge_sg_rules.md

@@ -0,0 +1,112 @@
+# `purge_sg_rules` Utility
+
+The `purge_sg_rules` utility is a specialized Python script designed to audit and remediate AWS Security Group rules. It provides a human-readable "List Mode" for inspecting rules (including Managed Prefix List resolution) and a "Purge Mode" to strip all ingress and egress rules from a target group.
+
+This tool is particularly useful for cleaning up duplicate security groups, remediating "default" VPC groups, or preparing resources for decommissioning across an AWS organization.
+
+---
+
+## Features
+
+* **Managed Prefix List Resolution:** Automatically looks up Prefix List IDs (e.g., `pl-12345`) to show the friendly name and entry weight.
+* **Numerical Sorting:** Rules are automatically sorted by the "From" port number for easier auditing.
+* **Detailed Header:** Displays the Security Group's Name and all associated tags in a clear, vertical list.
+* **Safety First:** Includes a mandatory `--dry-run` validation and an interactive `(y/n)` confirmation before any rules are deleted.
+* **Dual Mode:** Use `--list` for a read-only inventory or omit it to enter the purge workflow.
+
+---
+
+## Prerequisites
+
+* Python 3.x
+* `boto3` library (`pip install boto3`)
+* Configured AWS CLI profiles with appropriate permissions (`ec2:DescribeSecurityGroups`, `ec2:RevokeSecurityGroupIngress`, `ec2:RevokeSecurityGroupEgress`, and `ec2:DescribeManagedPrefixLists`).
+
+---
+
+## Usage
+
+### Example 1: List Only (Audit)
+To view the rules in a security group without making any changes:
+
+```bash
+python purge_sg_rules.py --group-id sg-0123456789abcdef --region us-east-1 --profile my-aws-profile --list
+```
+
+### Example 2: Purge (Dry Run)
+To simulate the removal of all rules and verify permissions:
+
+```bash
+python purge_sg_rules.py --group-id sg-0123456789abcdef --region us-east-1 --profile my-aws-profile --dry-run
+```
+
+### Example 3: Execute Purge
+To permanently remove all rules:
+
+```bash
+python purge_sg_rules.py --group-id sg-0123456789abcdef --region us-east-1 --profile my-aws-profile
+```
+
+---
+
+## Sample Output
+
+```text
+---------------------------------------------------------------------------------------------------------------
+SG RULE PURGE MODE v1.2.4 | sg-08e6f42a1bc3d5f | us-east-1 | Profile: prod-it-mgmt
+NAME: Web-Tier-Access
+TAGS:
+  Environment         : Production
+  Project             : Cloud-Migration
+  Service             : Frontend-App
+---------------------------------------------------------------------------------------------------------------
+
+INGRESS RULES (Sorted by Port):
+   1. [INGRESS] Proto: tcp   | Ports: 80 -> 80        | Targets: 0.0.0.0/0 (HTTP Public)
+   2. [INGRESS] Proto: tcp   | Ports: 443 -> 443      | Targets: 0.0.0.0/0 (HTTPS Public), pl-63a5400a [com.amazonaws.us-east-1.s3 (25 entries)]
+   3. [INGRESS] Proto: tcp   | Ports: 1024 -> 65535   | Targets: sg-076543210987 (Ephemeral Return)
+
+EGRESS RULES (Sorted by Port):
+   1. [EGRESS ] Proto: all   | Ports: ALL             | Targets: 0.0.0.0/0
+
+----------------------------------------
+SUMMARY OF RULES FOUND:
+  Total Ingress: 3
+  Total Egress:  1
+----------------------------------------
+
+CONFIRM: Purge all 4 rule sets? (y/n): y
+  Successfully revoked all rules.
+```
+
+---
+
+## Changelog
+
+### v1.2.4
+* Added numerical sorting of rules by "From" port.
+* Updated port display to explicitly show `From -> To` range for all rules.
+
+### v1.2.3
+* Refactored tag header to display one key/value pair per line for improved readability.
+* Alphabetized tag output (excluding the Name tag, which remains at the top).
+
+### v1.2.2
+* Enhanced header to include the Security Group `Name` tag and other associated metadata.
+* Added a footer summary displaying the total count of ingress and egress rules.
+
+### v1.2.1
+* Added sequential index numbering (`1..N`) for rule entries within each category.
+* Improved terminal alignment for ingress/egress blocks.
+
+### v1.2.0
+* Added support for **Managed Prefix Lists**, including automated lookup of names and entry counts.
+* Introduced the `--list` option for non-destructive rule auditing.
+
+### v1.1.0
+* Added detailed rule inspection to the output, showing CIDRs, Ports, and Protocols.
+* Implemented interactive `(y/n)` confirmation before execution.
+
+### v1.0.0
+* Initial release with basic `--group-id`, `--region`, `--profile`, and `--dry-run` support.
+