Skip to main content

ELLIO Traefik Middleware Plugin

The ELLIO Traefik Middleware Plugin provides dynamic IP-based access control for services behind Traefik proxy. It integrates seamlessly with the ELLIO platform to automatically manage IP allowlists and blocklists through External Dynamic Lists (EDL), protecting your services against malicious scanners and mass exploitation attempts.

Blocked Request What malicious actors see when blocked by the ELLIO Traefik Middleware Plugin

Overview​

This middleware plugin protects your Traefik-proxied services by automatically blocking or allowing traffic based on dynamic IP lists managed through the ELLIO platform.

Key Benefits:

  • Automatic Threat Protection: Block malicious IPs without manual intervention
  • Zero-Maintenance Security: Set once, get continuous protection updates
  • Centralized Control: Manage IP rules for all your services from one platform
  • Flexible Protection Modes: Block known bad IPs or allow only trusted IPs
  • Reliable Operation: Continues protecting during network outages using cached lists

GitHub Repository: ELLIO-Traefik-Middleware-Plugin

Prerequisites​

  • Traefik v3.0 or later
  • Bootstrap token from your EDL configured for "Traefik Middleware"

Quick Start​

1. Add Plugin to Traefik​

Add the ELLIO plugin to your Traefik static configuration:

# traefik.yml
experimental:
  plugins:
    ellio:
      moduleName: github.com/ELLIO-Technology/ELLIO-Traefik-Middleware-Plugin
      version: v1.0.1

2. Configure Middleware​

Create a middleware instance in your dynamic configuration:

# dynamic-config.yml
http:
  middlewares:
    ellio-edl:
      plugin:
        ellio:
          bootstrapToken: "YOUR_ELLIO_BOOTSTRAP_TOKEN"
          logLevel: "info"
          ipStrategy: "direct"

3. Apply to Routes​

Apply the middleware to your services:

http:
  routers:
    my-service:
      rule: Host(`api.example.com`)
      middlewares:
        - ellio-edl
      service: my-backend

Deployment Scenarios​

Choose the setup guide that matches your infrastructure:

Configuration Reference​

Core Parameters​

ParameterTypeRequiredDefaultDescription
bootstrapTokenstringYes-EDL bootstrap token from ELLIO platform
logLevelstringNo"info"Logging verbosity: trace, debug, info, warn, error
machineIdstringNorandom UUIDMachine identifier - by default plugin generates random UUID, but you can override it, especially for multiple Traefik instances using the same EDL
ipStrategystringNo"direct"IP extraction strategy
trustedHeaderstringNo-Custom header name (for "custom" strategy)
trustedProxies[]stringNo-Trusted proxy IP ranges

IP Extraction Strategies​

  • direct - Use the direct connection IP address (default)
  • xff - Extract from X-Forwarded-For header (reverse proxies)
  • real-ip - Extract from X-Real-IP header
  • custom - Extract from a custom header specified in trustedHeader

How It Works​

Using the bootstrap token, the plugin fetches your EDL configuration and adjusts the access control mode:

  • Blocklist mode: All IPs in the EDL are blocked and receive 403 errors, other IPs are allowed
  • Allowlist mode: Only IPs in the EDL are allowed, all other IPs are blocked. Be careful when protecting services that require additional IPs like local IP ranges (for example, if protecting a Pangolin installation, you need to also allow site IP ranges)

EDL configuration (blocklist/allowlist mode) is refreshed approximately every 5 minutes. The actual EDL IP lists are downloaded based on your EDL update frequency settings in the platform (from every 5 minutes to every 24 hours).

Blocked events are sent to the ELLIO platform for monitoring. If you have access to CTI, you can lookup blocked IPs, search by User Agents and ASNs.

Testing Your Setup​

For blocklist mode (most common):

  1. Add a test IP to your IP ruleset in ELLIO platform
  2. Wait for EDL regeneration (based on your update frequency)
  3. Test from the blocked IP - should receive 403 Forbidden
  4. Test from other IPs - should access normally

For allowlist mode:

  1. Add your current IP to the allowlist in ELLIO platform
  2. Wait for EDL regeneration
  3. Test from allowed IP - should work normally
  4. Test from non-allowed IP - should be blocked

Monitoring in ELLIO Platform​

When the plugin is working correctly, you'll see blocked requests logged in the ELLIO platform:

ELLIO Platform Logs Example of blocked requests visible in the ELLIO platform dashboard

Support​