Skip to main content

damage-control-dev

A guardrail layer for AI coding agents. It runs as a Claude Code PreToolUse hook and blocks or asks before destructive commands, secret access, protected-path writes and risky MCP calls, before the tool runs.

It is a seatbelt, not a sandbox. See What it is not.

uv tool install damage-control-dev      # or: pipx install damage-control-dev
damage-control-dev init                 # register the hooks, self-test them, record the install
damage-control-dev status               # read-only drift report

Supports Claude Code on macOS and Linux, Python 3.9 or newer. Nothing else is supported or planned.

What it does

  • Guards Bash, Edit, Write, Read and MCP tool calls through one policy ladder (allow, ask, block).
  • Re-scans wrapped commands as commands in their own right: ssh host "...", sh -c, database clients (psql -c, mysql -e), git -c keys that run programs.
  • Reads the script a command runs: bash x.sh, ./x.sh, source x, python3 x.py and a file written then run in one command are judged on the file's text with the same rules as a typed command, and script-looking text written with Write, Edit or NotebookEdit is checked on the way in. The recipes that make, npm run and just run are read the same way, and a recipe the scan cannot resolve is an ask. A seatbelt: it does not cover scripts fetched at run time, task recipes, binaries, or a file that changes after the hook read it. See script indirection.
  • Protects its own control plane: the hook scripts, the settings that register them, and its policy file cannot be edited by the agent it guards.
  • Fails closed: any crash or import failure in the hook exits 2 (block), and init registers the hook with onFailure: block (Claude Code 2.1.295 or newer) so a missing interpreter blocks the call instead of silently allowing it.
  • Unattended mode: when no human can answer a prompt, an ask becomes a block unless a rule carries an explicit grant.
  • Rules ship as groups that are on by default (control-plane, core, git, uv, registry, payloads, remote, mcp-tools, outbound) and opt-in vendor packs: aws, gcp, firebase, cloud-hosting, databases, containers, infrastructure, publish, tmux. Every rule has a frozen, stable id.
  • Offline: after init nothing touches the network.
damage-control-dev check "git push --force origin main"   # what would the hooks decide?
damage-control-dev explain "git push --force origin main"  # how it was judged: words, files read, rules, mode
damage-control-dev rules                                   # list enforced rule ids
damage-control-dev packs                                   # list packs; enabling is human-terminal only
damage-control-dev doctor --fix                            # self-test and repair
damage-control-dev uninstall                               # remove exactly our entries

What it is not

  • Not a sandbox, and not a boundary against a determined adversary. A process running as the same OS user can edit anything this tool can.
  • Only as strong as the harness's hook surface: commands you type yourself with !, tools that have no hook event, and a hook that times out are outside its reach.
  • No network egress filtering, containment or resource limits.
  • Expect false positives and false negatives. The policy is: ask, then learn.

See docs/threat-model.md.

Where things live

Everything the installer keeps is under ~/.damage-control/ (or $DAMAGE_CONTROL_HOME), except the policy file, which is always ~/.damage-control/damagecontrol.yml:

  • damagecontrol.yml: the protected policy (kill switch, packs:, disabled_groups:)
  • damage-control/, tooldefs/: your own rule overlays
  • state/install.json: what init recorded (interpreter, ruleset digest, per-scope write hash); state/backups/ holds first-write backups of your settings file
  • bin/damage-control-breakglass: a stdlib-only script that unregisters the hooks if the Python environment is ever broken
  • logs/damage-control/<date>.jsonl: the audit log, one JSON line per decision

A policy with no packs: key loads the default groups and no vendor packs; an unreadable policy loads everything.

If the environment breaks (for example a uv tool install --force interrupted mid-upgrade) and the hook cannot start, every tool call is blocked by design. Run python3 ~/.damage-control/bin/damage-control-breakglass unregister from a normal terminal, then reinstall and run init again.

Docs

Start at docs/index.md.

Security

A bypass of a shipped rule that the threat model says should be caught is a vulnerability. Report it privately, see SECURITY.md.

License

Apache-2.0. Contributions are signed off under the DCO, see CONTRIBUTING.md.

Metadata

Release files for damage-control-dev 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for damage-control-dev 0.7.0
File Size Uploaded Provenance Actions
damage_control_dev-0.7.0.tar.gz 303.3 kB With provenance Details for damage_control_dev-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for damage-control-dev 0.7.0
File Interpreter ABI Platform Actions
damage_control_dev-0.7.0-py3-none-any.whl Python 3 none any Details for damage_control_dev-0.7.0-py3-none-any.whl

Total release size: 642.4 kB

Release files / damage_control_dev-0.7.0.tar.gz

Download URL damage_control_dev-0.7.0.tar.gz
Size 303.3 kB
Tags Source
SHA-256 checksum
How to use checksums
e0fa4025c14a235e612fae2ab9fa8dcb550b990ec56986bd48ed5333d0aa8200
BLAKE2b-256 checksum
How to use checksums
9f950d57d3d022dbfafdf5622b33678f40dbd5f2a457b1b22d9c64493457d46a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / damage_control_dev-0.7.0-py3-none-any.whl

Download URL damage_control_dev-0.7.0-py3-none-any.whl
Size 339.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3de59084e87c20a28db0ec239f501f98d56859dcc7b83fab8b14fcf065e43de5
BLAKE2b-256 checksum
How to use checksums
53dffe5b0ae9b859535a3944df89d6b89ff8e0829a7720d93009ec85e1334c9a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for damage-control-dev 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for damage_control_dev-0.7.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page