API

Pull the list into your server, check single addresses, and report what your server blocks. Every call is JSON over HTTPS.

The MCSec plugin

The easiest way: one plugin for Spigot, Paper, BungeeCord, Waterfall and Velocity. It downloads the list, refuses listed addresses at login and reports join floods, ping floods, chat spam bots and crash books by itself.

Download MCSec.jar and put it in the plugins folder of your proxy (best) or server.
Start the server once, then put your API key in plugins/MCSec/config.properties (api-key=).
Run /mcsec reload. /mcsec status shows the list size and what was refused and reported.

Commands (permission mcsec.admin): /mcsec status, /mcsec reload, /mcsec check <player|ip>, /mcsec report <player|ip> <category> [evidence]. Set mode=log to only watch for a while before refusing anyone.

Your key

Use your server's API key from Panel → API & integrations. Only servers that are live on CraftRank can use MCSec. Send the key in a header, never in the address:

X-API-Key: your-32-character-key

Twenty wrong keys from one address in ten minutes and that address waits ten minutes.

Pull the list

GET https://craftrank.org/api/mcsec?a=blocklist&min=75
GET https://craftrank.org/api/mcsec?a=blocklist&min=60&format=txt
GET https://craftrank.org/api/mcsec?a=blocklist&category=crash-exploit

min is the lowest confidence to include, 40 to 100 (default 75). format=txt gives one address per line; IPv6 entries are /64 ranges. Pull at most once a minute on Free (every 15 seconds on Pro, every 10 on Network); every few minutes is enough for most servers. Firewall formats are under Formats.

{"min":75,"count":2,"generated":1793567000,
 "addresses":[{"ip":"203.0.113.7","ref":"MCT-7F3A9C","score":92,"category":"bot-join-flood","last":1793566880}, …]}

Check one address

GET https://craftrank.org/api/mcsec?a=check&ip=203.0.113.7

Up to 120 checks a minute. The answer has listed, score, ref and the categories.

Report an attacker

POST https://craftrank.org/api/mcsec?a=report
ip=203.0.113.7&category=bot-join-flood&evidence=46 joins in 60 s with 46 names

For many at once, send up to 100 in one call:

POST https://craftrank.org/api/mcsec?a=bulk
Content-Type: application/json

{"reports":[{"ip":"203.0.113.7","category":"crash-exploit","evidence":"oversized book packet, 2.1 MB","time":1793566880}]}

Report only what your server blocked itself. Write the evidence in a few words: what was seen and how much. Do not paste the attack itself (payloads, exploit strings) and do not include addresses, links or e-mail addresses; they are removed, because evidence is shown in public. Reports of the same address and category within ten minutes count as one. Up to 2,000 reports an hour per server. Collect reports and send them with bulk every few seconds instead of one call per report: more than about 90 calls a minute from one address is slowed down by the site firewall.

Categories

category	Name	What it is
`bot-join-flood`	Bot join flood	Many fake players joining from one address or range.
`ping-flood`	Ping & status flood	Server list pings sent hundreds of times a second.
`query-flood`	Query flood	UDP query packets used to load or reflect traffic.
`ddos`	Network flood (DDoS)	Raw traffic aimed at taking the server offline.
`crash-exploit`	Crash exploit	Packets built to crash the server: books, NBT, chunks.
`packet-spam`	Packet spam	Movement, chat or click packets far above normal rates.
`login-brute-force`	Login brute force	Many wrong passwords on /login or /register.
`rcon-brute-force`	RCON brute force	Password guessing on the RCON port.
`server-scanner`	Server scanner	Bots that sweep the internet looking for open servers.
`port-scan`	Port scan	Probing many ports on the same machine.
`forwarding-bypass`	Forwarding bypass	Joining the backend directly to skip BungeeCord or Velocity.
`remote-code`	Remote code attempt	Log4Shell and similar payloads in names or chat.
`chat-spam`	Chat spam bots	Bots posting ads, links or slurs right after joining.
`proxy-abuse`	Open proxy or VPN abuse	Exit nodes used for repeated attacks or ban evasion.
`website-attack`	Website attack	Attacks on the server website, store or vote pages.
`panel-attack`	Hosting panel attack	Login guessing or exploits against game panels.

How the score works

Each server that reported an address in the last 30 days adds to its score. A server counts more when other servers report the same addresses (its trust), when it reported the address several times, and when the reports are recent; a week-old report counts half. Crash exploits and remote code attempts count more than scans.

One server alone can never take an address above 55. Refusing needs several servers.
Home and mobile connections stay at 60 or below and leave the list after 3 days without reports, because their addresses change.
40 and up is listed. 75 and up is refused by servers that use the default.
A listing ends after 14 days without reports.

Formats

Add format= to the blocklist call. port=25565 limits the firewall formats to one port.

format	What you get
`json`	The default: every address with its reference, score, category and last report.
`txt`	One address per line.
`csv`	A spreadsheet: ip, ref, score, category, last_report.
`ipset`	For `ipset restore`: sets `mcsec` (IPv4) and `mcsec6` (IPv6).
`nftables`	For `nft -f`: a table `inet mcsec` that drops listed addresses.
`iptables`, `ip6tables`	For `iptables-restore -n`: a chain `MCSEC`; jump to it from INPUT.
`crowdsec`	For `cscli decisions import -i file.json`: 24-hour bans.

curl -s -H "X-API-Key: $KEY" "https://craftrank.org/api/mcsec?a=blocklist&min=75&format=nftables&port=25565" | nft -f -

Pro and Network calls

These calls come with the paid plans.

GET  https://craftrank.org/api/mcsec?a=history&ip=203.0.113.7        (Pro)
GET  https://craftrank.org/api/mcsec?a=changes&since=0              (Network)
POST https://craftrank.org/api/mcsec?a=check_bulk   {"ips":["203.0.113.7", …]}  (Network, up to 500)

The changes feed returns addresses that joined or left the list, or crossed 75; pass the next number back as since. A call your plan does not include answers 402 plan_required.

Errors

401 bad_key, 403 not_active, 403 blocked, 400 bad_ip / bad_category / not_reportable (private addresses, search engines and Cloudflare are never listed), 402 plan_required, 429 rate_limited with a Retry-After header.