🛑 Hardstop

👉 ⭐ Star on GitHub if Hardstop keeps you safe!

Pre-execution safety validation for AI coding agents. Validates every shell command against 428 security patterns before execution — blocking destructive operations, credential theft, infrastructure teardown, and prompt injection. Fail-closed: blocks by default when uncertain.

Ecosystem: The detection patterns are published separately as hardstop-patterns (GitHub) — reusable in any Node.js tool.

Installation • How It Works • Commands • Report Issue

⚡️ Why Hardstop?

You trust your AI, but you shouldn't trust it with rm -rf / or reading your ~/.aws/credentials. Hardstop sits between the LLM and your system, enforcing a strict Fail-Closed policy on dangerous operations.

🛡️ Pattern Matching: Instant regex-based detection for known threats (fork bombs, reverse shells)
🧠 LLM Analysis: Semantic analysis for edge cases and obfuscated attacks
⛓️ Chain Awareness: Scans every link in a command chain (&&, |, ;)
🔐 Secrets Protection: Blocks reading of credential files (.ssh, .aws, .env) (v1.3)
🍎 macOS Coverage: Keychain, diskutil, Time Machine, Gatekeeper, SIP, LaunchDaemons (v1.3.6)
📚 LLM Guidance: Teaches Claude how to think about safety, not just blocks

🚀 Quick Demo

Claude tries to ruin your day? Hardstop says no.

# Claude attempts a home directory deletion
$ rm -rf ~/
🛑 BLOCKED: Deletes home directory

# Claude tries to read your AWS credentials
$ Read ~/.aws/credentials
🛑 BLOCKED: AWS credentials file

# You check the status
$ /hs status
Hardstop v1.4.3
  Status:      🟢 Enabled
  Session Risk: Moderate (35/100)
  Blocked: 2 commands this session

# One-time bypass for a command you trust
$ /hs skip
⏭️  Next command will skip safety check

# Multi-skip: bypass next 3 commands (v1.3.2)
$ /hs skip 3
⏭️  Next 3 commands will skip safety check

# View recent security decisions
$ /hs log
2026-01-20 10:30:45 🛑 [pattern] rm -rf ~/
                     └─ Deletes home directory

⚙️ How It Works

Hardstop uses a two-layer verification system for Bash commands and pattern-based protection for file reads.

graph TD
    A[Tool Call] --> B{Bash or Read?};
    B -- Bash --> C{Layer 1: Patterns};
    C -- Dangerous Pattern --> D[🛑 BLOCK];
    C -- Safe Pattern --> E[✅ ALLOW];
    C -- Unknown --> F{Layer 2: LLM Analysis};
    F -- Risky --> D;
    F -- Safe --> E;
    B -- Read --> G{Credential File?};
    G -- .ssh/.aws/.env --> D;
    G -- Source Code --> E;
    D --> H[Log to Audit];
    E --> I[Execute];

The 428 detection patterns (Layer 1) are published as a standalone npm package: hardstop-patterns — usable in any Node.js tool, not just Hardstop.

🤝 Works Well With

PatchPilot - Package vulnerability scanner that blocks risky npm/pip/brew installations.

| Tool | Focus | What It Protects | |------|-------|------------------| | Hardstop | Command execution safety | Blocks dangerous commands (rm -rf /, credential theft) | | PatchPilot | Package installation security | Blocks packages with known CVEs |

Use both for complete Claude Code security:

# Install PatchPilot (package vulnerability scanning)
npx patchpilot-cli install

# Install Hardstop (command execution safety)
npx hardstop install

Why both? PatchPilot secures your dependencies, Hardstop secures your execution layer. No overlap—they're complementary.

📦 Installation

Option 1: npm (Recommended)

Install with a single command:

npx hardstop install

Or install globally:

npm install -g hardstop
hardstop install

Option 2: Manual Installation

macOS / Linux:

git clone https://github.com/frmoretto/hardstop.git && cd hardstop && ./install.sh

Windows:

git clone https://github.com/frmoretto/hardstop.git
cd hardstop
powershell -ExecutionPolicy Bypass -File install.ps1

Verify Installation

Restart Claude Code / Desktop / Cowork, then:

/hs status

You should see:

Hardstop v1.4.3
  Status:      🟢 Enabled
  Session Risk: Low (0/100)
  262 patterns loaded (MITRE ATT&CK mapped)

Uninstall

macOS / Linux:

cd hardstop && ./uninstall.sh

Windows:

cd hardstop
powershell -ExecutionPolicy Bypass -File uninstall.ps1

The uninstaller removes plugin files, skills, and hooks from settings. State/audit logs are optionally preserved.

🕹️ Controls

Control Hardstop directly from the chat prompt.

| Command | Action | |---------|--------| | /hs on | Enable protection (Default) | | /hs off | Disable temporarily | | /hs skip | Bypass checks for the next command | | /hs skip [n] | Bypass checks for the next n commands (v1.3.2) | | /hs status | Check system health | | /hs log | View recent security decisions |

🛡️ Protection Scope

<details> <summary>🐧 Unix (macOS/Linux) Bash Triggers</summary>

Annihilation: rm -rf ~/, rm -rf /, mkfs, shred
Malware: Fork bombs, Reverse shells (/dev/tcp, nc -e)
Theft: Exfiltration via curl/wget of .ssh, .aws credentials
Trickery: Encoded payloads, Pipe-to-shell (curl | bash)
System damage: chmod 777 /, recursive permission changes
Dangerous sudo: sudo rm -rf /, sudo dd
Cloud CLI: AWS, GCP, Firebase, Kubernetes destructive commands
Database CLI: Redis FLUSHALL, MongoDB dropDatabase, PostgreSQL dropdb

</details> <details> <summary>🪟 Windows Bash Triggers</summary>

Destruction: rd /s /q, format C:, bcdedit /delete
Registry: reg delete HKLM, Persistence via Run keys
Credential theft: mimikatz, cmdkey /list, SAM database access
Download cradles: PowerShell IEX, certutil, bitsadmin, mshta
Encoded payloads: powershell -e <base64>
Privilege escalation: net user /add, net localgroup administrators

</details> <details> <summary>🔐 Read Tool Triggers (v1.3)</summary>

Blocked (Credentials):

SSH keys: ~/.ssh/id_rsa, ~/.ssh/id_ed25519
Cloud credentials: ~/.aws/credentials, ~/.config/gcloud/credentials.db
Environment files: .env, .env.local, .env.production
Docker/Kubernetes: ~/.docker/config.json, ~/.kube/config
Package managers: ~/.npmrc, ~/.pypirc

Allowed (Safe):

Source code: .py, .js, .ts, .go, .rs
Documentation: README.md, CHANGELOG.md, LICENSE
Config templates: .env.example, .env.template

</details>

📋 Audit Logging

All decisions are logged to ~/.hardstop/audit.log in JSON-lines format:

{"timestamp": "2026-01-20T10:30:45", "version": "1.3.0", "command": "rm -rf ~/", "cwd": "/home/user", "verdict": "BLOCK", "reason": "Deletes home directory", "layer": "pattern"}

View recent entries with /hs log.

📁 State Files

| File | Purpose | |------|---------| | ~/.hardstop/state.json | Enabled/disabled state | | ~/.hardstop/skip_next | One-time bypass flag | | ~/.hardstop/audit.log | Decision audit log |

📚 Skill-Only Mode (Claude.ai / Desktop Projects)

For Claude.ai Projects or Claude Desktop without hook support, use the SKILL.md file directly:

Copy skills/hs/SKILL.md to your Project's knowledge base
The skill provides LLM-level safety awareness (soft guardrails, no deterministic blocking)

This is useful for platforms that don't support hooks but can load custom instructions.

Note on SKILL.md Files: The skill files contain imperative LLM instructions ("ALWAYS block", "Your task is to run..."). If you integrate these into a RAG system or multi-tool agent, scope them tightly to the Hardstop safety context only. The directive language is intentional but should not affect unrelated tools.

🆚 Why Hardstop?

| Feature | Hardstop | cc-safety-net | damage-control | Leash | |---------|----------|---------------|----------------|-------| | Fail-closed by default | ✅ | ❌ (opt-in) | ❌ | ❌ | | LLM fallback layer | ✅ | ❌ | ❌ | ❌ | | Windows support | ✅ | ❌ | ❌ | ❌ | | Read tool protection | ✅ | ❌ | ❌ | ❌ | | LLM behavioral skill | ✅ | ❌ | ❌ | ❌ |

⚠️ Known Limitations

Hardstop is a robust safety net, but it is not a guarantee.

Pattern-Based Detection:

Sophisticated obfuscation may bypass regex patterns
The LLM layer provides defense-in-depth

Hardstop

Install / Use

README