Package Information
Available Nodes
Documentation generating…
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.
- In n8n, go to Settings → n8n API → Create an API key.
- Create an n8n API credential with the key, and the Base URL of your n8n ending in
/api/v1(for examplehttps://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/8and block10.0.0.5, and only10.0.0.5is 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