hardstop 1.4.0 → 1.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +23 -2
  2. package/install.md +89 -0
  3. package/package.json +19 -3
package/README.md CHANGED
@@ -1,8 +1,29 @@
1
1
  # 🛑 Hardstop
2
2
 
3
- **The Emergency Brake for Claude Code, Claude Desktop & Cowork.**
3
+ 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.
4
4
 
5
- Hardstop is a defense-in-depth safety layer that catches dangerous commands and credential file reads before they execute: even when soft guardrails fail.
5
+ ## 🚀 Quick Start
6
+
7
+ **Install as Claude Code / Cowork plugin:**
8
+ ```bash
9
+ npx hardstop install
10
+ ```
11
+
12
+ Or clone and install manually:
13
+ ```bash
14
+ git clone https://github.com/frmoretto/hardstop.git && cd hardstop && ./install.sh
15
+ ```
16
+
17
+ **Pattern library standalone (npm):**
18
+ ```bash
19
+ npm install hardstop-patterns
20
+ ```
21
+
22
+ ```js
23
+ const { checkBashDangerous } = require('hardstop-patterns');
24
+ const result = checkBashDangerous('rm -rf ~/');
25
+ // { matched: true, pattern: { id: 'DEL-001', message: 'Deletes home directory', ... } }
26
+ ```
6
27
 
7
28
  [![npm version](https://img.shields.io/npm/v/hardstop.svg)](https://www.npmjs.com/package/hardstop)
8
29
  [![Tests](https://github.com/frmoretto/hardstop/workflows/Tests/badge.svg)](https://github.com/frmoretto/hardstop/actions/workflows/test.yml)
package/install.md ADDED
@@ -0,0 +1,89 @@
1
+ # hardstop
2
+
3
+ > Pre-execution safety validation for AI coding agents. Blocks dangerous shell commands before they execute.
4
+
5
+ ## OBJECTIVE
6
+
7
+ Install and activate HardStop as a safety layer for Claude Code, Claude Desktop, or Cowork. HardStop intercepts shell commands via PreToolUse hooks and validates them against 428 security patterns before execution.
8
+
9
+ ## DONE WHEN
10
+
11
+ - Running `/hs status` in Claude Code returns protection status as enabled
12
+ - A test dangerous command like `rm -rf /` triggers a block response from HardStop
13
+ - The hook is registered in `~/.claude/settings.json` (or project-level `.claude/settings.json`)
14
+
15
+ ## TODO
16
+
17
+ - [ ] Install HardStop for your platform
18
+ - [ ] Restart Claude Code / Claude Desktop / Cowork
19
+ - [ ] Verify protection is active
20
+ - [ ] Test that a dangerous command is caught and blocked
21
+
22
+ ## Installation
23
+
24
+ ### Option 1: npm (Recommended)
25
+
26
+ ```bash
27
+ npx hardstop install
28
+ ```
29
+
30
+ Or install globally:
31
+
32
+ ```bash
33
+ npm install -g hardstop
34
+ hardstop install
35
+ ```
36
+
37
+ ### Option 2: Manual — macOS / Linux
38
+
39
+ ```bash
40
+ git clone https://github.com/frmoretto/hardstop.git
41
+ cd hardstop
42
+ chmod +x install.sh
43
+ ./install.sh
44
+ ```
45
+
46
+ ### Option 3: Manual — Windows (PowerShell)
47
+
48
+ ```powershell
49
+ git clone https://github.com/frmoretto/hardstop.git
50
+ cd hardstop
51
+ powershell -ExecutionPolicy Bypass -File install.ps1
52
+ ```
53
+
54
+ ## What the installer does
55
+
56
+ 1. Copies plugin files to `~/.claude/plugins/hs/`
57
+ 2. Creates the `/hs` skill at `~/.claude/skills/hs/`
58
+ 3. Registers PreToolUse and PreRead hooks in `~/.claude/settings.json`
59
+ 4. Does NOT modify any system files or install system-wide packages
60
+
61
+ ## Verification
62
+
63
+ After restarting Claude Code / Desktop / Cowork:
64
+
65
+ ```
66
+ /hs status
67
+ ```
68
+
69
+ Expected: HardStop reports as enabled with pattern count and version.
70
+
71
+ Test with a dangerous command — ask Claude to run `rm -rf /`. HardStop should intercept and block it before execution.
72
+
73
+ ## Troubleshooting
74
+
75
+ - If `/hs status` is not recognized, restart Claude Code completely (VS Code: Cmd+Shift+P > "Developer: Reload Window")
76
+ - Ensure Python 3.9+ is available in PATH
77
+ - Check `~/.claude/settings.json` for hook entries pointing to `~/.claude/plugins/hs/hooks/`
78
+ - Check `~/.claude/plugins/hs/hooks/` contains `pre_tool_use.py` and `pre_read.py`
79
+
80
+ ## Uninstall
81
+
82
+ macOS/Linux: `cd hardstop && ./uninstall.sh`
83
+ Windows: `cd hardstop && powershell -ExecutionPolicy Bypass -File uninstall.ps1`
84
+
85
+ ## More information
86
+
87
+ - Repository: https://github.com/frmoretto/hardstop
88
+ - Pattern library (npm): https://www.npmjs.com/package/hardstop-patterns
89
+ - Issues: https://github.com/frmoretto/hardstop/issues
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hardstop",
3
- "version": "1.4.0",
3
+ "version": "1.4.1",
4
4
  "description": "Pre-execution safety layer for Claude Code - blocks dangerous commands before they run",
5
5
  "keywords": [
6
6
  "claude-code",
@@ -11,7 +11,22 @@
11
11
  "shell-protection",
12
12
  "ai-safety",
13
13
  "mitre-attack",
14
- "risk-scoring"
14
+ "risk-scoring",
15
+ "command-validation",
16
+ "shell-safety",
17
+ "ai-agent-security",
18
+ "bash-guardrail",
19
+ "pre-execution-check",
20
+ "prompt-injection-defense",
21
+ "agentic-safety",
22
+ "claude-code-hooks",
23
+ "llm-command-filter",
24
+ "dangerous-command-detection",
25
+ "supply-chain-security",
26
+ "fail-closed",
27
+ "command-allowlist",
28
+ "command-blocklist",
29
+ "claude-cowork"
15
30
  ],
16
31
  "author": {
17
32
  "name": "Francesco Marinoni Moretto",
@@ -38,7 +53,8 @@
38
53
  "skills/",
39
54
  "LICENSE",
40
55
  "README.md",
41
- "CHANGELOG.md"
56
+ "CHANGELOG.md",
57
+ "install.md"
42
58
  ],
43
59
  "engines": {
44
60
  "node": ">=16.7.0"