From 0748bd0451a7cc2af6ff2f77153852ecd3bdb662 Mon Sep 17 00:00:00 2001 From: badra001 Date: Thu, 19 Mar 2026 16:24:39 -0400 Subject: [PATCH] add readme --- .../cross-organization/purge_sg_rules.md | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 local-app/python-tools/cross-organization/purge_sg_rules.md diff --git a/local-app/python-tools/cross-organization/purge_sg_rules.md b/local-app/python-tools/cross-organization/purge_sg_rules.md new file mode 100644 index 00000000..12c6966e --- /dev/null +++ b/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. +