What to expect in beta

Shieldlist 0.1.0 is a beta. That word is doing real work here, so this page says exactly what it means — what is solid, what will move, and what is not built yet.

Run it on a server you can afford to fix

Not because it is fragile: the fleet it was built for runs it in production and it blocks tens of thousands of offenders a day. But it is young, you are among the first outside that fleet, and the failure mode of a blocker that gets something wrong is that somebody legitimate cannot reach you.

Start in detect-only. A fresh install does, and a machine that enrols does, and that is deliberate. Read a day of what it would have done — shield tail, shield status, or the console — and arm it when the verdicts are the ones you would have made. That single habit prevents almost every bad first day.

Exempt yourself first. Your own addresses, your monitoring, your office. The console will happily ban the address you administer from, and warns you once a session while it is not exempt.

Read what a rule says before arming it. Every shipped rule says what it blocks, what it applies to, what it needs and what to watch out for — in the file, in the console, in GET /v1/rules. Some are off by default because they cannot tell a customer from an attacker without a setting you have to make; they say so.

What is solid

Detection, scoring and enforcement. The rules are the ones running a real fleet daily; their numbers come from measurement, not taste, and every one carries its reasoning in the file.

The kernel side. Bans survive a restart, expire on their own, and losing the controller never unbans anything.

The agent alone. It has no database, no daemon beside it, and it does not need a controller to be useful.

Debian and Ubuntu. Debian 12 and 13 are what the fleet runs on; Ubuntu 26.04 LTS is where a fresh install was walked through from the public pages before this release, agent and controller both. The Red Hat family is next.

What will move

Rule and configuration formats. They are stable enough that we run them, and they have changed twice this year. When they change again, the change comes with a converter, but an upgrade may want your attention.

Storage. One SQLite file per product. It holds a large fleet comfortably; it is not the last word, and a future version will split the counters and the heavy background writes from the store people read.

One controller. No clustering, no failover. If it stops, agents keep enforcing what they already know and buffer what they see.

The rule library. How rules reach you will change: today they ship in the binary and an upgrade replaces them under /usr/share; a catalogue with accounts, updates you accept with a diff, and premium packs is being built.

Abuse desks. Mailing the networks' abuse desks is new and the desks are a zoo: robots, forms, tickets, silence. The patterns that read their answers are the ones we have met; a desk we have not is sorted as unknown and waits for you. Turn it on rule by rule, and read the Reports page for a week before you trust it unattended.

What is not built yet

• Roles. An account is either an operator, who can do everything, or an owner of named machines with a permission per area. Granular roles for operators are next.
• A corrected rule reaches you whole, or not at all. The library lives under /usr/share, which an upgrade replaces: a rule we corrected replaces ours on your machine, and a copy you made under the same name in /etc keeps winning. There is no diff to accept yet; the catalogue will do that properly.
• Packages beyond Debian and Ubuntu. RPM for the Red Hat family is planned. Other distributions build from source without trouble; shield init writes the library from the binary. Tell us if you need one.
• Reporting into a shared base. What the fleet has learned is published as lists you can subscribe to; letting you report into that base is designed and not written.

Known issues

mail-auth reads zero hits until Dovecot logs refused passwords. It needs auth_verbose_passwords = sha1:6 in conf.d/10-logging.conf, which is off by default everywhere — no distribution and no panel turns it on. Nothing is broken while it is off; there is simply nothing to read. mail-auth-fail, off by default, is the rule for a Dovecot without the hash: turn it on instead of mail-auth, not beside it, and read its beware first.

A ban scoped to ports on a whole range is refused, not applied. Ranges are blocked entirely or not at all; a range ban carrying a port list is said in the journal and bans nothing. It is bounded and rare — the fix belongs in the data plane.

Custom resolvers allow one origin. If the public page detects the visitor's addresses through resolvers of your own (ipv4_url, ipv6_url), they answer with Access-Control-Allow-Origin for the page's name; move the page to a name of its own and the resolvers must allow the new one too — otherwise the page shows no address and says nothing about why.

The registries' dumps cost memory to build. With registries: on, the first build and the weekly rebuild read a few hundred megabytes and hold about a gigabyte for a minute. A controller co-installed on a small machine should leave it off and let RDAP answer.

Telling us

Issues on the repository, in English or French. What helps most: the version of both products, what you expected, what happened, and the log line if a rule judged something wrongly — a false positive with its line is worth ten reports without one.

Rules are data. If one of ours is wrong for your machine, you can lower it, except a path from it, or switch it off, without waiting for us — and an exemption is the right first answer to a customer's odd client, not a rule change that lives on every machine.