Skip to content

feat(audit): a report nobody finishes reading teaches nothing - #5

Merged
gclluch merged 1 commit into
mainfrom
feat/audit-verbosity
Aug 1, 2026
Merged

feat(audit): a report nobody finishes reading teaches nothing#5
gclluch merged 1 commit into
mainfrom
feat/audit-verbosity

Conversation

@gclluch

@gclluch gclluch commented Aug 1, 2026

Copy link
Copy Markdown
Owner

Phase 2a. Every finding printed its full lesson - evidence, why, fix, verify - so a network with fifteen findings produced a wall of text people stop reading. A lesson nobody reads teaches nothing, which defeats the point of having a teaching layer at all.

Depth is now something you ask for. Measured on five findings: 75 lines before, 13 after.

$ netdiff audit 192.168.1.0/24
audit 12: 192.168.1.0/24 - 1 critical, 2 high, 1 medium, 1 info

    critical  nas.local (192.168.1.23:8080) is reachable from the internet on port 8080   [NEW]
    high      Telnet on port 23 sends usernames, passwords and every keystroke of the
              session in cleartext
    medium    the router lets any device on the LAN open its firewall
    info      7 open port(s) observed, and not reported as problems

-v adds the evidence each line rests on, why it matters, how to fix it,
and a command you can run yourself to confirm it.

-v is exactly the previous output, unchanged. --json and --explain are untouched.

Two choices worth naming:

  • The severity rides on each line rather than sitting in a CRITICAL heading above a group. It costs nine columns and buys a line that still says what it is once it has been copied into a ticket or a message. The group headings are still there under -v, where there is room.
  • The compact footer is load-bearing. It is the only thing pointing at -v; without it the teaching layer exists and nobody ever finds it.

print_headline reuses print_field with the severity as its label, so wrapping and the hanging indent came for free.

New tests/test_cli_output.py drives cmd_audit against a stubbed discover, so it pins the rendering without touching a network. The one that matters most is test_both_views_report_the_same_findings - brevity is allowed to drop detail, it is not allowed to drop a finding.

@gclluch
gclluch merged commit 0f478b5 into main Aug 1, 2026
8 checks passed
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