sunir/bashguard
GitHub: sunir/bashguard
基于 tree-sitter AST 解析的 Bash 命令安全拦截器，为 LLM Agent 沙箱提供结构化裁决和可插拔规则引擎。
Stars: 0 | Forks: 0
# bashguard
用于 LLM agent 沙箱的 Bash 命令安全拦截器。通过 tree-sitter 将命令解析为 AST，运行可插拔的安全规则，并返回结构化裁决 (ALLOW/BLOCK/CONFIRM/REDIRECT)。
## 架构
三阶段流水线 —— 检测与响应正交：
```
bash string → parse() → audit() → decide() → Verdict
[CST] [Findings] [ALLOW/BLOCK/CONFIRM/REDIRECT]
```
## 安装
```
uv pip install -e ".[dev]"
```
## 用法
### Hook 模式 (Claude Code 集成)
```
echo "$CLAUDE_HOOK_INPUT" | bashguard hook
```
### Analyze 模式 (调试)
```
bashguard analyze --command 'git push --force origin main'
```
### 审计日志
```
bashguard log --verdict block --rule network.unknown_host -n 20 --json
bashguard stats --days 7
```
## 规则 (342 个测试，70 个语料库条目)
| 规则 | 检测内容 | ActionType |
|------|---------|------------|
| `parse.error_node` | 格式错误/混淆命令 | OBFUSCATED |
| `credentials.privileged_path` | ~/.ssh, ~/.aws, /etc, .env | CREDENTIAL_ACCESS |
| `network.unknown_host` | curl/wget/nc 到未知主机 | NETWORK_OUTBOUND |
| `network.dev_tcp` | /dev/tcp bash 技巧 | NETWORK_OUTBOUND |
| `destructive.irreversible` | rm -rf, dd, mkfs, shred | FILESYSTEM_DELETE |
| `package_install.global` | brew/apt/npm -g | PACKAGE_INSTALL |
| `git.destructive` | force push, reset --hard, branch -D | GIT_DESTRUCTIVE |
| `paths.protected_write` | 重定向写入到 /etc /usr /sys | SYSTEM_CONFIG |
| `content.secret_in_args` | 参数中的 API keys/PEM/tokens | CREDENTIAL_ACCESS |
| `content.exfiltration_pattern` | 敏感文件通过管道传输到网络 | NETWORK_OUTBOUND |
| `content.outside_boundary` | 访问工作区 (worktree) 外的文件 | FILESYSTEM_READ |
| `self_protection.*` | 试图修改 bashguard 本身 | SYSTEM_CONFIG |
| `comms.*` | email/SMS/webhook 发送 | NETWORK_OUTBOUND |
| 13 条 `evasion.*` 规则 | eval, shell-in-shell, decode pipelines, IFS 等 | OBFUSCATED/ENV_MUTATION |
### Strict 模式 (可选)
仅允许白名单：阻止任何不在安全词汇表中的命令。默认不注册。
```
from bashguard.strict_mode import StrictModeRule
```
## 配置
### `.bashguard.yaml` (项目本地，棘轮机制)
只能收紧策略 (allow→block)，绝不放宽 (block→allow)：
```
policy:
severity:
medium: block
rules:
- rule_id: git.destructive
verdict: block
context:
allowed_hosts:
- internal.corp.com
```
### LLM 后备 (可选)
针对 CONFIRM 裁决的可选 LLM 第二意见：
```
export BASHGUARD_LLM_FALLBACK=1
export BASHGUARD_LLM_KEY=sk-...
```
## Python API
```
from bashguard.auditor import audit
from bashguard.context import make_context
from bashguard.policy import PolicyConfig, decide
ctx = make_context()
findings = audit("rm -rf /", ctx)
verdict = decide(findings, ctx, PolicyConfig.default())
```
## 测试
```
.venv/bin/pytest tests/ -q
```
标签：Agent 安全, AST 抽象语法树, Bash 命令拦截, DevSecOps, DNS 反向解析, Force Push 防护, LLM 安全, Obfuscation Detection, StruQ, TCP/UDP协议, Tree-sitter, UV Python, 上游代理, 代码安全分析, 凭证泄露防护, 命令行审计, 子域名变形, 恶意命令识别, 提示词注入防御, 文件系统保护, 无线安全, 服务器监控, 沙箱隔离, 网络信息收集, 网络安全审计, 网络安全拦截, 逆向工具, 风险检测