camjac251/tool-gates
GitHub: camjac251/tool-gates
一个用 Rust 编写的 AI 编程助手智能权限网关，通过 Bash AST 解析实现精确的命令分析和分级审批，支持 300+ 命令的安全策略控制。
Stars: 2 | Forks: 0
# Tool Gates
*原名 `bash-gates`*
**AI 编程助手的智能工具权限网关**
[](https://github.com/camjac251/tool-gates/actions/workflows/ci.yml)
[](https://github.com/camjac251/tool-gates/actions/workflows/release.yml)
[](https://www.rust-lang.org/)
[](LICENSE)
一个 Claude Code [hook](https://code.claude.com/docs/en/hooks)，利用 AST 解析对 Bash 命令、文件操作和工具调用进行把关——根据潜在影响决定是允许、询问还是阻止。
[安装](#installation) · [权限网关](#permission-gates) · [安全](#security-features) · [测试](#testing)
## 功能
| 功能 | 描述 |
| ------------------------ | ------------------------------------------------------------------------------------------------------ |
| **审批学习** | 跟踪已批准的命令，并通过 TUI 或 CLI 将模式保存到 settings.json |
| **设置集成** | 遵循您的 `settings.json` 允许/拒绝/询问规则 - 不会绕过您的显式权限 |
| **接受编辑模式** | 在 acceptEdits 模式下，自动允许文件编辑命令（`sd`, `prettier --write` 等） |
| **现代 CLI 提示** | 通过 `additionalContext` 建议现代替代工具（`bat`, `rg`, `fd` 等），帮助 Claude 学习 |
| **AST 解析** | 使用 [tree-sitter-bash](https://github.com/tree-sitter/tree-sitter-bash) 进行精确的命令分析 |
| **复合命令** | 正确处理 `&&`, `\|\|`, `\|`, `;` 链 |
| **安全第一** | 捕获管道到 shell、eval、命令注入模式 |
| **未知保护** | 无法识别的命令需要审批 |
| **Claude Code 插件** | 作为插件安装，提供 `/tool-gates:review` 技能用于交互式审批管理 |
| **300+ 命令** | 13 个专用网关，覆盖全面 |
| **文件卫士** | 阻止符号链接的 AI 配置文件（CLAUDE.md, .cursorrules 等），以防止混淆读取/编辑 |
| **工具阻断** | 可配置规则以阻断工具（如 Glob, Grep, firecrawl 在 GitHub 上），支持域名过滤 |
| **配置** | `~/.config/tool-gates/config.toml` 用于功能开关、自定义阻断规则和文件卫士扩展 |
| **快速** | 静态原生二进制文件，无解释器开销 |
## 工作原理
```
flowchart TD
CC[Claude Code] --> CMD[Bash Command]
subgraph PTU [PreToolUse Hook]
direction TB
PTU_CHECK[tool-gates check] --> PTU_DEC{Decision}
PTU_DEC -->|dangerous| PTU_DENY[deny]
PTU_DEC -->|risky| PTU_ASK[ask + track]
PTU_DEC -->|safe| PTU_CTX{Context?}
PTU_CTX -->|main session| PTU_ALLOW[allow ✓]
PTU_CTX -->|subagent| PTU_IGNORED[ignored by Claude]
end
CMD --> PTU
PTU_IGNORED --> INTERNAL[Claude internal checks]
INTERNAL -->|path outside cwd| PR_HOOK
subgraph PR_HOOK [PermissionRequest Hook]
direction TB
PR_CHECK[tool-gates re-check] --> PR_DEC{Decision}
PR_DEC -->|safe| PR_ALLOW[allow ✓]
PR_DEC -->|dangerous| PR_DENY[deny]
PR_DEC -->|risky| PR_PROMPT[show prompt]
end
PTU_ASK --> EXEC[Command Executes]
PR_PROMPT --> USER_APPROVE[User Approves] --> EXEC
subgraph POST [PostToolUse Hook]
direction TB
POST_CHECK[check tracking] --> POST_DEC{Tracked + Success?}
POST_DEC -->|yes| PENDING[add to pending queue]
POST_DEC -->|no| POST_SKIP[skip]
end
EXEC --> POST
PENDING --> REVIEW[tool-gates review]
REVIEW --> SETTINGS[settings.json]
```
**为什么有三个 hook？**
- **PreToolUse**: 为主会话把关命令，跟踪“询问”决策
- **PermissionRequest**: 为子智能体把关命令（PreToolUse 的 `allow` 在此会被忽略）
- **PostToolUse**: 检测成功执行，排队等待永久审批
**决策优先级：** `阻断 > 询问 > 允许 > 跳过`
| 决策 | 效果 |
| :-------: | --------------------------- |
| **拒绝** | 命令被阻断并附带原因 |
| **询问** | 提示用户审批 |
| **允许** | 自动批准 |
### settings.json 集成
tool-gates 读取 `~/.claude/settings.json` 和 `.claude/settings.json`（项目）中的 Claude Code 设置，以遵循您的显式权限规则：
| settings.json | tool-gates | 结果 |
| ------------- | ---------- | -------------------------------------------- |
| `deny` 规则 | (任意) | 延迟至 Claude Code（遵循您的拒绝） |
| `ask` 规则 | (任意) | 延迟至 Claude Code（遵循您的询问） |
| `allow` 规则 | 危险 | **拒绝**（tool-gates 仍会阻断危险操作） |
| `allow`/无 | 安全 | **允许** |
| 无 | 未知 | **询问** |
这确保了 tool-gates 不会意外绕过您的显式拒绝规则，同时仍能防御危险命令。
**设置文件优先级**（最高者胜出）：
| 优先级 | 位置 | 描述 |
| ----------- | ---------------------------------------- | ----------------------------- |
| 1 (最高) | `/etc/claude-code/managed-settings.json` | 企业托管 |
| 2 | `.claude/settings.local.json` | 本地项目（未提交） |
| 3 | `.claude/settings.json` | 共享项目（已提交） |
| 4 (最低) | `~/.claude/settings.json` | 用户设置 |
### 接受编辑模式
当 Claude Code 处于 `acceptEdits` 模式时，tool-gates 自动允许文件编辑命令：
```
# 在 acceptEdits 模式下 - 自动允许
sd 'old' 'new' file.txt # Text replacement
prettier --write src/ # Code formatting
ast-grep -p 'old' -r 'new' -U . # Code refactoring
sed -i 's/foo/bar/g' file.txt # In-place sed
black src/ # Python formatting
eslint --fix src/ # Linting with fix
```
**仍需审批（即使在 acceptEdits 模式下）：**
- 包管理器：`npm install`, `cargo add`
- Git 操作：`git push`, `git commit`
- 删除操作：`rm`, `mv`
- 被阻断的命令：`rm -rf /` 仍会被拒绝
### 现代 CLI 提示
_需要 Claude Code 1.0.20+_
当 Claude 使用旧版命令时，tool-gates 会通过 `additionalContext` 建议现代替代工具。这有助于 Claude 随着时间推移学习更好的模式，而无需修改命令。
```
# Claude 运行：cat README.md
# tool-gates 返回：
{
"hookSpecificOutput": {
"permissionDecision": "allow",
"additionalContext": "Tip: Use 'bat README.md' for syntax highlighting and line numbers (Markdown rendering)"
}
}
```
| 旧版命令 | 现代替代 | 触发时机 |
| ----------------------------- | ------------------ | ------------------------------------ |
| `cat`, `head`, `tail`, `less` | `bat` | 总是（`tail -f` 除外） |
| `grep` (代码模式) | `sg` | AST 感知的代码搜索 |
| `grep` (文本/日志/配置) | `rg` | 任何 grep 用法 |
| `find` | `fd` | 总是 |
| `ls` | `eza` | 带 `-l` 或 `-a` 标志 |
| `sed` | `sd` | 替换模式 (`s/.../.../`) |
| `awk` | `choose` | 字段提取 (`print $`) |
| `du` | `dust` | 总是 |
| `ps` | `procs` | 带 `aux`, `-e`, `-A` 标志 |
| `curl`, `wget` | `xh` | JSON API 或详细模式 |
| `diff` | `delta` | 双文件比较 |
| `xxd`, `hexdump` | `hexyl` | 总是 |
| `cloc` | `tokei` | 总是 |
| `tree` | `eza -T` | 总是 |
| `man` | `tldr` | 总是 |
| `wc -l` | `rg -c` | 行计数 |
**仅建议已安装的工具。** 提示会被缓存（7天 TTL）以避免重复调用 `which`。
```
# 刷新 tool detection 缓存
tool-gates --refresh-tools
# 检查检测到哪些工具
tool-gates --tools-status
```
### 审批学习
当您批准命令（通过 Claude Code 的权限提示）时，tool-gates 会跟踪它们，并允许您将模式永久保存到 settings.json。
```
# 批准部分命令后，查看待批准项
tool-gates pending list
# 交互式 TUI 仪表板
tool-gates review # current project only
tool-gates review --all # all projects
# 或直接通过 CLI 批准
tool-gates approve 'npm install*' -s local
tool-gates approve 'cargo*' -s user
# 管理现有规则
tool-gates rules list
tool-gates rules remove 'pattern' -s local
```
**作用域：**
| 作用域 | 文件 | 用例 |
|-------|------|----------|
| `local` | `.claude/settings.local.json` | 个人项目覆盖（未提交） |
| `user` | `~/.claude/settings.json` | 全局个人使用 |
| `project` | `.claude/settings.json` | 与团队共享 |
**审查 TUI** (`tool-gates review`)：
三面板仪表板 —— 项目侧边栏、命令列表和详情面板。
- **侧边栏**：列出项目及其待处理计数，自动选择当前项目。点击或使用方向键切换。
- **命令列表**：带有颜色编码段（绿色=允许，黄色=询问，红色=阻断）的完整命令。使用空格键多选以进行批量操作。
- **详情面板**：显示段细分、模式（用 左/右 循环）、作用域（用 左/右 循环）和操作按钮。
复合命令（`&&`, `||`, `|`）显示每段模式，以便您可以批准各个部分。
| 按键 | 动作 |
| --- | ------ |
| `Tab` | 切换面板焦点 (侧边栏 -> 命令 -> 详情) |
| `Up`/`Down` 或 `j`/`k` | 在聚焦面板内导航 |
| `Left`/`Right` 或 `h`/`l` | 循环模式或作用域（在详情面板中） |
| `Space` | 切换命令多选 |
| `Enter` | 批准选中的命令 |
| `d` | 跳过（从待处理中移除） |
| `D` | 拒绝（添加到 settings.json 拒绝列表） |
| `q` 或 `Esc` | 退出 |
## 安装
### 下载二进制文件
```
# Linux x64
curl -Lo ~/.local/bin/tool-gates \
https://github.com/camjac251/tool-gates/releases/latest/download/tool-gates-linux-amd64
chmod +x ~/.local/bin/tool-gates
# Linux ARM64
curl -Lo ~/.local/bin/tool-gates \
https://github.com/camjac251/tool-gates/releases/latest/download/tool-gates-linux-arm64
chmod +x ~/.local/bin/tool-gates
# macOS Apple Silicon
curl -Lo ~/.local/bin/tool-gates \
https://github.com/camjac251/tool-gates/releases/latest/download/tool-gates-darwin-arm64
chmod +x ~/.local/bin/tool-gates
# macOS Intel
curl -Lo ~/.local/bin/tool-gates \
https://github.com/camjac251/tool-gates/releases/latest/download/tool-gates-darwin-amd64
chmod +x ~/.local/bin/tool-gates
```
### 从源码构建
```
# 需要 Rust 1.85+
cargo build --release
# Binary: ./target/x86_64-unknown-linux-musl/release/tool-gates
```
### 配置 Claude Code
使用 `hooks` 子命令来配置 Claude Code：
```
# 安装到用户设置（推荐）
tool-gates hooks add -s user
# 安装到项目设置（与团队共享）
tool-gates hooks add -s project
# 安装到本地项目设置（不提交）
tool-gates hooks add -s local
# 预览更改而不写入
tool-gates hooks add -s user --dry-run
# 检查安装状态
tool-gates hooks status
# 输出 hooks JSON 用于手动配置
tool-gates hooks json
```
**作用域：**
| 作用域 | 文件 | 用例 |
|-------|------|----------|
| `user` | `~/.claude/settings.json` | 个人使用（推荐） |
| `project` | `.claude/settings.json` | 与团队共享 |
| `local` | `.claude/settings.local.json` | 个人项目覆盖 |
**三个 hook 均已安装：**
- `PreToolUse` - 为主会话把关命令，跟踪“询问”决策
- `PermissionRequest` - 为子智能体把关命令（PreToolUse 的 allow 在此会被忽略）
- `PostToolUse` - 检测成功执行，排队等待永久审批
手动安装
添加到 `~/.claude/settings.json`： ``` { "hooks": { "PreToolUse": [ { "matcher": "Bash|Read|Write|Edit|MultiEdit|Glob|Grep", "hooks": [ { "type": "command", "command": "~/.local/bin/tool-gates", "timeout": 10 } ] } ], "PermissionRequest": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "~/.local/bin/tool-gates", "timeout": 10 } ] } ], "PostToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "~/.local/bin/tool-gates", "timeout": 10 } ] } ] } } ```标签：AI编程助手, Bash解析, Claude Code, DevSecOps, Homebrew安装, Hook钩子, odt, Python安全, Rust, Tree-sitter, 上游代理, 云安全监控, 代码安全, 可视化界面, 命令过滤, 威胁情报, 开发者工具, 抽象语法树, 文件保护, 权限控制, 沙箱隔离, 漏洞枚举, 终端安全, 网络流量审计, 自动化运维, 通知系统, 静态分析