Central Blocklist

UnrealIRCd.org Central API Services

• Central API: What is it and how to get an API Key
• Central Blocklist: Block spammers/drones on-connect
• Central Spamreport: Report spam via SPAMREPORT
• Central Spamfilter: Centralized spamfilter rules

The UnrealIRCd Central Blocklist is an attempt to detect and block spammers.

This works similar to DNS Blacklists but the central blocklist receives many more details about the user that is trying to connect and therefore can make a better decision on whether a user is likely a spammer or not.

The same module also comes with a way to report spam to us, via Central spamreport.

IMPORTANT: All documentation on this page assumes UnrealIRCd 6.1.3(-git) or higher. If you want to test with 6.1.2 then see here for the old docs.

Current status

Since November 25, 2023, this functionality is being integrated in (upcoming) UnrealIRCd 6.1.3 and all documentation reflects this.

Since November 6, 2023, you can request an API key here.

Since October 8, 2023, multiple networks have been testing centralblocklist and since then we achieve a 100% rate of catching efknockr.

How it works / Privacy

How it works

When a user connects, the following information is sent to the central blocklist over HTTPS. This information may be expanded on future module updates. The current list is: server name, unrealircd version, central-blocklist module version, api key, timestamps, nick, user/ident, realname/gecos, IP, host, server, local port, remote port, TLS details, TCP/IP session details, geoip and reputation as looked up by the IRCd, plus the entire IRC handshake except that PASS and AUTHENTICATE are excluded (not sent).

Thanks to all that information, the central blocklist has a lot of information and will assign a spam score from 0 to 15. Then, it is up to the configuration in the module on your server what to do with that. By default a score of 5 and above are flagged as spam and cause the connection to be rejected.

Not all users are checked by central blocklist. By default users using SASL and with a high reputation score are allowed in without checking.

Why sending data to a centralized server

The reason we send nick/user/host/ip and all of the other data is because they all give "properties" to match and detect on. The checking centralized has big benefits because it allows the system to spot patterns, score at lots of different properties, putting it all together, without exposing to spammers the way we detect them. You can probably understand how some botnets can easily be detected when they have a fixed list of nick names and usernames, and how proxies can be detected via DNSBL lookups. Central blocklist does that (or may do that) and also has other detection methods. It can benefit from multiple sources of information and do quick updates.

The source code of the central blocklist server is not available because then spammers could read how things are detected and (more) easily evade the detection. Not 100% relies on this secrecy, but sadly quite some of it does. Yes, I wished that problem would not exist, as everyone self-hosting or using an unrealircd module locally would be so much easier for us, saves us all the money for hosting the centralblocklist infrastructure too. But that isn't an option, spammers would just work around things and harm this effort to stop spam.

Not publishing the source code / not showing how things are detected is not unique to centralblocklist. Right now, especially with all the efknockr spam, most of the medium and larger nets made spamfilters, modules, configured tools, to fight the spam but they do not share it with the rest of the world. At least with centralblocklist all the (legit) networks running UnrealIRCd, even smaller ones have a chance to combat this spam.

Who gets to see the data

Traffic is routed through Cloudflare, and then to our webserver(s) handling the central blocklist. IP addresses may be further sent on to DNSBLs and other blacklist services, exposing the IP to them. Such third-party exposure of the IP address is pretty similar to using a blacklist { } block. Or, actually even a bit better because the DNSBL gets queried by us so they have no idea that the IP is from a user on your network.

Currently, logs on the webserver are kept and contain both requests and responses, because everything is so new and in development, to help debug problems and to improve things. Log files are retained in RAM (not on disk) for a maximum of 30 days after which they are deleted. The plan is to reduce this to 7 days or shorter.

There's one exception: for users who scored 5+ (so were detected as potentially troublesome) we may retain details for up to 30 days, which may include on-disk (like a database). This so we can investigate genuine hits and false positives.

Staff consists of two groups:

• Currently only Syzop has access to the CBL worker machines and the logs
• More staff members (5-10) have access to an admin dashboard to approve and issue API keys, see all current API accounts, block API accounts, see general hit statistics, status, etc. They do not have access to CBL request/response logs.

Should I use this service?

Above it was mentioned what data is sent, why, if and what data is stored, where and who has access to what. Maybe you are still not comfortable with this. Then it is perfectly fine and understandable if you don't want to use this service. After all, IRC is decentralized and this checking is the opposite: centralized. IRC being decentralized is great as it allows anyone to self-host their network and make their own rules, community and everything. The checking centralized has big benefits as mentioned under Why centralized. If you use the service then you can enjoy blocking a lot of spammers before they even get online. If you don't want to use this service then you can still use all the other great spam fighting features of UnrealIRCd. We totally understand both points of view, it is up to you to decide.

Configuration

Before you begin, you also need the central-api module loaded with the api-key set there. See Central API or request an API key straight at https://www.unrealircd.org/central-api/request-account.

Then, you need to load the central-blocklist module:

loadmodule "central-blocklist";

You may also want to enable Central spamreport now that you are at it, this service is opt-in:

spamreport unrealircd { type central-spamreport; }

If you want to configure the module further, here are all the config options, including the defaults. It is recommended that you DO NOT COPY all of this, so we can change the defaults later:

/* These are the current default settings */
set {
	central-blocklist {
		/* Enable Central Blocklist? This defaults to 'yes'.
		 */
		blocklist-enabled yes;

		/* You can have multiple score blocks, each with different actions.
		 * The highest score wins (order does not matter) and only that block is executed.
		 * By default we have actions for score 7+ and 5+.
		 * IMPORTANT: If you add ANY score block to the conf, then all the
		 * default score blocks will not be used. So you need to either add all or none.
		 */

		/* Score 10+ is likely a real spambot, so we shun silently for a decent period */
		score 10 {
			ban-action shun;
			ban-time 1h;
			ban-reason "Rejected by central blocklist";
		}

		/* Score 5 to 9 are proxies or spambots with less certainty - do a short kline */
		score 5 {
			/* Ban action */
			ban-action kline;
			ban-time 15m;
			ban-reason "Rejected by central blocklist";
		}

		/* Don't check these users. By default we include
		 * various exceptions here that are a good idea.
		 * NOTE: If you add your own except block then the
		 * defaults settings are completely ignored. So to
		 * amend it (eg add an IP) you would need to duplicate
		 * the entire block and then add that IP.
		 */
		except {
			reputation-score 2006;
			mask { *.irccloud.com; }
			ip { 127.*; 192.168.*; 10.*; }
			identified yes;
		}
	}
}