Overview
One agent blocking an address is an observation. Forty agents blocking the same address is a different kind of fact, and it is invisible to any agent looking only at its own traffic.
Fleet bans close that gap in two halves: the ban ledger uploads what this agent decided to block, and the fleet set downloads what the deployment corroborated. They are kept apart on purpose, so a fleet ban is never re-reported as fresh evidence and corroboration never becomes an echo.
When you see this
- The same source shows up on several agents, minutes apart.
- An attacker works through your sites one after another.
- Each agent blocks the source, but only after the source has reached it first.
Steps
- 01
Turn on both halves
Both inherit platform.base_url. interval_secs is how fast a ban propagates, not how much traffic it costs: a tick whose snapshot has not changed sends nothing. refresh_secs is a cheap version check; the set is downloaded only when its version changes.
/etc/synapse/config.yaml platform: ban_ledger: enabled: true interval_secs: 60 fleet_bans: enabled: true refresh_secs: 60 advisory: true advisory_dedup_secs: 300 enforce: false - 02
Protect your own infrastructure
Every agent re-applies two checks to whatever the platform serves: anything not unambiguously global-unicast is dropped, and so is your own infrastructure in HOME_NET. A public load balancer VIP is global-unicast, so it must be in HOME_NET; banning it blackholes every client behind it. On Kubernetes the operator puts the VIPs there.
/etc/synapse/config.yaml ids: address_vars: HOME_NET: "10.0.0.0/8" - 03
Run it advisory and read the numbers
Out of the box a fleet ban is consulted, counted and logged, and traffic is unaffected. Judge a ban by agents against agent_count_total, a ratio rather than a count, and by the layers that reported it: three agents agreeing through three layers is stronger than one rule firing three times.
DecisionDo the corroborated bans hold up against your own traffic?Yes Enforce on the agents where they do.
No Stay advisory. The set is still consulted, counted and logged.
- 04
Enforce in the kernel
Each fleet ban goes into the same kernel IP filter local bans use, and comes out when its deadline passes or the fleet withdraws it. Fleet bans take at most a quarter of the filter, leaving the rest for this agent's own bans. enforce is read at startup, so changing it takes a restart.
/etc/synapse/config.yaml platform: fleet_bans: enforce: true - 05
Behind a load balancer, enforce at the proxy
The kernel sees only the balancer's address, so a kernel ban on the client never matches. With PROXY protocol the proxy knows the real client and refuses a fleet-banned one with 403 and X-Block-Reason: fleet_ban. It does not use X-Forwarded-For for this.
/etc/synapse/config.yaml proxy: protocol: enabled: true - 06
Know what is never enforced
An address you allow in access_rules.allow, your own infrastructure, an address your configuration already blocks, and a ban without a deadline. Rejections are counted as rejected_unsafe, rejected_protected and rejected_malformed, so a set that arrives but is discarded is visible rather than looking empty.
Common mistakes
- Writing a threshold as a count of agents instead of a ratio of agent_count_total.
- Leaving a load balancer VIP out of HOME_NET.
- Expecting a kernel fleet ban to work behind a load balancer without PROXY protocol at the proxy.
Escalate when
- A fleet ban on an address your own users come from.
- rejected_protected climbing: the platform is serving bans on your own infrastructure.
Where this stops working
- An unloaded set is not an empty one. Before the first set arrives, a miss means we do not know yet, not that the address is clean.
- A stopped agent lifts nothing. What it installed stays in the filter until the next start.
- Turning enforcement off takes a restart.