Skip to content

feat(glossary): explain the words, not just the findings - #9

Merged
gclluch merged 2 commits into
mainfrom
glossary
Aug 2, 2026
Merged

feat(glossary): explain the words, not just the findings#9
gclluch merged 2 commits into
mainfrom
glossary

Conversation

@gclluch

@gclluch gclluch commented Aug 2, 2026

Copy link
Copy Markdown
Owner

audit --explain RULE explains a finding. This explains the vocabulary a finding is written in - "the router answered an unauthenticated control request" only lands on someone who already knows what UPnP is, and the people this tool helps most are exactly the ones who do not.

  • netdiff glossary lists 30 terms, one line each; netdiff glossary upnp prints the whole entry with see-also links. Unknown term exits 2 and names the known ones, same shape as --explain.
  • One rule keeps it from becoming an encyclopaedia of networking: a term earns an entry only if netdiff itself prints it. Every slug appears in a finding, a change line, a column heading or a README limitation.
  • Reuses print_field for wrapping - no new rendering code. The tests pin the structure, not the prose: a see-also link pointing at nothing is the only thing here that can be wrong rather than merely badly worded.

Two unrelated fixes found by an earlier audit, folded in as a second commit:

  • findings dropped a row it should have kept. A TCP and a UDP forward on the same external port produce identical rule/device/title, so the primary key collapsed them - the audit the database recorded was not the audit that was printed. Evidence carries the protocol, so it joins the key.
  • _decode_txt truncated where parse_records bails. A TXT string claiming to be longer than its rdata gave model=Mac, a confident wrong answer where no answer is the honest outcome.

@gclluch
gclluch merged commit 270db1d into main Aug 2, 2026
8 checks passed
@gclluch
gclluch deleted the glossary branch August 2, 2026 01:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant