1
0
Fork 0

feat(disposition): separate the assessment axis from the action

`decide` returned a `Disposition` — WARN / QUARANTINE_REVIEW / FAIL_SECURE —
which names an ACTION. But BRIEF design principle 4 says the library reports
and the pipeline decides, and disposition.py admitted the gap in its own
docstring: "It imposes no blocking of its own." So we returned an action we
cannot enforce, having discarded the judgement that produced it. A consumer
wanting different behaviour had to reinterpret the action itself — which is
why a consumer ends up pinning our GRADING: the action was all they got.

`Risk` (NONE/LOW/ELEVATED/SEVERE) now carries that judgement, and
`Policy.action_map` lets a caller map it to their own action. Both overlays
move the assessment rather than the action, so a custom map cannot silently
drop the compound escalation or the quarantine floor. `guard`'s fail-closed
path pins both axes and deliberately bypasses the map: downgrading SEVERE
means "I accept this class of finding", never "I accept a crashed scanner".

`DispositionResult.assessment` is required with no default. `Risk.NONE` is the
natural-looking default and the wrong one — a site that forgot the field would
report clean, and the axis would fail open.

MEASURED ADDITIVE, not assumed:
  - 703 -> 715 tests, no existing test changed
  - coverage matrix 128/128 recall, 6/6 documented gaps still hold
  - the PRESET_USER_UPLOAD grading table locked in 0.3.1 re-measured row by
    row: ordinary link/image/autolink/refdef -> warn on BOTH doors, unchanged

Both locked consumer promises in docs/PLAN-v1.md were checked against that
measurement and neither fires: the grading is untouched (linkedin-studio), and
the relative-target asymmetry is untouched (llm-ingestion-okf).

Scope held to disposition, per PLAN-v1.md:380. Version stays 0.4.0; the 0.5.0
bump lands in its release commit with all five version surfaces at once —
that is the fix for the defect where the v0.4.0 tag carried a 0.3.4 README.

Records limitation 32: `Severity` still carries disposition intent on the
DETECTION side, which this change does not address and cannot without moving
the grading.
This commit is contained in:
Kjell Tore Guttormsen 2026-08-10 20:55:46 +02:00
commit de097110d2
7 changed files with 329 additions and 38 deletions

View file

@ -334,6 +334,25 @@ fails the test, forcing this doc to be updated:
5. **Pure beaconing** — a bare-path remote image on a hostile host is LOW (above).
6. **Short opaque URL segment (<24 chars)** — below what entropy can resolve (above).
- **`Severity` still carries disposition intent on the detection side.** The
0.5.0 axis separation split the *assessment* (`Risk`) from the *action*
(`Disposition`), but only on the caller side of the boundary. Inside the
detectors, a finding's `Severity` is still calibrated partly for the
disposition it will produce rather than purely for what was observed, and two
places in the tree say so outright: `calibration.py`'s
`ACTIVE_CONTENT_ORDINARY_SEVERITY = LOW` exists because grading an ordinary
external image `HIGH` fail-secured ordinary uploads (measured on v0.3.0), and
`disposition.py`'s quarantine floor was raised from *any finding* to *MEDIUM+*
to repair the same regression from the other end. Both fixes are correct for
the dispositions they produce; the cost is that an ordinary external image is
recorded as low-severity rather than as *a real outward-fetch capability that
is not evidence of an attack* — so no policy, however strict, can act on that
capability, because the detector already decided it did not matter. Closing
this means giving detectors a channel that says what was seen separately from
how bad it is, which changes the grading and therefore fires the
consumer-notification promise in `docs/PLAN-v1.md`. Deferred deliberately, not
overlooked.
## Out-of-scope (documented boundary)
Embedding/vector-layer defenses (OWASP LLM08, downstream of persist); multimodal