Skip to main content

AWS WAF Ipset

Knocknoc has no built-in AWS WAF integration. You drive a WAF IP set with a Custom script knoc and a script you write, which the agent calls as add <aclname> <address> and del <aclname> <address>. This page covers the AWS side first, then the Knocknoc side.

AWS WAF Setup from Scratch

Create a WAF Web ACL (REGIONAL Scope)

  1. AWS Console → WAF & Shield → Web ACLs → Create web ACL
  2. Name: e.g., KnocknocWebACL
  3. Scope: REGIONAL (for ALB)
  4. Region: Same as your ALB
  5. Default action: Block. Expand Customize the response on it: response code 403, and paste the HTML below as the response body. Anything that does not match the allow rule gets this page.
  6. Logging (optional): Enable if you want to view WAF logs in CloudWatch Logs, S3, or Kinesis Firehose
  7. Create Web ACL
<head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Forbidden</title>
        <link rel="preconnect" href="https://fonts.googleapis.com">
        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
        <link href="https://fonts.googleapis.com/css2?family=Raleway:ital,wght@0,100..900;1,100..900&display=swap" rel="stylesheet">
        <style>
                body {
                        text-align: center;
                        background-color: #171717;
                        color: #ffffff;
                }
                .container {
                        margin: 60px 0;
                        padding: 60px;
                }
                h1 {
                        font-family: "Raleway", sans-serif;
                        font-optical-sizing: auto;
                        font-size: 4em;
                        font-weight: 300;
                        font-style: normal;
                }
                h2 {
                        font-family: "Raleway", sans-serif;
                        font-optical-sizing: auto;
                        font-size: 2em;
                        font-weight: 300;
                        font-style: normal;
                }
                span {
                        color: #35b59b;
                }
        </style>
</head>
<body>
        <div class="container">
                <h1>Access Denied.</h1>
                <h1>You must <span>Knoc</span> before you enter.</h1>
        </div>

        <svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" width="300" height="300" viewBox="0 0 166.57 156.56">
                <defs>
                        <style>
                                .cls-1 {
                                        fill: none;
                                }
                                .cls-1, .cls-2 {
                                        stroke-width: 0px;
                                }
                                .cls-2 {
                                        fill: #35b59b;
                                }
                        </style>
                </defs>
                <g id="Layer_1-2" data-name="Layer 1">
                        <path class="cls-2" d="M166.57,119.18c0,4-2.29,5.09-5,6.28l-103.5,31.1L0,126.1l86-17.7c.36-.16.73-.3,1.11-.41,3.26-.87,4.2-.65,8.58,1l42,17.66.14-117.91L90.75.81V.24l75.77-.24.05,119.18Z"/>
                        <line class="cls-1" x1="55.63" y1="32.13" x2="41.78" y2="18.28"/>
                        <rect class="cls-2" x="44.57" y="15.4" width="8.27" height="19.59" transform="translate(-3.55 41.82) rotate(-45)"/>
                        <rect class="cls-2" x="29.03" y="46.02" width="18.27" height="8.27"/>
                        <line class="cls-1" x1="54.19" y1="67.14" x2="40.34" y2="79.15"/>
                        <rect class="cls-2" x="38.1" y="69.01" width="18.34" height="8.27" transform="translate(-36.37 48.85) rotate(-40.93)"/>
                </g>
        </svg>
        <div class="container">

                <h2>It can take around 30 seconds for access to be granted.</h2>
        </div>
</body>

Tip: The AWS Console has a limit of ~4 KB for the custom response body. This snippet is within that limit, but if you have a larger HTML page, you may need to reduce it.

Create an IP Set

  1. WAF & Shield → IP sets → Create IP set
  2. Name: e.g., KnocknocIPSet
  3. Scope: REGIONAL (same region as above)
  4. IP address version: IPv4 (commonly)
  5. You can leave addresses empty for now and update via the script.
  6. Create IP set. Note the Name and ID (e.g. ipset-abc12345).

Attach the Web ACL to Your ALB

  1. EC2 Console → Load Balancers
  2. Select your Application Load Balancer
  3. Under Description / “Edit attributes,” find AWS WAF Web ACL
  4. Edit → Select the Web ACL you created (e.g., KnocknocWebACL)
  5. Save

Alternatively, you can map the ALB to the WAF rule on first setup.

Add a Rule to Allow the IP Set

  1. Go to WAF & Shield → Web ACLs → click KnocknocWebACL → Rules tab
  2. Add rules → Add my own rules and rule groups → Regular rule
  3. Name: BlockIPsViaKnocknocAllowIPsViaKnocknoc (for example)
  4. IF → IP set → select the IP set you created (KnocknocIPSet)
    • Match type: Source IP
  5. Then → Action: Allow
  1. Click Add rule → Save.

Now any address in KnocknocIPSet reaches your ALB, and everything else gets the custom 403 page.

IAM Permissions (Minimal)

Attach a policy allowing:

  • ListIPSets (wafv2:ListIPSets)
  • GetIPSet (wafv2:GetIPSet)
  • UpdateIPSet (wafv2:UpdateIPSet)

…for your Knocknoc user or an IAM role. Example snippet:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowListingAllIPSets",
            "Effect": "Allow",
            "Action": [
                "wafv2:ListIPSets"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AllowGetUpdateSpecificIPSet",
            "Effect": "Allow",
            "Action": [
                "wafv2:GetIPSet",
                "wafv2:UpdateIPSet"
            ],
            "Resource": "<INSERT YOUR ARN HERE>"
        }
    ]
}

Substitute your region, account ID, and IP set details.

Configure Knocknoc to Update the WAF IP set

You need an agent on a host that can reach the AWS API, and the AWS CLI on it if your script uses it. knocker checks both:

/opt/knocknoc-agent/knocker/knocker enable aws

Knocknoc ships no WAF script, so write your own. The agent calls it as add <aclname> <address> to grant and del <aclname> <address> to revoke, with the same values in knoc_action, knoc_aclname and knoc_ipaddr. The full contract, including the info and list actions, is on Custom Script. Your script reads the set with aws wafv2 get-ip-set and writes it back with aws wafv2 update-ip-set, which is what the IAM policy above grants.

In the admin portal, on Knocs, choose Create new knoc, then Custom script under On host. Pick the agent, give it the absolute path to your script, and put the IP set id in the knoc's ACL name so the script knows which set to write. Assign users or groups as usual.

Custom scripts are refused unless the agent was started with them enabled.

Final Notes

  1. Propagation Delay: Expect about 30–60 seconds for WAF changes to take effect.
  2. Testing: Confirm by hitting the ALB from the allowed IP after an “add” (should see normal access) or from a removed IP (should see the HTML 403).
  3. Minimal IAM Policy: Provide only wafv2:ListIPSets, wafv2:GetIPSet, and wafv2:UpdateIPSet for the specific IP set ARN.
  4. Logging: If you enabled WAF logging, you can watch CloudWatch Logs for real-time evidence that the IP was blocked (action=BLOCK) or allowed.

You are now set to manage IP-based access, with a custom 403 page, on your ALB using AWS WAF and your own script.