How can I create, list, get, or update AWS WAFV2 IPSets using the AWS CLI?

Last updated: 2022-10-31

How can I create, list, get, or update an IPSet in AWS WAFV2 using the AWS Command Line Interface (AWS CLI)?

Short description

An IPSet specifies the web requests to permit or block based on the IP addresses that the requests originate from . You can use IPSet to define a set of IP addresses for a web access control list (ACL) using the AWS CLI.

Resolution

Note: If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you’re using the most recent AWS CLI version.

This resolution uses the wafv2 CLI to create an IPSet in a specific AWS Region or a global IPSet for use in Amazon CloudFront.

Important: Before proceeding, you must check the default AWS Region of the AWS CLI to verify that’s the Region where you want to create the IPSet. Otherwise, you must specify the correct Region for the IPSet (using the —region option) in your commands. When using Amazon CloudFront, you must create the IPSet in the US East (N. Virginia) us-east-1 Region.

Create an IPSet

1.     Sign in to the AWS CLI.

2.    Create an IPSet using the command create-ip-set.

Note: The —scope option specifies whether this IPSet is for an Amazon CloudFront distribution or for a Regional application. Regional applications include: Application Load Balancer (ALB), Amazon API Gateway, REST API, AWS AppSync, GraphQL API, or, an Amazon Cognito user pool.

Regional IPSet example:

$ aws wafv2 create-ip-set --name ipv4-block --scope REGIONAL --ip-address-version IPV4 --addresses 10.1.1.1/32 --region us-west-1
{
    "Summary": {
        "Name": "ipv4-block",
        "Id": "952c5e24-2352-4a1e-a90b-01499086be1b",
        "Description": "",
        "LockToken": "c54cc0d5-42dc-4b4b-9335-a86c7ad784a6",
        "ARN": "arn:aws:wafv2:us-west-1:1111222233334444:regional/ipset/ipv4-block/952c5e24-2352-4a1e-a90b-01499086be1b"
    }
}

CloudFront IPSet example:

$ aws wafv2 create-ip-set --name ipv4-block-cf --scope CLOUDFRONT --ip-address-version IPV4 --addresses 10.1.1.1/32 --region us-east-1
{
    "Summary": {
        "Name": "ipv4-block-cf",
        "Id": "1fef3860-8b6e-4201-8a56-6d8d49e93057",
        "Description": "",
        "LockToken": "9e9bc59e-678e-4b83-98d8-5a4c119b0123",
        "ARN": "arn:aws:wafv2:us-east-1:1111222233334444:global/ipset/ipv4-block-cf/1fef3860-8b6e-4201-8a56-6d8d49e93057"
    }
}

List IPSets

To list IPSets, use the command list-ip-sets. The response returns an array of IPSetSummary objects.

Regional IPSet example output:

$ aws wafv2 list-ip-sets --scope REGIONAL --region us-west-1
{
    "NextMarker": "ipv4-block",
    "IPSets": [
        {
            "Name": "ipv4-block",
            "Id": "952c5e24-2352-4a1e-a90b-01499086be1b",
            "Description": "",
            "LockToken": "c54cc0d5-42dc-4b4b-9335-a86c7ad784a6",
            "ARN": "arn:aws:wafv2:us-west-1:1111222233334444:regional/ipset/ipv4-block/952c5e24-2352-4a1e-a90b-01499086be1b"
        }
    ]
}

CloudFront IPset example output:

$ aws wafv2 list-ip-sets --scope CLOUDFRONT --region us-east-1
{
    "NextMarker": "ipv4-block-cf",
    "IPSets": [
        {
            "Name": "ipv4-block-cf",
            "Id": "1fef3860-8b6e-4201-8a56-6d8d49e93057",
            "Description": "",
            "LockToken": "9e9bc59e-678e-4b83-98d8-5a4c119b0123",
            "ARN": "arn:aws:wafv2:us-east-1:1111222233334444:global/ipset/ipv4-block-cf/1fef3860-8b6e-4201-8a56-6d8d49e93057"
        }
    ]
}

Note: If you specify a value for Limit and have more IPSets than this value, then AWS WAFV2 returns a NextMarker value. See Request parameters.

Update an IPSet

To update an IPSet, use the command update-ip-set with either shorthand syntax or a JSON file.

Shorthand syntax method

1.    Use the list-ip-sets command to retrieve the IPSet Id and LockToken for the IPSet you want to update.    

Note: AWS WAFV2 uses a token for optimistic locking. To make changes to the entity associated with the token, provide the token to operations such as update and delete. WAFV2 uses the token to confirm that no changes were made to the entity since you last retrieved it. If a change was made, the update fails with a WAFOptimisticLockException. If this happens, perform another list or get, then use the new token returned by that operation.

Shorthand syntax example:

$ aws wafv2 list-ip-sets --scope REGIONAL --region us-west-1  
{
    "NextMarker": "ipv4-block",
    "IPSets": [
        {
            "Name": "ipv4-block",
            "Id": "952c5e24-2352-4a1e-a90b-01499086be1b",
            "Description": "",
            "LockToken": "c54cc0d5-42dc-4b4b-9335-a86c7ad784a6",
            "ARN": "arn:aws:wafv2:us-west-1:1111222233334444:regional/ipset/ipv4-block/952c5e24-2352-4a1e-a90b-01499086be1b"
        }
    ]
}

2.    Use the update-ip-set command to override the current IPSet configuration with the new desired configuration. You must include the IPSet Id and LockToken retrieved in step 1 above.

Example:

$ aws wafv2 update-ip-set --name ipv4-block --scope REGIONAL --id 952c5e24-2352-4a1e-a90b-01499086be1b --addresses "10.1.1.1/32" "10.1.1.2/32" --lock-token c54cc0d5-42dc-4b4b-9335-a86c7ad784a6 --region us-west-1
{
    "NextLockToken": "a459c121-f160-4475-9352-fa602ff33df7"
}

3.    Use the get-ip-set command to review the changes to the IPSet. You must include the IPSet Id from step 1 and the NextLockToken from step 2.

Example:

$ aws wafv2 get-ip-set --scope REGIONAL --name ipv4-block --id 952c5e24-2352-4a1e-a90b-01499086be1b --region us-west-1
{
    "IPSet": {
        "Name": "ipv4-block",
        "Id": "952c5e24-2352-4a1e-a90b-01499086be1b",
        "ARN": "arn:aws:wafv2:us-west-1:1111222233334444:regional/ipset/ipv4-block/952c5e24-2352-4a1e-a90b-01499086be1b",
        "Description": "",
        "IPAddressVersion": "IPV4",
        "Addresses": [
            "10.1.1.2/32",
            "10.1.1.1/32"
        ]
    },
    "LockToken": "a459c121-f160-4475-9352-fa602ff33df7"
}

JSON file method

1.    Create a JSON file (such as ip.json) with your update request syntax. Do this using your preferred editor.

Example:

$ nano ip.json
{
    "Addresses": ["10.1.1.0/24", "10.1.2.0/24", "10.1.3.0/24"]
}

2.    Use the list-ip-sets or get-ip-set commands to retrieve the IPSet Id and LockToken for the IPSet you want to update.

Example:

$ aws wafv2 list-ip-sets --scope REGIONAL --region us-west-1 
{
    "NextMarker": "ipv4-block",
    "IPSets": [
        {
            "Name": "ipv4-block",
            "Id": "952c5e24-2352-4a1e-a90b-01499086be1b",
            "Description": "",
            "LockToken": "238872dc-fcfb-4a45-93fd-115cfcc94480",
            "ARN": "arn:aws:wafv2:us-west-1:1111222233334444:regional/ipset/ipv4-block/952c5e24-2352-4a1e-a90b-01499086be1b"
        }
    ]
}

3.    Use the update-ip-set command to override the current IPSet configuration with the new desired configuration. Rather than including the addresses inline, you will reference the “ip.json” file created in step 2. You must include the IPSet Id and LockToken retrieved in step 2 above.    

Example:

$ aws wafv2 update-ip-set --scope REGIONAL --name ipv4-block --id 952c5e24-2352-4a1e-a90b-01499086be1b --lock-token a459c121-f160-4475-9352-fa602ff33df7 --region us-west-1 --cli-input-json file://ip.json
{
    "NextLockToken": "238872dc-fcfb-4a45-93fd-115cfcc94480"
}

4.    Use the get-ip-set command to review the changes to the IPSet. You must include the IPSet Id from step 2 and the NextLockToken from step 3.

Example:

$ aws wafv2 get-ip-set --scope REGIONAL --name ipv4-block --id 952c5e24-2352-4a1e-a90b-01499086be1b --region us-west-1
{
    "IPSet": {
        "Name": "ipv4-block",
        "Id": "952c5e24-2352-4a1e-a90b-01499086be1b",
        "ARN": "arn:aws:wafv2:us-west-1:1111222233334444:regional/ipset/ipv4-block/952c5e24-2352-4a1e-a90b-01499086be1b",
        "Description": "",
        "IPAddressVersion": "IPV4",
        "Addresses": [
            "10.1.1.0/24",
            "10.1.2.0/24",
            "10.1.3.0/24"
        ]
    },
    "LockToken": "238872dc-fcfb-4a45-93fd-115cfcc94480"
}