v0.18.5 — retention, self-awareness, and a tighter bar for tutorials

Retention, self-awareness, and a tighter bar for tutorials. The decision log can now be
pruned by age or row budget without touching pending approvals, and it prunes every resolved
AUTH row, not just three literal outcomes. doberman update and a passive nudge in status
tell you when you're behind PyPI. The dashboard lets you copy a pending approval's redacted
details, shows the real mark, and keeps its counters in step with the feed. The doctor reports
the password factor and the optional dash/tui extras; changelog fragments end the CHANGELOG
conflict tax; and the plugin tutorials are covered by CI without ever being installed.

• Decision-log retention is explicit and fail-safe. doberman decision-log-prune lets an
  operator delete resolved rows by age and/or retained-row budget; pending AUTH challenges and the
  append-only policy-change ledger are never touched, and mediated agents cannot invoke the
  mutating command through the shell. Any AUTH row with a recorded outcome (approval method,
  denied, blocked, error, executed) counts as resolved and is eligible for pruning, not only the
  three literal values it originally accepted (#461, #502)

• doberman update — and a passive "new version available" nudge. Doberman now tells you when the
  installed version is behind PyPI, so a friction fix reaches you without watching the releases page.
  doberman update does one timeout-bounded PyPI check and prints the pip install -U command (it never
  installs anything); doberman status shows a one-line nudge when a newer version is cached. The check is
  best-effort and fail-open (an unreachable PyPI is silent, never an error), caches for 24h, never runs on
  the hook/proxy hot paths, and is off under DO_NOT_TRACK, CI, or DOBERMAN_UPDATE_CHECK=off (#508).

• Copy a pending approval's details from the dashboard. A Copy details action on each pending card copies only the existing redacted fields as formatted JSON (thanks @slegarraga, #498, closes #443)

• doberman doctor reports the password factor: a Password row next to 2FA, OK when
  enrolled, a non-critical WARN with the doberman password set hint when not; presence only, never
  the secret (thanks @slegarraga, #474, closes #439)

• doberman doctor reports the optional UI extras: Dash extra and TUI extra rows say
  whether starlette/textual are installed (via find_spec, nothing imported) and print the
  pip install 'doberman[dash]'/[tui] hint when not (thanks @slegarraga, #475, closes #440)

• doberman egress-velocity [KNOB] [VALUE]: show or set the burst, volume-bytes, and
  fanout detection thresholds from the CLI. Lowering a threshold applies at once; raising one
  crosses the same possession-factor gate as every other loosening (TOTP if enrolled, else the
  password), is recorded in the policy-change ledger, and is saved only when approved, so
  hand-editing the policy file is no longer the only way to set them (thanks @Maqbool61, #459,
  closes #457)

• install-hooks --dry-run previews the command the installer really writes. The SessionStart
  line now comes from the same DASHBOARD_COMMAND constant as the write path (doberman session-summary), so the preview cannot drift again (thanks @slegarraga, #463, closes #429)

• tune --json is compact like every other JSON command (separators=(",", ":")), keeping
  the machine-readable output contract in docs/CLI.md (thanks @slegarraga, #470, closes #431)

• doberman log columns no longer shift for the 15-character action types (network_request,
  package_install): the action column width now comes from the ActionType enum, the way verdict
  labels already do (thanks @slegarraga, #472, closes #428)

• The dashboard stats strip stays in step with the live feed. A decision landing in the feed
  now triggers an immediate (trailing-debounced 150 ms) stats refresh instead of lagging up to 5 s
  behind the list; the 5 s interval remains as a fallback. (#491)

• Tests: the data-class rule's two documented non-detections are now proven: a six-digit
  one-time code bound for an external host stays PASS, and the valid SSN's digits without dashes
  stay PASS, so the rule is pinned to the dashed shape rather than the value (thanks @slegarraga,
  #468, closes #405)

• Docs: five stale "(a later slice)" comments that promised features which have since shipped
  now describe what the code does today (thanks @slegarraga, #473, closes #426)

• Changelog entries no longer collide on every parallel pull request. Each PR now adds its
  own changelog.d/<PR-number>.md, and release tooling compiles those fragments together
  (thanks @slegarraga, #476, closes #456)

• The dashboard header now shows the real Doberman mark. The placeholder "D" is replaced by
  an embedded PNG data URI, so doberman dash stays one self-contained page with no static-file
  route. (#490)

• docs/README.md indexes every doc page. An "open this when…" guide to each document makes
  the right one a single scan away (thanks @navaneethsankar07, #492, #500, closes #409)

• Tests: the core standalone-guarantee test asserts no doberman.audit_sinks plugin is
  registered by default again; the plugin-audit-sink tutorial is now covered by a CI-visible test
  that never installs it (#501)

v0.18.4 — friction reduction, part three; telemetry on by default

Friction reduction, part three, and the lights come on. A repeat of an approved action now
re-prompts at a one-click confirm instead of the full ladder; uninstall --global and the doctor's
Hook command check close the dangling-hook trap; demo --quiet and the global-hook exclusion
round out the CLI. Usage telemetry is on by default with a one-time notice, the same allowlist, and
the kill switches unchanged, so from this version the project can see what people actually use.

• Telemetry is now on by default (opt-out). Anonymous usage counts (the same five allowlisted
  events, no paths, prompts, secrets, or profiles) are sent unless you turn them off; the first CLI
  command prints a one-line notice to stderr before anything is sent, doberman setup asks with a
  default of Yes, and doberman telemetry off, DO_NOT_TRACK, DOBERMAN_TELEMETRY=0, and CI
  still switch it off. The PostHog project key ships in the package, so events flow from this
  version on.
• doberman demo --quiet: suppresses the banner, the per-scenario narration, and the closing
  doberman dash hint, keeping only the summary line/table (silent on a full match, loud on a
  mismatch) and the exit code — so demo can run as a CI smoke test ("is the engine alive")
  without polluting build logs. Mirrors scan --quiet; display-only, the scenarios and the engine
  path are untouched.
• doberman uninstall now actually stops protection when hooks are global. Previously,
  uninstall was project-scoped only: if a global (--global) Claude Code hook or a Codex
  user-scope hook was still installed, it kept firing in the "uninstalled" project and silently
  recreated .doberman/ there the next time any decision needed recording. uninstall now
  detects this and automatically adds the project to a device-wide exclusion list
  (~/.doberman/excluded_projects.json) that the (unchanged) global hook checks — first, before
  anything else — on every call, so an excluded project gets a true no-op instead. The list is
  only ever written by the already possession-factor-gated uninstall flow; reading it is a pure,
  side-effect-free check that fails closed. Run doberman install-hooks in that project again to
  clear the exclusion (no gate needed — re-arming protection is a strengthen). doberman status
  reports whether the current project is excluded.
• doberman doctor catches dangling hook entries. New critical Hook command check: when hooks are
  installed but the bare doberman they invoke is not on PATH (package removed, bin dir not on PATH), the
  host fails the hook and carries on unmediated, so doctor now fails and names the fix - put the binary
  back on PATH, or strip the entries with doberman uninstall-hooks. Diagnosis only; doctor stays
  read-only.
• Device-wide uninstall: doberman uninstall --global now removes writable Claude Code and Codex
  hooks, project state, possession factors, the fingerprint key, and device state before removing the
  package through pip or pipx. The same fail-closed factor gate runs before any removal; --yes skips
  only the typed DOBERMAN confirmation, --dry-run changes nothing, and --keep-package preserves
  the package. Codex plugin hooks remain under codex plugin control.
• Five-minute exact-action approval memory. A repeat of an action approved with local auth or
  2FA still prompts, but at one-click soft_confirm, keyed only by an HMAC of the exact pre-redaction
  action. Destructive, critical, excluded, or tainted-session actions never downgrade; soft confirms
  never chain; doberman approvals status|clear|ttl exposes bounded human controls.

v0.18.2 — friction reduction

v0.18.2 — friction reduction

Doberman gets out of your way. This patch removes the biggest source of spurious approval prompts and hardens the secret detector against being broken.

Fixed

• No more false prompts on ordinary identifiers, paths, and UUIDs. The secret detector keyed on Shannon entropy per character, which reads a normal identifier, a relative path, or a UUID much like a short base64 token — so it fired AUTH prompts on benign shapes, and via the multi-step taint ledger a single UUID-bearing temp path could gate a whole session's egress. It now recognizes digest/UUID ids and short word+number build tags (py311, x86) and lets them through. Raise-only: every real credential still fires (recall pinned by tests), and the strong credential-shape path is untouched.

Added

• The secret rule self-checks and fails closed. It verifies its own invariants at import; if a change ever breaks it, it degrades to a fail-closed AUTH instead of erroring on every action — it can neither let a secret through nor brick tool mediation.
• Opt-in anonymous CLI telemetry — doberman telemetry on|off|status. Off by default, allowlisted counts and command names only, never on the per-tool hook or proxy hot path.
• A documentation site at docs.trydoberman.dev, plus a full docs/ + README rewrite for accuracy and voice.

Notes

• Detection is unchanged. Synthetic benchmark: attacks-stopped 1.0. The fix only removes false AUTH prompts on benign shapes; no BLOCK verdict changed.
• Also included: a per-project dashboard tab title, a macOS GUI auth-dialog thread-safety fix (#399), and a river version cap on Python 3.11.

Upgrade: pip install -U doberman-core

v0.18.1 — README images on PyPI

Docs-only patch on top of v0.18.0. The README's logo and demo GIF now use absolute raw.githubusercontent.com URLs so they render on the PyPI project page (repo-relative paths render on GitHub but not on PyPI, which shows the README standalone). No code change.

Install: pip install --upgrade doberman-core

v0.18.0 — security-audit wave

The security-audit wave. Three fixes held privately until every one was ready ship together, so no fix disclosed a live bypass ahead of its own remediation. This release also carries the RAND-aligned guardrail rehaul and the UX/contributor work merged since 0.17.1.

Security fixes

• Proxy output-secret gate now covers error results and structured/embedded channels (#378, ADR 0062). An isError=True result skipped the output scan at both call sites, and the scan folded only TextContent — so a credential in structuredContent or an EmbeddedResource, or in any errored result, could reach the model. All three channels are now scanned; taint-recording and single-use consumption are hoisted above the error guard too (raise-only).
• Per-user auth state is now control plane (#379, ADR 0065). The TOTP seed, its lockout counter, and the password hash live outside any repo and so sat outside the control-plane path globs — a mediated command deleting or overwriting them was not recognised as tamper. They are now matched explicitly.
• Control-plane paths are recognised regardless of separator style (#380, ADR 0066). POSIX tokenization treats \ as an escape, so a control-plane path spelled with Windows separators slipped past the command rule. The rule now also scans a separator-normalized view (scan-only, raise-only).

Related: GHSA-4vvj-9m89-648r (trailing space/dot path bypass on Windows, CVSS 7.1) was fixed in 0.17.0 and is now published with a full vector and all-platforms scope note.

Also in this release

The RAND-aligned guardrail rehaul (session correlator, opt-in least-privilege default role, subjective-memory governance, egress task-match leg, the labeled detection corpus with per-category FPR/TPR), a gated doberman uninstall, doberman 2fa reset-lockout, doberman taint clear, the WebhookAuditSink, and the UX/contributor work since 0.17.1. Full detail in the changelog.

Install: pip install --upgrade doberman-core

v0.17.1 — UX + machine-readable output

A UX and machine-readable-output polish wave, from the 2026-08-05 UX audit.

Verdict rendering is consistent everywhere. Every verdict-printing surface routes through the shared render layer: color when the terminal supports it, NO_COLOR- and pipe-safe, fixed-width labels that never shift alignment (#252). The dash re-tunes light mode to AA contrast on verdict badges, announces pending approvals through a polite live region and a tab-title count, and labels the TOTP input properly (#261).

Auth deadlines are visible. Every AUTH channel now states its auto-deny deadline (TTY prompt, GUI dialog, dash card expiry), and doberman status surfaces challenges auto-denied in the last 24h (#265).

--json and --jsonl on the read-only commands. scan, doctor, policy-history, and log emit machine-readable output, so Doberman's decisions pipe into other tooling instead of being scraped. Each JSON path writes an explicit allowlist of already-redacted columns instead of serializing rows wholesale, so a column added to the decisions table later cannot leak into a stream by default (#207, #208, #210).

doberman dashboard is now doberman session-summary. The old name survives as a hidden permanent alias, so existing SessionStart hooks keep working (#267).

Smaller fixes. The setup wizard re-prompts on a mistyped mode instead of exiting and losing every answer (#266). The dash Approve control is arm-then-confirm; Deny stays single-click, because denying is the safe direction (#268). New docs: docs/CLI.md and docs/REASON_CODES.md, which catalogues all 51 ReasonCode values with the condition that fires each one.

Full notes: CHANGELOG.md

Thanks to @slegarraga, @AshSgDe29071999, and NanoRisk6 for the contributions in this release.

Doberman is alpha and defense-in-depth, not airtight. Issues and PRs welcome: https://github.com/fu351/Doberman-Core/issues

v0.17.0 — runtime egress broker

Adds the runtime egress broker (RB.1–RB.7) and ships three security fixes.

Install / upgrade:

pip install --upgrade doberman-core

Runtime egress broker (RB.1–RB.7)

A new public package, doberman.egress, plus a new plugin entry-point group doberman.egress_brokers. Third-party brokers register the same way as every other Doberman seam.

• RB.1 — the EgressBroker interface, registry, and fail-closed default (wired but dormant)
• RB.2a — default-deny host allowlist + a two-sided enforcement probe (a failed direct connection alone is never accepted as proof of enforcement)
• RB.2b — a stdlib-only forcing forward proxy that enforces the allowlist at the socket; a denied destination's upstream connection is never opened
• RB.3 — retrospective ground-truth reconciliation; an observed route diverging from static host trust raises the verdict
• RB.4 — broker-backed egress PASS, but only behind enforcement genuinely proven at the socket
• RB.5 — mode-gated egress posture; Paranoid hard-blocks non-allowlisted egress, and only when a broker attests it will actually drop it
• RB.6 — per-entity egress velocity signals (burst / volume / fan-out), bounded and memory-safe
• RB.7 — post-fetch artifact digest verification against operator-pinned digests

Every one of these is raise-only and dormant with no broker registered — behavior is byte-for-byte unchanged unless you register one.

Security fixes

• Bounded AUTH challenges (AN-4). An unanswered challenge now denies on a wall-clock deadline instead of hanging forever. An indefinite block is not a denial — and it failed worst exactly where agents run: headless and unattended.
• Raw socket/shell egress classification (CRIT-1). Network reach hidden inside shell_exec / package_install / git_op is now visible to the guardrails instead of passing as an opaque command.
• Path canonicalization padding. Trailing dots and spaces are stripped per path component before glob matching, on every platform — a padded spelling and its unpadded counterpart are the same file on Windows and must match the same rule.

Also in this release

• CI/CD-config protection extended beyond GitHub Actions to GitLab CI, Jenkins, CircleCI, and Azure Pipelines
• devops role no longer allow-lists .github/workflows/** — CI config now escalates consistently for every role
• doberman 2fa remove to unenroll TOTP
• Color-coded verdicts and width-aware explanation wrapping in CLI output
• Dashboard fixes: authentication survives a reload; the 2s poll no longer wipes the TOTP field

Full detail: CHANGELOG.md

v0.16.0 — raise-only static egress classification (EB.1)

Egress-breakout defense (EB.1) — raise-only static egress classification

Doberman now parses the raw shell/package/git command an agent runs and surfaces the network destination hidden inside it — so an exfil attempt tucked into a shell_exec / package_install / git_op (curl, wget, pip, git push, …) is visible to the guardrails instead of slipping past as an opaque command.

• secret + command egress → BLOCK — the existing secret-exfil floor now fires
• command egress + one ambiguity signal → AUTH — dynamic host, route/proxy override, unbalanced quoting, the 256-char work cap, or multi-host, via ExternalDestinationRule
• parser crash → fail-closed objective floor — new NormalizationFailureRule
• command egress is excluded from the subjective baseline (can't be slow-boiled to "familiar"); secret-shaped host labels are HMAC-redacted before they reach the SecurityObject

Strictly raise-only: never a new PASS, never a lowered verdict.

Also

• doberman.__version__ is now single-sourced from the installed package metadata, so it can never drift from the published version again.

Install: pip install doberman-core==0.16.0

v0.15.0 - Turn gate + live dashboard

v0.15.0 — Turn gate + live dashboard

First PyPI release: pip install doberman-core

Highlights

• Turn gate: a session-level defense layer that extends Doberman's per-call lethal-trifecta protection across an agent's multi-step turns — provenance inheritance between related actions, tiered risk clamping, and repeat-action awareness.
• doberman dash: a local dashboard (pip install "doberman-core[dash]") with a live decision feed, verdict/rule stats, and interactive approve/deny for AUTH prompts. Loopback-only, per-run bearer token, fail-closed — the decision path never depends on the dashboard being alive.
• doberman demo: a scripted attack reel — secret exfiltration, rm -rf ~, force-push to a protected branch, Unicode-smuggled egress, .env read — driven through the real decision engine, so you can watch the dashboard light up.
• Hardening train (17 PRs): proxy output secret-gate parity with the host hook, unified redaction on the shared strong-secret detector, persisted TOTP lockout with cooldown, elevation glob escaping, shelled control-plane command blocking, host-hook role-boundary enforcement, and more.
• Docs: new CONTRIBUTING guide for external contributors.

Install

pip install doberman-core          # core
pip install "doberman-core[dash]"  # + local dashboard

Python 3.11+. See the README for quickstart (Claude Code host hook + MCP proxy adapters).

v0.11.0 — first public release

First public release of Doberman — an adaptive authorization layer for coding agents.

pip install doberman-core

The distribution is doberman-core (the bare doberman name on PyPI belongs to an unrelated, abandoned project). The import name and CLI are unchanged: import doberman / doberman --help.

Included

• Tool mediation + decision engine — every tool call → allow / authenticate / block
• Objective guardrail: path confinement, destructive-command, external-destination, secret-pattern, and smuggled-token-channel rules
• Subjective guardrail: adaptive behavioral baselines + OOD/homoglyph token signals; universal subjective layer (SL1–SL9)
• Roles & boundaries, capability discovery, tiered auth (confirm → TOTP → scoped elevation)
• Local redacted audit log, policy-drift & poisoning defense, turn gate (pre-inference prompt-injection screening)
• Suite-agnostic ASR/FPR benchmark harness
• doberman serve stdio MCP proxy runtime

Apache-2.0 · standalone with no proprietary dependency (CI-enforced) · published via PyPI Trusted Publishing (OIDC).