shieldlist-controller

The central service for a fleet of Shieldlist agents: it assembles and pushes each machine's configuration, records the sanctions agents decide and redistributes them to the fleet, takes the operator's decisions — lift, exempt, settle a machine, edit a rule — reports the offenders to a reputation database and to the abuse desks of the networks they come from, reads what the desks answer, and shows it all in a console and through an API. Log ingestion and fleet-wide detection come next (SPEC §10).

The product specification is docs/SPEC.md; the configuration reference — the agent's files, the controller's tree, the API and the console — is docs/CONFIG.md. The agent that runs on protected machines lives in shieldlist-agent; the wire protocol it implements is published here, in proto/shieldlist/v1/agent.proto.

Running it

shieldlist-controller -t -config /etc/shieldlist/controller   # validate the tree, every machine's assembly included
shieldlist-controller -config /etc/shieldlist/controller      # serve: agents on :17453, API and console on 127.0.0.1:17454
shieldlist-controller account -name you                        # the first person; api-token -name x for a script
shieldlist-controller token                                    # a join token; then `shield enrol <token>` on the machine

On Debian and its derivatives, from the APT repository (https://repo.lrob.net/apt/shieldlist/ — the key, the suites stable and dev, and the two lines to add are on that page; fingerprint B528 0C88 7016 8A94 40A9 05C4 3BB5 8113 CFAB 6DC5): apt install shieldlist-controller, or apt install ./shieldlist-controller_<version>_<arch>.deb from the release page (one per architecture). The package creates the shieldlist user, puts the free rule library under /usr/share/shieldlist-controller (six packs, given to every machine that enrols without a declaration, in test), writes a starter tree under /etc/shieldlist/controller (local listeners), and enables the service; shieldlist-controller init does the same by hand, never replacing a file. packaging/ holds the unit and the hand-install notes for other systems. shield -controller URL -token T drives the fleet from any machine.

Third-party software

The binaries link a handful of Go modules, each under its own licence: yaml.v3 (MIT/Apache-2.0), modernc.org/sqlite with libc, mathutil and memory (BSD-3), google.golang.org/protobuf (BSD-3), golang.org/x/sys, x/crypto and x/term (BSD-3), github.com/google/uuid (BSD-3), github.com/dustin/go-humanize (MIT), github.com/remyoudompheng/bigfft (BSD-3), github.com/emersion/go-imap (MIT). Their licence texts are reproduced in THIRD_PARTY_LICENSES (regenerated by make third-party from what is actually linked) and shipped in the packages under /usr/share/doc/shieldlist-controller/. Shieldlist itself is free software under the GNU AGPL v3.

Contributing

See CONTRIBUTING.md. Go 1.25; make proto regenerates the protocol (buf, protoc-gen-go); the rule language is imported from the agent's public config package.

License

This project is licensed under the GNU Affero General Public License v3.0 — see the LICENSE file.

SPDX identifier: AGPL-3.0-only

Credits

Shieldlist stands on other people's work, credited here, on the console's Settings → About page, and in the wiki.

• Map: Natural Earth country outlines (public domain), embedded — no tiles, no third party at run time.
• Geolocation: with geoip: {source: dbip} the controller fetches the free DB-IP Lite country, ASN and (optionally) city databases monthly — IP Geolocation by DB-IP, CC BY 4.0.
• Published blocklists (the console's catalogue, fetched only when turned on): malicious-ip by Romain Marcoux, an hourly aggregate of fifteen threat feeds, MIT licence.
• Published allow lists (sources:, fetched only when turned on): the address ranges their publishers make public — Google (Googlebot, special crawlers), Microsoft (Bingbot), Apple (Applebot), DuckDuckGo (DuckDuckBot, DuckAssistBot), OpenAI (OAI-SearchBot, ChatGPT-User, GPTBot), Anthropic (Claude-User, Claude-SearchBot, ClaudeBot), Perplexity (Perplexity-User, PerplexityBot), Mistral AI (MistralAI-User, MistralAI-Index; and its outbound addresses, for MCP connectors), Google's user-triggered fetchers, PrestaShop (CloudSync), Cloudflare, Fastly, Ahrefs, Automattic (Jetpack), UptimeRobot, Pingdom, Stripe (webhooks).
• Abuse reports: the X-ARF export and the mails to the networks' abuse desks follow the XARF specification (v4) by the XARF Project, MIT licence — xarf.org. The abuse desks are found through the free Abusix Abuse Contact DB (one DNS query per network, drawn from the RIRs' records; each mail acknowledges it, as they ask); then, when the operator keeps them locally, the registries' own databases — the RIPE Database (data of the RIPE NCC, under the RIPE Database Terms and Conditions) and the AFRINIC database (data of AFRINIC, under its Database Terms and Conditions), fetched as their published dumps, personal data removed by the registries — and, failing that, the registries' own RDAP service via rdap.org. The delivery failures are read over IMAP with go-imap by Simon Ser (MIT).
• Rules: parts of the rule packs are translated from the CrowdSec hub (MIT) and the bad-bots list is built from Mitchell Krogza's nginx-ultimate-bad-bot-blocker — both credited in the rules repository too.
• Software: the Go modules listed under Third-party software.