sneak
dfb44c5546
The old README opened with project history and one list of a hundred settings. The new one leads with what smallwebwaf is, what it protects against, how to build and deploy it, how it sits in front of the app, what happens to a request, the settings most deployments touch, how to check it works and how to develop it. The reference material, every setting, bans, rule files, the Core Rule Set, the admin endpoints, the request log, alerts, metrics, state files, lookups, reputation sources, the image and gitea, moves to files under docs/, each linked from the README. Every statement was checked against the code on next. Model: fable-5-1
3.7 KiB
GeoJS and the lookup database
smallwebwaf looks up each client's AS number and country, through GeoJS by
default or in a database file on your own host. The settings are under "Looking
up the AS number and country" in settings.md; the reasons for
the defaults are under "Lookup of AS number and country" in
SPEC.md.
GeoJS
By default smallwebwaf asks GeoJS, a free web service that needs no account,
about every new visitor's address. It asks whether or not a setting uses the
answer, since the log line, the history, the ban notes and the metrics carry the
AS number and country. These addresses are never sent:
- one in
SWWAF_ALLOW_NETSorSWWAF_DENY_NETS; - one under a ban;
- a private, loopback or link-local address, which no source can place.
For an IPv6 visitor, GeoJS is asked about the first address of its group.
Addresses are asked about together, up to 200 in one request
(https://get.geojs.io/v1/ip/geo.json?ip=a,b,c), one request at a time. Each
answer's country_code, asn and organization_name are read. An answer
without a country_code, or with the asn 64512, counts as unknown. Each
answer is kept for seven days, in memory and in lookups.json, separately from
the table of clients. Up to 100,000 answers are kept; past that, the answer used
longest ago goes first.
A request waits for its client's first answer only when a setting needs the
answer before the request goes on. It waits up to SWWAF_LOOKUP_TIMEOUT. The
settings that make it wait:
- a country list;
SWWAF_ADD_LOOKUP_HEADERS;- any setting under "Lower limits by AS number and country" in
settings.md.
Otherwise the request goes on at once, logged without the answer. The answer
reaches the client's history and ban notes when it comes. A client whose answer
has not come in time counts as from an unknown country until it comes, and its
later requests do not wait. While GeoJS fails, new visitors count as from an
unknown country, which SWWAF_EXCLUSIVELY_ALLOWED_COUNTRIES refuses. GeoJS is
then left alone for a second, and twice as long after each further failure, up
to five minutes, and one source_failure alert is sent per cooldown.
The database file
To keep your visitors' addresses on your own host, set
SWWAF_LOOKUP_SOURCE=off, or set it to file. file looks every client up in
the free IPinfo Lite database (ipinfo_lite.mmdb) at SWWAF_LOOKUP_DB_PATH,
reading its asn, as_name and country_code fields. You download the
database with an IPinfo account and mount it into the container; smallwebwaf
never fetches it and holds no account or token for it. It answers at once, with
nothing sent off the host. A client whose address it does not hold counts as
from an unknown country.
smallwebwaf reads the whole file at start. It reads the file again once it has
gone 2 seconds without a change after you replace it. A replacement it cannot
read is logged and alerted, and the file read before stays in use. Mount the
directory that holds the file, not the file itself. Many editors and download
tools save a file by replacing it, and a container keeps seeing the old file
when only the file is mounted.
IPinfo updates the database daily, and releases it under the Creative Commons Attribution-ShareAlike 4.0 licence. It asks for a link to IPinfo on the site that uses it, such as "IP address data is powered by IPinfo".
A client without a country
A client the lookup cannot place has an unknown country and AS number. That is one of:
- a client on a private address;
- one GeoJS or the database does not know;
- one whose GeoJS answer has not come in time.
SWWAF_EXCLUSIVELY_ALLOWED_COUNTRIES refuses such a client, and the lower
limits give it SWWAF_UNKNOWN_LIMIT_PERCENT. Nothing else treats it
differently.