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.4.1

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.4.1
File Size Uploaded Provenance Actions
damage_control_dev-0.4.1.tar.gz 277.9 kB With provenance Details for damage_control_dev-0.4.1.tar.gz

Built distribution (wheel)

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

Total release size: 587.8 kB

Release files / damage_control_dev-0.4.1.tar.gz

Download URL damage_control_dev-0.4.1.tar.gz
Size 277.9 kB
Tags Source
SHA-256 checksum
How to use checksums
2f9737cbf985a0cedde08fe8aa1580d7cb06e78bbcfa3215df4c70fe3254b0d7
BLAKE2b-256 checksum
How to use checksums
83a53265846f73ce10b430c318f83169a7ff0cfe59d1aadc2a3081de6a244a29
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 6, 2026.

Transparency log

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

Download URL damage_control_dev-0.4.1-py3-none-any.whl
Size 309.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a41a1bd2dbbef2ea4cf203257128da8df70a0ec18101a7ef0b9f3d8d1528274f
BLAKE2b-256 checksum
How to use checksums
0e376863139cd2ef210e326d7b7c74b2882ccc787c4dc16ff538ef310155a437
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 6, 2026.

Transparency log

Security for damage-control-dev 0.4.1

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.4.1.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 6, 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