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 — and shows it all in a console and through an API. Log ingestion, fleet-wide detection and controller-side reporting 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, a starter tree under /etc/shieldlist/controller (local listeners, no rules yet), and enables the service. 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). 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), OpenAI (OAI-SearchBot, ChatGPT-User, GPTBot), Cloudflare, Fastly, Ahrefs, Automattic (Jetpack), UptimeRobot, Pingdom, Stripe (webhooks).
• 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.