DEV Community

Cover image for Introducing aws-ip-lookup: A Fast CLI Tool for Querying AWS IP Ranges
Eduardo Santana
Eduardo Santana

Posted on • Originally published at eduardosantana.dev on

Introducing aws-ip-lookup: A Fast CLI Tool for Querying AWS IP Ranges

#aws #go #programming #networking

Introducing aws-ip-lookup: A Fast CLI Tool for Querying AWS IP Ranges

Recent estimates say Amazon owns over 100 million public IPv4 IP addresses, and that number is growing every day. With such a vast network, chances are you've encountered an Amazon-owned IP address at some point in your life, whether you knew it or not.

While AWS publishes a document outlining all the IP ranges they own, they don't provide an easy way to filter and search through this data outside of manually filtering the JSON using something like jq. This makes it challenging to quickly determine if a given IP address belongs to an AWS service, and utilize this data to improve your security posture, troubleshoot network issues, or plan your network architecture.

Enter aws-ip-lookup, a command-line utility I created that allows you to look up any IPv4 and IPv6 address or CIDR range and determine if it belongs to an AWS service, and if so, which service and in which region.

It helps quickly answer the question of "where did this IP come from?" that often comes up when troubleshooting or diving into things like VPC Flow Logs, security scanning tools, compliance audits, and firewall logs.

What does it do?

aws-ip-lookup downloads and caches AWS IP range data locally from the AWS IP Address Ranges page that AWS maintains.

You can then search through this data by filtering by IP addresses, CIDR ranges, AWS services, regions, and network border groups to quickly find out if that IP belongs to an AWS service.

Key Features

Smart Caching

The tool maintains a local cache and uses AWS's SyncToken (a string at the beginning of the AWS IP ranges file) to check for updates, ensuring you always have the latest data while minimizing unnecessary downloads.

The SyncToken is compared with the local cache to determine if you have the latest version of the file, and if not, it will download the latest version automatically, without having to download the entire file every time.

  "syncToken": "1737150791",
  "createDate": "2025-01-17-21-53-11",
  "prefixes": [
    {
      "ip_prefix": "3.4.12.4/32",
      "region": "eu-west-1",
      "service": "AMAZON",
      "network_border_group": "eu-west-1"
    },
    ...
Enter fullscreen mode Exit fullscreen mode

Flexible Search

Search by:

  • IP address
  • AWS service
  • Region
  • Any combination of the above

Multiple Output Formats

Get results in:

  • Human-readable text
  • JSON for automation
  • CSV for spreadsheets
  • YAML for configuration files

Use Cases

Security Teams

  • Validate if suspicious IPs belong to AWS
  • Build allowlists for firewalls
  • Audit network access rules

DevOps/Platform Engineers

  • Troubleshoot connectivity issues
  • Plan network segmentation
  • Document AWS-owned network ranges

Getting Started

Installation is straightforward, you can clone the repository and build the binary using go build, like so:

```bash:install aws-ip-lookup
git clone https://github.com/pausethelogic/aws-ip-lookup.git
cd aws-ip-lookup
go build ./cmd/aws-ip-lookup




### Basic usage:


```bash:aws-ip-lookup
# Search by IP address
aws-ip-lookup search -i 54.231.0.1

# Search by IPv6 CIDR in a specific region
aws-ip-lookup search -i 2600:1f18:1f8::/48 -r us-east-1

# Filter by service
aws-ip-lookup search -s EC2

# List all services
aws-ip-lookup services

#List all regions
aws-ip-lookup regions

# List all network border groups
aws-ip-lookup network-border-groups
Enter fullscreen mode Exit fullscreen mode

Example Usage 

~❯ aws-ip-lookup search -i 111.13.171.192/26
Downloading latest IP ranges from AWS...
Found 2 matching ranges:

IP Prefix: 111.13.171.192/26
Service: AMAZON
Region: GLOBAL
Network Border Group: GLOBAL

IP Prefix: 111.13.171.192/26
Service: CLOUDFRONT
Region: GLOBAL
Network Border Group: GLOBAL

~/Doc/g/aws-ip-lookup/cmd/aws-ip-lookup main ❯ aws-ip-lookup search -i 127.0.0.1                                           

Downloading latest IP ranges from AWS...
Error: No matching IP ranges found
IP 127.0.0.1 does not belong to any AWS range

~/Doc/g/aws-ip-lookup/cmd/aws-ip-lookup main ❯
Enter fullscreen mode Exit fullscreen mode

What's Next?

Future releases will include:

  • Checking if an IP address belongs to a specific AWS account.
  • Querying private IP ranges (e.g., VPC CIDR blocks).
  • Checking if an IP address belongs to a specific resource you own (e.g., EC2 instance, NAT Gateway, ALB, etc).

Contributing

Contributions, issues, and feature requests are welcome!

Visit the GitHub repository to get started.

I built aws-ip-lookup to scratch my own itch while debugging AWS networking issues. If you work with AWS infrastructure, give it a shot and drop me a note on GitHub with your thoughts! 🚀

Top comments (0)