From 4ce65cc17fd4e1a73535d1bfee79a3703c816216 Mon Sep 17 00:00:00 2001
From: badra001 <donald.e.badrak.ii@census.gov>
Date: Thu, 12 Mar 2026 12:17:07 -0400
Subject: [PATCH] add readme

---
 local-app/python-tools/ipam/README.md | 125 ++++++++++++++++++++++++++
 1 file changed, 125 insertions(+)
 create mode 100644 local-app/python-tools/ipam/README.md

diff --git a/local-app/python-tools/ipam/README.md b/local-app/python-tools/ipam/README.md
new file mode 100644
index 00000000..03ba6f5a
--- /dev/null
+++ b/local-app/python-tools/ipam/README.md
@@ -0,0 +1,125 @@
+# AWS IPAM Discovery Exporter and Aggregator
+
+This repository contains Python utilities to aggregate and export AWS IPAM (IP Address Manager) discovered resources across all operating regions and post-process them into summarized network blocks.
+
+## Tools Overview
+
+1. **export_ipam_discovery.py**: Crawls all operating regions in an AWS IPAM Resource Discovery and exports sorted VPC and Subnet data to CSV and JSON.
+2. **summarize_ipam.py**: Processes the exported JSON to collapse contiguous CIDR blocks into the largest possible supernets, handling IPv4 and IPv6 independently.
+
+---
+
+## Installation
+
+### Prerequisites
+
+* Python 3.6+
+* AWS CLI configured with appropriate permissions.
+* Boto3 library.
+
+### 1. Install Dependencies
+
+The `ipaddress` and `json` modules are part of the Python standard library. You only need to install `boto3`:
+
+```bash
+pip install boto3
+
+```
+
+### 2. Required Permissions
+
+The IAM principal must have the following permissions:
+
+* ec2:DescribeIpamResourceDiscoveries
+* ec2:GetIpamDiscoveredResourceCidrs
+
+---
+
+## Tool 1: export_ipam_discovery.py
+
+### Usage
+
+Run the script by providing your AWS profile and the Home Region where your IPAM is managed.
+
+```bash
+python3 export_ipam_discovery.py --profile my-aws-profile --region us-gov-west-1
+
+```
+
+### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| --profile | The AWS CLI profile to use for authentication. | No |
+| --region | The AWS Region where the IPAM is located. | Yes |
+
+### Features
+
+* Global Scoping: Automatically detects all "Operating Regions" monitored by the IPAM.
+* Dual Output: Generates both .csv and .json files simultaneously.
+* Filename Format: Uses ISO 8601 Basic format (ipam-export.YYYYMMDDTHHMMSS.csv).
+* Numerical Sorting: Sorts by Resource Type, then numerically by IP block (not string).
+
+---
+
+## Tool 2: summarize_ipam.py
+
+### Usage
+
+Run this script against the JSON output of the exporter to create a summarized routing or firewall list.
+
+```bash
+python3 summarize_ipam.py ipam-export.20260312T112005.json
+
+```
+
+### Features
+
+* Dual Stack Support: Separates IPv4 and IPv6 addresses into distinct lists to prevent processing errors.
+* CIDR Collapsing: Uses the collapse_addresses algorithm to merge contiguous networks (e.g., merging two /24s into one /23).
+* Text Output: Produces a clean text file grouped by IP version for easy copy-pasting into network configuration tools.
+
+---
+
+## Changelog
+
+### export_ipam_discovery.py
+
+**v1.0.4**
+
+* Feature: Standardized filename timestamp to ISO 8601 Basic format (YYYYMMDDTHHMMSS).
+
+**v1.0.3**
+
+* Feature: Implemented numerical CIDR sorting using the ipaddress module.
+* Feature: Added multi-level sorting (Resource Type > CIDR Block).
+
+**v1.0.2**
+
+* Bugfix: Resolved missing data issue by implementing multi-region crawling.
+* Feature: Added automatic detection of IPAM Operating Regions.
+* Feature: Added error handling for restricted or inaccessible regions.
+
+**v1.0.1**
+
+* Bugfix: Corrected Boto3 parameter error (ResourceRegion).
+* Feature: Added simultaneous JSON and CSV output.
+
+**v1.0.0**
+
+* Initial release.
+
+---
+
+### summarize_ipam.py
+
+**v1.0.1**
+
+* Bugfix: Resolved TypeError when processing mixed IPv4/IPv6 environments.
+* Feature: Added logic to bucket and collapse IP versions independently.
+* Feature: Updated output format to clearly distinguish between stack types.
+
+**v1.0.0**
+
+* Initial release: Basic VPC CIDR aggregation.
+