Last pass: the sixth README review and the fifth SPEC review

The spec names every fault that stops the start, runs step 15 for every
request but the health check, and states each of the fourteen repeated
requirements once. docs/alerts.md says which alerts have an empty client
and netblock and what a summary's detail holds; docs/settings.md lists
the settings that need a lookup and points at step 3 for the two static
lists. The README and the spec now travel in one branch, so the README
never names a spec section that does not exist yet.

Model: fable-5-1

docs/alerts.md

@@ -79,10 +79,11 @@ on one line:
 - `instance`: `SWWAF_INSTANCE_NAME`. `time`: when the alert was raised. `event`:
   one of the events above.
 - `client`: the address whose request raised the alert. Empty for
-  `source_failure` and `file_error`.
-- `netblock`: empty for `source_failure` and `file_error`; otherwise one of:
+  `source_failure`, `file_error` and `summary`.
+- `netblock`: empty for `source_failure`, `file_error` and `summary`; otherwise
+  one of:
     - the ban's netblock;
-    - the netblock an anomaly counted;
+    - the netblock an anomaly counted, empty in the `asn` and `total` scopes;
     - for the other events, the client as rate limiting counts it: an IPv4
       address as a /32, or an IPv6 group.
 - `asn`, `as_name` and `country`: the client's, as known when the alert was
@@ -97,6 +98,8 @@ on one line:
     - for a Core Rule Set match, the `rule_ids`, `score`, `method` and `path`;
     - for a source failure, the `source` and `error`;
     - for a file error, the `file` and `error`;
+    - for a summary, the `hour` it covers, the `count` of alerts held back, and
+      that count by event in `events`;
     - `mode`, when the request was not refused: `detect` or `observe`.
 - `suppressed_repeats`: how many repeats the cooldown held back before this
   alert.

docs/metrics.md

@@ -1,8 +1,8 @@
 # The metrics
 
-The metrics `GET /_smallwebwaf/metrics` answers with, as "Metrics endpoint" in
-[`SPEC.md`](../SPEC.md) describes it. Prometheus keeps the `instance` label as
-`exported_instance` unless the scrape sets `honor_labels: true`.
+What `GET /_smallwebwaf/metrics` answers with. "Metrics endpoint" in
+[`SPEC.md`](../SPEC.md) describes the endpoint. Prometheus keeps the `instance`
+label as `exported_instance` unless the scrape sets `honor_labels: true`.
 
 ## Traffic
 

docs/settings.md

@@ -91,11 +91,11 @@ that take `off`, the `_FILE` form, and what each group does and why.
 ## Static lists
 
 - `SWWAF_ALLOW_NETS` (default empty): netblocks you trust, such as your
-  monitoring. Their clients are refused only for a size or time limit or a
-  missing or wrong token.
+  monitoring (see step 3 in [`SPEC.md`](../SPEC.md)).
 - `SWWAF_RATE_LIMIT_EXEMPT_NETS` (default empty): netblocks whose clients are
   exempt from rate limiting and the byte limits.
-- `SWWAF_DENY_NETS` (default empty): netblocks whose clients are always refused.
+- `SWWAF_DENY_NETS` (default empty): netblocks whose clients are refused (see
+  step 3 in [`SPEC.md`](../SPEC.md)).
 
 ## Request rate limits, per client
 
@@ -136,7 +136,13 @@ that take `off`, the `_FILE` form, and what each group does and why.
 
 ## Lookup of AS number and country
 
-- `SWWAF_LOOKUP_SOURCE` (default `geojs`): `geojs`, `file` or `off`.
+- `SWWAF_LOOKUP_SOURCE` (default `geojs`): `geojs`, `file` or `off`. `off` stops
+  the start while a setting that needs a lookup is set:
+    - the two country lists;
+    - `SWWAF_ADD_LOOKUP_HEADERS`;
+    - the four biased threshold lists and `SWWAF_ASN_LIMIT_PERCENT_URL`;
+    - `SWWAF_UNKNOWN_LIMIT_PERCENT` below `100`;
+    - an anomaly threshold per AS number.
 - `SWWAF_LOOKUP_DB_PATH` (default empty): the IPinfo Lite database file, in its
   `.mmdb` form, for `SWWAF_LOOKUP_SOURCE=file`.
 - `SWWAF_LOOKUP_TIMEOUT` (default `1s`): how long a request waits for its
@@ -286,7 +292,7 @@ as `REQUESTS_PER_MINUTE`:
       client;
     - `SWWAF_ANOMALY_NET_V6_PREFIX` (default `48`, from 0 to 128) for an IPv6
       client.
-- `SWWAF_ANOMALY_ASN_...`: per AS number. Needs a lookup source.
+- `SWWAF_ANOMALY_ASN_...`: per AS number.
 - `SWWAF_ANOMALY_TOTAL_...`: the whole service.
 - `SWWAF_WATCH_...`: each netblock in `SWWAF_WATCH_NETS`, as a whole.
   `SWWAF_WATCH_NETS` (default empty) is a list of name, `=` and netblock, such