firewall

Block IPs in front of your n8n webhooks: one Firewall Manager holds the list and the switches, every Firewall Scope in the channel follows it

Documentation

@abraao_o_h/n8n-nodes-firewall

Block IPs in front of your n8n webhooks, from one place.

  • Firewall Manager: holds the IP list and the switches of a channel. You edit it, save, and that is it.
  • Firewall Scope: goes right after each Webhook. It follows the Manager of its channel and sends each request to Allowed or Blocked.
  • Firewall Trigger (optional): starts a workflow when a Scope blocks an IP on the channel, for the Operator of the Manager.
Webhook → Firewall Scope ─ Allowed → your flow
                         └ Blocked → Respond to Webhook (403)

"Firewall" workflow:  Firewall Manager (channel: production)
                      IPs: 203.0.113.7, 198.51.100.0/24 …

Add an IP in the Manager, save the workflow, and within 10 seconds every Scope of the channel blocks it. You never open the Scopes.

Install

In n8n, go to Settings → Community Nodes → Install and enter @abraao_o_h/n8n-nodes-firewall.

Credential

Both nodes use the n8n API credential that comes with n8n: the Scopes read the Manager through the n8n API, and the Manager lists the Scopes of its channel.

  1. In n8n, go to Settings → n8n API → Create an API key.
  2. Create an n8n API credential with the key, and the Base URL of your n8n ending in /api/v1 (for example https://n8n.mycompany.com/api/v1).

The nodes only read. If your API key has limited scopes, it needs workflow:list and workflow:read.

For Import From Cloudflare, the Manager also uses the Cloudflare API credential that comes with n8n, with a token that can read: Account Filter Lists: Read for IP Lists, Account Firewall Access Rules: Read and Zone Firewall Services: Read for IP Access Rules.

Firewall Manager

Put it in a workflow of its own (for example "Firewall"). It does not need to run or to be active: saving the workflow is enough.

Field
Channel The Scopes with the same channel follow this Manager. One Manager per channel
Channel State Active: check the IP. Stop All Scopes: every Scope blocks everything. Let Everything Through: every Scope lets everything pass (maintenance)
List Mode Block the IPs Below, Allow Only the IPs Below (for partner webhooks), or Allow and Block (an Action on each IP)
IPs IPv4 or IPv6, alone or as a range (203.0.113.0/24, 2001:db8::/32). With a reason and an optional Expires At. In Allow and Block, an Action: Allow or Block
Ready-Made Lists Countries, Tor, Stripe, GitHub, Cloudflare IPs, read from their official sources (see below)
Import From Cloudflare The IP Lists and IP Access Rules of your Cloudflare account (see below)
Rate Limit Block an IP that sends more than Requests in Window seconds (see below)
Auto Block With Rate Limit: an IP that goes over the limit too often is blocked on every Scope of the channel for a while (see below)
Operator With Auto Block: reads what the Scopes blocked, sets a level from 1 to 3 and tells you, optionally with an AI (see below)
Scope Rules A state for one Scope: Active, Stop, Let Everything Through, or Follow the Channel. It wins over the Channel State. With Rate Limit on, also the limit of that Scope: the channel's, its own, or none

In Allow and Block:

  • A Block IP never passes, even inside an Allow range: allow 10.0.0.0/8 and block 10.0.0.5, and only 10.0.0.5 is blocked.
  • When some IP is Allow, only the Allow IPs pass. With only Block IPs, everyone else passes, as in Block the IPs Below.

Ready-Made Lists

List Source Read again every
Country (BR, PT, …) The IPs the internet registries (LACNIC, RIPE NCC, ARIN, APNIC, AFRINIC) gave to the country 24 h
Tor Exit Nodes The Tor Project 1 h
Stripe Webhooks stripe.com 6 h
GitHub Webhooks api.github.com/meta 6 h
Cloudflare IPs cloudflare.com/ips 6 h

The Scopes download the lists themselves, once per n8n process, and keep them in memory. The first request after n8n starts waits for the download (a few seconds for a country); after that the lists are read again in the background. If a download fails, the last list is kept and tried again in 5 minutes.

A country is not exact. The list says where an IP was registered, not where the person is. A server of a foreign cloud in Brazil (for example AWS São Paulo, registered in the US) is not in "BR", and a VPN gets around it. If a service of yours sends webhooks from a cloud, allow its IPs too.

An Allow list that could not be read yet blocks (it does not let everyone through). The blocked items show it in unavailable.

Import From Cloudflare

Turn on Import From Cloudflare and add what to read:

Read Becomes
IP List The IPs of a custom list of the account, as Allow or Block
IP Access Rules of a zone or an account Block and Challenge rules become Block, Allow rules become Allow. Country rules become country lists, and Tor (T1) the Tor list. ASN rules are skipped

Cloudflare is read when the workflow runs: put a Schedule Trigger before the Manager (every hour, for example) and activate the workflow. Each run saves what it read in the workflow, and the Scopes get it within their Sync Interval. A manual run shows what was read but does not save it. In Block mode the Allow rules of Cloudflare are left out, and in Allow mode the Block rules.

If n8n is behind the same Cloudflare zone, the IPs blocked there never reach n8n: importing them is useful for another zone, to use a list as Allow, or when n8n is not behind Cloudflare.

Rate Limit

Turn on Rate Limit and set Requests and Window (Seconds): 60 and 60 means one IP can send 60 requests in any 60 seconds. Above that, the requests go to Blocked with:

{ "allowed": false, "reason": "rate_limited", "ip": "203.0.113.7", "channel": "production", "rule": "60 per 60 s", "retryAfter": 12 }

Answer them with code 429 and the header Retry-After: {{ $json.firewall.retryAfter }}.

Field
Count Each Scope on Its Own (an IP has the limit on each webhook), or All Scopes Together (its requests to every webhook of the channel add up)
Skip Allowed IPs In Allow modes, the IPs let through by an Allow IP or list have no limit
A Scope Rule Own Limit gives a Scope another number of requests, No Limit turns it off for that Scope. Use the State Follow the Channel for a rule that only changes the limit

The rate limit protects your flow (the API or AI it calls, your database), not n8n: the requests still reach n8n. Blocked IPs and Let Everything Through are not counted.

Where the count is kept is chosen in each Scope, in Rate Limit Count:

  • In Memory (default): exact with one n8n. In queue mode each process counts on its own, so the real limit is the limit times the number of processes.
  • In Redis: every process shares the count. Uses the Redis credential that comes with n8n (you can use the Redis of queue mode). If Redis fails, the Scope counts in memory until it is back.

Auto Block

With Rate Limit on, turn on Auto Block: an IP that keeps going over the limit on one webhook is blocked on every webhook of the channel, not only on that one.

Field
Requests Over the Limit How many requests over the rate limit, on any Scope of the channel, block the IP. 10 by default
Within (Minutes) In this long. 10 by default
Block For (Minutes) How long the IP stays blocked on the whole channel. 15 by default
Show Blocked IPs From Where the Scopes keep the blocks, to list them when the Manager runs: Memory or Redis, as the Rate Limit Count of the Scopes
A Scope Rule Auto Block: Off leaves a Scope out: it neither blocks IPs for the channel nor follows the blocks

The blocked requests go to Blocked with reason: auto_blocked and retryAfter, the seconds left on the block. Execute step on the Manager lists the IPs blocked right now, with the seconds left.

  • Allowed IPs are never auto blocked: an IP let through by an Allow IP or list (Stripe, GitHub, a partner) is only rate limited. To unblock an IP before its time, add it as Allow.
  • The blocks are kept where the Scopes count (Rate Limit Count). In memory they only reach the Scopes of the same n8n process: in queue mode, count in Redis.
  • Keep Block For short: a mobile carrier can put many people behind one IP (CGNAT).
  • It does not stop an attacker who changes IP on every request.

Operator

The Manager can also work as the security guard of the channel: it reads what the Scopes blocked, sets a level, acts within limits, and tells you. Everything here is optional: without it the Manager works as before.

Firewall Trigger → Firewall Manager ─ Summary
                        ↑           ├ Level 1 → (nothing, or a log)
                   Chat Model       ├ Level 2 → Telegram
                   (optional)       └ Level 3 → Email

Turn on Operator (it needs Rate Limit and Auto Block). The Manager gets an output for each level, and an optional Chat Model input. Put a trigger before it and activate the workflow:

  • Firewall Trigger: starts right away when a Scope blocks an IP. Set the same Channel, and in Read From where the Scopes keep what they block (their Rate Limit Count). Gather For waits a few seconds for more events, so an attack is one run, not hundreds.
  • Or a Schedule Trigger every minute: the same, up to a minute later.

Each run reads what the Scopes blocked since the last run. With nothing new, only Summary comes out. Otherwise one item comes out on the output of its level:

{ "channel": "production", "level": 2, "by": "rules", "message": "Level 2 on the channel \"production\": 203.0.113.7 came to 2 webhooks. Blocked: 203.0.113.7 (Orders → Scope, Leads → Scope).", "ips": [{ "ip": "203.0.113.7", "webhooks": ["Orders → Scope", "Leads → Scope"], "until": "…" }], "events": 2 }
Level From the rules
1. Routine An IP went over the rate limit and was blocked on the channel
2. Attention Level 2 From IPs blocked in the Window (3 in 5 minutes by default), or one IP that came to more than one webhook
3. Critical Level 3 From IPs blocked in the window (20 by default), or an attack on an Important Webhook

With a Chat Model connected (OpenAI, Anthropic, Gemini, Ollama, any of n8n), the AI judges each case too: attack or false positive (a mobile carrier, a partner retrying). It writes the message in your Message Language, like a guard reporting to the boss, and comes out with by: "ai":

  • It can raise the level, never lower it: a big attack is always level 3, whatever the requests say.
  • It can extend the block of the IPs it was shown, up to AI Can Extend a Block Up To (24 hours by default). These come out in extended.
  • To unblock an IP or block it for good, it only proposes, in proposals: you decide.
  • What the clients sent (the User-Agent) goes to it as data. It is told never to follow instructions found there, and whatever it answers, it can only do the above.
  • If the AI fails or does not answer as asked, the rules decide, with aiError.

A Scope rule lets you stop everything but one Scope (Channel State Stop + a rule Active for it), or stop only one (a rule Stop for it).

The Scope list in Scope Rules comes from your saved workflows: save a Scope's workflow and it shows there as "Workflow → node". The rule follows the Scope by workflow and node name: if you rename the Scope node, choose it again.

The Scopes read the Manager as typed: expressions are not used in the Manager.

Execute step on the Manager shows what the Scopes will get: the IPs in force, the expired and invalid ones, every Scope of the channel with its state, and warnings (for example another Manager with the same channel: the last one saved wins).

Firewall Scope

Field
Channel The Manager to follow
Client IP From Where your proxy puts the real client IP (see below)
Sync Interval How often it reads the Manager again. 10 s by default, 2 s minimum
Without a Manager Allow (default) or Block, when the channel has no Manager or the n8n API failed before the first read

Set the Webhook to respond Using 'Respond to Webhook' Node, and connect a Respond to Webhook with code 403 to Blocked. Allowed items come out unchanged. Blocked items come out with a firewall field:

{ "allowed": false, "reason": "ip_blocked", "ip": "203.0.113.7", "channel": "production", "rule": "203.0.113.7", "note": "spam" }
reason
ip_blocked The IP is in the list (block mode), or is a Block IP (allow and block mode). rule says which: the IP, country:CN, tor, cloudflare:…
ip_not_allowed The IP is not in the list (allow mode), or not an Allow IP (allow and block mode)
channel_stopped The Manager stopped every Scope
scope_stopped The Manager stopped this Scope
no_ip The request has no client IP in the chosen header: check Client IP From
no_manager No Manager, and Without a Manager is Block
rate_limited The IP sent more than the Rate Limit. retryAfter says in how many seconds it can send again
auto_blocked The IP went over the Rate Limit too often, on some Scope of the channel. retryAfter says when the block ends

If the n8n API fails after a first read, the Scope keeps the last list it read (and adds stale: true to blocked items). It does not let everything through.

Client IP From

The Webhook does not see the client's address directly: your proxy passes it in a header. Choose the header your proxy sets, because any other header can be sent by the client with a fake IP.

n8n behind… Choose
Cloudflare Cloudflare (CF-Connecting-IP)
nginx, Traefik, Caddy, a load balancer, Easypanel, Coolify X-Forwarded-For, Last IP
nginx with proxy_set_header X-Real-IP $remote_addr X-Real-IP
Anything else Custom Expression

X-Forwarded-For, First IP is only safe when your proxy replaces the header instead of adding to it.

Limits

  • The Scope runs after the Webhook received the request: it stops your flow from handling a blocked IP, but the request still reaches n8n. Against floods (DDoS), block at Cloudflare or at your proxy.
  • Changes reach the Scopes within the Sync Interval (10 s by default), not instantly.
  • A new Manager is found within 30 seconds. After that, the Scopes only read the Manager workflows again, plus a full scan every 5 minutes.
  • The IPs typed in the Manager are meant for hundreds or a few thousands. The ready-made lists and Cloudflare are searched by range, and stay fast with hundreds of thousands.
  • The Scopes need to reach the internet to download the ready-made lists.

License

MIT

Discussion