Crate awsipranges

Expand description

awsipranges allows you to quickly and efficiently search, filter, and use public AWS IP address ranges answering questions like:

Is some IPv4/IPv6 <address> a public AWS IP address?
- What region is it in?
- What service(s) does it belong to?
- What supernets does it belong to?
What are the supernets of <some-cidr-block>?
What services publish their IP ranges in the ip-ranges.json file?
What IP ranges are used by <some-supported-service> in <some-region>?
What Local / Wavelength Zones are attached to <some-region>?
What are the IP ranges for <some-local-zone>?

You could get answers to some of these ☝️ questions by downloading, parsing, and filtering the JSON file yourself, but awsipranges features make searching and filtering more accessible. awsipranges parses and understands the structure of IPv4 and IPv6 CIDRs allowing you to work with IP ranges as they were meant to - as structured data.

If you find this project useful, please consider giving it a star ⭐ on GitHub. Your support is greatly appreciated!

§Features

Retrieve & Cache: ip-ranges.json to ${HOME}/.aws/ip-ranges.json; refreshing the cache after 24 hours (by default).
Search: IP ranges for an IPv4/IPv6 address or CIDR (any prefix length) to view the AWS IP ranges that contain the provided address or CIDR.
Filter: IP ranges by region, service, network border group, and IP version (IPv4/IPv6).

§Example

use awsipranges::ipnetwork::IpNetwork;
use awsipranges::Result;

fn main() -> Result<()> {
    // Get the AWS IP Ranges
    let aws_ip_ranges = awsipranges::get_ranges()?;

    // Find the longest match prefix for an IP Address
    let ip_address: IpNetwork = "3.141.102.225".parse().unwrap();
    let prefix = aws_ip_ranges.get_longest_match_prefix(&ip_address);
    println!("{:?}", prefix);

    // Search for IP Prefixes
    let search_prefixes: Vec<IpNetwork> = vec![
        "3.141.102.225".parse().unwrap(),
        "44.192.140.65".parse().unwrap(),
    ];
    let search_results = aws_ip_ranges.search(&search_prefixes);
    for aws_ip_prefix in search_results.aws_ip_ranges.prefixes().values() {
        println!("{:?}", aws_ip_prefix);
    }

    // Filter the AWS IP Ranges
    let filtered_ranges = aws_ip_ranges
        .filter_builder()
        .ipv4()
        .regions(["us-west-2"])?
        .services(["S3"])?
        .filter();
    for aws_ip_prefix in filtered_ranges.prefixes().values() {
        println!("{:?}", aws_ip_prefix);
    }

    Ok(())
}

§Configuration

The get_ranges function, Client::new, and ClientBuilder::new use environment variables and default values to configure the client that retrieves the AWS IP Ranges. You can use the Client::default and ClientBuilder::default methods to create a client with the default configurations, ignoring environment variables. Use the ClientBuilder struct to build a client with a custom configuration.

Environment Variable	Default Value	Configuration Method
`AWSIPRANGES_URL`	`https://ip-ranges.amazonaws.com/ip-ranges.json`	ClientBuilder::url
`AWSIPRANGES_CACHE_FILE`	`${HOME}/.aws/ip-ranges.json`	ClientBuilder::cache_file
`AWSIPRANGES_CACHE_TIME`	`86400` seconds (24 hours)	ClientBuilder::cache_time
`AWSIPRANGES_RETRY_COUNT`	`4`	ClientBuilder::retry_count
`AWSIPRANGES_RETRY_INITIAL_DELAY`	`200` milliseconds	ClientBuilder::retry_initial_delay
`AWSIPRANGES_RETRY_BACKOFF_FACTOR`	`2`	ClientBuilder::retry_backoff_factor
`AWSIPRANGES_RETRY_TIMEOUT`	`5000` milliseconds (5 seconds)	ClientBuilder::retry_timeout

Re-exports§

pub use ipnetwork;

Structs§

AwsIpPrefix: AWS IP Prefix record containing the IP prefix, region, network border group, and services associated with the prefix.
AwsIpRanges: Collection of AWS IP ranges providing methods to access, AwsIpRanges::search, and AwsIpRanges::filter the AWS IP Ranges.
Client: A client for retrieving the AWS IP Ranges from the cached JSON file, when available and fresh, or from the URL when the cache is stale or unavailable. Client implements a simple exponential- backoff retry mechanism to retrieve the JSON from the URL.
ClientBuilder: A builder for the Client struct that allows you to customize the client configuration. The ClientBuilder struct provides setters for each configuration value and a ClientBuilder::build method to create a Client instance.
Filter: Filter used to include AWS IP Prefixes based on the prefix type (IPv4/IPv6), regions, network border groups, and services associated with the prefixes. Use the FilterBuilder to construct a Filter object with the desired filter parameters.
FilterBuilder: Builder used to construct a Filter object with the desired filter parameters.
SearchResults: Search results containing the matching AwsIpRanges, a map of found prefixes, and the set of prefixes not found in the AWS IP Ranges.

Functions§

get_ranges: Simple library interface quickly retrieves and parses the AWS IP Ranges using the default client configuration. Returns a boxed AwsIpRanges object that allows you to quickly query (search, filter, etc.) the AWS IP Ranges.

Type Aliases§

Error
Result

Crate awsiprangesCopy item path