Shieldlist

Get started

Shieldlist is two programs. The agent runs on every server you protect; it reads the logs, decides and bans on its own. The controller runs on one machine of yours and gives the fleet a single console, a single place for rules and exemptions, shared bans and reporting. Start with the agent; the controller comes when you have more than one machine — or when you want rules delivered automatically.

1. Install the agent

On Debian and its derivatives, from the APT repository:

curl -fsSL https://repo.lrob.net/apt/shieldlist/shieldlist.gpg -o /usr/share/keyrings/shieldlist.gpg
echo "deb [signed-by=/usr/share/keyrings/shieldlist.gpg] https://repo.lrob.net/apt/shieldlist stable main" > /etc/apt/sources.list.d/shieldlist.list
apt update && apt install shieldlist-agent

stable carries the releases. There is also a dev suite with our development builds: ahead of the releases, and expected to break.

The package installs the agent, the shield command and a systemd unit, and starts in detect-only: every rule records what it would have done, the firewall is not touched. Look at shield status and shield why <address> for a day, then arm it.

Other distributions and the build from source are covered in the agent's Getting Started.

2. Give it rules

A rule is a short YAML file; a pack is a directory of them, with the parsers the rules read with and the ban policies they apply. Free packs are in the library: read them, download them, copy the files under /etc/shieldlist/, then validate:

shieldlist-agent -t      # reports every problem at once
shieldlist-agent -dry-run /var/log/auth.log   # what the rules would have done

3. Enrol the machine to a controller

This is the step that makes rules arrive on their own. An enrolled agent stays the same program — it still decides locally — but its configuration comes from the controller, and the controller fetches the packs your account allows, free and premium, and pushes them and their updates to every machine that should have them. Without enrolment, rules only reach a machine by hand.

Install the controller on one machine (same repository, apt install shieldlist-controller), open its console, mint a join token, and on each server:

# /etc/shieldlist/agent.yaml
mode: enrolled
controller: https://controller.example.net:17453

systemctl restart shieldlist-agent
shield enrol <join-token>

The full procedure is in the controller's Getting Started and the Enrolment page.

Where to read more