Metadata-Version: 2.4
Name: aws-json-ips
Version: 0.1.0
Summary: Resolve AWS IP CIDR ranges from the authoritative published JSON source
Author: GetAWSIPs
Keywords: aws,json,ip,cidr,network
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: flask>=3.0.0

# 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

```bash
pip install aws-json-ips
```

### Local Development

From the project root:

```bash
pip install -e .
```

## Library Usage

```python
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:

```python
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:

```bash
python examples/print_aws_ips.py
```

## Flask JSON Server Example

Run:

```bash
python examples/flask_server.py
```

All endpoints return JSON.

Examples:

```bash
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"
```
