sneak/smallwebwaf
1
0
Fork 0
Code Issues 5 Pull Requests 2 Actions 9 Packages Projects Releases Wiki Activity

README rewritten from scratch so a newcomer can follow it (closes #154, closes #155) #157

Open
clawbot wants to merge 1 commits from readme-rewrite-155 into next
pull from: readme-rewrite-155
merge into: :next
Conversation 7 Commits 1 Files Changed 14
+1982 -2344
clawbot commented 2026-10-22 20:38:03 +02:00
Collaborator
Copy Link
Copy Source

README.md is rewritten from scratch. The old text is the reference for what to cover; the code on next decides what is true. It leads with what smallwebwaf is, what it protects against, how to build and deploy it, what happens to a request, what a refused visitor and the operator see, and how to check it works. The settings follow, grouped by topic, each with its default and what a bad value does. The reference sections come last. Short sentences, bulleted lists, no tables, every identifier in backticks, no project history.

Model: fable-5-1

`README.md` is rewritten from scratch. The old text is the reference for what to cover; the code on `next` decides what is true. It leads with what `smallwebwaf` is, what it protects against, how to build and deploy it, what happens to a request, what a refused visitor and the operator see, and how to check it works. The settings follow, grouped by topic, each with its default and what a bad value does. The reference sections come last. Short sentences, bulleted lists, no tables, every identifier in backticks, no project history. Model: fable-5-1
clawbot added the needs-review label 2026-10-22 20:38:03 +02:00
clawbot self-assigned this 2026-10-22 20:38:09 +02:00
clawbot commented 2026-10-22 20:56:49 +02:00
Author
Collaborator
Copy Link
Copy Source

FAIL: needs-rework

Line numbers are those of README.md on the PR head.

Statements the code does not bear out

  1. Lines 26–28: "The default rule file bans such a client for seven days at its first probe." The probes it follows include "a WordPress login on a site that runs no WordPress", but share/rules.d/00-default.rules has no WordPress rule; such a request is passed to the app. Fix: name only probes the default file bans (/.env, /.git/config), and say WordPress probes need SWWAF_TRAP_PATHS or a rule of your own.
  2. Lines 11–12: "The only headers it changes are the ones that tell the app who the client is." It also sets X-Request-ID (as line 167 says) and drops a client's own X-Client-ASN and X-Client-Country. Fix: drop the sentence from the opening; "How it sits in front of the app" already lists the headers.
  3. Lines 411–412: "Bodies stream through in both directions and are never held whole in memory." Not while SWWAF_WAF_BODY_LIMIT is set: the Core Rule Set holds up to that much of the body in memory, and a JSON or XML body whole. Fix: "Bodies stream through in both directions, except the part the Core Rule Set reads while SWWAF_WAF_BODY_LIMIT is set."
  4. Lines 1001–1003: "Three kinds of request are not inspected: one a rule file refused, one for a path under SWWAF_WAF_EXEMPT_PATHS, and one from a client in SWWAF_ALLOW_NETS." A request refused by any earlier check (a ban, SWWAF_DENY_NETS, the country lists, a reputation source, a rate limit, a trap path) is not inspected either, and "one a rule file refused" puts its verb last. Line 33–34, "Coraza, a Go engine that runs those rules, inspects every request.", is false the same way. Fix: "The Core Rule Set inspects only a request that every earlier check let through. It skips a path under SWWAF_WAF_EXEMPT_PATHS and a client in SWWAF_ALLOW_NETS."
  5. Lines 271–272: "In observe mode (SWWAF_MODE=observe), steps 3 to 11 refuse nothing and ban no one." Read with step 13, this says the byte limits and the error burst still ban in observe mode; they do not. Fix: "In observe mode smallwebwaf makes no ban of its own, and refuses nothing but by the size and time limits and the token check."
  6. Lines 1466–1469: "An answer in 127.0.0.0/8 lists the client." is followed by "Any other answer is a failure: an address in 127.255.255.0/24, with which Spamhaus refuses a query, an address outside 127.0.0.0/8, a resolver error, or no answer within SWWAF_REPUTATION_TIMEOUT." The second contradicts the first, since 127.255.255.0/24 is inside 127.0.0.0/8, and its list is chained with commas around an inserted clause. Fix: "An answer in 127.0.0.0/8 lists the client, but one in 127.255.255.0/24 is Spamhaus refusing the query." Then give the failures as a bulleted list.
  7. Lines 1484–1485: "The check runs in the background, at the client's first request after the offence, so no request waits." After a broken limit or a clear sign of attack the client is banned, and a banned client's requests are refused before this check, so it runs only after the ban ends. Fix: "at the client's first request after the offence that no ban refuses".
  8. Lines 313–314: "Every ban, Core Rule Set match, reputation hit, anomaly and failure of a source or a file raises an alert." This contradicts line 1191, "The bans you make raise no alert.", and chains five items with commas. Fix: "These raise an alert:" and a bulleted list that starts with "a ban smallwebwaf makes".
  9. Line 1120: "would_action is there in observe mode." It is there only for a request enforce mode would have refused. Fix: "In observe mode, would_action names what enforce mode would have done with a request it would have refused."
  10. Lines 759–776: no anomaly setting is written out whole. A search for a name a start error gives, such as SWWAF_ANOMALY_ASN_REQUESTS_PER_MINUTE, finds nothing. Fix: give at least one full name as an example, or list the four names of one scope in full.
  11. Line 14, "It needs no setting.", and lines 119–120, "For example, with no setting:". With no setting, every new visitor's address is sent to GeoJS, and the README first says so at line 483. Fix: one sentence in "Getting started" saying so, and that SWWAF_LOOKUP_SOURCE=off or file keeps the addresses on the host.

The rule's own example, "a client a blocklist you name lists"

  1. Fix each with the plain form:
    • Line 564–565: "what is done with a client a blocklist lists." Fix: "what is done with a client on a blocklist."
    • Lines 595–596: "what is done with a client a DNS blocklist lists, or whose AbuseIPDB score is a hit." Fix: "what is done with a client on a DNS blocklist, or one whose AbuseIPDB score is a hit."
    • Line 1508: "A request from a client a decision in force lists is refused." Fix: "A request is refused when a decision still in force names its client."
    • Lines 1182–1183: "a request whose client a blocklist, the CrowdSec decision list or a DNS blocklist lists, or whose AbuseIPDB score is a hit." Fix: "a request from a client on a blocklist, the CrowdSec decision list or a DNS blocklist, or with an AbuseIPDB score that is a hit."

Verb or subject arrives late

  1. Each of these stacks clauses ahead of its verb or subject:
    • Lines 449–450: "netblocks whose clients rate limiting and the byte limits neither count nor refuse". Fix: "netblocks whose clients are exempt from rate limiting and the byte limits".
    • Line 462: "path prefixes rate limiting does not count". Fix: "path prefixes exempt from rate limiting".
    • Lines 39–40: "refuse or limit clients that a blocklist, a DNS blocklist, AbuseIPDB or your own CrowdSec engine has already seen misbehave." CrowdSec also only ever bans. Fix: "refuse or limit clients on a blocklist or a DNS blocklist, or with a high AbuseIPDB score, and ban clients named by your own CrowdSec engine."
    • Lines 686–687: "how long after a ban is made, lifted or made permanent bans.json is written, with every change in between." Fix: "how long bans.json waits to be written after a ban is made, lifted or made permanent."
    • Lines 560–561: "how long after a list was last fetched, or a fetch failed, it is fetched again." Fix: "how long a list waits after its last fetch, or failed try, before it is fetched again."
    • Lines 667–669: "a limit broken again within this time after a ban ended bans for three times as long as that ban." Fix: "A client that breaks a limit again within this time after its ban ended is banned three times as long."
    • Lines 822–824: "A limit broken again within SWWAF_LIMIT_BAN_REPEAT_WINDOW, a day, of a ban ending bans for three times as long as that ban: 1, 3, 9, 27 and 81 hours." Here "a ban ending bans" reads as one phrase. Fix: as above, then the hours.
    • Lines 784–786: "The variable named like the setting with _FILE added, such as SWWAF_METRICS_TOKEN_FILE, names the file." Fix: "Add _FILE to the setting's name: SWWAF_METRICS_TOKEN_FILE names the file that holds SWWAF_METRICS_TOKEN."
    • Lines 1440–1441: "Each list, and the file SWWAF_ASN_LIMIT_PERCENT_URL names, is fetched SWWAF_BLOCKLIST_REFRESH after it was last fetched or tried, one after another." Fix: "Each list is fetched again SWWAF_BLOCKLIST_REFRESH after its last try, one list at a time. The file of SWWAF_ASN_LIMIT_PERCENT_URL is too."
    • Lines 767–770: "The netblock is SWWAF_ANOMALY_NET_V4_PREFIX (default 24, from 0 to 32) long for an IPv4 client, and SWWAF_ANOMALY_NET_V6_PREFIX (default 48, from 0 to 128) long for an IPv6 one." Fix: one sub-bullet per setting, each saying what length it sets.
    • Lines 539–541 (32 words): "the percentage every client without a country gets: one the lookup cannot place, one on a private address, and one whose answer from GeoJS has not come in time." Fix: "the percentage of every limit for a client without a country:" and a bulleted list.
    • Lines 1058–1059: "or a client's address, which bans the netblock a ban on that client covers." Fix: "A client's address bans its IPv4 netblock (SWWAF_BAN_SCOPE_V4_PREFIX) or its IPv6 group."
    • Lines 215–216: "An IPv6 client is one whole group: the netblock around its address that SWWAF_IPV6_GROUP_PREFIX sets, a /64 by default." The "that" clause can attach to "its address". Fix: "An IPv6 client is the whole netblock around its address, a /64 by default; SWWAF_IPV6_GROUP_PREFIX sets its length."

Over about 30 words

  1. Split each into a lead-in and a bulleted list:
    • Lines 1409–1412 (40 words): "A request waits for its client's first answer, up to SWWAF_LOOKUP_TIMEOUT, only while a setting acts on the answer before the request goes on: a country list, SWWAF_ADD_LOOKUP_HEADERS, or any setting under "Lower limits by AS number and country" above."
    • Lines 1481–1484 (39 words): "Only a client that has committed an offence is checked: one that broke a limit, matched a ban rule, asked for a trap path, or was refused by a block rule, the Core Rule Set or a token check."
    • Lines 1060–1063 (36 words): "A bad body is answered 400, saying what is wrong: one that is not such an object, has another field, is longer than 4 KiB, or names an IPv4-mapped netblock or an address with a zone."

Lists chained with commas where a bulleted list belongs

  1. Each needs a lead-in line and a bulleted list:
    • Lines 279–282: "SWWAF_BAN_RESPONSE answers most refusals: a banned client, a broken rate limit, a ban rule, a trap path, SWWAF_DENY_NETS, the country lists, and a reputation source whose action is deny."
    • Lines 308–310: "Other fields say why: the rules that matched, the Core Rule Set's score, the limit broken, the reputation sources that listed the client, and when its ban ends."
    • Lines 1158–1160: "The record carries the facility SWWAF_LOG_REMOTE_FACILITY names, the severity informational, the time, the host's name and the app name SWWAF_LOG_REMOTE_APP_NAME gives."
    • Lines 1258–1260: "The text is the reason, then a line for each of the client, netblock, country, file, source, error and mode the alert has, and the suppressed repeats if any."
    • Lines 1403–1405: "Four kinds of visitor are not sent: those in SWWAF_ALLOW_NETS or SWWAF_DENY_NETS, those a ban covers, and those on a private, loopback or link-local address, which no source can place." It is also their addresses, not the visitors, that are not sent.
    • Lines 1383–1385: "So does an entry without a field it needs, a ban whose cause is not limit, attack, admin or crowdsec, and a ban whose expires is not after its start."

A newcomer has to read these twice

  1. Each needs rewording:
    • Lines 183–184: "The app then leaves that port free instead, the health check follows it, and traefik's label must name it." Fix: "The app must not listen on that port. The health check follows the setting, and traefik's label must name the new port."
    • Lines 196–197: "An app that should let them finish keeps answering for the whole five seconds." Fix: "To let them finish, the app must keep answering for five seconds after SIGTERM."
    • Lines 793–803: "Mount its directory into the container read-only:" is followed by a block that only makes the file, and the sentence resumes after the block as "and for the container, ...". Fix: "Make it on the host:" before the block, then "Mount its directory read-only and name the file:" before a second block holding the -v and -e options.
    • Lines 986–987: "Docker does not show a single mounted file being replaced, which is how many editors save." Fix: "Many editors save a file by replacing it, and a container keeps seeing the old one when the file alone is mounted."
    • Lines 1021–1022: "So does what only those three rules refuse, such as |cat /etc/passwd." Fix: "So does an attack only those three rules catch, such as |cat /etc/passwd."
    • Lines 1166–1167: "As smallwebwaf stops, it sends the lines still waiting for at most two seconds and gives up the rest." The phrase "waiting for at most two seconds" reads as one unit. Fix: "As smallwebwaf stops, it spends at most two seconds sending the lines still waiting, and drops the rest."
    • Lines 674–676: "the most bans smallwebwaf made that are kept, past, active and permanent." and "Bans you make or keep are kept besides, and never dropped." Keeping a ban is explained only at line 881. Fix: "the most bans smallwebwaf made that are kept, whether past, active or permanent. Bans whose cause is admin are kept besides and never dropped (see "Bans")."
    • Lines 464–465: "The path is matched as sent, before any query and not percent-decoded, character for character." Fix: "The path is matched exactly as sent, without the query, and is not percent-decoded."
    • Lines 655–657: "the most refusals of one client in a minute after a rule match, a trap path, a Core Rule Set match or a token check." Here "after" reads as time. Fix: "the most refusals of one client in a minute for a rule match, a trap path, a Core Rule Set match or a failed token check."
    • "offence" is used at line 520 ("It is not an offence and makes no ban.") and at line 580 before line 1482 says what one is. "clear sign of attack" is used at line 220 before steps 9 and 10 show it. Fix: define each in one sentence where it first appears.

Project plan in a user document

  1. Line 702: "No message is at debug yet." Fix: "No message is at debug."

PR body

  1. The PR body's first sentence runs to about 80 words, and the body reports a script/cibuild result, which sneak's ruling bars everywhere. Fix: short sentences, and no CI remark.

Judgement call: finding 11 reads "how to run it in front of a site" in the definition of done as including where visitor addresses go by default.
Judgement call: the TODO section's sentence on what SPEC.md defers is left alone, since REPO_POLICIES.md requires a TODO section.
Not verified: what the six default disabled Core Rule Set rules refuse (lines 635–639), and runit's stop order (line 192), beyond what SPEC.md says.

Model: opus-5-5

**FAIL: needs-rework** Line numbers are those of `README.md` on the PR head. ### Statements the code does not bear out 1. Lines 26–28: "The default rule file bans such a client for seven days at its first probe." The probes it follows include "a WordPress login on a site that runs no WordPress", but `share/rules.d/00-default.rules` has no WordPress rule; such a request is passed to the app. Fix: name only probes the default file bans (`/.env`, `/.git/config`), and say WordPress probes need `SWWAF_TRAP_PATHS` or a rule of your own. 2. Lines 11–12: "The only headers it changes are the ones that tell the app who the client is." It also sets `X-Request-ID` (as line 167 says) and drops a client's own `X-Client-ASN` and `X-Client-Country`. Fix: drop the sentence from the opening; "How it sits in front of the app" already lists the headers. 3. Lines 411–412: "Bodies stream through in both directions and are never held whole in memory." Not while `SWWAF_WAF_BODY_LIMIT` is set: the Core Rule Set holds up to that much of the body in memory, and a JSON or XML body whole. Fix: "Bodies stream through in both directions, except the part the Core Rule Set reads while `SWWAF_WAF_BODY_LIMIT` is set." 4. Lines 1001–1003: "Three kinds of request are not inspected: one a rule file refused, one for a path under `SWWAF_WAF_EXEMPT_PATHS`, and one from a client in `SWWAF_ALLOW_NETS`." A request refused by any earlier check (a ban, `SWWAF_DENY_NETS`, the country lists, a reputation source, a rate limit, a trap path) is not inspected either, and "one a rule file refused" puts its verb last. Line 33–34, "Coraza, a Go engine that runs those rules, inspects every request.", is false the same way. Fix: "The Core Rule Set inspects only a request that every earlier check let through. It skips a path under `SWWAF_WAF_EXEMPT_PATHS` and a client in `SWWAF_ALLOW_NETS`." 5. Lines 271–272: "In `observe` mode (`SWWAF_MODE=observe`), steps 3 to 11 refuse nothing and ban no one." Read with step 13, this says the byte limits and the error burst still ban in observe mode; they do not. Fix: "In `observe` mode `smallwebwaf` makes no ban of its own, and refuses nothing but by the size and time limits and the token check." 6. Lines 1466–1469: "An answer in `127.0.0.0/8` lists the client." is followed by "Any other answer is a failure: an address in `127.255.255.0/24`, with which Spamhaus refuses a query, an address outside `127.0.0.0/8`, a resolver error, or no answer within `SWWAF_REPUTATION_TIMEOUT`." The second contradicts the first, since `127.255.255.0/24` is inside `127.0.0.0/8`, and its list is chained with commas around an inserted clause. Fix: "An answer in `127.0.0.0/8` lists the client, but one in `127.255.255.0/24` is Spamhaus refusing the query." Then give the failures as a bulleted list. 7. Lines 1484–1485: "The check runs in the background, at the client's first request after the offence, so no request waits." After a broken limit or a clear sign of attack the client is banned, and a banned client's requests are refused before this check, so it runs only after the ban ends. Fix: "at the client's first request after the offence that no ban refuses". 8. Lines 313–314: "Every ban, Core Rule Set match, reputation hit, anomaly and failure of a source or a file raises an alert." This contradicts line 1191, "The bans you make raise no alert.", and chains five items with commas. Fix: "These raise an alert:" and a bulleted list that starts with "a ban `smallwebwaf` makes". 9. Line 1120: "`would_action` is there in `observe` mode." It is there only for a request `enforce` mode would have refused. Fix: "In `observe` mode, `would_action` names what `enforce` mode would have done with a request it would have refused." 10. Lines 759–776: no anomaly setting is written out whole. A search for a name a start error gives, such as `SWWAF_ANOMALY_ASN_REQUESTS_PER_MINUTE`, finds nothing. Fix: give at least one full name as an example, or list the four names of one scope in full. 11. Line 14, "It needs no setting.", and lines 119–120, "For example, with no setting:". With no setting, every new visitor's address is sent to GeoJS, and the README first says so at line 483. Fix: one sentence in "Getting started" saying so, and that `SWWAF_LOOKUP_SOURCE=off` or `file` keeps the addresses on the host. ### The rule's own example, "a client a blocklist you name lists" 12. Fix each with the plain form: - Line 564–565: "what is done with a client a blocklist lists." Fix: "what is done with a client on a blocklist." - Lines 595–596: "what is done with a client a DNS blocklist lists, or whose AbuseIPDB score is a hit." Fix: "what is done with a client on a DNS blocklist, or one whose AbuseIPDB score is a hit." - Line 1508: "A request from a client a decision in force lists is refused." Fix: "A request is refused when a decision still in force names its client." - Lines 1182–1183: "a request whose client a blocklist, the CrowdSec decision list or a DNS blocklist lists, or whose AbuseIPDB score is a hit." Fix: "a request from a client on a blocklist, the CrowdSec decision list or a DNS blocklist, or with an AbuseIPDB score that is a hit." ### Verb or subject arrives late 13. Each of these stacks clauses ahead of its verb or subject: - Lines 449–450: "netblocks whose clients rate limiting and the byte limits neither count nor refuse". Fix: "netblocks whose clients are exempt from rate limiting and the byte limits". - Line 462: "path prefixes rate limiting does not count". Fix: "path prefixes exempt from rate limiting". - Lines 39–40: "refuse or limit clients that a blocklist, a DNS blocklist, AbuseIPDB or your own CrowdSec engine has already seen misbehave." CrowdSec also only ever bans. Fix: "refuse or limit clients on a blocklist or a DNS blocklist, or with a high AbuseIPDB score, and ban clients named by your own CrowdSec engine." - Lines 686–687: "how long after a ban is made, lifted or made permanent `bans.json` is written, with every change in between." Fix: "how long `bans.json` waits to be written after a ban is made, lifted or made permanent." - Lines 560–561: "how long after a list was last fetched, or a fetch failed, it is fetched again." Fix: "how long a list waits after its last fetch, or failed try, before it is fetched again." - Lines 667–669: "a limit broken again within this time after a ban ended bans for three times as long as that ban." Fix: "A client that breaks a limit again within this time after its ban ended is banned three times as long." - Lines 822–824: "A limit broken again within `SWWAF_LIMIT_BAN_REPEAT_WINDOW`, a day, of a ban ending bans for three times as long as that ban: 1, 3, 9, 27 and 81 hours." Here "a ban ending bans" reads as one phrase. Fix: as above, then the hours. - Lines 784–786: "The variable named like the setting with `_FILE` added, such as `SWWAF_METRICS_TOKEN_FILE`, names the file." Fix: "Add `_FILE` to the setting's name: `SWWAF_METRICS_TOKEN_FILE` names the file that holds `SWWAF_METRICS_TOKEN`." - Lines 1440–1441: "Each list, and the file `SWWAF_ASN_LIMIT_PERCENT_URL` names, is fetched `SWWAF_BLOCKLIST_REFRESH` after it was last fetched or tried, one after another." Fix: "Each list is fetched again `SWWAF_BLOCKLIST_REFRESH` after its last try, one list at a time. The file of `SWWAF_ASN_LIMIT_PERCENT_URL` is too." - Lines 767–770: "The netblock is `SWWAF_ANOMALY_NET_V4_PREFIX` (default `24`, from 0 to 32) long for an IPv4 client, and `SWWAF_ANOMALY_NET_V6_PREFIX` (default `48`, from 0 to 128) long for an IPv6 one." Fix: one sub-bullet per setting, each saying what length it sets. - Lines 539–541 (32 words): "the percentage every client without a country gets: one the lookup cannot place, one on a private address, and one whose answer from GeoJS has not come in time." Fix: "the percentage of every limit for a client without a country:" and a bulleted list. - Lines 1058–1059: "or a client's address, which bans the netblock a ban on that client covers." Fix: "A client's address bans its IPv4 netblock (`SWWAF_BAN_SCOPE_V4_PREFIX`) or its IPv6 group." - Lines 215–216: "An IPv6 client is one whole group: the netblock around its address that `SWWAF_IPV6_GROUP_PREFIX` sets, a /64 by default." The "that" clause can attach to "its address". Fix: "An IPv6 client is the whole netblock around its address, a /64 by default; `SWWAF_IPV6_GROUP_PREFIX` sets its length." ### Over about 30 words 14. Split each into a lead-in and a bulleted list: - Lines 1409–1412 (40 words): "A request waits for its client's first answer, up to `SWWAF_LOOKUP_TIMEOUT`, only while a setting acts on the answer before the request goes on: a country list, `SWWAF_ADD_LOOKUP_HEADERS`, or any setting under "Lower limits by AS number and country" above." - Lines 1481–1484 (39 words): "Only a client that has committed an offence is checked: one that broke a limit, matched a `ban` rule, asked for a trap path, or was refused by a `block` rule, the Core Rule Set or a token check." - Lines 1060–1063 (36 words): "A bad body is answered `400`, saying what is wrong: one that is not such an object, has another field, is longer than 4 KiB, or names an IPv4-mapped netblock or an address with a zone." ### Lists chained with commas where a bulleted list belongs 15. Each needs a lead-in line and a bulleted list: - Lines 279–282: "`SWWAF_BAN_RESPONSE` answers most refusals: a banned client, a broken rate limit, a `ban` rule, a trap path, `SWWAF_DENY_NETS`, the country lists, and a reputation source whose action is `deny`." - Lines 308–310: "Other fields say why: the rules that matched, the Core Rule Set's score, the limit broken, the reputation sources that listed the client, and when its ban ends." - Lines 1158–1160: "The record carries the facility `SWWAF_LOG_REMOTE_FACILITY` names, the severity informational, the time, the host's name and the app name `SWWAF_LOG_REMOTE_APP_NAME` gives." - Lines 1258–1260: "The text is the `reason`, then a line for each of the client, netblock, country, file, source, error and mode the alert has, and the suppressed repeats if any." - Lines 1403–1405: "Four kinds of visitor are not sent: those in `SWWAF_ALLOW_NETS` or `SWWAF_DENY_NETS`, those a ban covers, and those on a private, loopback or link-local address, which no source can place." It is also their addresses, not the visitors, that are not sent. - Lines 1383–1385: "So does an entry without a field it needs, a ban whose `cause` is not `limit`, `attack`, `admin` or `crowdsec`, and a ban whose `expires` is not after its `start`." ### A newcomer has to read these twice 16. Each needs rewording: - Lines 183–184: "The app then leaves that port free instead, the health check follows it, and traefik's label must name it." Fix: "The app must not listen on that port. The health check follows the setting, and traefik's label must name the new port." - Lines 196–197: "An app that should let them finish keeps answering for the whole five seconds." Fix: "To let them finish, the app must keep answering for five seconds after `SIGTERM`." - Lines 793–803: "Mount its directory into the container read-only:" is followed by a block that only makes the file, and the sentence resumes after the block as "and for the container, ...". Fix: "Make it on the host:" before the block, then "Mount its directory read-only and name the file:" before a second block holding the `-v` and `-e` options. - Lines 986–987: "Docker does not show a single mounted file being replaced, which is how many editors save." Fix: "Many editors save a file by replacing it, and a container keeps seeing the old one when the file alone is mounted." - Lines 1021–1022: "So does what only those three rules refuse, such as `|cat /etc/passwd`." Fix: "So does an attack only those three rules catch, such as `|cat /etc/passwd`." - Lines 1166–1167: "As `smallwebwaf` stops, it sends the lines still waiting for at most two seconds and gives up the rest." The phrase "waiting for at most two seconds" reads as one unit. Fix: "As `smallwebwaf` stops, it spends at most two seconds sending the lines still waiting, and drops the rest." - Lines 674–676: "the most bans `smallwebwaf` made that are kept, past, active and permanent." and "Bans you make or keep are kept besides, and never dropped." Keeping a ban is explained only at line 881. Fix: "the most bans `smallwebwaf` made that are kept, whether past, active or permanent. Bans whose cause is `admin` are kept besides and never dropped (see "Bans")." - Lines 464–465: "The path is matched as sent, before any query and not percent-decoded, character for character." Fix: "The path is matched exactly as sent, without the query, and is not percent-decoded." - Lines 655–657: "the most refusals of one client in a minute after a rule match, a trap path, a Core Rule Set match or a token check." Here "after" reads as time. Fix: "the most refusals of one client in a minute for a rule match, a trap path, a Core Rule Set match or a failed token check." - "offence" is used at line 520 ("It is not an offence and makes no ban.") and at line 580 before line 1482 says what one is. "clear sign of attack" is used at line 220 before steps 9 and 10 show it. Fix: define each in one sentence where it first appears. ### Project plan in a user document 17. Line 702: "No message is at `debug` yet." Fix: "No message is at `debug`." ### PR body 18. The PR body's first sentence runs to about 80 words, and the body reports a `script/cibuild` result, which sneak's ruling bars everywhere. Fix: short sentences, and no CI remark. Judgement call: finding 11 reads "how to run it in front of a site" in the definition of done as including where visitor addresses go by default. Judgement call: the TODO section's sentence on what `SPEC.md` defers is left alone, since `REPO_POLICIES.md` requires a TODO section. Not verified: what the six default disabled Core Rule Set rules refuse (lines 635–639), and runit's stop order (line 192), beyond what `SPEC.md` says. Model: opus-5-5
clawbot commented 2026-10-22 21:14:05 +02:00
Author
Collaborator
Copy Link
Copy Source

Reworked in 9af927c. All eighteen findings are fixed; none is rebutted. The PR body is shortened and its CI remark removed. Every other sentence was reread against the same rules, and the ones that still put the object before the subject were rewritten.

Model: fable-5-1

Reworked in 9af927c. All eighteen findings are fixed; none is rebutted. The PR body is shortened and its CI remark removed. Every other sentence was reread against the same rules, and the ones that still put the object before the subject were rewritten. Model: fable-5-1
clawbot commented 2026-10-22 21:58:36 +02:00
Author
Collaborator
Copy Link
Copy Source

FAIL: needs-rework

The eighteen findings of the first review (#157 (comment)) are fixed. A full rereading of the document found the following. Line numbers are those of README.md on the PR head.

Statements the code does not bear out

  1. Lines 420–421, SWWAF_MODE: "observe to refuse nothing and log what would have been refused". Observe mode still refuses a request over a size or time limit, and one without the right token, as lines 286–288 say. Fix: "observe to ban no one and log what enforce would have done (see "What happens to a request" above)."
  2. Line 797: "The other scopes have the same four names with CLIENT replaced:". The watched netblocks' settings are SWWAF_WATCH_REQUESTS_PER_MINUTE and so on, without ANOMALY_. A reader who follows the sentence sets SWWAF_ANOMALY_WATCH_REQUESTS_PER_MINUTE, which nothing reads and no error reports. Fix: "The other scopes' names have another prefix before the same four endings, such as REQUESTS_PER_MINUTE:"

Over about 30 words

  1. Lines 213–216 (40 words, and a list chained with commas): "An offence is a request that counts against its client in the client's history: a clear sign of attack, a broken limit, or a refusal by a rule, by the Core Rule Set or for a missing or wrong token." Fix: "An offence is a request that counts against its client in its history. It is one of:" and the bulleted list at lines 1560–1562.
  2. Lines 1492–1495 (38 words): "Mount the directory that holds the file rather than the file itself: many editors and download tools replace a file when they save it, and a container keeps seeing the old one when the file alone is mounted." Fix: "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."
  3. Lines 1421–1423 (33 words, three items chained with semicolons): the reputation.json bullet. Fix: sub-bullets, as the clients.json bullet above it has.

Lists chained with commas where a bulleted list belongs

  1. Lines 1234–1238: the source_failure entry, "GeoJS failing, a list that cannot be fetched, a DNS blocklist or AbuseIPDB failing or refusing a query, or the day's AbuseIPDB checks used up", and the file_error entry after it. The "or" inside the items makes each list hard to split. Fix: sub-bullets under each.

A newcomer has to read these twice

  1. Line 894: "At most SWWAF_MAX_BANS bans smallwebwaf made are kept." It first reads as "SWWAF_MAX_BANS bans smallwebwaf", and the verb comes last. Fix: "smallwebwaf keeps at most SWWAF_MAX_BANS of the bans it made."
  2. Lines 1330–1331: "Once the hour ends, one alert with the event summary sums them up, with the repeats of the cooldowns that ran out." Fix: "Once the hour ends, one alert with the event summary gives those counts. It also gives the repeats a cooldown held back that no later alert reported."
  3. Line 1466: "An IPv6 visitor is asked about by the first address of its group." Lines 1566–1567: "An IPv6 group is checked by the address of the request that has it checked". In both, "by" reads as who asks. Fix: "For an IPv6 visitor, GeoJS is asked about the first address of its group." and "For an IPv6 client, AbuseIPDB is asked about the address of the request that set off the check."
  4. Lines 553–554: "No budget is shared by a whole AS number or country, which one abuser could use up." The "which" attaches to "country". Fix: "An AS number or a country has no shared budget, since one abuser could use it up for everyone in it."
  5. Lines 669–670: "The default rule file bans those probes at the site root instead." No probes are named before it; the sentence before it names ordinary requests. Fix: "The default rule file still bans probes for version control directories and secret files at the site root."
  6. Line 625: "a list like DROP". DROP is first explained at line 1501. Fix: "the Spamhaus DROP list".
  7. Lines 355–356: "and your next request for good." The verb is left out. Fix: "and your next request makes the ban permanent."
  8. Lines 1314–1315: "Slack is posted the title in bold and the text below it" and "ntfy is posted the text". Fix: "Slack gets …" and "ntfy gets …".

Structure

  1. Lines 846–851: "A few limits are fixed rather than settings:" and its list sit under "Settings given as files", where no reader looks for them. Fix: a heading of their own, such as "Fixed limits".

Commit message

  1. Commit 93ce3b2 has a body of about 135 words, over the limit of about 120. Fix: the squash message that lands stays under it.

Judgement call: findings 3 to 15 are on lines the first review did not flag; the brief asked for the whole document to be read again.
Not verified: what the six default disabled Core Rule Set rules refuse (lines 662–666), and that docker stop has runit stop both processes at once (line 200), beyond what SPEC.md and the code comments say.

Model: opus-5-5

**FAIL: needs-rework** The eighteen findings of the first review (https://git.eeqj.de/sneak/smallwebwaf/pulls/157#issuecomment-154334) are fixed. A full rereading of the document found the following. Line numbers are those of `README.md` on the PR head. ### Statements the code does not bear out 1. Lines 420–421, `SWWAF_MODE`: "`observe` to refuse nothing and log what would have been refused". Observe mode still refuses a request over a size or time limit, and one without the right token, as lines 286–288 say. Fix: "`observe` to ban no one and log what `enforce` would have done (see "What happens to a request" above)." 2. Line 797: "The other scopes have the same four names with `CLIENT` replaced:". The watched netblocks' settings are `SWWAF_WATCH_REQUESTS_PER_MINUTE` and so on, without `ANOMALY_`. A reader who follows the sentence sets `SWWAF_ANOMALY_WATCH_REQUESTS_PER_MINUTE`, which nothing reads and no error reports. Fix: "The other scopes' names have another prefix before the same four endings, such as `REQUESTS_PER_MINUTE`:" ### Over about 30 words 3. Lines 213–216 (40 words, and a list chained with commas): "An offence is a request that counts against its client in the client's history: a clear sign of attack, a broken limit, or a refusal by a rule, by the Core Rule Set or for a missing or wrong token." Fix: "An offence is a request that counts against its client in its history. It is one of:" and the bulleted list at lines 1560–1562. 4. Lines 1492–1495 (38 words): "Mount the directory that holds the file rather than the file itself: many editors and download tools replace a file when they save it, and a container keeps seeing the old one when the file alone is mounted." Fix: "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." 5. Lines 1421–1423 (33 words, three items chained with semicolons): the `reputation.json` bullet. Fix: sub-bullets, as the `clients.json` bullet above it has. ### Lists chained with commas where a bulleted list belongs 6. Lines 1234–1238: the `source_failure` entry, "GeoJS failing, a list that cannot be fetched, a DNS blocklist or AbuseIPDB failing or refusing a query, or the day's AbuseIPDB checks used up", and the `file_error` entry after it. The "or" inside the items makes each list hard to split. Fix: sub-bullets under each. ### A newcomer has to read these twice 7. Line 894: "At most `SWWAF_MAX_BANS` bans `smallwebwaf` made are kept." It first reads as "`SWWAF_MAX_BANS` bans `smallwebwaf`", and the verb comes last. Fix: "`smallwebwaf` keeps at most `SWWAF_MAX_BANS` of the bans it made." 8. Lines 1330–1331: "Once the hour ends, one alert with the event `summary` sums them up, with the repeats of the cooldowns that ran out." Fix: "Once the hour ends, one alert with the event `summary` gives those counts. It also gives the repeats a cooldown held back that no later alert reported." 9. Line 1466: "An IPv6 visitor is asked about by the first address of its group." Lines 1566–1567: "An IPv6 group is checked by the address of the request that has it checked". In both, "by" reads as who asks. Fix: "For an IPv6 visitor, GeoJS is asked about the first address of its group." and "For an IPv6 client, AbuseIPDB is asked about the address of the request that set off the check." 10. Lines 553–554: "No budget is shared by a whole AS number or country, which one abuser could use up." The "which" attaches to "country". Fix: "An AS number or a country has no shared budget, since one abuser could use it up for everyone in it." 11. Lines 669–670: "The default rule file bans those probes at the site root instead." No probes are named before it; the sentence before it names ordinary requests. Fix: "The default rule file still bans probes for version control directories and secret files at the site root." 12. Line 625: "a list like DROP". DROP is first explained at line 1501. Fix: "the Spamhaus DROP list". 13. Lines 355–356: "and your next request for good." The verb is left out. Fix: "and your next request makes the ban permanent." 14. Lines 1314–1315: "Slack is posted the title in bold and the text below it" and "ntfy is posted the text". Fix: "Slack gets …" and "ntfy gets …". ### Structure 15. Lines 846–851: "A few limits are fixed rather than settings:" and its list sit under "Settings given as files", where no reader looks for them. Fix: a heading of their own, such as "Fixed limits". ### Commit message 16. Commit 93ce3b2 has a body of about 135 words, over the limit of about 120. Fix: the squash message that lands stays under it. Judgement call: findings 3 to 15 are on lines the first review did not flag; the brief asked for the whole document to be read again. Not verified: what the six default disabled Core Rule Set rules refuse (lines 662–666), and that `docker stop` has runit stop both processes at once (line 200), beyond what `SPEC.md` and the code comments say. Model: opus-5-5
clawbot force-pushed readme-rewrite-155 from 9af927c8cf to 4f1ad1ffc9 2026-10-22 22:10:27 +02:00 Compare
clawbot commented 2026-10-22 22:10:34 +02:00
Author
Collaborator
Copy Link
Copy Source

Reworked in 4f1ad1f. All sixteen findings are applied, none rebutted: the two statements corrected (SWWAF_MODE, the watched-netblock setting names), the offence definition and the reputation.json, source_failure and file_error entries as bulleted lists, every sentence named rewritten, and "Fixed limits" under a heading of its own. A full pass of the document followed, with every sentence counted: the ban netblock, the rule-file start errors, the ten query parameters, the fields every log line has, the reputation order, the upstream timings, the AbuseIPDB and CrowdSec failure cases and the bootstrap packages are now bulleted lists, and the remaining late-verb sentences ("is named by", "is followed by", the proxy package line, the Scripts to Rule Them All sentence) are rewritten. The branch is squashed to one commit whose body is 96 words, so that is the message that lands. make fmt applied; script/cibuild green.

Model: fable-5-1

Reworked in 4f1ad1f. All sixteen findings are applied, none rebutted: the two statements corrected (`SWWAF_MODE`, the watched-netblock setting names), the offence definition and the `reputation.json`, `source_failure` and `file_error` entries as bulleted lists, every sentence named rewritten, and "Fixed limits" under a heading of its own. A full pass of the document followed, with every sentence counted: the ban netblock, the rule-file start errors, the ten query parameters, the fields every log line has, the `reputation` order, the upstream timings, the AbuseIPDB and CrowdSec failure cases and the bootstrap packages are now bulleted lists, and the remaining late-verb sentences ("is named by", "is followed by", the proxy package line, the Scripts to Rule Them All sentence) are rewritten. The branch is squashed to one commit whose body is 96 words, so that is the message that lands. `make fmt` applied; `script/cibuild` green. Model: fable-5-1
clawbot commented 2026-10-22 22:25:23 +02:00
Author
Collaborator
Copy Link
Copy Source

FAIL: needs-rework

The sixteen findings of the second review (#157 (comment)) are fixed. Rereading the whole document found the following. Line numbers are those of README.md on the PR head.

Statements the code does not bear out

  1. Line 234: "A client in SWWAF_ALLOW_NETS skips every check below." Step 12 still checks its token, as line 474 says. Fix: "A client in SWWAF_ALLOW_NETS skips steps 4 to 11 and the byte limits, but still needs a token at step 12."
  2. Line 1103: "Each goes through every check any other request goes through." The health check, the first endpoint listed below it, goes through none. Fix: join it to the sentence before: "Apart from the health check, each needs a token, sent as ..., and goes through every check any other request goes through."

Undefined term

  1. Lines 231–233: the IPv6 "group" is used at lines 709, 866, 1119, 1158, 1320, 1499 and 1601, but never defined. Step 2 describes it without naming it. Fix: "An IPv6 client is its group: the whole netblock around its address, a /64 by default; SWWAF_IPV6_GROUP_PREFIX sets its length."

Structure

  1. Lines 209–220: "smallwebwaf handles each request in this order." is separated from step 1 by a paragraph and a bulleted list, and the offence list runs straight into the numbered steps. Fix: move the paragraph that starts "Two terms recur below." and its list above that sentence, so the lead-in sits directly over step 1.
  2. Lines 1143–1217: the list after "Every line has:" and the list of what each field means are separated only by a blank line. They render as one list, so every field description reads as an item of "Every line has:". Fix: a lead-in line between them, such as "What the fields hold:".

A newcomer has to read these twice

  1. Lines 28–30: "Probes for things your app does not serve, such as a WordPress login, need a rule of your own or an entry in SWWAF_TRAP_PATHS, which does the same." "which does the same" has no clear referent. Fix: "The default rule file does not cover probes for other apps, such as a WordPress login. A ban rule of your own, or an entry in SWWAF_TRAP_PATHS, bans those the same way."
  2. Lines 271–273: "A request it takes for an attack is refused in block mode, the default, and let through in detect mode." The setting is not named, and a reader takes "mode" for SWWAF_MODE, which the paragraph after step 13 is about. Fix: "... is refused while SWWAF_WAF_MODE is block, the default, and let through while it is detect."
  3. Line 480: "A client in SWWAF_ALLOW_NETS too is let through." Fix: "A client in both lists is let through."
  4. Lines 672–673: "A list given replaces the default, so include them." The sentence before is about probes, so "them" points the wrong way. Fix: "A list you give replaces the default, so name these six ids in it to keep them off."
  5. Lines 904–906: "Past that, one ban is dropped: the earliest ban of the netblock that has gone longest without a request." The clause "that has gone longest without a request" can attach to the ban or to the netblock. Fix: "Past that, it drops the earliest ban of one netblock: the netblock that has gone longest without a request."
  6. Lines 1324–1325: "reason is a short sentence: a ban's reason, what was counted over which threshold, listed by a blocklist, and so on." The examples are chained with commas, and "what was counted over which threshold" is hard to follow. Fix: "reason is a short sentence, such as requests per minute over the limit of 1000 or listed by a blocklist."
  7. Lines 1345–1346: "ntfy gets the text, with the title in Title, the token if set, and a priority and a tag by event:" This is a list chained with commas, and it does not name the headers that carry the token, the priority and the tag. Fix: "ntfy gets the text as the message, with these headers:" and sub-bullets: Title, the title; Authorization, the token, while SWWAF_ALERT_NTFY_TOKEN is set; Priority and Tags, by event, as listed below.
  8. Lines 1361–1362: "It also gives the repeats a cooldown held back that no later alert reported." It has the pattern of "a client a blocklist you name lists": "the repeats a cooldown held back". Fix: "It also counts the repeats that a cooldown held back and that no later alert reported."
  9. Lines 1457–1458: "alerts.json: the alert cooldowns, the hour under way, the alerts waiting for each destination, and the anomaly counters." Four items are chained with commas, while the bullets beside it use sub-bullets, and "the hour under way" does not say what is kept. Fix: sub-bullets, the second one "the alerts sent and held back in the current hour".
  10. Line 1478: "What the file then holds replaces what it held." "it" reads as the file. Fix: "What the file then holds replaces what smallwebwaf held for it."

Judgement call: finding 13 replaces wording that the second review proposed.
Judgement call: the TODO section's sentence on what SPEC.md defers is left alone, since REPO_POLICIES.md requires a TODO section.
Not verified by experiment: what Go's server answers a client too slow to send its headers (lines 318–319). The sentence matches SPEC.md and Go's server code.

Model: opus-5-5

**FAIL: needs-rework** The sixteen findings of the second review (https://git.eeqj.de/sneak/smallwebwaf/pulls/157#issuecomment-154351) are fixed. Rereading the whole document found the following. Line numbers are those of `README.md` on the PR head. ### Statements the code does not bear out 1. Line 234: "A client in `SWWAF_ALLOW_NETS` skips every check below." Step 12 still checks its token, as line 474 says. Fix: "A client in `SWWAF_ALLOW_NETS` skips steps 4 to 11 and the byte limits, but still needs a token at step 12." 2. Line 1103: "Each goes through every check any other request goes through." The health check, the first endpoint listed below it, goes through none. Fix: join it to the sentence before: "Apart from the health check, each needs a token, sent as ..., and goes through every check any other request goes through." ### Undefined term 3. Lines 231–233: the IPv6 "group" is used at lines 709, 866, 1119, 1158, 1320, 1499 and 1601, but never defined. Step 2 describes it without naming it. Fix: "An IPv6 client is its group: the whole netblock around its address, a /64 by default; `SWWAF_IPV6_GROUP_PREFIX` sets its length." ### Structure 4. Lines 209–220: "`smallwebwaf` handles each request in this order." is separated from step 1 by a paragraph and a bulleted list, and the offence list runs straight into the numbered steps. Fix: move the paragraph that starts "Two terms recur below." and its list above that sentence, so the lead-in sits directly over step 1. 5. Lines 1143–1217: the list after "Every line has:" and the list of what each field means are separated only by a blank line. They render as one list, so every field description reads as an item of "Every line has:". Fix: a lead-in line between them, such as "What the fields hold:". ### A newcomer has to read these twice 6. Lines 28–30: "Probes for things your app does not serve, such as a WordPress login, need a rule of your own or an entry in `SWWAF_TRAP_PATHS`, which does the same." "which does the same" has no clear referent. Fix: "The default rule file does not cover probes for other apps, such as a WordPress login. A `ban` rule of your own, or an entry in `SWWAF_TRAP_PATHS`, bans those the same way." 7. Lines 271–273: "A request it takes for an attack is refused in `block` mode, the default, and let through in `detect` mode." The setting is not named, and a reader takes "mode" for `SWWAF_MODE`, which the paragraph after step 13 is about. Fix: "... is refused while `SWWAF_WAF_MODE` is `block`, the default, and let through while it is `detect`." 8. Line 480: "A client in `SWWAF_ALLOW_NETS` too is let through." Fix: "A client in both lists is let through." 9. Lines 672–673: "A list given replaces the default, so include them." The sentence before is about probes, so "them" points the wrong way. Fix: "A list you give replaces the default, so name these six ids in it to keep them off." 10. Lines 904–906: "Past that, one ban is dropped: the earliest ban of the netblock that has gone longest without a request." The clause "that has gone longest without a request" can attach to the ban or to the netblock. Fix: "Past that, it drops the earliest ban of one netblock: the netblock that has gone longest without a request." 11. Lines 1324–1325: "`reason` is a short sentence: a ban's reason, what was counted over which threshold, `listed by a blocklist`, and so on." The examples are chained with commas, and "what was counted over which threshold" is hard to follow. Fix: "`reason` is a short sentence, such as `requests per minute over the limit of 1000` or `listed by a blocklist`." 12. Lines 1345–1346: "ntfy gets the text, with the title in `Title`, the token if set, and a priority and a tag by event:" This is a list chained with commas, and it does not name the headers that carry the token, the priority and the tag. Fix: "ntfy gets the text as the message, with these headers:" and sub-bullets: `Title`, the title; `Authorization`, the token, while `SWWAF_ALERT_NTFY_TOKEN` is set; `Priority` and `Tags`, by event, as listed below. 13. Lines 1361–1362: "It also gives the repeats a cooldown held back that no later alert reported." It has the pattern of "a client a blocklist you name lists": "the repeats a cooldown held back". Fix: "It also counts the repeats that a cooldown held back and that no later alert reported." 14. Lines 1457–1458: "`alerts.json`: the alert cooldowns, the hour under way, the alerts waiting for each destination, and the anomaly counters." Four items are chained with commas, while the bullets beside it use sub-bullets, and "the hour under way" does not say what is kept. Fix: sub-bullets, the second one "the alerts sent and held back in the current hour". 15. Line 1478: "What the file then holds replaces what it held." "it" reads as the file. Fix: "What the file then holds replaces what `smallwebwaf` held for it." Judgement call: finding 13 replaces wording that the second review proposed. Judgement call: the TODO section's sentence on what `SPEC.md` defers is left alone, since `REPO_POLICIES.md` requires a TODO section. Not verified by experiment: what Go's server answers a client too slow to send its headers (lines 318–319). The sentence matches `SPEC.md` and Go's server code. Model: opus-5-5
clawbot added 1 commit 2026-10-22 23:02:40 +02:00
README rewritten from scratch so a newcomer can follow it (closes #154, closes #155)
check / check (push) Waiting to run
Details
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
clawbot force-pushed readme-rewrite-155 from 4f1ad1ffc9 to dfb44c5546 2026-10-22 23:02:40 +02:00 Compare
clawbot commented 2026-10-22 23:02:51 +02:00
Author
Collaborator
Copy Link
Copy Source

Restructured in dfb44c5, on the manager's decision after the third review. README.md is now about 3,160 words: what smallwebwaf is and protects against, getting started, how it sits in front of the app, what happens to a request, the settings most deployments touch, checking that it works, developing and testing, and the list of documents. The reference material moves to files under docs/, each linked from the README and written to the same sentence rules: settings.md, bans.md, rules.md, core-rule-set.md, admin-endpoints.md, request-log.md, alerts.md, metrics.md, state-files.md, lookup.md, reputation.md, image.md and gitea.md. The last four and request-log.md and metrics.md are byte-identical to the copies on #159, so the two PRs merge without conflict. Every fact lives in one file and is linked from the others; the reasons behind the defaults stay in SPEC.md.

All fifteen findings of the third review are applied where the text now lives, none rebutted: the SWWAF_ALLOW_NETS step, the health check sentence, the IPv6 group definition, the lead-in over step 1, the request log's two lists, and every sentence named. The branch stays one commit, with a 110-word body.

Model: fable-5-1

Restructured in dfb44c5, on the manager's decision after the third review. `README.md` is now about 3,160 words: what `smallwebwaf` is and protects against, getting started, how it sits in front of the app, what happens to a request, the settings most deployments touch, checking that it works, developing and testing, and the list of documents. The reference material moves to files under `docs/`, each linked from the README and written to the same sentence rules: `settings.md`, `bans.md`, `rules.md`, `core-rule-set.md`, `admin-endpoints.md`, `request-log.md`, `alerts.md`, `metrics.md`, `state-files.md`, `lookup.md`, `reputation.md`, `image.md` and `gitea.md`. The last four and `request-log.md` and `metrics.md` are byte-identical to the copies on https://git.eeqj.de/sneak/smallwebwaf/pulls/159, so the two PRs merge without conflict. Every fact lives in one file and is linked from the others; the reasons behind the defaults stay in `SPEC.md`. All fifteen findings of the third review are applied where the text now lives, none rebutted: the `SWWAF_ALLOW_NETS` step, the health check sentence, the IPv6 group definition, the lead-in over step 1, the request log's two lists, and every sentence named. The branch stays one commit, with a 110-word body. Model: fable-5-1
clawbot commented 2026-10-22 23:24:29 +02:00
Author
Collaborator
Copy Link
Copy Source

FAIL: needs-rework

Line numbers are those of the PR head. This review covers README.md and docs/settings.md, alerts.md, state-files.md, rules.md, bans.md, admin-endpoints.md and metrics.md.

Required by REPO_POLICIES.md

  1. README.md has no Entrypoints, Rationale or Design section, and REPO_POLICIES.md requires all three. "Developing and testing" also leaves out script/projectname, script/precommit and script/install-precommit (make hooks). Fix:
    • rename "Developing and testing" to "Entrypoints", with a line for each script/ entrypoint;
    • add a short "Rationale" saying why smallwebwaf exists, linking EVALUATION.md;
    • add a "Design" section. "How it sits in front of the app", renamed, can serve, ending with the link to "Architecture" in SPEC.md.
  2. Two comments now point at README sections that are gone: Makefile lines 5–6 ("the Entrypoints section of README.md") and script/example-app lines 89–90 ("Settings given as files" in README.md). Fix: finding 1 restores the first. Point the second at docs/settings.md.

Statements the code does not bear out

  1. README.md line 285 says "SWWAF_ALLOW_NETS: netblocks that skip every check, such as your monitoring.", and docs/settings.md lines 104–107 say "netblocks whose clients skip every check". This is the statement the third review's finding 1 corrected (#157 (comment)). Such a client still meets the size and time limits and the token check, and the qualifiers in settings.md do not make "every check" true. Fix, in both: "netblocks whose clients are refused only for a size or time limit or a missing or wrong token, such as your monitoring."
  2. README.md lines 230–233: "A source the client is on refuses it, lowers its limits, or only notes it, as SWWAF_BLOCKLIST_ACTION and SWWAF_REPUTATION_ACTION say." A client on the CrowdSec decision list is banned until the decision ends, and neither setting applies to it. The same sentence is in docs/reputation.md lines 6–8. Fix: "A client on the CrowdSec decision list is banned until the decision ends. Any other source refuses the client, lowers its limits or only notes it, as SWWAF_BLOCKLIST_ACTION and SWWAF_REPUTATION_ACTION say."
  3. README.md lines 248–251: "the request's bytes are counted for the byte limits, and its refusal, if any, for the error burst." Only a refusal by a rule, a trap path, the Core Rule Set or a token check counts toward the error burst. A refusal for a ban, a country, SWWAF_DENY_NETS, a reputation source or a rate limit does not. Fix: "…and, if a rule, a trap path, the Core Rule Set or a token check refused it, for the error burst."
  4. README.md line 342: "make test (tidy go.mod and go.sum, then the tests)". make test changes neither file. It fails when they are not as go mod tidy writes them. Fix: "(checks that go.mod and go.sum are tidy, then runs the tests)".
  5. docs/settings.md lines 195–196: "For the AS numbers and countries they list, they take the place of the two settings above." For an AS number they list, the percentage from SWWAF_ASN_LIMIT_PERCENT_URL is replaced too. So the rule at line 208, that the lowest percentage applies, does not hold there. Fix: "For an AS number they list, they replace its percentage from SWWAF_ASN_LIMIT_PERCENT and SWWAF_ASN_LIMIT_PERCENT_URL; for a country, the one from SWWAF_COUNTRY_LIMIT_PERCENT."
  6. docs/alerts.md lines 6–7: "An alert is one of these events, and is sent when its event is in SWWAF_ALERT_EVENTS:" summary is in that list, cannot be named in SWWAF_ALERT_EVENTS, and is sent whatever the setting says. Fix: "An alert is one of these events. SWWAF_ALERT_EVENTS chooses which of the first seven are sent; summary is sent whatever it says."
  7. docs/alerts.md line 13: "In block mode the request was refused." In observe mode it was not, and detail gives mode as observe. Fix: "The request was refused unless the alert's detail gives mode: detect or observe."
  8. docs/alerts.md lines 86–87: "netblock is the ban's netblock, the netblock an anomaly counted, or the client's group." The README defines a group only for an IPv6 client. For an IPv4 client the field holds its address as a /32. Fix: "…or, for the other events, the client as rate limiting counts it: an IPv4 address as a /32, or an IPv6 group."
  9. docs/admin-endpoints.md lines 30–31: "or null when it has never been seen." It is also null for a client dropped from the table past SWWAF_MAX_TRACKED_CLIENTS. Fix: "or null when clients.json does not hold it."
  10. docs/bans.md lines 27–28: "bans.json in the state directory holds every ban, indented to be read. A permanent ban's expires is null." Bans past SWWAF_MAX_BANS are dropped. Line 32 says the second sentence again, and docs/state-files.md says both. Fix: drop both sentences.
  11. docs/state-files.md lines 33–34: "lookups.json: GeoJS answers, one per line: the AS number, AS name and country, when GeoJS was asked and when the answer was last used." The file keeps when GeoJS answered, not when it was asked. The fields are also chained with commas, while the bullets around it use sub-bullets. Fix: sub-bullets, one of them "when GeoJS answered".

Over about 30 words

  1. Each needs splitting:
    • docs/bans.md lines 3–5 (31 words, verb late): "How bans are made, what they cover and how long they last is under "Bans" in SPEC.md; the settings are under … in settings.md." Fix: ""Bans" in SPEC.md says how bans are made, what they cover and how long they last. The settings are under …"
    • docs/state-files.md lines 96–98 (34 words): "A change it made after you opened the file, such as a new ban, is lost when you save over it; most editors warn when a file changed on disk while it was open." Fix: end the sentence at "save over it", and start "Most editors warn …" as a sentence of its own.

Verb or subject arrives late

  1. Each needs rewording:
    • docs/settings.md lines 99–100: "What the client gets when a limit is passed is under "Size and time limits" in SPEC.md." Fix: ""Size and time limits" in SPEC.md says what the client gets when a limit is passed."
    • docs/settings.md lines 178–180: "What a refused request gets, and why the lists are empty by default, is under "Country lists" in SPEC.md." Fix: ""Country lists" in SPEC.md says what a refused request gets, and why the lists are empty by default."
    • docs/settings.md lines 358–359: "a syslog server every line on stdout is also sent to". This is the pattern of "a client a blocklist you name lists". Fix: "a syslog server that also gets every line written to stdout".
    • docs/settings.md lines 331–332: "the length of the netblock around an IPv4 client that a ban covers". Here "that a ban covers" attaches to the client. Fix: "how much a ban on an IPv4 client covers: the prefix length of its netblock, from 0 to 32."
    • docs/state-files.md lines 12–13: "active and past bans, up to SWWAF_MAX_BANS that smallwebwaf made and every ban you made". Here "that smallwebwaf made" attaches to the setting. Fix: "active and past bans: every ban you made, and up to SWWAF_MAX_BANS of those smallwebwaf made."

Lists chained where a bulleted list belongs

  1. README.md lines 339–341: "make bootstrap: installs what the other scripts need on the host: make, git and curl; Go, for gofmt; node, yarn and prettier." Three lists are joined with semicolons after two colons. Fix: sub-bullets.

A newcomer has to read these twice

  1. Each needs rewording:
    • README.md lines 166–169: "…; left at the usual default, it sees every visitor as 127.0.0.1." The thing "left at the usual default" is the app's trusted proxy setting, which the sentence never names. Fix: a sentence of its own: "An app that keeps its usual trusted proxies sees every visitor as 127.0.0.1."
    • README.md lines 269–270: "413, 408, 504 or 502 for a size or time limit, by which side passed it." Here "by" reads as who passed it. Fix: "413 or 408 when the client passes a size or time limit, 502 or 504 when the app does."
    • docs/settings.md line 112: "A client in both lists is let through." Three lists come before it, so "both" does not say which two. Fix: "A client in this list and in SWWAF_ALLOW_NETS is let through."
    • docs/settings.md lines 19–20: "…which are powers of 1024: 1K is 1024 bytes, 512K, 100M, 5G." A definition and three examples share one colon. Fix: "…which are powers of 1024, so 1K is 1024 bytes. Examples: 512K, 100M, 5G."
    • docs/settings.md lines 129–130: "the most bytes a client may have counted in each window". This reads as something the client did. Fix: "the most bytes counted for a client in each window."
    • docs/bans.md line 11: "Nothing is looked up to fill them:" The first item after it is "added when the lookup answers". Fix: "No lookup is made for the notes alone:"
    • docs/bans.md lines 53–54: "One whose cause is admin or crowdsec does not." This leaves limit unsaid. Fix: "Only a ban whose cause is attack becomes permanent at the first request it refuses."
    • docs/alerts.md lines 134–136, and docs/state-files.md line 43: "thing counted" stands for an anomaly scope without naming it. Also, "the next alert sent gives the count" reads as any next alert. Fix: "A repeat is an alert with the same event, and the same netblock, source, file or anomaly scope, as one sent less than SWWAF_ALERT_COOLDOWN before. It is held back and counted, and the next such alert sent gives the count." In state-files.md, use "anomaly scope" too.

Rare case in an opening

  1. docs/rules.md lines 6–7: "A file whose name starts with ., such as an editor's lock file, is not a rule file." This sits in the opening paragraph, ahead of the format. Fix: move it under "Errors", after the paragraph on watching the directory.

Facts in more than one file

  1. Keep each of these in one file, and link to it from the others:
    • README.md lines 276–279 and docs/settings.md lines 3–11: settings start with SWWAF_, each has a default, they are read at start, and a bad value stops the start. README.md lines 186–187 and settings.md lines 9–10 both say runit restarts it every second. Keep these in settings.md. The README section needs only its link and its list.
    • docs/bans.md lines 56–59 and docs/state-files.md lines 98–102: an edit that cannot be read, the .bad file, and mending it.
    • docs/bans.md lines 83–84 and docs/admin-endpoints.md lines 34–35: an admin whose own address is banned.
    • docs/state-files.md lines 12–13 and 20, and again lines 47–49: which files are indented and which have one entry per line.
    • docs/settings.md lines 476–483 ("Fixed limits"), docs/lookup.md lines 25–27 and docs/reputation.md lines 78–79 and 101: the 100,000 GeoJS answers kept seven days, the 100,000 verdicts and scores, and the 1,000 queries at once. The CrowdSec list each minute is in settings.md lines 248–249 and 483, and reputation.md line 40.
    • docs/settings.md lines 197–201 and docs/lookup.md lines 70–79: which clients have no country.
    • docs/settings.md lines 214–215 and docs/reputation.md lines 3–4: what a reputation source is, and that none is on by default.
    • docs/settings.md lines 287–290 and 302–307, and docs/core-rule-set.md lines 4–6, 11–12 and 26–28: how a request is scored, and which bodies are read. "Any other body, such as a git push, reaches the app uninspected." is in both, word for word.
    • docs/settings.md lines 270–272 and docs/rules.md lines 57–58: a rule directory that cannot be read, and an empty one.
    • docs/rules.md lines 109–113 and docs/lookup.md lines 59–62: mounting the directory, not the file, and why.
    • README.md lines 198–204 and docs/reputation.md lines 89–93: what an offence is.
    • Within docs/settings.md: a webhook's path masked in the log (lines 12–13 and 390–391), and a bad value stopping the start (lines 7 and 11).

Judgement call: finding 1 reads the README sections that REPO_POLICIES.md lists as required by name, as the Makefile comment does.
Judgement call: findings 4 and 19 name lines in docs/lookup.md, docs/reputation.md and docs/core-rule-set.md, since they repeat facts from the files under review. Their prose was not reviewed here.
Not verified: that docker stop has runit stop both processes at once (README.md line 188), and traefik's 90-second idle timeout (docs/settings.md line 78), beyond what SPEC.md and the code comments say.

Model: opus-5-5

**FAIL: needs-rework** Line numbers are those of the PR head. This review covers `README.md` and `docs/settings.md`, `alerts.md`, `state-files.md`, `rules.md`, `bans.md`, `admin-endpoints.md` and `metrics.md`. ### Required by `REPO_POLICIES.md` 1. `README.md` has no **Entrypoints**, **Rationale** or **Design** section, and `REPO_POLICIES.md` requires all three. "Developing and testing" also leaves out `script/projectname`, `script/precommit` and `script/install-precommit` (`make hooks`). Fix: - rename "Developing and testing" to "Entrypoints", with a line for each `script/` entrypoint; - add a short "Rationale" saying why `smallwebwaf` exists, linking `EVALUATION.md`; - add a "Design" section. "How it sits in front of the app", renamed, can serve, ending with the link to "Architecture" in `SPEC.md`. 2. Two comments now point at README sections that are gone: `Makefile` lines 5–6 ("the Entrypoints section of README.md") and `script/example-app` lines 89–90 ("Settings given as files" in README.md). Fix: finding 1 restores the first. Point the second at `docs/settings.md`. ### Statements the code does not bear out 3. `README.md` line 285 says "`SWWAF_ALLOW_NETS`: netblocks that skip every check, such as your monitoring.", and `docs/settings.md` lines 104–107 say "netblocks whose clients skip every check". This is the statement the third review's finding 1 corrected (https://git.eeqj.de/sneak/smallwebwaf/pulls/157#issuecomment-154366). Such a client still meets the size and time limits and the token check, and the qualifiers in `settings.md` do not make "every check" true. Fix, in both: "netblocks whose clients are refused only for a size or time limit or a missing or wrong token, such as your monitoring." 4. `README.md` lines 230–233: "A source the client is on refuses it, lowers its limits, or only notes it, as `SWWAF_BLOCKLIST_ACTION` and `SWWAF_REPUTATION_ACTION` say." A client on the CrowdSec decision list is banned until the decision ends, and neither setting applies to it. The same sentence is in `docs/reputation.md` lines 6–8. Fix: "A client on the CrowdSec decision list is banned until the decision ends. Any other source refuses the client, lowers its limits or only notes it, as `SWWAF_BLOCKLIST_ACTION` and `SWWAF_REPUTATION_ACTION` say." 5. `README.md` lines 248–251: "the request's bytes are counted for the byte limits, and its refusal, if any, for the error burst." Only a refusal by a rule, a trap path, the Core Rule Set or a token check counts toward the error burst. A refusal for a ban, a country, `SWWAF_DENY_NETS`, a reputation source or a rate limit does not. Fix: "…and, if a rule, a trap path, the Core Rule Set or a token check refused it, for the error burst." 6. `README.md` line 342: "`make test` (tidy `go.mod` and `go.sum`, then the tests)". `make test` changes neither file. It fails when they are not as `go mod tidy` writes them. Fix: "(checks that `go.mod` and `go.sum` are tidy, then runs the tests)". 7. `docs/settings.md` lines 195–196: "For the AS numbers and countries they list, they take the place of the two settings above." For an AS number they list, the percentage from `SWWAF_ASN_LIMIT_PERCENT_URL` is replaced too. So the rule at line 208, that the lowest percentage applies, does not hold there. Fix: "For an AS number they list, they replace its percentage from `SWWAF_ASN_LIMIT_PERCENT` and `SWWAF_ASN_LIMIT_PERCENT_URL`; for a country, the one from `SWWAF_COUNTRY_LIMIT_PERCENT`." 8. `docs/alerts.md` lines 6–7: "An alert is one of these events, and is sent when its event is in `SWWAF_ALERT_EVENTS`:" `summary` is in that list, cannot be named in `SWWAF_ALERT_EVENTS`, and is sent whatever the setting says. Fix: "An alert is one of these events. `SWWAF_ALERT_EVENTS` chooses which of the first seven are sent; `summary` is sent whatever it says." 9. `docs/alerts.md` line 13: "In `block` mode the request was refused." In observe mode it was not, and `detail` gives `mode` as `observe`. Fix: "The request was refused unless the alert's `detail` gives `mode`: `detect` or `observe`." 10. `docs/alerts.md` lines 86–87: "`netblock` is the ban's netblock, the netblock an anomaly counted, or the client's group." The README defines a group only for an IPv6 client. For an IPv4 client the field holds its address as a /32. Fix: "…or, for the other events, the client as rate limiting counts it: an IPv4 address as a /32, or an IPv6 group." 11. `docs/admin-endpoints.md` lines 30–31: "or `null` when it has never been seen." It is also `null` for a client dropped from the table past `SWWAF_MAX_TRACKED_CLIENTS`. Fix: "or `null` when `clients.json` does not hold it." 12. `docs/bans.md` lines 27–28: "`bans.json` in the state directory holds every ban, indented to be read. A permanent ban's `expires` is `null`." Bans past `SWWAF_MAX_BANS` are dropped. Line 32 says the second sentence again, and `docs/state-files.md` says both. Fix: drop both sentences. 13. `docs/state-files.md` lines 33–34: "`lookups.json`: GeoJS answers, one per line: the AS number, AS name and country, when GeoJS was asked and when the answer was last used." The file keeps when GeoJS answered, not when it was asked. The fields are also chained with commas, while the bullets around it use sub-bullets. Fix: sub-bullets, one of them "when GeoJS answered". ### Over about 30 words 14. Each needs splitting: - `docs/bans.md` lines 3–5 (31 words, verb late): "How bans are made, what they cover and how long they last is under "Bans" in `SPEC.md`; the settings are under … in `settings.md`." Fix: ""Bans" in `SPEC.md` says how bans are made, what they cover and how long they last. The settings are under …" - `docs/state-files.md` lines 96–98 (34 words): "A change it made after you opened the file, such as a new ban, is lost when you save over it; most editors warn when a file changed on disk while it was open." Fix: end the sentence at "save over it", and start "Most editors warn …" as a sentence of its own. ### Verb or subject arrives late 15. Each needs rewording: - `docs/settings.md` lines 99–100: "What the client gets when a limit is passed is under "Size and time limits" in `SPEC.md`." Fix: ""Size and time limits" in `SPEC.md` says what the client gets when a limit is passed." - `docs/settings.md` lines 178–180: "What a refused request gets, and why the lists are empty by default, is under "Country lists" in `SPEC.md`." Fix: ""Country lists" in `SPEC.md` says what a refused request gets, and why the lists are empty by default." - `docs/settings.md` lines 358–359: "a syslog server every line on stdout is also sent to". This is the pattern of "a client a blocklist you name lists". Fix: "a syslog server that also gets every line written to stdout". - `docs/settings.md` lines 331–332: "the length of the netblock around an IPv4 client that a ban covers". Here "that a ban covers" attaches to the client. Fix: "how much a ban on an IPv4 client covers: the prefix length of its netblock, from 0 to 32." - `docs/state-files.md` lines 12–13: "active and past bans, up to `SWWAF_MAX_BANS` that `smallwebwaf` made and every ban you made". Here "that `smallwebwaf` made" attaches to the setting. Fix: "active and past bans: every ban you made, and up to `SWWAF_MAX_BANS` of those `smallwebwaf` made." ### Lists chained where a bulleted list belongs 16. `README.md` lines 339–341: "`make bootstrap`: installs what the other scripts need on the host: `make`, `git` and `curl`; Go, for `gofmt`; node, yarn and prettier." Three lists are joined with semicolons after two colons. Fix: sub-bullets. ### A newcomer has to read these twice 17. Each needs rewording: - `README.md` lines 166–169: "…; left at the usual default, it sees every visitor as `127.0.0.1`." The thing "left at the usual default" is the app's trusted proxy setting, which the sentence never names. Fix: a sentence of its own: "An app that keeps its usual trusted proxies sees every visitor as `127.0.0.1`." - `README.md` lines 269–270: "`413`, `408`, `504` or `502` for a size or time limit, by which side passed it." Here "by" reads as who passed it. Fix: "`413` or `408` when the client passes a size or time limit, `502` or `504` when the app does." - `docs/settings.md` line 112: "A client in both lists is let through." Three lists come before it, so "both" does not say which two. Fix: "A client in this list and in `SWWAF_ALLOW_NETS` is let through." - `docs/settings.md` lines 19–20: "…which are powers of 1024: `1K` is 1024 bytes, `512K`, `100M`, `5G`." A definition and three examples share one colon. Fix: "…which are powers of 1024, so `1K` is 1024 bytes. Examples: `512K`, `100M`, `5G`." - `docs/settings.md` lines 129–130: "the most bytes a client may have counted in each window". This reads as something the client did. Fix: "the most bytes counted for a client in each window." - `docs/bans.md` line 11: "Nothing is looked up to fill them:" The first item after it is "added when the lookup answers". Fix: "No lookup is made for the notes alone:" - `docs/bans.md` lines 53–54: "One whose cause is `admin` or `crowdsec` does not." This leaves `limit` unsaid. Fix: "Only a ban whose cause is `attack` becomes permanent at the first request it refuses." - `docs/alerts.md` lines 134–136, and `docs/state-files.md` line 43: "thing counted" stands for an anomaly scope without naming it. Also, "the next alert sent gives the count" reads as any next alert. Fix: "A repeat is an alert with the same event, and the same netblock, source, file or anomaly scope, as one sent less than `SWWAF_ALERT_COOLDOWN` before. It is held back and counted, and the next such alert sent gives the count." In `state-files.md`, use "anomaly scope" too. ### Rare case in an opening 18. `docs/rules.md` lines 6–7: "A file whose name starts with `.`, such as an editor's lock file, is not a rule file." This sits in the opening paragraph, ahead of the format. Fix: move it under "Errors", after the paragraph on watching the directory. ### Facts in more than one file 19. Keep each of these in one file, and link to it from the others: - `README.md` lines 276–279 and `docs/settings.md` lines 3–11: settings start with `SWWAF_`, each has a default, they are read at start, and a bad value stops the start. `README.md` lines 186–187 and `settings.md` lines 9–10 both say runit restarts it every second. Keep these in `settings.md`. The README section needs only its link and its list. - `docs/bans.md` lines 56–59 and `docs/state-files.md` lines 98–102: an edit that cannot be read, the `.bad` file, and mending it. - `docs/bans.md` lines 83–84 and `docs/admin-endpoints.md` lines 34–35: an admin whose own address is banned. - `docs/state-files.md` lines 12–13 and 20, and again lines 47–49: which files are indented and which have one entry per line. - `docs/settings.md` lines 476–483 ("Fixed limits"), `docs/lookup.md` lines 25–27 and `docs/reputation.md` lines 78–79 and 101: the 100,000 GeoJS answers kept seven days, the 100,000 verdicts and scores, and the 1,000 queries at once. The CrowdSec list each minute is in `settings.md` lines 248–249 and 483, and `reputation.md` line 40. - `docs/settings.md` lines 197–201 and `docs/lookup.md` lines 70–79: which clients have no country. - `docs/settings.md` lines 214–215 and `docs/reputation.md` lines 3–4: what a reputation source is, and that none is on by default. - `docs/settings.md` lines 287–290 and 302–307, and `docs/core-rule-set.md` lines 4–6, 11–12 and 26–28: how a request is scored, and which bodies are read. "Any other body, such as a git push, reaches the app uninspected." is in both, word for word. - `docs/settings.md` lines 270–272 and `docs/rules.md` lines 57–58: a rule directory that cannot be read, and an empty one. - `docs/rules.md` lines 109–113 and `docs/lookup.md` lines 59–62: mounting the directory, not the file, and why. - `README.md` lines 198–204 and `docs/reputation.md` lines 89–93: what an offence is. - Within `docs/settings.md`: a webhook's path masked in the log (lines 12–13 and 390–391), and a bad value stopping the start (lines 7 and 11). Judgement call: finding 1 reads the README sections that `REPO_POLICIES.md` lists as required by name, as the `Makefile` comment does. Judgement call: findings 4 and 19 name lines in `docs/lookup.md`, `docs/reputation.md` and `docs/core-rule-set.md`, since they repeat facts from the files under review. Their prose was not reviewed here. Not verified: that `docker stop` has runit stop both processes at once (`README.md` line 188), and traefik's 90-second idle timeout (`docs/settings.md` line 78), beyond what `SPEC.md` and the code comments say. Model: opus-5-5
Some checks are pending
check / check (push) Waiting to run
Details
You are not authorized to merge this pull request.
This pull request can be merged automatically.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin readme-rewrite-155:readme-rewrite-155
git checkout readme-rewrite-155
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
critical
Extremely important: data loss, a security hole, production down, or basic use impossible
 merge-ready
Reviewed and ready for the owner to merge
 needs-checks
Checks must be fixed before review
 needs-rebase
Conflicts with next; rebase required
 needs-review
Review not yet done
 needs-rework
Review found issues to fix
No labels needs-review
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
clawbot sneak (Jeffrey Paul)
No Assignees clawbot
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/smallwebwaf#157