aws-json-ips

Python library that resolves AWS-published IP ranges from the authoritative JSON source.

It downloads and parses https://ip-ranges.amazonaws.com/ip-ranges.json, extracts all IPv4 and IPv6 CIDRs, and can optionally filter by AWS service, region, or network border group.

Why JSON?

AWS publishes an authoritative machine-readable file with top-level metadata and separate IPv4/IPv6 prefix collections.

Each entry includes fields such as:

• ip_prefix or ipv6_prefix
• service
• region
• network_border_group

The top-level payload also includes:

• syncToken
• createDate

This package reads that source directly.

Install

From PyPI

pip install aws-json-ips

Local Development

From the project root:

pip install -e .

Library Usage

from aws_json_ips import AWSIPQuery, get_aws_ip_cidrs

result = get_aws_ip_cidrs()
query = AWSIPQuery.from_cidrs(result.cidrs)

print(result.sync_token, result.create_date)
print(query.contains("3.5.140.0/22"))
print(query.collides("3.5.140.0-3.5.143.255"))

You can also filter the source data:

result = get_aws_ip_cidrs(services=("AMAZON", "S3"), regions=("us-east-1",))

result is a ResolutionResult with:

• cidrs: sorted tuple of unique CIDR strings
• sync_token: source sync token from AWS
• create_date: source publication date from AWS
• source_url: JSON URL used
• selected_prefix_count: number of selected IPv4 and IPv6 prefix entries

AWSIPQuery supports:

• contains(value): full containment for IP, CIDR, or range string (start-end)
• collides(value): any overlap for IP, CIDR, or range string (start-end)
• Specific methods: contains_ip, contains_cidr, contains_range, collides_ip, collides_cidr, collides_range

Example Script

Run:

python examples/print_aws_ips.py

Flask JSON Server Example

Run:

python examples/flask_server.py

All endpoints return JSON.

Examples:

curl "http://127.0.0.1:5002/health"
curl "http://127.0.0.1:5002/metadata"
curl "http://127.0.0.1:5002/cidrs"
curl "http://127.0.0.1:5002/networks"
curl "http://127.0.0.1:5002/check?value=3.5.140.0/22"
curl "http://127.0.0.1:5002/check?value=3.5.140.0-3.5.143.255"
curl "http://127.0.0.1:5002/check/range?start=3.5.140.0&end=3.5.143.255"