Skip to content

docs: describe request inspection, and correct a limitation that stopped being true - #100

Merged
CharmingGroot merged 1 commit into
mainfrom
docs/inspectors-and-changelog
Sep 1, 2026
Merged

CharmingGroot merged 1 commit into
mainfrom
docs/inspectors-and-changelog

Conversation

@CharmingGroot

Copy link
Copy Markdown
Owner

README said pasu does no L7 content inspection. It does now.

A limitations list that understates what a security tool inspects misleads as badly as one that overstates it — a reader deciding whether pasu covers their case would decide wrongly in both directions.

That entry is now split into what is actually true:

  • the kernel layer is L3/L4 and cannot see inside TLS
  • the proxy layer inspects content, but only in request shapes it parses
  • detection is regex and checksums — no NER, so PII without a pattern (a person's name) is not caught
  • it blocks rather than masks

What had no documentation at all

The Inspector plugin point, pasu-pii-kr becoming reachable, and pasu-inspect-presidio appeared in no README, no docs page, and no changelog entry. ## [Unreleased] was empty.

Both READMEs now carry a request-inspection section with the commands, why the request body is the only place content is readable, and what does not survive a Presidio import. The changelog carries a Known gaps heading, not only the additions.

Running the commands caught something

Every command in the new section was run against the built binary rather than written from memory. On a rule file it refuses, the error told the operator to call read_lossy — a library function a person holding a CLI cannot call.

The library no longer names a remedy. Its two callers have different moves available: one can call read_lossy, the other can only change a flag or the file, and naming either is advice the other cannot take. Each now adds its own:

Error: import presidio rules /tmp/rec.yaml

Either remove those recognizers from the file, or lower --presidio-min-score
(currently 0.5) if you accept that a weaker pattern will match more ordinary text.

Caused by:
    1 recognizer(s) could not be imported, so this rule set is not what the file describes:
      Zip code Recognizer — its best pattern scores 0.01, below the 0.5 threshold; …

And the documented workaround does what the docs say it does:

$ pasu-proxy … --presidio-rules ./recognizers.yaml --presidio-min-score 0.0
pasu-proxy: 2 presidio pattern(s) loaded
pasu-proxy: requests are inspected by presidio and refused on a match (rule ids are logged, never the matched text)
pasu-proxy listening on 127.0.0.1:8788

🤖 Generated with Claude Code

…ped being true

README said pasu does no L7 content inspection. It does now, and a limitations
list that understates what a security tool inspects is as misleading as one that
overstates it — a reader deciding whether pasu covers their case would decide
wrongly in both directions.

So that entry is split into what is actually true: the kernel layer is L3/L4 and
cannot see inside TLS; the proxy layer inspects content, but only in request
shapes it parses; detection is regex and checksums, so PII without a pattern is
not caught; and it blocks rather than masks.

The Inspector plugin point, the two new crates and the Presidio import were in
no README, no docs page and no changelog entry. The CHANGELOG Unreleased section
was empty. Both READMEs now carry a request-inspection section with the commands,
and the changelog carries a Known gaps heading rather than only the additions.

Every command in that section was run against the built binary rather than
written from memory. Doing that caught one thing: on a rule file it refuses, the
error told the operator to call read_lossy — a library function a person holding
a CLI cannot call. The library no longer names a remedy, because its two callers
have different moves available, and each now adds its own. The proxy says to
remove the recognizers or lower --presidio-min-score, and prints the current
value.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@CharmingGroot
CharmingGroot merged commit dc96307 into main Sep 1, 2026
5 checks passed
@CharmingGroot
CharmingGroot deleted the docs/inspectors-and-changelog branch September 1, 2026 02:45
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