hs

🛑 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

🐧 Unix (macOS/Linux) Bash Triggers

• 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

🪟 Windows Bash Triggers

• 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

🔐 Read Tool Triggers (v1.3)

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

---

📋 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:

1. Copy skills/hs/SKILL.md to your Project's knowledge base
2. 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 for edge cases

Secrets in Code Files:

• API keys hardcoded in .py, .js, or other "safe" extensions will NOT be blocked
• Generic config files (config.json, settings.json) trigger warnings but are allowed
• Unusual credential paths not matching known patterns will be allowed

Recommended Practices:

• Never store secrets in code files—use environment variables or secret managers
• Always review commands before execution
• Use /hs skip sparingly and intentionally

---

🔍 Verify Before You Trust

You should never blindly trust any security tool—including this one.

Before installing Hardstop, we encourage you to review the code yourself.

Verify Build Provenance

Every release tarball is signed with Sigstore via GitHub's build provenance attestation. Verify that a package was built from this repo's CI:

gh attestation verify hardstop-*.tgz --repo frmoretto/hardstop

Quick Code Review with GitIngest

1. Get the full codebase in LLM-friendly format: https://gitingest.com/frmoretto/hardstop

2. Copy the output and use this prompt with your preferred LLM: