IP Whitelist Shaping Using the Middleware Manager and Pangolin

Mattercoder · May 25, 2025, 8:23am

Getting Started with the IP Whitelist Shaper Plugin Using Middleware Manager and Pangolin

IP Whitelist Shaper is a Traefik plugin that provides dynamic, admin-approved IP whitelisting. It’s especially useful for environments where temporary access to protected services is required.

This guide will walk you through a minimal working example using Pangolin, Middleware Manager, and the new Plugin Hub.

Use the Traefik Dashboard to debug and confirm that your configurations are active.

Features At-a-Glance

Temporary, time-limited IP access
Admin approval via Discord webhook
User-friendly request UI (/knock-knock endpoint)
Automatic whitelist expiration
Smart IP detection (with support for proxies)

Step-by-Step: Simple Setup

Step 1: Enable the Plugin

Open the Plugin Hub in Middleware Manager and enable:

experimental:
  plugins:
    ipwhitelistshaper:
      moduleName: github.com/hhftechnology/ipwhitelistshaper
      version: v1.0.7

Screenshot - the plugin added to traefik_config.yml

Restart Traefik:

docker compose restart traefik

Step 2 (Optional): Set Up Discord Webhook

To receive approval requests in Discord:

Create a server
Create a channel or use an existing one
Click the gear icon > Integrations > Webhooks > Create Webhook
Copy the webhook URL

Screenshot webhook creation in Discord

Step 3: Add Middleware via Middleware Manager

If not already in templates.yml, add:

- id: "ipwhitelistshaper"
  name: "ipwhitelistshaper"
  type: "plugin"
  config:
    ipwhitelistshaper:
      approvalURL: "https://mywebsite.yourdomain.com"
      defaultPrivateClassSources: "true"
      excludedIPs:
      expirationTime: "300"
      ipStrategyDepth: "0"
      knockEndpoint: "/knock-knock"
      notificationURL: "https://discord.com/api/webhooks/webhook-id"
      saveInterval: "30"
      secretKey: ""
      storageEnabled: "false"
      whitelistedIPs:
        - "127.0.0.1/32"
        - "192.168.1.0/24"
        - "10.0.0.0/8"

Restart Middleware Manager:

docker compose restart middleware-manager

Step 4: Create a Resource to Protect

Option A: Use an Existing Resource

Just attach the ipwhitelistshaper middleware.

Option B: Create a Test Resource

Add to docker-compose.yml:

  python-http:
    image: python:3.11-slim
    container_name: python-http
    working_dir: /app
    command: python -m http.server 15000
    ports:
      - "15000:15000"
    restart: unless-stopped

Then in Pangolin:

Create resource mywebsite.yourdomain.com
Point to: python-http port 15000
Apply your new ipwhitelistshaper middleware in Middleware Manager

Screenshot Suggestion: Resource form in Pangolin for mywebsite.yourdomain.com

Step 5: Testing

Attempt to Access the Protected Resource

Visit:

https://mywebsite.yourdomain.com

You should get a 403 Forbidden.

Visit the Knock Endpoint

Go to:

https://mywebsite.yourdomain.com/knock-knock

You will see:

Approval Required
Your request requires approval.
Validation code: elephant

Screenshot - Knock-knock page showing validation code

‍:clipboard: Admin Approves the Request

The admin receives a Discord message with:
- IP address
- Validation code
- Approval link

Clicking the approval link:

Whitelists the IP for 5 minutes (or your configured value)
Displays a confirmation page

Screenshot - Discord webhook message + approval success screen

Summary

You now have a working, secure IP approval system that:

Prevents unauthorized access
Empowers admins to grant short-lived access
Supports Discord for approval workflows
Is fully integrated into Pangolin and Middleware Manager

Thanks for Following Along

For more complex configurations (e.g., persistent storage, advanced headers, or multi-admin workflows), visit the official GitHub repo.

Happy shaping!

phneeley · June 25, 2025, 11:09pm

If The approval URL refers to a specific resource being protected, how is it that we can apply the IP whitelist shaper to multiple resources at the same time? What am I missing?

Mattercoder · June 26, 2025, 6:13am

Use the middleware manager to add the middleware to each resource

phneeley · June 26, 2025, 11:18am

Thanks for the reply. I’ve added it to one of my resources via middleware manager, but since the approval url in the JSON config refers to that specific resource (app1.mydomain.com), how does one successfully apply it in middle ware manager to another resource (app2.mydomain.com). I must be missing how to configure the JSON to dynamically apply to the protected resource’s url.

Mattercoder · June 26, 2025, 11:33am

Yes. I see the problem. @hhf.technoloy may know if there’s a workaround

joe-cole1 · August 4, 2025, 12:13pm

If I might make a suggestion…

This would be incredible if integrated with pangolins email whitelist or perhaps just the normal user login.

Use case:

User is added as an approved user via pangolin authentication

This doesn’t allow login via apps, like for example phone or TV apps

User visits url and logs in via pangolin, which then automatically whitelists their IP

No admin intervention required!

hhf.technoloy · August 4, 2025, 12:15pm

interesting suggestion.. let see what i can do.

joe-cole1 · August 5, 2025, 5:13pm

I’ve been thinking about this a lot. I want to use pangolin authentication as much as possible. Whitelisting an IP doesn’t bypass pangolin authentication right?

So this idea would really need to be integrated into pangolin, not just traefik? Or does the pangolin IP whitelist under rules also use traefik, so this idea would bypass pangolin authentication as well?

joe-cole1 · August 24, 2025, 6:24pm

@hhf.technoloy A fork of this script would allow a very quick update to the knock knock to allow pangolin whitelisting as well. A version that could whitelist in pangolin and crowdsec via a visit to a URL would be absolutely KILLER!

Anyone willing to take on the project? I unfortunately do not have the capability.