aws-ec2-checker

Classify a list of IP addresses into CloudFront, S3, EC2, and other AWS/non-AWS buckets, then recommend the best EC2 region based on detected EC2 IPs.

---

How it works

1. Reads a plain-text file of IP addresses (one per line).
2. Performs either a reverse-DNS lookup or Api Ninjas WHOIS lookup on each IP.
3. In whois mode, if API lookup fails or times out (5s timeout), it automatically falls back to reverse-DNS for that IP.
4. Classifies each IP into service buckets (CloudFront, S3, EC2, AWS-other, other).
5. (Optional) Downloads the joetek EC2 IP ranges JSON and maps each EC2 IP to its AWS region.
6. Prints a frequency table and recommends the region where the most open EC2 IPs were found — so you know where to create your next instance.

---

Requirements

• Python 3.10+
• No third-party runtime dependencies (only the standard library is used).

Install the (optional) test dependency:

pip install -r requirements.txt

---

Usage

python3 checker.py <input_file.txt> [options]

Arguments

Argument	Description
input_file	Path to a .txt file with one IP per line. Lines starting with # and blank lines are ignored.
-o / --output FILE	Write categorized results to FILE instead of stdout.
--no-pattern	Skip downloading EC2 ranges and skip the region analysis.
--ec2-ranges-url URL	Override the URL used to fetch the EC2 CIDR JSON.
--lookup-mode {rdns,whois}	Detection mode: reverse DNS (rdns, default) or Api Ninjas WHOIS (whois).
--api-ninjas-key KEY	Api Ninjas API key (or set API_NINJAS_API_KEY) for --lookup-mode whois.
--workers N	Number of concurrent lookup workers (default 32).
--only-ec2	Output only EC2-classified entries (instead of all categories).

Output format (stdout / output file)

cloudfront:
<ip>TAB<label>TAB<region>

s3:
<ip>TAB<label>TAB<region>

ec2:
<ip>TAB<label>TAB<region>

Example:

34.199.102.114	ec2-34-199-102-114.compute-1.amazonaws.com	us-east-1

---

Examples

Basic run — filter EC2 IPs and show region stats

python3 checker.py ips.txt

[*] Loaded 5 IP(s) from 'ips.txt'
[*] Fetching EC2 IP ranges from:
    https://raw.githubusercontent.com/joetek/aws-ip-ranges-json/master/ip-ranges-ec2.json
[*] Loaded 1234 EC2 CIDR prefix(es).
[*] Performing reverse-DNS lookups with 32 worker(s)…
[*] Classified 5 IP(s): ec2=3, s3=1, cloudfront=1.
cloudfront:
13.32.0.1	d111111abcdef8.cloudfront.net	unknown

s3:
3.5.76.142	s3-us-west-2-r-w.amazonaws.com	unknown

ec2:
34.199.102.114	ec2-34-199-102-114.compute-1.amazonaws.com	us-east-1

[*] Region distribution of found EC2 IPs:
    us-east-1                      2 IP(s)
    eu-west-1                      1 IP(s)

[+] Recommended region for your next EC2 instance: us-east-1

Save only EC2 IPs to a file, skip region analysis

python3 checker.py ips.txt -o ec2_only.txt --no-pattern --only-ec2

Use Api Ninjas WHOIS mode for EC2 detection

API_NINJAS_API_KEY=your_key_here \
python3 checker.py ips.txt --lookup-mode whois --workers 64

---

Input file format

# AWS IP addresses to check
3.5.76.142
34.199.102.114
52.28.5.10
# blank lines are fine

1.1.1.1

---

Running tests

python3 -m pytest tests/ -v