Metadata-Version: 2.4
Name: cloudflare-json-ips
Version: 0.1.0
Summary: Resolve Cloudflare IP CIDR ranges from the authoritative published JSON source
Author: GetCloudflareIPs
Keywords: cloudflare,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

# cloudflare-json-ips

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

It downloads and parses `https://api.cloudflare.com/client/v4/ips`, extracts
all IPv4 and IPv6 CIDRs, and provides helpers for containment and overlap queries.

## Why JSON?

Cloudflare publishes an authoritative machine-readable API response with:

- `result.ipv4_cidrs`
- `result.ipv6_cidrs`
- `result.etag`

This package reads that source directly.

## Install

### From PyPI

```bash
pip install cloudflare-json-ips
```

### Local Development

From the project root:

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

## Library Usage

```python
from cloudflare_json_ips import CloudflareIPQuery, get_cloudflare_ip_cidrs

result = get_cloudflare_ip_cidrs()
query = CloudflareIPQuery.from_cidrs(result.cidrs)

print(result.etag)
print(query.contains("104.16.0.0/13"))
print(query.collides("104.16.0.0-104.23.255.255"))
```

`result` is a `ResolutionResult` with:

- `cidrs`: sorted tuple of unique CIDR strings
- `etag`: source etag from Cloudflare's response
- `source_url`: JSON URL used
- `selected_prefix_count`: number of selected IPv4 and IPv6 prefix entries

`CloudflareIPQuery` 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_cloudflare_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:5003/health"
curl "http://127.0.0.1:5003/metadata"
curl "http://127.0.0.1:5003/cidrs"
curl "http://127.0.0.1:5003/networks"
curl "http://127.0.0.1:5003/check?value=104.16.0.0/13"
curl "http://127.0.0.1:5003/check?value=104.16.0.0-104.23.255.255"
curl "http://127.0.0.1:5003/check/range?start=104.16.0.0&end=104.23.255.255"
```
