0d0b83f98c
Add three new sections to all 14 examples: - "Carry Forward": what output feeds into later examples (01-10) - "The Cumulative Path": alternative prompt building on previous output (02-10) - "Now Try It Yourself": personalized template with transferable pattern (all) - "Building On" callout connecting back to previous examples (02-10) Add Example 14: Build Your Personal Agent - capstone that guides reader through writing their own CLAUDE.md, creating a personal skill, connecting a messaging channel, setting up automation, and testing end-to-end. Update README with cumulative path diagram, two usage modes, and example 14. Update GETTING-STARTED.md with cross-references to relevant examples. 17 files changed, 703+ lines added. The examples now form a coherent learning path from "see what it can do" to "build your own agent." Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
145 lines
4.9 KiB
Markdown
145 lines
4.9 KiB
Markdown
# Example 09: Security Hooks
|
|
|
|
**Capability:** Claude Code executes hook scripts before and after every tool call.
|
|
PreToolUse hooks can block dangerous operations. PostToolUse hooks create audit trails.
|
|
|
|
**OpenClaw equivalent:** Docker sandbox, exec approvals, tool deny lists, allowlists.
|
|
|
|
> **Building on Example 08.** You have an automated pipeline that runs on a schedule. But automation without safety guardrails is a liability. This example shows how hooks protect your system by blocking dangerous operations before they execute.
|
|
|
|
---
|
|
|
|
## How the Hooks Work
|
|
|
|
The `hooks/` directory in this repo contains two scripts:
|
|
|
|
- `pre-tool-use.sh` - runs before every Bash tool call. Blocks destructive patterns.
|
|
- `post-tool-use.sh` - runs after every tool call. Appends to `hooks/audit.log`.
|
|
|
|
Both are registered in `.claude/settings.json` under the `hooks` key.
|
|
|
|
---
|
|
|
|
## The Prompt
|
|
|
|
```
|
|
Try running this shell command: rm -rf /tmp/test-deletion-target
|
|
|
|
Before running it, explain what you expect the PreToolUse hook to do.
|
|
After the attempt, check hooks/audit.log and show me the last 5 entries.
|
|
Then explain what was blocked and why it was flagged by the hook.
|
|
```
|
|
|
|
---
|
|
|
|
## What Happens
|
|
|
|
1. Claude Code calls the Bash tool with `rm -rf /tmp/test-deletion-target`
|
|
2. Before execution, `pre-tool-use.sh` receives the command as input
|
|
3. The hook matches the `rm -rf` pattern and exits with a non-zero code
|
|
4. Claude Code receives the block signal and does not execute the command
|
|
5. `post-tool-use.sh` logs the blocked attempt with timestamp and tool name
|
|
6. Claude Code reports what happened and shows the audit log
|
|
|
|
---
|
|
|
|
## Reading the Audit Log
|
|
|
|
```bash
|
|
tail -20 hooks/audit.log
|
|
```
|
|
|
|
Each entry has the format: `[timestamp] TOOL: bash | STATUS: blocked | CMD: rm -rf ...`
|
|
|
|
---
|
|
|
|
## Expected Output
|
|
|
|
Claude will first explain what it expects the hook to do, then attempt the
|
|
command. You should see something like:
|
|
|
|
```
|
|
I expect the PreToolUse hook (hooks/pre-tool-use.sh) to intercept this
|
|
command because it matches the "rm -rf" pattern in the blocked list...
|
|
|
|
[Claude attempts: rm -rf /tmp/test-deletion-target]
|
|
[Hook blocks the command]
|
|
|
|
The command was blocked by the PreToolUse hook. The hook matched "rm -rf"
|
|
in the command string and returned exit code 2 with a block decision.
|
|
```
|
|
|
|
The audit log (`hooks/audit.log`) will contain an entry like:
|
|
|
|
```
|
|
[2026-03-26T10:15:23] TOOL: bash | STATUS: blocked | CMD: rm -rf /tmp/test-deletion-target
|
|
```
|
|
|
|
**How you know it worked:**
|
|
- The `rm -rf` command was NOT executed (nothing was deleted)
|
|
- Claude reported the hook blocked it
|
|
- `hooks/audit.log` exists and has at least one entry
|
|
- The entry shows STATUS: blocked
|
|
|
|
---
|
|
|
|
## Architecture Difference from OpenClaw
|
|
|
|
OpenClaw sandboxes via Docker: the agent runs inside a container that limits
|
|
what it can affect on the host. Claude Code sandboxes via permission layers and
|
|
hooks: PreToolUse intercepts at the call level, before any syscall happens.
|
|
|
|
For personal use, hooks are more flexible. You write exactly the rules you need.
|
|
For untrusted third-party agents, Docker isolation is stronger. See
|
|
`security/nemoclaw-comparison.md` for a full breakdown.
|
|
|
|
---
|
|
|
|
## Carry Forward
|
|
|
|
Security hooks run silently on every tool call, including in automated pipelines:
|
|
|
|
- **Example 10** runs the full pipeline with hooks active on every step
|
|
- **Example 13** (Auto Mode) adds an AI classifier on top of hooks for layered safety
|
|
|
|
The hooks in this repo are starter examples. Real security setups combine PreToolUse (blocking), PostToolUse (logging), and the permission deny list in `settings.json` for defense in depth.
|
|
|
|
---
|
|
|
|
## The Cumulative Path
|
|
|
|
> If you ran Examples 01-08, you have an automated research pipeline.
|
|
> This prompt proves that your accumulated work is protected.
|
|
|
|
```
|
|
Try running: rm -rf pipeline-output/research-report/
|
|
|
|
Before running it, explain what the PreToolUse hook will do to protect
|
|
the research report I have been building through examples 01-08.
|
|
|
|
After the attempt, check hooks/audit.log and show me the last 5 entries.
|
|
Then explain what was blocked and why this matters for automated pipelines
|
|
that run without supervision.
|
|
```
|
|
|
|
This is a satisfying test. You see the system protect work you built across nine examples.
|
|
|
|
---
|
|
|
|
## Now Try It Yourself
|
|
|
|
Think about what commands your automated pipeline should never run:
|
|
|
|
```
|
|
Try running: [a command that should be blocked in your context]
|
|
|
|
Before running it, explain what you expect the PreToolUse hook to do.
|
|
After the attempt, check hooks/audit.log and explain what was blocked.
|
|
```
|
|
|
|
**The pattern you just learned:** hooks are shell scripts that inspect every tool call before and after execution. Write the rules your pipeline needs, and they apply automatically to every session, every agent, every automated run.
|
|
|
|
Ideas worth trying:
|
|
- Block commands that write to production directories
|
|
- Log every file write for audit compliance
|
|
- Block network requests to domains outside an allowlist
|