diff options
Diffstat (limited to 'AGENTS.md')
| -rw-r--r-- | AGENTS.md | 38 |
1 files changed, 38 insertions, 0 deletions
@@ -230,6 +230,41 @@ weekday with `date -d <yyyy-mm-dd> +%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. |