Skip to content
Back to search

Doberman-Core

Your AI's guard dog. Doberman sits at runtime, gating every input, output and tool call to stop unsafe or unintended actions before they execute.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/DobermanCore/Doberman-Core with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/DobermanCore/Doberman-Core'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dobermancore--doberman-core/badge.svg)](/listings/dobermancore--doberman-core)

HTML

<a href="/listings/dobermancore--doberman-core"><img src="/api/listings/dobermancore--doberman-core/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Doberman guards any MCP-compatible coding agent: pick your agent, run one command, and every tool call is reviewed before it executes. The full walkthrough (every option and flag, the dashboard, health checks) is the [Setup guide](docs/SETUP.md).

pip install doberman-core

After installing, run `doberman --install-completion` to enable shell tab completion.

> **Note** > Run `doberman uninstall --global` to remove Doberman from the whole machine. It removes the > writable Claude Code and Codex hooks, project and device state, and enrolled factors before it > removes the `doberman-core` package with pip or pipx. Uninstalling the package first leaves hooks > pointing at a missing binary. Already hit this? Reinstall `doberman-core`, then run the global > uninstall. `doberman doctor` flags any hook entry whose `doberman` is not on PATH. More recovery > steps: [Recover](docs/RECOVERY.md).

- Install integrity: `install-hooks` records a keyed fingerprint (a short tag derived from a secret key, so the original value can't be worked out from it) of Doberman's own hook entries, in your per-user Doberman config directory, never in the repo. If those entries are later stripped or altered, the next hook invocation that still runs warns about it, and `doberman doctor` reports which scope diverged. This is detection only; it never blocks. (#239)

| Your agent | How Doberman plugs in | Get started | |---|---|---| | **Claude Code** | Hooks: gates every built-in and MCP tool call *(recommended)* | `doberman setup` → [guide](docs/SETUP.md) | | **Codex CLI** | Native PreToolUse hook *(experimental)* | `doberman install-hooks --host codex` | | **Claude Desktop / Cursor** | MCP proxy: wraps your tool server | `doberman serve -- <your-server>` → [guide](docs/SETUP.md) | | **OpenClaw** | Native plugin adapter | [guide](docs/SETUP.md) · [adapter](adapters/openclaw/README.md) | | **Cursor** | Native hooks adapter *(experimental)* | `doberman install-hooks --host cursor` · [adapter](adapters/cursor/README.md) | | **Any MCP-compatible agent** | MCP proxy | [guide](docs/SETUP.md) |

**Fastest path (Claude Code):**

doberman setup      # asks which agents to guard, then picks a strictness mode, tunes guardrails, wires them

Anonymous usage counts are on by default: command names and daily totals, never paths, prompts, or secrets. The first command prints a notice, and `doberman telemetry off` or `DO_NOT_TRACK=1` turns them off. See [Telemetry](docs/TELEMETRY.md).

Doberman now reviews every tool call your agent makes. Confirm it with `doberman doctor`, or watch real verdicts with `doberman demo`. MCP-proxy wiring, the dashboard, the TUI, scan, and 2FA (two-factor authentication) are in the [Setup guide](docs/SETUP.md). Pending-approval cards in the dashboard can copy their already-redacted decision details as JSON for review handoffs without exposing raw targets or paths.

Terminal explanations wrap to 60–78 columns. Paths and URLs remain intact, while other overlong tokens are split to stay within the configured width.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 343 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="https://raw.githubusercontent.com/DobermanCore/Doberman-Core/main/logo.png" alt="Doberman logo" width="200">
  3. # Doberman
  4. **Adaptive Authorization & Runtime Guardrails for AI Coding Agents**
  5. [![CI](https://github.com/DobermanCore/Doberman-Core/actions/workflows/ci.yml/badge.svg)](https://github.com/DobermanCore/Doberman-Core/actions/workflows/ci.yml)
  6. [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
  7. [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
  8. [![Status](https://img.shields.io/badge/status-alpha-orange.svg)](#roadmap)
  9. [![Discord](https://img.shields.io/badge/Discord-join%20the%20pack-5865F2?logo=discord&logoColor=white)](https://discord.gg/Sfy5XGNqty)
  10. [![Product Hunt](https://img.shields.io/badge/Product%20Hunt-we're%20live-DA552F?logo=producthunt&logoColor=white)](https://www.producthunt.com/products/doberman?utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-doberman)
  11. Your AI coding agent can run `rm -rf` on your repo, leak your API keys, or get tricked by hidden instructions into leaking data on its own, with no undo. Doberman is the guard dog on the execution path. It stops the dangerous call before it runs.
  12. </div>
  13. <p align="center">
  14. <img src="https://raw.githubusercontent.com/DobermanCore/Doberman-Core/main/docs/assets/dash-demo.gif" alt="The doberman demo attack reel against the live dashboard: a secret exfiltration, a destructive rm -rf, a protected-branch force push, a smuggled-token egress and a .env read are blocked in the live feed, then a human denies a high-risk shell egress to an unknown host from the pending-approvals queue" width="820">
  15. <br>
  16. <em><code>doberman demo</code> against the live dashboard (<code>doberman dash</code>): five attacks blocked as they happen, then a human denies a high-risk approval.</em>
  17. </p>
  18. > A guardrail that isn't on the execution path can only advise.
  19. Doberman sits between the agent and its tools, through a transparent **MCP proxy** or **host hook** (MCP: Model Context Protocol, the standard interface between an agent and its tools; a hook is code the host runs automatically around a tool call), and turns every action into an explicit, auditable decision. Every tool call gets exactly one verdict, decided before it runs:
  20. | Verdict | What happens |
  21. |---|---|
  22. | `PASS` | Routine work, straight through, zero friction. |
  23. | `AUTH` | Sensitive, paused for your approval. Repeat the exact same action within five minutes and it re-prompts with a one-click confirm (never for destructive work). |
  24. | `BLOCK` | Dangerous, stopped cold. It never runs. |
  25. ```
  26. AI agent ──▶ Doberman ──▶ real tools (files, shell, MCP servers, APIs)
  27. └─ normalize → risk engine → PASS / AUTH / BLOCK
  28. ```
  29. Works with Claude Code, Codex, OpenClaw, and any MCP-compatible agent. Cursor is guarded through its native hooks *(experimental)*; other MCP clients connect through the [MCP proxy](#quick-start). It's open source and local first, and it holds two guarantees: it fails closed (uncertainty denies the action) and it's raise-only (it can tighten automatically, but never silently loosens).
  30. <div align="center">
  31. ### [Get protected in two commands](#quick-start) · [Join the pack on Discord](https://discord.gg/Sfy5XGNqty)
  32. **Full docs:** [docs.trydoberman.dev](https://docs.trydoberman.dev)
  33. </div>
  34. ---
  35. ## Contents
  36. - [Why Doberman](#why-doberman): what it does, and its two guarantees
  37. - [Quick start](#quick-start): install and protect an agent in two commands
  38. - [Verify it end-to-end](#verify-it-end-to-end): watch it front a real MCP server
  39. - [Turn gate](#turn-gate): the optional check that runs before the model even starts thinking
  40. - [Benchmark](#benchmark): attack-block rate vs. false positives (flagging something harmless)
  41. - [Write a guardrail plugin](#write-a-guardrail-plugin): register your own rule or audit sink
  42. - [Policy as code](#policy-as-code): a repo-committed `doberman.policy.yaml`, reviewed like code
  43. - [Tune to your risk tolerance](#tune-to-your-risk-tolerance): strictness modes and the enforcement dial
  44. - [Who is this for](#who-is-this-for)
  45. - [Roadmap](#roadmap)
  46. - [Contributing](#contributing) · [License](#license)
  47. ---
  48. ## Why Doberman
  49. Most "AI guardrails" inspect prompts and offer advice after the model has already decided what to do.
  50. Doberman sits on the tool-execution path instead, so a blocked action never runs, no matter how it
  51. talked its way past the model's own guardrails first. Two properties make that a guarantee:
  52. - **Fail closed**: any error, uncertainty, or unhandled case denies the action. There's no path to a
  53. tool that goes around the decision engine. This includes silence: if nobody answers an approval
  54. prompt, a hard deadline resolves it to a denial (2 minutes for the desktop dialog, 10 minutes as the
  55. backstop for the whole approval flow), logged distinctly as `timeout` rather than `denied`. A hung
  56. prompt is not a denial on its own, and agents usually run unattended, so that deadline matters.
  57. - **Raise-only learning**: guardrails and adaptive learning can tighten automatically, but never
  58. silently loosen. Every permanent policy weakening needs explicit, audited human approval, gated
  59. behind a possession factor: proof you hold something specific, such as TOTP (a time-based one-time
  60. code from an authenticator app) if you've enrolled one, or otherwise the local Doberman password.
  61. The [parity matrix](docs/PARITY.md) maps each protection to each host Doberman fronts: Claude Code,
  62. Codex, the MCP proxy, and OpenClaw. Every checkmark links to the CI test that proves it. Open cells
  63. are contributor-sized work, and the matrix regenerates from those tests on every build, so it can't
  64. drift from what's actually proven.
  65. ---
  66. ## Quick start
  67. Doberman guards any MCP-compatible coding agent: pick your agent, run one command, and every tool call
  68. is reviewed before it executes. The full walkthrough (every option and flag, the dashboard, health checks)
  69. is the [Setup guide](docs/SETUP.md).
  70. ```bash
  71. pip install doberman-core
  72. ```
  73. After installing, run `doberman --install-completion` to enable shell tab completion. If your shell
  74. can't find `doberman` (a `pip install --user` on Windows often leaves its Scripts folder off PATH),
  75. `python -m doberman` runs the same CLI.
  76. > **Note**
  77. > Run `doberman uninstall --global` to remove Doberman from the whole machine. It removes the
  78. > writable Claude Code and Codex hooks, project and device state, and enrolled factors before it
  79. > removes the `doberman-core` package with pip or pipx. Uninstalling the package first leaves hooks
  80. > pointing at a missing binary. Already hit this? Reinstall `doberman-core`, then run the global
  81. > uninstall. `doberman doctor` flags any hook entry whose `doberman` is not on PATH. More recovery
  82. > steps: [Recover](docs/RECOVERY.md).
  83. - Install integrity: `install-hooks` records a keyed fingerprint (a short tag derived from a secret
  84. key, so the original value can't be worked out from it) of Doberman's own hook entries, in your
  85. per-user Doberman config directory, never in the repo. If those entries are later stripped or
  86. altered, the next hook invocation that still runs warns about it, and `doberman doctor` reports
  87. which scope diverged. This is detection only; it never blocks. (#239)
  88. | Your agent | How Doberman plugs in | Get started |
  89. |---|---|---|
  90. | **Claude Code** | Hooks: gates every built-in and MCP tool call *(recommended)* | `doberman setup` → [guide](docs/SETUP.md) |
  91. | **Codex CLI** | Native PreToolUse hook *(experimental)* | `doberman install-hooks --host codex` |
  92. | **Claude Desktop / Cursor** | MCP proxy: wraps your tool server | `doberman serve -- <your-server>` → [guide](docs/SETUP.md) |
  93. | **OpenClaw** | Native plugin adapter | [guide](docs/SETUP.md) · [adapter](adapters/openclaw/README.md) |
  94. | **Cursor** | Native hooks adapter *(experimental)* | `doberman install-hooks --host cursor` · [adapter](adapters/cursor/README.md) |
  95. | **Any MCP-compatible agent** | MCP proxy | [guide](docs/SETUP.md) |
  96. **Fastest path (Claude Code):**
  97. ```bash
  98. doberman setup # asks which agents to guard, then picks a strictness mode, tunes guardrails, wires them
  99. ```
  100. Anonymous usage counts are on by default: command names and daily totals, never paths, prompts, or
  101. secrets. The first command prints a notice, and `doberman telemetry off` or `DO_NOT_TRACK=1` turns
  102. them off. See [Telemetry](docs/TELEMETRY.md).
  103. Interactive setup step counters include only the sections that the current run actually shows,
  104. including when a refused mode lowering skips preference tuning.
  105. Doberman now reviews every tool call your agent makes. Confirm it with `doberman doctor`, or watch
  106. real verdicts with `doberman demo`. MCP-proxy wiring, the dashboard, the TUI, scan, and 2FA
  107. (two-factor authentication) are in the [Setup guide](docs/SETUP.md). Pending-approval cards in the
  108. dashboard can copy their already-redacted decision details as JSON for review handoffs without
  109. exposing raw targets or paths. A script the agent writes and runs can answer its own prompts
  110. ([Limitations](docs/LIMITATIONS.md)); `doberman doctor` checks whether Claude Code's sandbox keeps
  111. your 2FA secret out of its reach, and [Setup §4](docs/SETUP.md) shows the settings. On Windows,
  112. an opt-in Hello-required mode (`doberman 2fa hello enroll`) replaces the 2FA secret with a Windows
  113. Hello gesture that signs the action, so no secret exists to steal; it narrows that gap, not closes it.
  114. Terminal explanations wrap to 60–78 columns. Paths and URLs remain intact, while other overlong
  115. tokens are split to stay within the configured width.
  116. ---
  117. ## Verify it end-to-end
  118. Two ways to watch Doberman front a real MCP server, with no in-process test doubles (fakes standing
  119. in for real components) anywhere in the chain.
  120. **Interactive demo (MCP Inspector and a real filesystem server):**
  121. ```bash
  122. npx -y @modelcontextprotocol/inspector doberman serve -- npx -y @modelcontextprotocol/server-filesystem ~/my-project
  123. ```
  124. Open the Inspector UI and call tools through Doberman: routine reads and writes pass straight through
  125. to the real filesystem server; a destructive call comes back as a policy error and never executes.
  126. **End-to-end test (in a dev checkout):**
  127. ```bash
  128. pytest tests/integration/test_serve_end_to_end.py -q
  129. ```
  130. This spawns `doberman serve` as a real subprocess in front of a real stdio (standard input/output)
  131. tool server ([`tests/fixtures/stdio_tool_server.py`](tests/fixtures/stdio_tool_server.py)). It
  132. connects to that subprocess with a real MCP client playing the agent, and checks the whole chain
  133. over actual stdio: the downstream server's tools are re-exposed through the proxy, a `PASS` verdict
  134. reaches the tool and the downstream's call log records it, and a `BLOCK` verdict (`rm -rf /`) never
  135. reaches it, so the call log stays empty. That last check is the core guarantee the whole project
  136. depends on: a blocked action never runs.
  137. > **Note**
  138. > The rest of the integration suite deliberately uses an in-process fake downstream
  139. > ([`tests/fixtures/fake_tool_server.py`](tests/fixtures/fake_tool_server.py)) that records every call
  140. > it executes, so the tests can prove a blocked action reached nothing. It's a test fixture, not the
  141. > runtime. `doberman serve` always talks to the real server: the one it spawns from the command after
  142. > `--`, or the remote one you point it at with `--url`.
  143. Doberman's proxy speaks MCP at the version pinned in `pyproject.toml` (`mcp>=1.27,<2`). Its cross-call
  144. protections (the taint ledger, a record of values that came from an untrusted source; read-vs-send
  145. fingerprints; and the decision log) key off repo-local identity, never the protocol session, and are
  146. regression-tested to stay stateless.
  147. Each proxy decision reuses one task-local SQLite connection across its storage checks. Standalone
  148. storage calls and concurrent decisions retain independent connection lifecycles.
  149. Reuse requires the owning task and event loop: child tasks and AUTH workers open their own
  150. connections, including tasks and workers whose copied context outlives the original decision.
  151. Operators can bound how many decision rows are kept with `doberman decision-log-prune`. It deletes
  152. only resolved decisions, never pending `AUTH` rows or the append-only policy-change ledger. See the
  153. [CLI reference](docs/CLI.md) for the age and row-budget options.
  154. `doberman log --jsonl` and the dashboard's live feed carry each decision's host session id, so a
  155. companion tool can group decisions by the agent session that made them. A value that does not look
  156. like an id, such as a path, is exported as `null`. The feed also names the agent role and who
  157. resolved an `AUTH` (`auth_path`, `human_confirmed`). A host-hook `AUTH` from Claude Code, Codex or
  158. Cursor can be answered on `doberman dash` too, when the dashboard runs on the folder the host works
  159. in, and its `/api/pending` item carries the same `session_id` (`null` for an MCP-proxy approval).
  160. ---
  161. ## Turn gate
  162. This is a second point where the same decision engine gets consulted: a host hook that runs on the
  163. user's turn (the prompt, plus anything attached, pasted, or fetched by a tool) before the model
  164. starts inferring, generating its response. That means a blatant attack in the turn gets judged
  165. before it costs a single token (a chunk of text the model processes) of inference.
  166. The turn gate is an efficiency and early-warning layer with a deliberately narrow guarantee: no turn
  167. matching a Tier-0 signature (a known, deterministic prompt-injection pattern) reaches the model. The
  168. action gate described above remains the real safety guarantee: an attacker who slips past the turn
  169. gate still has to get past it. Full mechanism, module map, and invariants:
  170. [Turn gate](docs/TURN_GATE.md).
  171. ---
  172. ## Benchmark
  173. A suite-agnostic harness (one that works with more than one benchmark suite) scores Doberman as a
  174. filter over labeled actions, and reports two numbers: the attack bypass rate and the benign
  175. over-block rate, how often something harmless gets flagged anyway. It runs the real decision engine
  176. over each labeled tool call, so the result is deterministic and needs no network access.
  177. A labeled detection corpus turns this into a per-category detection-quality measurement, and CI
  178. gates on any regression. Three more operator-supplied external suites (RedCode-Exec, MSB, and
  179. LLMail-Inject) are wired in the same way, alongside AgentDojo. Commands, methodology, and published
  180. results are in [Benchmarks](docs/BENCHMARKS.md).
  181. ---
  182. ## Write a guardrail plugin
  183. Third-party rules register through the `doberman.rules` entry point (a Python packaging mechanism
  184. that lets one package register a plugin for another to discover, without either importing the other
  185. by name). Core never imports your package by name, and nothing loads until you opt in with
  186. `doberman plugins enable <name>`. A five-minute worked example lives at
  187. [`examples/plugin-guardrail/`](examples/plugin-guardrail/). The same entry-point pattern
  188. (`doberman.audit_sinks`) forwards the redacted audit log to your own pipeline, for example a webhook.
  189. Full walkthrough: [Write a guardrail plugin](docs/PLUGINS.md).
  190. ---
  191. ## Policy as code
  192. Commit a `doberman.policy.yaml` file at the repo root, and its `blocked`/`sensitive` globs (wildcard
  193. file patterns) fold into every action decision alongside the local role. That way, a team reviews
  194. policy changes in the same PR as the code they govern, instead of relying on a teammate's local
  195. `.doberman/` state:
  196. ```yaml
  197. version: 1 # optional; if present must be 1
  198. blocked: ["secrets/**", "*.pem"]
  199. sensitive: ["infra/**"]
  200. ```
  201. This file is raise-only too. If a new version *drops* a glob the last-approved version enforced,
  202. that never silently loosens what's blocked or sensitive. The stricter set stays pinned locally
  203. (`.doberman/policy_file_pin.json`) and stays in force until a human runs `doberman policy-file
  204. --accept`, gated behind the same possession factor (2FA if enrolled, else the local password) as
  205. every other weakening. Running `doberman policy-file` with no flag shows what's currently applied
  206. and what's pending. A file placed under `.doberman/` instead of the repo root is ignored: this is
  207. git-reviewed policy, not local state.
  208. ---
  209. ## Tune to your risk tolerance
  210. Doberman ships with sane defaults, but every dial is yours to move: the strictness `mode`
  211. (Light/Balanced/Strict/Paranoid), the `enforcement` dial (enforce/monitor/off), the opt-in default
  212. `role`, the subjective `prefs` weights, `tune`'s friction telemetry, and `message-tone`. Lowering any
  213. of them requires a possession factor (TOTP if enrolled, otherwise the local Doberman password) and
  214. gets recorded in the append-only policy-change ledger. Raising one is always frictionless. Full
  215. reference: [Tune to your risk tolerance](docs/TUNING.md).
  216. Recovering from sticky taint, re-approving a changed tool, resetting learned memory, or fully
  217. removing a project: see [Recover](docs/RECOVERY.md).
  218. You can also warm a fresh install's baseline (its record of what counts as normal behavior) from
  219. your own already-allowed traces instead of starting cold: `doberman memory seed --from
  220. traces.jsonl` ([format and invariants](docs/BASELINE_SEEDING.md)).
  221. ---
  222. ## Who is this for
  223. - **Developers running AI coding agents** who want autonomous agents without `rm -rf` roulette.
  224. - **Security engineers** evaluating AI agent security, MCP security, LLM tool-use sandboxing, and
  225. zero-trust architectures for agentic AI.
  226. - **Platform teams** deploying agent fleets who need policy enforcement, audit logs, and
  227. human-in-the-loop approval for destructive actions.
  228. ---
  229. ## Roadmap <a name="roadmap"></a>
  230. See [the roadmap](ROADMAP.md) for what's planned and in flight, the
  231. [GitHub board](https://github.com/users/fu351/projects/5) for day-to-day tracking, and
  232. [the changelog](CHANGELOG.md) for what has already shipped.
  233. ---
  234. ## Contributing
  235. Start with [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, CI checks, project invariants, and the
  236. PR workflow.
  237. The Linux Python 3.12 CI leg installs and tests every `examples/plugin-*` package after the
  238. standalone core suite. Example suites stay outside root pytest discovery so core is tested without
  239. the tutorial plugins installed.
  240. CI also runs `python scripts/check_markdown_links.py`, a deterministic offline check for
  241. repository-local Markdown links and heading anchors. It skips external URLs and fenced code blocks
  242. and never makes network requests.
  243. **Come say hi.** Questions, ideas, a rule pack to share, or an attack you caught in the wild?
  244. [**Join the pack on Discord →**](https://discord.gg/Sfy5XGNqty). It's where the roadmap gets shaped.
  245. **Found a vulnerability or a way around a guardrail?** Please report it privately: see
  246. [SECURITY.md](SECURITY.md). Don't open a public issue or Discord post for a security report.
  247. ---
  248. ## License
  249. Apache-2.0. The core is standalone: it has no proprietary dependency, and CI enforces that. Each
  250. [release](https://github.com/DobermanCore/Doberman-Core/releases) also ships a CycloneDX SBOM
  251. (software bill of materials, a full list of a build's dependencies) listing the exact dependency
  252. set. See [SECURITY.md](SECURITY.md#software-bill-of-materials).
  253. ---

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.