#212 engine: add a built-in Detector for oversized base64 blobs in tool arguments

[Anonymous]

Originally created by: fu351

What

Doberman core ships one built-in subjective detector today: TokenChannelDetector (src/doberman/engine/detectors/token_channels.py), wired into BUILTIN_DETECTOR_TYPES in src/doberman/engine/detectors/__init__.py. Add a second built-in detector that flags suspiciously large base64-looking payloads inside tool-call arguments — a common exfiltration shape (smuggling file/secret contents out as an encoded blob). Mirror TokenChannelDetector's structure — a Guardrail with evaluate(action, ctx) -> GuardrailResult, running in the subjective guardrail so it can only raise risk to AUTH, never BLOCK, and never lower a verdict — and register it in BUILTIN_DETECTOR_TYPES the same way.

Needs a new ReasonCode (src/doberman/models.py, class ReasonCode) plus a one-line human explanation — every AUTH/BLOCK must carry both.

You'll need to reason explicitly about false positives: legitimately binary-ish arguments show up constantly (embedded images, patch/diff payloads, minified/base64 assets), so a naive "any long base64-looking string" rule will fire on benign traffic. Make the size threshold configurable rather than a hardcoded magic number.

Difficulty: level-7

Additive engine change (new detector) — raise-only by construction, but requires understanding the subjective-guardrail contract, the redaction discipline, and designing a threshold/heuristic that isn't naively noisy.

Starting files

• src/doberman/engine/detectors/token_channels.py — the existing detector to mirror
• src/doberman/engine/detectors/__init__.py — BUILTIN_DETECTOR_TYPES registration
• src/doberman/models.py — class ReasonCode for the new code
• tests/unit/test_detector_token_channels.py — the sibling test pattern to follow

Acceptance criteria

• [ ] New detector module (e.g. src/doberman/engine/detectors/base64_blob.py) implementing the Guardrail interface
• [ ] Registered in BUILTIN_DETECTOR_TYPES (src/doberman/engine/detectors/__init__.py)
• [ ] New ReasonCode added, with a one-line human explanation on every AUTH it raises
• [ ] Size threshold is configurable (not a hardcoded magic number baked into the logic)
• [ ] Detector only ever raises risk (AUTH), never blocks, never lowers an existing verdict
• [ ] existing behaviour unchanged
• [ ] ruff check . && ruff format --check . and lint-imports pass
• [ ] pytest passes

How to validate

pip install -e ".[dev]"
ruff check . && ruff format --check .
lint-imports
pytest tests/unit/test_detector_base64_blob.py -v
pytest --cov=doberman --cov-report=term-missing

Out of scope

• Modifying the existing detector (token_channels.py)
• Decoding and inspecting the base64 payload's contents — this detector reasons about shape/size only, never decodes payload content

Safety constraints (do not weaken these)

1. Raise-only — this detector may only ever add AUTH/BLOCK signal, never remove or lower existing signal (subjective-guardrail invariant: it can raise to AUTH at most, never BLOCK).
2. Explainability — the new reason code must carry a one-line human explanation on every non-PASS result.
3. Redaction — this one is easy to get wrong: the detector must never log, persist, or echo the suspicious payload itself. Record length / a fingerprint / a classification only. A detector that helpfully dumps the blob it caught would leak the very secret it was built to catch.

Notes for contributors

New here? Start with CONTRIBUTING.md. Issues are labelled level-1 (docs only) through level-10 (new subsystem) — pick one at your level and climb. Comment to claim an issue before starting.

[Anonymous]

Ticket changed by: fu351

• status: open --> closed