hideosugimoto/claude-settings-guard

# claude-settings-guard (csg) [](https://www.npmjs.com/package/claude-settings-guard) [](https://nodejs.org) [](LICENSE) []() [日本語](#日本語) | [English](#english) ## 日本語 Claude Code 的 `settings.json` 权限设置诊断、修复与增强 CLI 工具。 ### 快速开始 ``` npx claude-settings-guard ``` 只需执行此命令即可启动交互式指南，自动执行以下操作： 1. 设置诊断（检测旧版语法、结构问题、冲突） 2. 迁移（旧版语法到现代语法的批量转换） 3. 遥测分析（基于使用模式的推荐） 4. 配置文件选择（minimal / balanced / strict） 5. 双重防御设置（deny 规则 + 强制 hook） 在 CI 或自动化环境中，可以使用 `-y` 标志进行非交互式运行： ``` npx claude-settings-guard -y ``` ### 解决的问题 | 症状 | 原因 | csg 的解决方案 | |------|------|-------------| | 即使添加到 `allowedTools`，每次仍需请求许可 | 使用旧版语法 `Bash(npm:*)` | 通过 `csg migrate` 自动转换为 `Bash(npm *)` | | 设置为 `deny` 后有时仍无法阻止 | Claude Code 内部的模式匹配 bug | 通过 Layer 2 hook 实现双重防御 | | 每次都需要按 Yes，非常繁琐 | 常用工具未注册到 allow | 通过 `csg recommend` 提供基于遥测的推荐 | | 设置结构陈旧 | 需要从顶层迁移到 `permissions.*` | 通过 `csg migrate` 自动转换整个结构 | | `.env` 或机密文件被读取的风险 | deny 设置不充分 | 通过配置文件批量应用推荐的 deny 规则 | | 通过 `curl ... \| sh` 绕过 deny | 复合命令解析不足 | Layer 2 hook 会分解 `&&`, `\|\|`, `\|`, `$()` 并逐一检查 | ### 架构：双重防御系统 ``` ツール実行リクエスト | Layer 1: settings.json (Claude Code 内部) permissions.allow --> 確認なし許可 permissions.deny --> ブロック | (バグで通過した場合) Layer 2: PreToolUse Hook (独立した番犬) bash 正規表現で deny ルールを再チェック 複合コマンド (&&, ||, |, $(), <()) も分解して個別検査 --> 一致すれば exit 2 で強制ブロック ``` ### 设置层级 csg 会合并 3 个层级的设置文件并进行诊断： | 层级 | 路径 | 用途 | |---------|------|------| | 全局 | `~/.claude/settings.json` | 用户整体的基本设置 | | 本地 | `~/.claude/settings.local.json` | 特定机器的覆盖设置（git 管理范围外） | | 项目 | `.claude/settings.json` | 特定项目的设置 | ### 安装步骤 #### 方法 1：交互式指南（推荐） 最简单的方法。按顺序引导 5 个步骤。 ``` npx claude-settings-guard ``` 向导将依次执行以下操作： ``` Step 1/5: 診断 → 現在の設定の問題を検出 Step 2/5: 移行 → レガシー構文があれば自動変換 Step 3/5: 推薦 → テレメトリに基づく設定提案 Step 4/5: プロファイル → セキュリティレベルを選択 Step 5/5: セットアップ → deny ルール・フック・スラッシュコマンドを配置 ``` #### 方法 2：一行命令（非交互） 使用默认设置（balanced 配置文件）批量应用： ``` npx claude-settings-guard -y ``` #### 方法 3：指定配置文件初始化 ``` # balanced プロファイル（推奨デフォルト） npx claude-settings-guard init --profile balanced # セキュリティ重視 npx claude-settings-guard init --profile strict # 速度重視・最小制限 npx claude-settings-guard init --profile minimal ``` #### 方法 4：全局安装 适用于频繁使用的情况： ``` npm install -g claude-settings-guard csg # 対話型ガイド csg init --profile strict # プロファイル指定 ``` #### 安装后部署的文件 ``` ~/.claude/ ├── settings.json ← deny/allow/ask ルールが追加される ├── backups/ ← 設定変更前の自動バックアップ ├── hooks/ │ ├── enforce-permissions.sh ← Layer 2 強制フック │ └── session-diagnose.sh ← 起動時自動診断 (strict のみ) └── commands/ ├── csg.md ← /csg スラッシュコマンド ├── csg-diagnose.md ← /csg-diagnose └── csg-enforce.md ← /csg-enforce ``` #### 安装后验证 ``` # 設定に問題がないか確認 csg diagnose # 预览 hook 脚本 csg enforce --dry-run # Claude Code 内でスラッシュコマンドを使用 # /csg → 設定サマリー # /csg-diagnose → 詳細診断 # /csg-enforce → フック更新 ``` ### 配置文件 可以从 3 个预设中选择。每个配置文件都包含基本的 deny 规则（sudo, rm -rf, .env, secrets）。 #### minimal（优先速度） 几乎自动允许所有工具。适合希望最小化确认提示的用户。 | 设置 | 内容 | |------|------| | deny | `Bash(sudo *)`, `Bash(rm -rf /*)` | | allow | `Read`, `Edit`, `Write`, `Bash`, `Glob`, `Grep` | | ask | 无 | | hook | 仅 enforce-permissions | #### balanced（推荐默认值） 读取操作自动允许，写入和执行需要确认。适合大多数用户的平衡设置。 | 设置 | 内容 | |------|------| | deny | `Bash(sudo *)`, `Bash(rm -rf /*)`, `Read(**/.env)`, `Read(**/secrets/**)` | | allow | `Read`, `Glob`, `Grep` | | ask | `Bash`, `Edit`, `Write` | | hook | 仅 enforce-permissions | #### strict（优先安全） 也阻止网络命令。适合安全优先的环境。 | 设置 | 内容 | |------|------| | deny | 以上所有 + `Bash(curl *)`, `Bash(wget *)`, `Write(**/.env)` | | allow | `Read`, `Glob`, `Grep` | | ask | `Bash`, `Edit`, `Write` | | hook | enforce-permissions + 启动时自动诊断 | ### 命令列表 | 命令 | 说明 | |---------|------| | `csg` / `csg setup` | 交互式指南设置（默认） | | `csg diagnose [--json] [--quiet]` | 诊断 settings.json 并检测问题 | | `csg migrate [--dry-run]` | 将旧版语法批量转换为现代语法 | | `csg recommend [-y\|--yes]` | 分析遥测数据，推荐并自动应用权限设置 | | `csg enforce [--dry-run]` | 生成并注册 deny 规则的强制 hook (PreToolUse) | | `csg init [--profile NAME] [--force]` | 首次设置：部署斜杠命令、配置文件和 hook | | `csg mcp` | 作为 MCP 服务器启动（Claude Code 集成） | #### 退出代码 | 代码 | 条件 | |--------|------| | `0` | 无问题，或仅有 INFO 级别的问题 | | `1` | 检测到 CRITICAL 或 WARNING 级别的问题（使用 `--json` 时） | 可在 CI/CD 中用于设置质量门控： ``` # CI パイプラインで設定の健全性をチェック npx claude-settings-guard diagnose --json --quiet || echo "Settings issues detected" ``` ### 诊断检测的问题 | 代码 | 严重程度 | 内容 | |--------|--------|------| | `LEGACY_SYNTAX` | CRITICAL | 使用冒号语法 `Tool(arg:*)` | | `STRUCTURE_ISSUE` | WARNING | 顶层的 `deny`/`allowedTools` | | `INVALID_TOOL` | WARNING | 未知工具名 | | `CONFLICT` | WARNING | allow 和 deny 之间的冲突 | | `INVALID_PATTERN` | WARNING | 模式语法错误 | | `PIPE_VULNERABLE` | INFO | 可能通过管道绕过 → 由 Layer 2 处理 | ### 遥测推荐 `csg recommend` 会分析 `~/.claude/telemetry/` 中的事件，并按以下标准进行推荐： | 推荐 | 条件 | |------|------| | 添加到 allow | 同一工具被手动许可 3 次以上 | | 添加到 deny | 同一工具被拒绝 2 次以上 | #### 模式分组 当具有相同前缀的命令达到 3 个或更多时，会将其分组为通配符模式进行推荐： ``` Bash(npm install lodash) ─┐ Bash(npm install express) ─┼→ Bash(npm install *) を allow に追加 Bash(npm install chalk) ─┘ ``` 对于 `npm`, `git`, `cargo`, `pip` 等包管理器/VCS 命令，使用 2 个 token（如 `npm install`）进行分组，其他命令使用 1 个 token（如 `ls`）进行分组。 #### 自动应用 显示推荐后，可以交互式地确认是否应用。使用 `--yes` 标志可跳过确认： ``` csg recommend # 推薦を表示 → 「適用しますか？ [Y/n]」 csg recommend --yes # 確認なしで自動適用 ``` 如果应用时添加了 deny 规则，Layer 2 强制 hook 将自动重新生成。 ### MCP 服务器集成 可以直接从 Claude Code 检查和改进设置。 ``` // ~/.claude.json に追加 { "mcpServers": { "csg": { "command": "npx", "args": ["claude-settings-guard", "mcp"] } } } ``` 可用的 MCP 工具： | 工具 | 参数 | 说明 | |--------|------|------| | `csg_diagnose` | 无 | 诊断设置并返回问题 | | `csg_recommend` | `profile?` | 基于配置文件的改进建议 | | `csg_enforce` | `dryRun?` | 生成和更新 Layer 2 hook（支持 dry-run） | | `csg_setup` | `profile?` | 配置文件应用指南 | ### 开发 ``` git clone https://github.com/hideosugimoto/claude-settings-guard.git cd claude-settings-guard npm install npm run build # ビルド npm test # テスト実行 (19 files, 356 tests) npx tsx src/index.ts # ローカル実行 ``` #### 项目结构 ``` src/ ├── index.ts # CLI エントリポイント ├── commands/ # 各サブコマンドの実装 │ ├── setup.ts # 5ステップ対話型ウィザード │ ├── diagnose.ts # 診断 │ ├── migrate.ts # マイグレーション │ ├── recommend.ts # テレメトリ推薦 │ ├── enforce.ts # フック生成 │ ├── init.ts # 初期化 │ └── deploy-slash.ts # スラッシュコマンド配置 ├── core/ # コアロジック │ ├── settings-reader.ts # 3層設定読み込み・マージ │ ├── settings-writer.ts # 設定書き込み（自動バックアップ付き） │ ├── pattern-validator.ts # パターン検証 │ ├── pattern-migrator.ts # 構文・構造マイグレーション │ ├── hook-generator.ts # 強制フック生成 │ ├── hook-regenerator.ts # フック再生成の共通ロジック │ ├── hook-script-builder.ts # シェルスクリプト構築 │ ├── pattern-grouper.ts # コマンドプレフィックスのグルーピング │ ├── recommendation-applier.ts # 推薦の自動適用 │ ├── session-hook.ts # セッション起動時フック │ ├── telemetry-analyzer.ts # テレメトリ分析 │ └── mcp-protocol.ts # JSON-RPC 2.0 フレーミング ├── mcp-server.ts # MCP サーバー ├── profiles/ # プロファイル定義 ├── types.ts # Zod スキーマ・型定義 └── constants.ts # 定数・既知ツール一覧 ``` ## English 用于诊断、修复和增强 Claude Code `settings.json` 权限配置的 CLI 工具。 ### 快速开始 ``` npx claude-settings-guard ``` 此命令会启动交互式指南，自动执行以下操作： 1. 诊断设置（检测旧版语法、结构问题、冲突） 2. 迁移模式（从旧版语法批量转换为现代语法） 3. 分析遥测数据（基于使用模式的推荐） 4. 选择配置文件（minimal / balanced / strict） 5. 设置双层防御（deny 规则 + 强制 hook） 对于 CI 或自动化环境，使用 `-y` 标志进行非交互式运行： ``` npx claude-settings-guard -y ``` ### 解决的问题 | 症状 | 根本原因 | csg 解决方案 | |---------|-----------|--------------| | `allowedTools` 中的工具仍然提示请求权限 | 旧版冒号语法 `Bash(npm:*)` | `csg migrate` 自动转换为 `Bash(npm *)` | | `deny` 规则未按预期阻止操作 | Claude Code 中的模式匹配 bug | Layer 2 hook 提供双重防御 | | 手动确认 "Yes" 的次数过多 | 常用工具未在 allow 列表中 | `csg recommend` 提供基于遥测的建议 | | 设置结构过时 | 需要迁移到 `permissions.*` | `csg migrate` 处理结构和语法 | | `.env` 或机密文件被读取的风险 | deny 规则不足 | 配置文件批量应用推荐的 deny 规则 | | `curl ... \| sh` 绕过 deny 规则 | 未分析复合命令 | Layer 2 hook 分解 `&&`, `\|\|`, `\|`, `$()` 并逐一检查 | ### 架构：双层防御 ``` Tool execution request | Layer 1: settings.json (Claude Code internals) permissions.allow --> auto-approve permissions.deny --> block | (if bug lets it through) Layer 2: PreToolUse Hook (independent watchdog) Re-evaluates deny rules with bash regex Decomposes compound commands (&&, ||, |, $(), <()) Checks each part independently against deny rules --> exit 2 to force-block on match ``` ### 设置层级 csg 读取并合并 3 个层级的设置： | 层级 | 路径 | 用途 | |-------|------|---------| | 全局 | `~/.claude/settings.json` | 用户范围的基本设置 | | 本地 | `~/.claude/settings.local.json` | 特定机器的覆盖设置（不在 git 中） | | 项目 | `.claude/settings.json` | 特定项目的设置 | ### 安装 #### 方法 1：交互式指南（推荐） 最简单的方法。引导您完成 5 个步骤。 ``` npx claude-settings-guard ``` 向导按顺序执行这些步骤： ``` Step 1/5: Diagnose → Detect issues in current settings Step 2/5: Migrate → Auto-convert legacy syntax if found Step 3/5: Recommend → Suggest settings based on telemetry Step 4/5: Profile → Choose security level Step 5/5: Setup → Deploy deny rules, hooks, and slash commands ``` #### 方法 2：一行命令（非交互） 一次性应用所有默认设置（balanced 配置文件）： ``` npx claude-settings-guard -y ``` #### 方法 3：使用特定配置文件初始化 ``` # 均衡配置 (推荐默认) npx claude-settings-guard init --profile balanced # 安全优先 npx claude-settings-guard init --profile strict # 速度优先，最小限制 npx claude-settings-guard init --profile minimal ``` #### 方法 4：全局安装 适用于频繁使用： ``` npm install -g claude-settings-guard csg # Interactive guide csg init --profile strict # Profile-based init ``` #### 设置后部署的文件 ``` ~/.claude/ ├── settings.json ← deny/allow/ask rules added ├── backups/ ← Auto-backups before changes ├── hooks/ │ ├── enforce-permissions.sh ← Layer 2 enforcement hook │ └── session-diagnose.sh ← Startup auto-diagnostics (strict only) └── commands/ ├── csg.md ← /csg slash command ├── csg-diagnose.md ← /csg-diagnose └── csg-enforce.md ← /csg-enforce ``` #### 安装后验证 ``` # 检查配置问题 csg diagnose # 预览 hook 脚本 csg enforce --dry-run # 在 Claude Code 中使用斜杠命令 # /csg → 设置摘要 # /csg-diagnose → 详细诊断 # /csg-enforce → 更新强制执行 hook ``` ### 配置文件 从 3 个预设中选择。每个配置文件都包含基础 deny 规则（sudo, rm -rf, .env, secrets）。 #### minimal（侧重速度） 自动允许大多数工具。适合希望减少确认提示的用户。 | 设置 | 内容 | |---------|---------| | deny | `Bash(sudo *)`, `Bash(rm -rf /*)` | | allow | `Read`, `Edit`, `Write`, `Bash`, `Glob`, `Grep` | | ask | 无 | | hooks | 仅 enforce-permissions | #### balanced（推荐默认值） 自动允许读取操作，写入/执行需要确认。 | 设置 | 内容 | |---------|---------| | deny | `Bash(sudo *)`, `Bash(rm -rf /*)`, `Read(**/.env)`, `Read(**/secrets/**)` | | allow | `Read`, `Glob`, `Grep` | | ask | `Bash`, `Edit`, `Write` | | hooks | 仅 enforce-permissions | #### strict（侧重安全） 阻止网络命令。适合安全关键环境。 | 设置 | 内容 | |---------|---------| | deny | 以上所有 + `Bash(curl *)`, `Bash(wget *)`, `Write(**/.env)` | | allow | `Read`, `Glob`, `Grep` | | ask | `Bash`, `Edit`, `Write` | | hooks | enforce-permissions + 启动时自动诊断 | ### 命令 | 命令 | 说明 | |---------|-------------| | `csg` / `csg setup` | 交互式引导设置（默认） | | `csg diagnose [--json] [--quiet]` | 审计 settings.json 中的问题 | | `csg migrate [--dry-run]` | 将旧版语法批量转换为现代格式 | | `csg recommend [-y\|--yes]` | 分析遥测数据，建议并自动应用权限更改 | | `csg enforce [--dry-run]` | 从 deny 规则生成强制 hook | | `csg init [--profile NAME] [--force]` | 首次设置：部署斜杠命令、配置文件和 hook | | `csg mcp` | 动为 MCP 服务器，用于 Claude Code 集成 | #### 退出代码 | 代码 | 条件 | |------|-----------| | `0` | 无问题，或仅有 INFO 级别的问题 | | `1` | 检测到 CRITICAL 或 WARNING 问题（使用 `--json` 时） | 在 CI/CD 中用于设置质量门控： ``` # 在 CI pipeline 中检查设置健康状况 npx claude-settings-guard diagnose --json --quiet || echo "Settings issues detected" ``` ### 诊断问题代码 | 代码 | 严重程度 | 说明 | |------|----------|-------------| | `LEGACY_SYNTAX` | CRITICAL | 检测到冒号语法 `Tool(arg:*)` | | `STRUCTURE_ISSUE` | WARNING | 发现顶层 `deny`/`allowedTools` | | `INVALID_TOOL` | WARNING | 未知工具名 | | `CONFLICT` | WARNING | 模式同时出现在 allow 和 deny 中 | | `INVALID_PATTERN` | WARNING | 模式语法错误 | | `PIPE_VULNERABLE` | INFO | 管道绕过风险 → 由 Layer 2 处理 | ### 遥测推荐 `csg recommend` 使用以下阈值分析 `~/.claude/telemetry/` 中的事件： | 推荐 | 条件 | |----------------|-----------| | 添加到 allow | 工具被手动批准 3 次以上 | | 添加到 deny | 工具被拒绝 2 次以上 | #### 模式分组 当 3 个或更多命令共享相同前缀时，它们会被分组为通配符模式： ``` Bash(npm install lodash) ─┐ Bash(npm install express) ─┼→ Recommend Bash(npm install *) for allow Bash(npm install chalk) ─┘ ``` 包管理器和 VCS 命令（`npm`, `git`, `cargo`, `pip` 等）使用 2-token 前缀（例如 `npm install`）；其他命令使用 1-token 前缀（例如 `ls`）。 #### 自动应用 显示推荐后，您可以交互式地应用它们。使用 `--yes` 跳过确认： ``` csg recommend # Show recommendations → "Apply? [Y/n]" csg recommend --yes # Auto-apply without confirmation ``` 当添加 deny 规则时，Layer 2 强制 hook 会自动重新生成。 ### MCP 服务器集成 让 Claude 直接检查和改进设置。 ``` // Add to ~/.claude.json { "mcpServers": { "csg": { "command": "npx", "args": ["claude-settings-guard", "mcp"] } } } ``` 可用的 MCP 工具： | 工具 | 参数 | 说明 | |------|-----------|-------------| | `csg_diagnose` | 无 | 诊断设置并返回问题 | | `csg_recommend` | `profile?` | 基于配置文件建议改进 | | `csg_enforce` | `dryRun?` | 生成/更新 Layer 2 hook（支持 dry-run） | | `csg_setup` | `profile?` | 配置文件应用指南 | ### 开发 ``` git clone https://github.com/hideosugimoto/claude-settings-guard.git cd claude-settings-guard npm install npm run build # Build npm test # Run tests (19 files, 356 tests) npx tsx src/index.ts # Run locally ``` #### 项目结构 ``` src/ ├── index.ts # CLI entry point ├── commands/ # Subcommand implementations │ ├── setup.ts # 5-step interactive wizard │ ├── diagnose.ts # Diagnostics │ ├── migrate.ts # Migration │ ├── recommend.ts # Telemetry recommendations │ ├── enforce.ts # Hook generation │ ├── init.ts # Initialization │ └── deploy-slash.ts # Slash command deployment ├── core/ # Core logic │ ├── settings-reader.ts # 3-layer settings loading & merging │ ├── settings-writer.ts # Settings write (with auto-backup) │ ├── pattern-validator.ts # Pattern validation │ ├── pattern-migrator.ts # Syntax & structure migration │ ├── hook-generator.ts # Enforcement hook generation │ ├── hook-regenerator.ts # Shared hook regeneration logic │ ├── hook-script-builder.ts # Shell script building │ ├── pattern-grouper.ts # Command prefix grouping │ ├── recommendation-applier.ts # Auto-apply recommendations │ ├── session-hook.ts # Session startup hook │ ├── telemetry-analyzer.ts # Telemetry analysis │ └── mcp-protocol.ts # JSON-RPC 2.0 framing ├── mcp-server.ts # MCP server ├── profiles/ # Profile definitions ├── types.ts # Zod schemas & type definitions └── constants.ts # Constants & known tools list ``` ## 许可证 MIT

标签：AI 安全, Claude Code, CLI 工具, Cutter, DevSecOps, DNS 反向解析, GNU通用公共许可证, MITM代理, Node.js, NPX, Shell 命令组合, 上游代理, 云安全监控, 命令注入检测, 暗色界面, 权限管理, 模型越狱, 白名单, 私有化部署, 结构化查询, 网络安全审计, 自动化安全, 自动化攻击, 配置安全, 配置迁移, 防御规避, 静态分析, 黑名单