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 |
| What to expect in beta | What is solid, what will move, what is not built yet, the known issues |
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.1.0, the beta — the agent arrives with the free rule
library and finds the machine's logs by itself (shield init), reads
the journal where a service keeps no file, joins a controller in one
command (shield enrol) and takes its state from it, runs as its own
user, counts and bans IPv6 at the /64 and may widen a ban to the
allocation, caps a ban's length by trust, carries the source port of
each convicting line to the abuse desks, and sends its controller
deltas rather than the whole picture. Read
What to expect in beta before installing it
on a machine you cannot afford to fix.
Before it, v0.0.9 (2026-08-26) brought enrolment, the simple rule
format (one rule per file, threshold: 5/10m, packs as lists of rules,
levels instant/strict/standard/lenient), country and network
keys on rules and exemptions, per-site targets, ban sharing by pack
across a fleet, and published lists held in firewall sets of their
own; v0.0.3, one-chance reporting to AbuseIPDB, shield report and
shield tail, hooks, 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; packages beyond Debian; log centralisation on the controller.