From 00c68e841c416c7c069869a52d64e8c15a72e1de Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Tue, 8 Sep 2026 16:28:48 +0200 Subject: docs: record the real-mail sweep and open a backlog A synthetic fixture only ever holds the shapes someone thought of, and the shapes nobody thought of are the ones that leak. Sweeping the user's own tag:spam is the only source of those, and it earned its place: the first message found a header the parser did not read, and the corpus exercised a spoofed Reply-To display name no fixture had. AGENTS.md records it under Testing, beside the fixture rule it is the deliberate exception to: ask first, work from the scratchpad, compare every address in the raw source against the whole ioc output, and let only counts and stripped domains out. A finding becomes a synthetic fixture; the real message never enters the repository. BACKLOG.md opens with the one thing the sweep found that was not worth fixing blind: boilerplate namespace urls (w3.org doctypes) reported as indicators. Noise rather than a defect, and the argument for leaving it alone is real, so it is written down with both sides rather than built. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_019NHaqA1Rz5ybed7wFUeQbK --- AGENTS.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) (limited to 'AGENTS.md') diff --git a/AGENTS.md b/AGENTS.md index a5f195c..9aa6b08 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -230,6 +230,41 @@ weekday with `date -d +%A` rather than writing it from memory: an RFC2822 parser validates the day against the date and a wrong one reads as a malformed header. +**Sweep the user's real spam as a HAND TEST, and never as a fixture.** A +synthetic fixture only ever contains the shapes someone thought of, and the +shapes nobody thought of are the ones that leak. Real mail is the only source +of those, so the leak property is checked against `tag:spam` in the user's own +notmuch index. It is worth doing: the first message swept found a header the +parser did not read at all, and the corpus exercised a spoofed `Reply-To` +display name that no fixture had. + +Ask before reading the user's mail. Then, from a script in the scratchpad and +never in the repo: + +```python +raw = subprocess.run(["notmuch", "show", "--format=raw", mid], + capture_output=True, check=True).stdout +iocs = parse.iocs(raw, trusted=[...]) +blob = repr(iocs) +for addr in set(re.findall(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+", + raw.decode("utf-8", "replace"))): + assert addr not in blob, (mid, addr) +``` + +The assertion is the whole point and it must be that broad: compare EVERY +address in the raw source, headers and body, against the entire IOC output. +Checking only the recipient misses an address the parser invented from a +display name, which is exactly how the `_domain_of` defect reached a report. +Also count crashes and empty results; a message that parses to nothing is a +finding too. + +What may leave that script: counts, header names, origin tallies, and a +domain with its local part removed. What may not: an address, a subject, a +Message-ID, a URL from a real message, or a real domain written into a test. +When a sweep finds a defect, reproduce it as a synthetic fixture under the +rule above and commit THAT. The real message stays in the scratchpad, which +is per-session and outside the repository. + ## Working on this repo Work directly on `master`, no PR flow. Commits are GPG-signed (`git commit -S`); @@ -249,3 +284,6 @@ umbrella design settles only what they share. ordering between MISP and the vendors. - `docs/plans/2026-09-08-parse.md` — the plan `init` and `parse` were built from. Historical once built, but it records why each test exists. +- `docs/BACKLOG.md` — open items, with the cause verified in the code rather + than assumed. Read it before starting work; add to it rather than fixing + something unasked. -- cgit v1.2.3