🛡️ ShellShield

Real-time terminal guard for the AI era.
Stops rm -rf /, curl | bash traps, and homograph attacks — before they run.
~23.5 µs latency. Zero config. Local-only.

Get Started • Features • Demo • Performance • Config

---

🧐 Why ShellShield?

We've all been there. A misplaced space in rm -rf / tmp/, a copy‑paste from a malicious site, or a curl | bash that looked safe but used a Cyrillic 'і' instead of a Latin 'i'.

Your browser catches these attacks. Your terminal doesn't. ShellShield does.

ShellShield is a high‑performance, intelligent shell hook that tokenizes every command with a real shell parser to intercept destructive actions, homograph attacks, and terminal injections before they execute.

---

🎬 See It In Action

ShellShield intercepting rm -rf / and blocking a homograph attack before execution.

---

✨ Features

🛡️ Intelligent Destruction Blocking

• Context‑Aware: Uses shell-quote to distinguish rm as a command vs. a string in grep.
• Recursive Analysis: Dives into subshells (sh -c "...") up to 5 levels.
• Smart Suggestions: Blocks rm -rf folder/ and suggests trash folder/.
• Critical Path Guard: Prevents mv, cp, or rm on /etc, /usr, /, C:\Windows.

🔐 Advanced Security Guard

• Interpreter RCE Defense: Blocks python -c "$(curl ...)", node -e, ruby -e, perl, php.
• Homograph Defense: Catches visually identical malicious domains (іnstall.com).
• Injection Protection: Blocks ANSI escapes and zero‑width characters.
• Safe Pipe‑to‑Shell: Flags curl | bash unless domain is trusted.
• Encoded Payload Guard: Blocks base64 -d | sh and xxd -r -p | sh.
• Credential Guard: Detects plain‑text passwords in URLs.

🚜 Terminal Governance

• Git Workflow Safety: Prevents deleting files with uncommitted changes.
• Volume Threshold: Intercepts accidental globs that target too many files.
• Permissive Mode: Log‑only mode for audits and CI.
• Rotated Audit Log: JSON trace in ~/.shellshield/audit.log (auto‑rotated at 1MB).

---

⚡ Performance

• 42,573 ops/sec benchmark throughput
• ~23.5µs latency per command (imperceptible to humans)
• 117 tests covering bypasses, edge cases, and advanced attacks

---

🔎 Why Trust This?

• Local-only execution: runs as a shell hook on your machine.
• No daemon required: checks happen at command time.
• Transparent audit log: records decisions to ~/.shellshield/audit.log.
• Open ruleset: all detection logic lives in src/parser/rules/.
• Extensive tests: security and bypass cases covered in tests/.
• ReDoS Protection: All regex patterns use bounded quantifiers and input validation to prevent catastrophic backtracking attacks.

---

🔐 Security

If you believe you have found a security issue, please report it privately. Preferred: open a GitHub Security Advisory with clear reproduction steps and impact. If private reporting is not possible, open a GitHub issue without exploit details.

Regular Expression Safety (ReDoS Protection)

ShellShield uses regex patterns for threat detection. To prevent Regular Expression Denial of Service (ReDoS) attacks:

• Input length limits: All regex operations are limited to 10,000 character inputs
• Bounded quantifiers: Patterns use {0,10} instead of * or + where possible
• Character class negation: Uses [^|]* instead of .* to prevent backtracking
• Lazy quantifiers: Uses .*? instead of .* where unbounded matching is necessary
• Performance testing: All patterns are tested against malicious inputs

See src/security/patterns.ts for implementation details and tests/regex_security.test.ts for security test cases.

---

🆚 Why Not Just Use alias rm='rm -i'?

Feature	ShellShield	Basic Aliases	shellcheck
Context‑aware parsing	✅	❌	⚠️ (static)
Homograph detection	✅	❌	❌
Subshell recursion	✅	❌	❌
Zero config needed	✅	❌	❌
AI agent safe	✅	❌	❌
Performance	42.6k ops/sec	N/A	~10k ops/sec

---

🚀 Quick Start

Secure Install (recommended)

1. Download the installer

curl -fsSL https://hevlyo.github.io/ShellShield/install.sh -o /tmp/shellshield-install.sh

2. Verify integrity

echo "c92fe9ac968e5e7c421130b50981c4bdd715b51117390e936e1d122a82c00e3c  /tmp/shellshield-install.sh" | sha256sum --check

3. Run only if OK

SHELLSHIELD_INSTALL_SHA256="c92fe9ac968e5e7c421130b50981c4bdd715b51117390e936e1d122a82c00e3c" \
  bash /tmp/shellshield-install.sh

That’s it. ShellShield is now guarding your terminal.

SHA256 (install.sh): c92fe9ac968e5e7c421130b50981c4bdd715b51117390e936e1d122a82c00e3c

GPG verification (optional):

curl -fsSL https://hevlyo.github.io/ShellShield/install.sh.asc -o /tmp/shellshield-install.sh.asc
gpg --keyserver keys.openpgp.org --recv-keys 744857708F52A3F4885EDA5CF38DA114834A9FA0
gpg --verify /tmp/shellshield-install.sh.asc /tmp/shellshield-install.sh

Try:

rm -rf /tmp/test

Manual Install (no curl)

git clone https://github.com/hevlyo/ShellShield
cd ShellShield
bun install
bun run src/index.ts --init

Install via npm (local checkout)

npm i -g .
shellshield --init

Install via npm registry

When the published package exposes the shellshield binary:

npm i -g @shellshield/shellshield
shellshield --init

Shell Integration

Run:

shellshield --init

Choose your protection mode (recommended after install):

shellshield --select-mode

Paste the output into your shell profile. Supported shells: bash, zsh, fish, PowerShell (PSReadLine). The installer auto-wires bash/zsh/fish profiles by default.

Common profile locations:

• bash: ~/.bashrc
• zsh: ~/.zshrc
• fish: ~/.config/fish/config.fish
• PowerShell: $PROFILE

Optional: zsh bracketed paste hook (auto-checks pasted blocks):

export SHELLSHIELD_PASTE_HOOK=1

Paste Mode (Clipboard Safety)

Paste mode checks multi-line paste buffers before execution:

shellshield --paste

Examples:

• macOS: pbpaste | shellshield --paste
• Linux (xclip): xclip -o -selection clipboard | shellshield --paste
• PowerShell: Get-Clipboard | shellshield --paste

URL Risk Score

Score potentially risky URLs:

shellshield --score https://example.com/install.sh

JSON output:

shellshield --score https://example.com/install.sh --json

Safe Remote Runner

Safer replacement for curl | bash: download, inspect, score, and confirm.

shellshield --run https://example.com/install.sh

Useful flags:

• --dry-run: review only, do not execute
• --yes: execute without interactive confirmation
• --force: allow execution in enforce mode even with risky findings

shellshield --run https://example.com/install.sh --dry-run

Explain Last Block/Warning

Inspect the latest audit entry that triggered a rule:

shellshield --why

Execution Receipt

Show the latest shellshield --run audit receipt:

shellshield --receipt

List recent receipts:

shellshield --receipt --list --count 10

More Ways To Run

If your installed package version includes the shellshield binary:

• bunx: bunx @shellshield/shellshield --init
• npx: npx @shellshield/shellshield --init
• pnpm: pnpm dlx @shellshield/shellshield --init
• Standalone binary (local build): bun run build -> dist/shellshield

Uninstall

Remove the hook line from your shell config (~/.zshrc or ~/.bashrc) and restart your shell. Then delete local data:

rm -rf ~/.shellshield

📦 Manual Install

curl -fsSL https://bun.sh/install | bash
git clone https://github.com/hevlyo/ShellShield
cd ShellShield
bun install
bun run src/index.ts --init

---

👥 Who Is Using It?

Early adopters are welcome. Want your team listed here? Open a PR or issue with your logo/name.

---

🧭 Roadmap

See ROADMAP.md for public priorities and upcoming work.

---

⚙️ Configuration

ShellShield works out of the box. Create .shellshield.json to customize:

{
  "blocked": ["rm", "shred", "custom-killer"],
  "allowed": ["ls", "cat"],
  "trustedDomains": ["github.com", "my-company.com"],
  "threshold": 100,
  "mode": "enforce",
  "maxSubshellDepth": 5,
  "contextPath": "~/.shellshield/shell-context.json"
}

Modes

• enforce (default): blocks dangerous commands
• permissive: logs warnings but allows execution
• interactive: prompts for confirmation

Set or inspect mode from CLI:

shellshield --mode
shellshield --mode enforce
shellshield --mode interactive
shellshield --mode permissive
shellshield --select-mode

Mode	What it does	When to use
enforce	Blocks dangerous commands	Daily use
permissive	Logs only	First days / CI
interactive	Prompts for confirmation	When AI-generated commands are uncertain

Environment Variables

• SHELLSHIELD_THRESHOLD: max files per delete (default: 50)
• SHELLSHIELD_MODE: set permissive or interactive
• SHELLSHIELD_SKIP: bypass checks for next command (values: 1, true, yes, on, enable, enabled)
• SHELLSHIELD_MAX_SUBSHELL_DEPTH: max nested sh -c analysis depth (default: 5)
• Recommended: keep between 3 and 6 for low overhead; raise only if you rely on deep nested shells.

Bypass Examples

# All of these work:
SHELLSHIELD_SKIP=1 rm -rf /tmp/test
SHELLSHIELD_SKIP=true rm -rf /tmp/test
SHELLSHIELD_SKIP=yes rm -rf /tmp/test
SHELLSHIELD_SKIP=on rm -rf /tmp/test
SHELLSHIELD_SKIP=enable rm -rf /tmp/test
SHELLSHIELD_SKIP=enabled rm -rf /tmp/test

# Or set globally (not recommended for daily use):
export SHELLSHIELD_SKIP=1
rm -rf /tmp/test

Shell Context (Aliases / Functions)

ShellShield analyzes the raw command string. Your shell aliases/functions are not automatically expanded.

Optional safety check (recommended if you use lots of aliases):

# Generate a snapshot of `type <cmd>` for common commands
bun run src/index.ts --snapshot

# Enable checks (blocks if a seemingly-safe command resolves to an alias/function
# that references a blocked primitive like rm/shred)
export SHELLSHIELD_CONTEXT_PATH="$HOME/.shellshield/shell-context.json"

# Optional: auto-refresh snapshot when your shell loads the hook
export SHELLSHIELD_AUTO_SNAPSHOT=1

You can also inspect your current shell resolution with:

bun run src/index.ts --doctor

Examples

For AI coding assistants

{ "mode": "interactive", "trustedDomains": ["github.com", "githubusercontent.com"] }

For CI/CD pipelines

{ "mode": "permissive", "threshold": 1000 }

For junior onboarding

{ "mode": "enforce", "blocked": ["rm", "mv", "dd", "shred"] }

---

🤝 Contributing

Want to add a new security rule? It’s fast:

1. Create a class in src/parser/rules/ implementing SecurityRule
2. Add TSDoc explaining the threat
3. Write tests in tests/
4. Run bun test and bun run benchmark.ts

---

🙏 Acknowledgments

• claude-rm-rf by Zach Caceres — original inspiration for the project
• Tirith by @sheeki03 — inspiration for curl | bash protection after seeing their X post; great work on supply chain security

---

🚀 Ready to Protect Your Terminal?

⭐ Star this repo if ShellShield saved you from a disaster.

🛡️ Built for those who roll the boulder every day. Ship safe.