Shieldlist agent
The program that runs on a protected machine: it reads that machine's logs, decides what is an attack, and enforces the answer in the kernel. It is a complete product on its own — configured locally by default, enrolled to a controller as an option.
log line → parser → hit → threshold → trigger → ban → nftables
A parser recognises something in a category of logs. A rule counts what parsers find and fires when its threshold is crossed inside its window. A policy says how long the ban lasts and how it escalates on repeat. An exemption removes the sanction and never the observation.
Enforcement is nftables sets with per-element timeouts, so a ban outlives the agent: killing the process is a detection gap, never an unban.
Pages
| Getting started | Install, watch what it would do, then arm it |
| Enrolment | Joining a controller: what comes from it, what stays yours |
| Configuration | Every file and every key, with what each is for |
| Writing rules | Parsers, thresholds, weights, and testing a rule before arming it |
| Commands | The full CLI, and why acting commands go through the agent |
| Replay | Reading a log's past, and the rule that makes it useful |
| Abuse reporting | Submitting offenders to AbuseIPDB — and what can never leave |
| Enforcement | How a ban actually stops traffic, and what survives a restart |
| Sizing and limits | What it costs the machine — and the budget no setting bounds |
| Troubleshooting | When something looks wrong |
In the repositories
The wiki is the guide; these are the authority, and they are versioned with the code.
| Specification | Vocabulary, requirements and open decisions. Settles anything this wiki gets wrong. |
| Configuration reference | The format, key by key |
| What it costs the machine | Measured figures for memory, processor and disk |
Where the project stands
Released: v0.0.9 (2026-08-26) — enrolment to a controller, the
simple rule format (one rule per file, threshold: 5/10m, packs as
lists of rules, levels instant/strict/standard/lenient), rule
packs for sshd, the web, mail, BIND, MariaDB and Plesk, country and
network keys on rules and exemptions, per-site targets, ban sharing by
pack across a fleet, published lists held in firewall sets of their
own, and a large amount of work on how the agent behaves under a flood.
The releases before it: v0.0.3 brought one-chance reporting to
AbuseIPDB, shield report and shield tail, hooks, the
prefilter_any multi-literal prefilter, and the machine's own
addresses never banned. The agent does the whole job on its own: it reads files
and journald units, parses, evaluates order-tolerantly, decides with
policies, exemptions and trust, enforces in nftables, and keeps its own
durable record. It has been run against five million distinct attackers
on a two-core virtual machine without losing a ban.
The APT suite to install is stable: it carries the releases and keeps
them. A dev suite carries our development builds — ahead of the
releases, and expected to break. This wiki describes the released code.
Not there yet: release signing — the checksums prove the download was not corrupted and nothing more; discovery, which would propose what to watch instead of being told; log centralisation on the controller.