smallwebwaf/docs/state-files.md

State files

The five JSON files in SWWAF_STATE_DIR, and what each holds. "Persistent state" in SPEC.md says how they are written, read and edited. Each has a top-level version of 1.

bans.json

Active and past bans: every ban an admin made, and up to SWWAF_MAX_BANS of those smallwebwaf made. Per entry:

• netblock, start and expires (null for a permanent ban);
• cause: attack, limit, admin or crowdsec;
• reason: a short reason;
• lifted: when an admin lifted it, if one did;
• notes: the notes below.

To ban a netblock, add an entry with its netblock, start and expires. reason, notes and cause may be left out; the cause is then admin:

{
    "version": 1,
    "bans": [
        {
            "netblock": "203.0.113.0/24",
            "start": "2026-10-06T12:00:00Z",
            "expires": null,
            "reason": "probes for logins"
        }
    ]
}

To lift a ban, add "lifted" with the time you lift it, such as "lifted": "2026-10-06T13:00:00Z". To keep a ban smallwebwaf made, set its cause to admin. To forget a ban, delete its entry.

The notes:

• asn, as_name and country: the client's, added when the lookup answers (empty when lookups are off);
• what was broken: the rule id and target that matched, or the trap path, or the limit, its window and the count reached;
• the client's percentage of the limit, with the setting that gave it;
• the reputation sources the client is on;
• request: the request that caused the ban: time, method, host, path with its query string, status and user agent, each text cut to 256 bytes;
• requests and refused: the netblock's requests since it was first seen, and how many this ban has refused so far, kept up to date while the ban lasts;
• earlier_bans: how many earlier bans the netblock had, by cause.

clients.json

Per client, one per line: its minute, hour and day counters, and its history since it was first seen:

• the first and last time seen;
• the AS number, AS name and country last looked up, and when;
• total requests, and how many were forwarded and how many refused;
• bytes in each direction;
• responses by status class;
• offences by kind: limit, attack, rule_blocked, waf_blocked and token_refused.

lookups.json

GeoJS answers, one per line:

• client;
• asn, as_name and country;
• answered: when GeoJS answered;
• used: when the answer was last used.

reputation.json

• the last good copy of each list fetched from a URL, with when it was last tried;
• each DNS blocklist verdict still in use;
• AbuseIPDB's scores, and the checks spent today.

alerts.json

• the anomaly counters;
• the alert cooldowns: for each event and netblock, source, file or anomaly scope, when it was last sent and the count of repeats held back since;
• the alerts sent and held back in the current hour;
• the alerts waiting for each destination.

Sizes

• clients.json: about 1 KiB per client, about 20 MiB at the default SWWAF_MAX_TRACKED_CLIENTS. Written every 15 minutes, that is under 2 GiB of disk writes a day.
• bans.json: about 1.2 KiB per ban, at most about 2.5 KiB, so about 6 MiB at the default SWWAF_MAX_BANS. With a full file, a hundred new bans a day come to about 600 MiB of writes.
• lookups.json: about 150 bytes per answer, under 1.5 GiB of writes a day when full.
• reputation.json and alerts.json: usually a few MiB or less.