- Go 97.8%
- Shell 1.9%
- Makefile 0.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
5a9daa3d3a
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011J4W737efrhGtQRUEJ12Z2 Signed-off-by: Robin <git@lrob.net> |
||
| assets | ||
| cmd | ||
| config | ||
| docs | ||
| examples | ||
| geoip | ||
| internal | ||
| packaging | ||
| proto/shieldlist/v1 | ||
| report | ||
| scripts | ||
| shipped | ||
| testdata/load | ||
| .gitignore | ||
| buf.gen.yaml | ||
| buf.yaml | ||
| CLAUDE.md | ||
| CONTRIBUTING.md | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
| THIRD_PARTY_LICENSES | ||
shieldlist-agent
The Shieldlist agent runs on a protected machine and defends it on its own: it tails its declared log inputs, evaluates its rules locally, applies sanctions to the machine's nftables, and keeps every decision in a local store that survives restarts. One binary, configured by plain YAML files, no external service on the machine it protects.
The shield CLI ships alongside it: status, stats, bans, why,
unban, exempt, replay — aggregate-first, built for a store that can
hold millions of bans.
It arrives with the free rule library — SSH, mail, BIND, MariaDB, the
web rules that convict on the request itself — and shield init names
the logs the machine actually keeps, in detect-only: a machine is
watched the evening it is installed, and armed when a person says so.
The same agent enrols to a central controller as an option, never a
requirement — standalone is a mode, not a fork. Enrolled (shield enrol -controller URL <join-token>), it receives its parsers, rules, policies
and the fleet's exemptions from the controller and applies a new
revision in place, takes its state from it, reports every sanction it
decides, enforces the fleet's sanctions and the lifts decided centrally.
It is one implementation of the agent protocol, which is published from
shieldlist-controller as a public API; shield also drives the whole
fleet through the controller (-controller URL -token T).
Installing
On Debian and its derivatives, from the APT repository (amd64, arm64, armhf, riscv64):
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
The repository is signed with the Shieldlist key, fingerprint
B528 0C88 7016 8A94 40A9 05C4 3BB5 8113 CFAB 6DC5 (gpg --show-keys shieldlist.gpg); dev in
place of stable gets prereleases and development builds. The same .deb
files sit on the release page, one per architecture, for apt install ./file.deb.
The package installs shieldlist-agent and shield under /usr/sbin,
the rule library under /usr/share/shieldlist-agent, the shieldlist
user the agent runs as, the systemd unit, and — on a machine with no
agent.yaml yet — runs shield init, which names the logs this machine
keeps and enforces nothing; the service is enabled and started.
Upgrading (apt install ./newer.deb) restarts the agent, replaces the
library and touches no configuration; purging removes the agent's state
and configuration, never a co-installed controller's.
Elsewhere, or without packages, the installer script:
curl -fsSLO https://git.lrob.net/Shieldlist/shieldlist-agent/raw/branch/main/scripts/install.sh
less install.sh # it is one file of sh — read it
sh install.sh
It installs the binaries for this machine's architecture, checks them
against the release's SHA256SUMS, and installs the systemd unit; then
shield init writes the library from the binary and a first
configuration that names the logs it found and enforces nothing:
every rule records what it would have done and nftables is never
touched. Run it beside whatever already guards the machine, read a day
of it with shield status, shield bans and shield why, then set
state: on and restart.
Re-running upgrades the binaries and touches no configuration. Nothing is unbanned by a restart: the sets and their timeouts live in the kernel.
make build builds both binaries from source; there is no cgo, so every
supported architecture is a plain cross-compile (make dist).
Release signing is not implemented yet — a checksum served from the same host as the binary proves the download was not corrupted and nothing more (SPEC §11).
Documentation
- Configuration reference:
docs/CONFIG.mdinshieldlist-controller— the dry-run validator (shieldlist-agent -t) is its ground truth. - What the agent costs the machine, and the one limit no setting can bound: docs/RESOURCES.md.
- The administrator's guide: the wiki.
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 (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-agent/. Shieldlist itself is free
software under the GNU AGPL v3.
Contributing
See CONTRIBUTING.md.
Credits
An enrolled agent is served the free DB-IP Lite country and ASN databases by
its controller — IP Geolocation by DB-IP, CC BY 4.0 —
for countries/asns in rules and the origin shown by shield. The rule
packs credit their own sources (the CrowdSec hub, Mitchell Krogza's bad-bots
list) in the rules repository; the controller's README and wiki carry the
full credits.
License
This project is licensed under the GNU Affero General Public License v3.0 — see the LICENSE file.
SPDX identifier: AGPL-3.0-only