{
  "markdown": "# ccguard\n\nA security guard written in Zig that stops [Claude Code](https://docs.anthropic.com/en/docs/claude-code) before it runs `rm -rf /`.\n\nNormalizes shell evasion and obfuscation before pattern matching, catching attacks that simple string blocklists miss. Zero external dependencies, single binary.\n\n> Available in [Anthropic's community plugin marketplace](https://github.com/anthropics/claude-plugins-community) — install with `/plugin install ccguard@claude-community`.\n\n![demo](demo/demo.gif)\n\n## Why\n\nAI coding assistants can accidentally run destructive commands, read secrets, or install unwanted packages. Instead of maintaining a massive deny list in `settings.json`, ccguard inspects every tool call as a `PreToolUse` hook and blocks dangerous operations with shell-aware pattern matching.\n\n## Rules\n\n### Bash commands\n\n| Category | Examples | Reason |\n|---|---|---|\n| **Recursive delete** | `rm -rf /`, `rm -rf ~`, `rm -rf src`, `rm -rf $VAR` (allows ephemeral dirs like `node_modules`/`dist`/`build` and `/tmp/...` paths) | Prevent data loss without blocking routine cleanup |\n| **Destructive commands** | `mkfs`, `dd if=`, `shred`, `truncate` | Prevent data loss |\n| **Privilege escalation** | `sudo`, `su -`, `doas`, `pkexec`, `eval`, `exec` | Block unauthorized access |\n| **Git dangerous ops** | `git push --force`, `git reset --hard`, `git clean -f` | Protect git history |\n| **Reverse shells** | `bash -i`, `/dev/tcp/`, `pty.spawn`, `child_process` | Block code injection |\n| **Pipe-to-shell** | `curl \\| bash`, `wget \\| sh`, `cat file \\| zsh` | Block remote code execution |\n| **Secret exfiltration** | `curl` + `.env`, `wget` + `credentials` | Block data exfiltration |\n| **DNS exfiltration** | `dig $(cat .env)`, `nslookup $(...)` | Block DNS-based data theft |\n| **Env variable dumps** | `env`, `printenv`, `export -p` | Prevent secret exposure |\n| **Global installs** | `pip install`, `npm install -g`, `cargo install`, `brew install` | Prevent system modification |\n| **History evasion** | `unset HISTFILE`, `history -c`, `HISTSIZE=0` | Prevent audit trail tampering |\n| **File attribute changes** | `chown`, `chattr`, `xattr` | Block ownership/permission changes |\n| **Shell obfuscation** | `$'\\x72\\x6d'`, `$'\\0150'` | Defeat ANSI-C quoting bypass |\n| **Container escape** | `nsenter -t 1 -m -u -i -p` | Block container breakout |\n| **Docker dangerous ops** | `--privileged`, `-v /:/host` | Block privileged container access |\n| **macOS system commands** | `osascript`, `defaults write`, `diskutil`, `security` | Block system tampering |\n| **/proc sensitive access** | `/proc/self/environ`, `/proc/*/cmdline` | Block process secret access |\n| **Custom package registry** | `pip install --index-url`, `npm --registry` | Block supply chain attacks |\n| **Credential leakage** | `curl` + `AKIA*`, `ghp_*`, `sk-proj-*`, `xoxb-*` | Block API key exfiltration |\n| **Sensitive env var exfiltration** | `curl` + `$OPENAI_API_KEY`, `$AWS_SECRET_ACCESS_KEY` | Block credential exfiltration |\n| **Script sourcing** | `source script.sh`, `. setup.sh` | Block arbitrary script execution |\n| **Git config dangerous keys** | `core.hooksPath`, `core.pager`, `core.editor`, `core.sshCommand` | Block arbitrary code execution via git config |\n| **File upload exfiltration** | `curl -T`, `curl -F`, `curl -d @`, `wget --post-file` | Block file upload to external servers |\n| **Shell script execution** | `bash /tmp/script.sh`, `sh ./evil.sh` | Block download-and-execute attacks |\n| **Redirect to protected paths** | `echo \"evil\" > ~/.bashrc`, `printf > ~/.ssh/config` | Block redirect-based config writes |\n| **Kernel/system commands** | `insmod`, `modprobe`, `mount`, `sysctl`, `iptables` | Block kernel/network manipulation |\n| **Debug/process attach** | `gdb -p`, `strace -p`, `ltrace -p` | Block process inspection and injection |\n\n### File access (Read / Edit / Write)\n\n| Category | Applies to | Examples | Reason |\n|---|---|---|---|\n| **Secret file access** | Read, Edit, Write | `.env`, `.ssh/`, `.aws/`, `*.pem`, `credentials` | Prevent secret leaks |\n| **/proc sensitive access** | Read, Edit, Write | `/proc/self/environ`, `/proc/*/cmdline` | Block process secret access |\n| **Shell config modification** | Edit, Write, NotebookEdit | `.zshrc`, `.bashrc`, `.gitconfig`, `.claude/settings` | Protect shell environment |\n| **IDE/MCP config protection** | Edit, Write, NotebookEdit | `.vscode/settings.json`, `.idea/`, `.code-workspace`, `.cursorrules`, `copilot-instructions.md`, `.kiro/` | Prevent agent trust boundary attacks |\n| **CI/CD pipeline config** | Edit, Write, NotebookEdit | `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `.circleci/`, `terraform.tfstate` | Prevent supply chain attacks via CI/CD |\n| **System path protection** | Edit, Write, NotebookEdit | `/etc/`, `/usr/`, `/System/`, `/Library/LaunchDaemons/` | Protect system files |\n\n## Install\n\n### Anthropic community marketplace (recommended)\n\nccguard is published in [Anthropic's community plugin marketplace](https://github.com/anthropics/claude-plugins-community), where every entry passes Anthropic's automated security screening. Run in Claude Code:\n\n```\n/plugin marketplace add anthropics/claude-plugins-community\n/plugin install ccguard@claude-community\n```\n\n### Direct from this repo (latest version)\n\nThe community marketplace pins each plugin to a reviewed commit, so it may lag slightly behind. To track the latest `main` instead, add this repo as a marketplace directly:\n\n```\n/plugin marketplace add soyukke/ccguard\n/plugin install ccguard@ccguard\n```\n\nEither way, the binary is downloaded automatically on session start. No build tools, no JSON editing.\n\n### Build from source\n\n```bash\ngit clone https://github.com/soyukke/ccguard.git\ncd ccguard\nzig build -Doptimize=ReleaseFast\ncp zig-out/bin/ccguard ~/.local/bin/\n```\n\nThen add to `~/.claude/settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"ccguard\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n#### Requirements (source build only)\n\n- Zig 0.15.2+\n- `~/.local/bin` in your `$PATH`\n\n## How it works\n\n1. Claude Code calls a tool (Bash, Read, Edit, Write, NotebookEdit, MCP tools, etc.)\n2. Before execution, the hook sends JSON to ccguard via stdin:\n   ```json\n   {\"tool_name\": \"Bash\", \"tool_input\": {\"command\": \"rm -rf /\"}}\n   ```\n3. ccguard evaluates rules and responds:\n   - **Allow**: exit 0 + JSON with `\"permissionDecision\": \"allow\"`\n   - **Deny**: exit 2 + JSON with `\"permissionDecision\": \"deny\"`. The `permissionDecisionReason` names what was blocked and appends a standard note telling the agent the block is intentional and not to work around it with an equivalent command\n   - **Ask**: JSON with `\"permissionDecision\": \"ask\"` — Claude Code prompts the user to confirm\n4. Claude Code blocks or allows the tool call accordingly\n\n### Defense techniques\n\n- **Segment-aware matching** — splits chains (`&&`, `||`, `;`, `|`, `$(`, `` ` ``) and skips safe-arg commands (`grep`, `echo`, `git log`, etc.) to prevent false positives\n- **Shell evasion normalization** — `${IFS}`→space, tab→space, quote stripping, brace expansion, backslash-newline removal\n- **Commit message stripping** — removes `-m \"...\"` content before pattern matching\n- **Path normalization** — collapses `//`, `/./`, `/../` to prevent traversal bypass\n- **Symlink resolution** — resolves symlinks via `realpath` before file path checks to prevent TOCTOU bypass\n- **Redirect target extraction** — extracts paths after `>` / `>>` and checks against protected patterns\n- **MCP/unknown tool inspection** — applies Bash and file access checks to unknown tool inputs\n\n## Test\n\n```bash\nzig build test\n\n# Manual test\necho '{\"tool_name\":\"Bash\",\"tool_input\":{\"command\":\"rm -rf /\"}}' | ccguard\n# exit 2: ccguard: dangerous command blocked\n\necho '{\"tool_name\":\"Bash\",\"tool_input\":{\"command\":\"git status\"}}' | ccguard\n# exit 0: allowed\n```\n\n## Development\n\n```bash\n# Dev shell with Zig + ZLS (requires Nix with flakes)\ndirenv allow\n# or\nnix develop\n\n# Build & test\nzig build              # Debug build\nzig build test         # Run all tests\nzig build -Doptimize=ReleaseFast  # Release build\n```\n\nWith [just](https://just.systems/) (optional):\n\n```bash\njust test      # Run tests\njust build     # Debug build\njust release   # Release build\njust install   # Release build + install to ~/.local/bin\njust bench     # Benchmark all rule categories\n```\n\n## References\n\n- Liu, H., Shou, C., Wen, H., Chen, Y., Fang, R. J., & Feng, Y. (2025). *Your Agent Is Mine: Measuring Malicious Intermediary Attacks on the LLM Supply Chain*. arXiv:2604.08407. https://arxiv.org/abs/2604.08407\n  - Supply chain attack defense rules (custom registry detection, credential leakage, sensitive env var exfiltration) are based on findings from this paper.\n- Marzouk, A. (2025). *IDEsaster: A Novel Vulnerability Class in AI IDEs*. https://maccarita.com/posts/idesaster/\n  - IDE config protection rules (`.idea/`, `.code-workspace`, `.cursorrules`, `copilot-instructions.md`, `.kiro/`) are based on CVE-2025-53773, CVE-2025-54130, and related vulnerabilities.\n- Luo, Q., Ye, J., Chen, H., Tan, K., & Hou, B. (2025). *\"Your AI, My Shell\": Demystifying Prompt Injection Attacks on Agentic AI Coding Editors*. arXiv:2509.22040. https://arxiv.org/abs/2509.22040\n  - Validated existing rules against 314 AIShellJack attack payloads covering 70 MITRE ATT&CK techniques.\n- Maloyan, A. (2026). *Prompt Injection Attacks on Agentic Coding Assistants: A Systematic Analysis of Vulnerabilities in Skills, Tools, and Protocol Ecosystems*. arXiv:2601.17548. https://arxiv.org/abs/2601.17548\n  - AI IDE instruction file protection (`copilot-instructions.md`, `.cursorrules`) is informed by this analysis.\n- Ji, Z., Li, Z., Jiang, W., Gao, Y., & Wang, S. (2026). *Measuring the Permission Gate: A Stress-Test Evaluation of Claude Code's Auto Mode*. arXiv:2604.04978. https://arxiv.org/abs/2604.04978\n  - CI/CD pipeline config protection and symlink TOCTOU mitigation are motivated by this paper's finding that 36.8% of state-changing actions bypass the classifier via Edit/Write tools.\n\n## License\n\nMIT\n",
  "bytes": 10217,
  "sha": "3ffcb716918c8602c1497a646575395938d8975850cc7dffcc03f386e0293e7f",
  "repo_slug": "soyukke/ccguard",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_soyukke_ccguard_ccguard_82f77845/readme"
}