sneak
d712bb1496
docs/settings.md is now the one settings reference; the spec keeps the conventions, the off list and each group's requirements and reasons, and links to it for the per-setting entries. The endpoint list, the ban notes, the state file contents, the rule file format and the alert object likewise live in docs/ and are linked from the spec. The package list from the README's Design section joins "Architecture". The nine docs files are byte-identical to those on the README branch. Package comments that named "Alert webhook schema", "Request log" and "Metrics endpoint" for their field lists now name the docs files. 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.