cc-safety-net

English · 简体中文 · 日本語

CC Safety Net (Coding CLI Safety Net) blocks destructive commands and access to secrets such as SSH keys and .env files before the tool call runs. It parses what the command does. Wrapping the command or reordering flags does not hide it. A broken config file never blocks anything.

[!NOTE] Full documentation → covers installation, configuration, reference material, guides, and the security model. This README is the short version.

Supported coding CLIs

CC Safety Net supports the coding agent CLIs below on Windows, macOS, and Linux. Automated tests cover the analyzer and some Windows integrations. Windows support for the remaining CLIs is best effort and has not been tested.

Amp documents macOS, Linux, and WSL, but not native Windows.

Features

• Blocks destructive commands. git reset --hard, git push --force, rm -rf on dangerous targets, find -delete, and PowerShell Remove-Item. The hook still blocks the same command inside bash -c or python -c. A sandbox still allows git reset --hard inside your project. See vs Sandboxing.

• Blocks secret access. SSH keys, .env files, ~/.aws, and the credential files coding CLIs keep. The rules cover the shell and the agent's read, edit, write, and search tools. Blocking a CLI's own settings files is optional. It stays off until you turn it on.

• Customize the rules in a GUI. Run npx cc-safety-net gui and open Policy. Turn individual block and secret rules off. Add paths to allow or deny. You cannot turn off the rules that catch wiping / or ~.

• Adds blocks through rulebooks. Official packs for Terraform, AWS, gcloud, and Azure, or JSON you write yourself. A rulebook can only add blocks. It cannot turn built-in protection off. The packs live in cc-safety-net/rulebooks. Install a pack with:

  npx -y cc-safety-net rule add --only terraform aws --global
  

  See Official Rulebooks.

• Shares policy through git. Commit .cc-safety-net/ so clones and cloud sessions pick up the same rules. If a project file tries to loosen a member's stricter settings, status and doctor report it. policy apply asks for confirmation in a terminal. Copying the folder is not enough. The hook still has to be installed. See Team Setup and Cloud Environments.

• Embeds in your own tools. Install the npm package and call checkCommand to get allow or deny from your own code. No hook required. See Library API.

Full rule catalogs: Blocked Commands · Allowed Commands · Secret Protection.

Quick start

You need Node.js 18 or higher.

To install into the coding CLIs on this machine, run:

npx -y cc-safety-net@latest install

To update every installed integration:

npx -y cc-safety-net@latest update

Keep the @latest qualifier. A bare cc-safety-net spec can run an older copy from the npx cache. To uninstall, run npx -y cc-safety-net uninstall. npm install -g cc-safety-net also installs the ccsn alias.

Safety presets

To set a preset, run npx cc-safety-net gui and open Policy.

Preset	Effect
Standard	Blocks recognizable destructive Git and filesystem commands. Allows metadata-only checks of built-in sensitive paths while continuing to block content access. Recommended for normal coding.
Strict	Standard, plus blocks dynamic or unparseable commands the analyzer cannot verify safely. Also blocks metadata-only discovery of built-in sensitive paths. Occasional false positives on advanced shell.
Paranoid	Strict, plus blocks rm -rf inside your project and interpreter one-liners. Expect friction; for untrusted agents or high-stakes repos.

Linked-worktree mode relaxes only local discard. See Modes.

Diagnostics

# Summarize what is being enforced right now
npx cc-safety-net status
# Verify your installation and run a self-test
npx cc-safety-net doctor
# Trace how a command is analyzed step-by-step
npx cc-safety-net explain "git reset --hard"
# Browse recorded denials from the audit trail (add --all to include allowed commands)
npx cc-safety-net logs
# Review what was blocked and edit your policy in a local web GUI
npx cc-safety-net gui

doctor, explain, and logs support --json for machine-readable output. The audit trail stays on your machine. It records command decisions, but it does not record command output or prompts.

Details: CLI Commands · Explain Trace · Audit Log · Dashboard · Configuration Recovery.

Limitations

CC Safety Net denies a tool call before it runs. It does not set filesystem permissions, watch network egress, or contain a process.

The policy and secret-path extractors are mostly POSIX. For PowerShell they resolve a home prefix ($HOME, $env:USERPROFILE, $env:HOME, or ~) joined to a literal suffix with \ or /. The same check applies to Get-Content, Set-Content, Add-Content, Copy-Item, Move-Item, Remove-Item, and their aliases. Get-Content $HOME\.ssh\id_rsa is denied. A path built by concatenation, a subexpression, or Join-Path is not.

Policy-file protection matches exact paths. It does not emulate commands. Use OS permissions or a sandbox when you need that.

Codex has one integration-specific limit. Its unified exec path is the default on macOS and Linux. It sends a hook payload when a command starts a session, but it sends none for write_stdin. CC Safety Net can inspect and audit the command that opens the session. It cannot inspect or audit text that the model types into the running session. Codex emits no event for that call, so an adapter change cannot close this gap.

SECURITY.md contains the full residual-risk registry. Known Limitations explains what those risks mean in practice.

Upgrading from an older version

Run the update command from Quick start to upgrade every installed integration to the current release.

If you installed rulebooks from GitHub on version 2.2 or earlier, run npx -y cc-safety-net rule sync once per scope after upgrading. Add --global for user-scope sources. Rulebooks are now live files in your config. The command copies each cached rulebook into that location and removes the leftovers. Until you run it, those GitHub-sourced rules are inactive. status and doctor report the degraded sources.

[!WARNING] If you defined custom rules in a legacy inline config such as .safety-net.json or ~/.cc-safety-net/config.json, CC Safety Net no longer loads those files at runtime. Their rules enforce nothing. Normal use does not show this failure because the commands now run. Run npx -y cc-safety-net rule migrate to convert the rules to the rulebook layout. Then run npx -y cc-safety-net doctor and confirm that the runtime is ready. See the migration guide.

Full documentation

The ccsafetynet.com/docs site contains the full documentation:

Area	Pages
Get started	Introduction · Installation · Quickstart · Team Setup · Cloud Environments · How It Works · Dashboard
Configuration	Modes · Policy · Environment · Custom Rules · Official Rulebooks · Status Line · Configuration Recovery
Reference	Blocked Commands · Allowed Commands · Secret Protection · Audit Log · CLI Commands · Explain Trace · Glossary
Guides	Architecture · Analysis Engine · Design Principles · Security Model · vs Sandboxing · Integration Architecture · Embedding · Known Limitations · Troubleshooting
Project	Contributing · Security Policy

The cc-safety-net skill

The skill is the operating manual for CC Safety Net. Ask it anything about the tool: why a command was blocked, whether a block was wrong, how to write or migrate custom rules, how to change the policy or safety level, how to install or remove an integration, or whether protection is working at all. When the CLI output cannot settle a question, it reads the source of the installed version and answers from that.

/cc-safety-net why was my last git command blocked
/cc-safety-net block terraform destroy in this repo
/cc-safety-net is secret protection active in Codex?

The command ships with the Claude Code and Codex plugins and is built into the OpenCode and Pi integrations. The skill loads only when you invoke it, so it takes no context-window space until you type the command. The agent cannot trigger it on its own.

Library API

To check a command from Node.js without installing the hook:

npm install cc-safety-net

import { checkCommand } from 'cc-safety-net/api';

const result = checkCommand({ command: 'git status', cwd: process.cwd() });
if (result.kind !== 'allow') {
  throw new Error(result.reason);
}

cwd must be an absolute directory path. If checkCommand throws, do not run the command.

A full example is in Embedding.

Development

See CONTRIBUTING.md to contribute to the project.

License

MIT