aws-samples / aws-ipranges-api

Provides AWS IP prefixes as web feeds for auto update by firewalls and applications

AWS-IPRanges-API

Serverless web site that outputs IP prefixes from AWS ip-ranges.json as web feeds for use by firewalls and other applications. Also allows IP address lookup of corresponding Region, service and network border group.

Description

AWS publishes its IP ranges in json format through ip-ranges.json. The IP prefixes are commonly used by network firewalls for inbound and/or outbound network access control.

A common use case is Amazon CloudFront with on-premise web server as origin; only CloudFront origin facing (and if in use Route 53 Health Checks) IP prefixes are allowed inbound access at perimeter network firewall.

Another use case is for egress control where firewall administrators allow-list or deny-list outbound network acess to all or specific AWS service or Region such as Route 53 name servers or Amazon S3

Typically, the firewall administrator will extract out required IP prefixes from ip-ranges.json for use in firewall rules. The IP prefixes need to be updated whenever there are changes and users can subscribe to AWS IP address ranges notifications

This project makes IP prefixes available as web feeds for automatic updates by firewalls. Users have the option to filter IP prefixes by service, Region and network border group, and in combined IPv4 and IPv6, IPv4 only or IPv6 only format. Entire solution is serverless and can be deployed via a single CloudFormation file.

Solution is mentioned in blog post How to enhance CloudFront origin security of on-premise web servers using third-party firewalls

Architecture Diagram

Deployment via CloudFormation console

Download aws-ipranges-api.yaml file and login to AWS CloudFormation console. Choose Create Stack, Upload a template file, Choose File, select template.yaml and choose Next.

CloudFormation Parameters

Specify a Stack name and adjust parameters values as desired. Parameters options include

HTTP API

• allowNetworks: Source IP prefixes that are authorized to use site separated by commas. Default is 0.0.0.0/0
• awsServices: Name of AWS services to return by root URL separated by commas. Default is CLOUDFRONT_ORIGIN_FACING

Lambda

• pythonRuntime: Python runtime version. Default is python3.12
• cpuArchitecture: Instruction set architecture (x86_64 or arm64). Default is arm64
• lambdaFunctionName: Lambda function name. Default is aws-ipranges-api
• lambdaAuthorizerFunctionName: Lambda authorizer function name. Default is aws-ipranges-api-authorizer

[Optional] Custom domain name

This section allows the use of custom domain name and is optional.

• customDomainName: custom domain name for your API
• certificateArn: ARN of ACM certificate
• disableDefaultEndPoint: option to disable default endpoint. This ensures that clients can only access site by using specified custom domain name

Continue Next with Configure stack options, Review settings, and click Create Stack to launch your stack.

After stack has been successfully created, its status changes to CREATE_COMPLETE.

CloudFormation Outputs

The following are available in Outputs section

• apiGatewayInvokeURL (if disableDefaultEndPoint is false ): URL of format https://<api-id>.execute-api.<region>.amazonaws.com) for use by firewall. Refer to Output options below for details.

• apiFQDN (if customDomainName is specified): Create a DNS CNAME or Route 53 alias record of your customDomainName to this value

• apiGatewayLog: API Gateway CloudWatch log URL

• lambdaFunctionLog: Lambda function CloudWatch log URL

• lambdaAuthorizerFunctionLog: Lambda authorizer function CloudWatch log URL

Firewall Setup

Firewalls that support external IP prefixes web feeds include (but not limited to)

• Cisco: Custom Security Intelligence Feeds
• Fortinet: External Block List
• Palo Alto Networks: External Dynamic List
• OPNsense: URL Tables (IPs) Aliases
• pfSense: URL Table Aliases

Refer to vendor website documentation for configuration steps. Check Point users have access to AWS IP prefixes from Updatable Objects

Output options

Use different URLs to return IP prefixes and other values. Example

• / : return CloudFront origin facing prefixes, customizable via awsServices in CloudFormation template and Lambda function SERVICES environment variable
• /SERVICE : listing of available services
• /REGION : listing of available Regions
• /NETWORK : listing of network border groups which are a unique set of Availability Zones or Local Zones from where AWS advertises IP addresses
• /SERVICE/<SERVICE> : prefixes for specific SERVICE, e.g. /SERVICE/CLOUDFRONT_ORIGIN_FACING
• /SERVICE/<SERVICE>/<REGION> : prefixes for specific SERVICE and REGION, e.g. /SERVICE/EC2/us-east-1
• /REGION/<REGION> : prefixes for specific REGION, e.g. /REGION/ap-southeast-1
• /NETWORK/<NETWORK> : prefixes for specific network border group, e.g. /NETWORK/us-east-1-nyc-1
• /SEARCH/<IP ADDRESS>: IPv4 or IPv6 address to query, e.g. /SEARCH/13.34.96.200. This will return any matching entries, e.g.

  ip_prefix,region,service,network_border_group
  13.34.96.224/27,ap-southeast-1,AMAZON,ap-southeast-1
  

• /createDate : ip-ranges.json publication date and time, in UTC YY-MM-DD-hh-mm-ss format
• /syncToken : ip-ranges.json publication time, in Unix epoch time format

For IP prefixes, you can append /ipv4.txt or /ipv6.txt to filter by IPv4 or IPv6 respectively, e.g. /SERVICE/ROUTE53_HEALTHCHECKS/ipv4.txt

API Gateway Customisation

Refer to Amazon API Gateway documentation for HTTP API customisation options. Some examples include

• Setting up custom domain names
• Working with AWS Lambda authorizers for HTTP APIs: Lambda authorizer is used to limit access by source IP prefixes
• Configuring mutual TLS authentication
• Throttling requests to your HTTP API

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.