Package: aws-cidr-finder
aws-cidr-finderOverviewAn ExampleInstallationConfigurationUsageCLIPythonContributingOverviewaws-cidr-finderis a Python CLI tool and library that finds unused CIDR blocks (either IPv4 or
IPv6) in AWS VPCs. It is a very simple tool, but it can be of great help to users who manage many
subnets across one or more VPCs and do not want to spend the money required to use a solution likeAWS IPAM.An ExampleIt is easiest to see the value of this tool through an example. Imagine that we have the following
setup in AWS:A VPC whose CIDR is172.31.0.0/16, with aNametag ofHello WorldSix subnets inside that VPC whose CIDRs are:172.31.0.0/20172.31.16.0/20172.31.32.0/20172.31.48.0/20172.31.64.0/20172.31.80.0/20AnAWS CLI profilenamedmyprofileaws-cidr-finderallows you to quickly compute the CIDRs that you still have available in the VPC
without having to do a lot of annoying/tedious octet math. If we issue this command:aws-cidr-finder--profilemyprofileWe should see this output:Here are the available CIDR blocks in the 'Hello World' VPC (VPC CIDR block '172.31.0.0/16'):
CIDR               IP Count
---------------  ----------
172.31.96.0/19         8192
172.31.128.0/17       32768
Total                 40960You should notice that, by default,aws-cidr-finderwill automatically "simplify" the CIDRs
by merging adjacent free CIDR blocks so that the resulting table shows the maximum contiguous space
per CIDR (in other words, the resulting table has the fewest number of rows possible). This is why
the result of the command displayed only two CIDRs: a/19and a/17.Note that the first CIDR is/19instead of, for example,/18, because the/18CIDR would
mathematically have to begin at IP address172.31.64.0, and that IP address is already taken by a
subnet!However, we can change this "simplification" behavior by specifying the--prefixCLI flag:aws-cidr-finder--profilemyprofile--prefix20Now, the expected output should look something like this:Here are the available CIDR blocks in the 'Hello World' VPC (VPC CIDR block '172.31.0.0/16'):
CIDR               IP Count
---------------  ----------
172.31.96.0/20         4096
172.31.112.0/20        4096
172.31.128.0/20        4096
172.31.144.0/20        4096
172.31.160.0/20        4096
172.31.176.0/20        4096
172.31.192.0/20        4096
172.31.208.0/20        4096
172.31.224.0/20        4096
172.31.240.0/20        4096
Total                 40960With the--prefixargument, we can now query our available network space to our desired level of
detail. Note that if we specify a--prefixwith a value lower than any of the prefixes in the
originally-returned list, those CIDRs will be skipped. For example, if we run the following:aws-cidr-finder--profilemyprofile--prefix18We should see this output:Note: skipping CIDR '172.31.96.0/19' because its prefix (19) is numerically greater than the requested prefix (18)

Here are the available CIDR blocks in the 'Hello World' VPC (VPC CIDR block '172.31.0.0/16'):
CIDR               IP Count
---------------  ----------
172.31.128.0/18       16384
172.31.192.0/18       16384
Total                 32768The CIDR that was skipped was the172.31.96.0/19CIDR because it is impossible to convert a/19CIDR into one or more/18CIDRs.InstallationIf you have Python >=3.10 and <4.0 installed,aws-cidr-findercan be installed from PyPI using
something likepipinstallaws-cidr-finderConfigurationAll that needs to be configured in order to use this CLI is anAWS CLI profileor
a keypair. The former may be specified using the--profileargument on the CLI, while the keypair
must be specified in environment variables. If both are available at the same time,aws-cidr-finderwill prefer the profile.The environment variables for the keypair approach areAWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY, and optionallyAWS_SESSION_TOKEN(if authenticating with a session).
These are the same environment variables that Boto uses.You should also ensure that the profile/keypair you are using has the AWS IAM access needed to make
the underlying API calls via Boto. Here is a minimal IAM policy document that fills this
requirement:{"Effect":"Allow","Action":["ec2:DescribeVpcs","ec2:DescribeSubnets"],"Resource":"*"}Read more about the actions shown abovehere.UsageCLISeeAn Exampleabove for a detailed demonstration of the CLI interface of this tool.
You can also useaws-cidr-finder --helpto see command line options.PythonSetup:fromaws_cidr_finderimportJSONOutput,find_available_cidrs# All argumentsoutput:JSONOutput=find_available_cidrs(profile_name="",region="",ipv6=False,desired_prefix=20)# Minimal arguments (profile-based authentication)output:JSONOutput=find_available_cidrs(profile_name="")# Minimal arguments (environment variable-based authentication)output:JSONOutput=find_available_cidrs()# Other miscellaneous combinationsoutput:JSONOutput=find_available_cidrs(profile_name="",ipv6=True)output:JSONOutput=find_available_cidrs(profile_name="",desired_prefix=16)output:JSONOutput=find_available_cidrs(region="")# ...and so onAccessing the CIDR data:output:JSONOutput=find_available_cidrs(...)# See aboveformessageinoutput["messages"]:# Print the messages that would have been written to STDOUT when using the CLIprint(message)forcidrinoutput["cidrs_not_converted_to_prefix"]:# If aws-cidr-finder could not convert a given available CIDR block into one or more CIDR blocks# with the requested desired_prefix, it will be returned in this list# Note: this is only applicable if you passed desired_prefix to find_available_cidrsprint(f"aws-cidr-finder did not convert the following CIDR block to the desired prefix:{cidr}")forvpcinoutput["data"]:# Print all the information that is available in the VPC dictprint(f'VPC ID:{vpc["id"]}')print(f'VPC Name:{vpc["name"]}')print(f'VPC CIDR:{vpc["cidr"]}')forcidrinvpc["available_cidr_blocks"]:print(f"Available CIDR block:{cidr}")ContributingSeeCONTRIBUTING.mdfor developer-oriented information.