akasecurity/claude-tools

# aka-claude-tools

**让 Claude Code 的使用更安全。** 清洁的上下文、锁定的凭证、受控的网络出口。这是 Claude Code 默认未提供的安全设置，只需几分钟即可将其分层加载到其独立的配置文件中。 刚接触这个？把仓库交给 Claude，它会帮你设置好。熟悉终端？先逐个阅读每个 hook 吧。全部由纯 shell 和 TypeScript 编写，基于 MIT 协议，且防护机制在本地扫描：不会上传任何内容来执行它们。 来自 [akasecurity](https://github.com/akasecurity) · MIT · 需要 `jq` + `bun`。 ## 它能防范什么 编程代理会代替你运行 shell 命令并访问网络。此工具包为常见的“自残”行为添加了防护机制： - **读取你的凭证**（SSH 密钥、云 token、`.env` 文件、keychain）→ 拒绝。 - **`curl … | bash`** 及其同类（将网络脚本直接管道传输到你的 shell 中）→ 阻止。 - **编辑你的 shell 启动文件**（这是一种让程序悄悄持久化运行的常见方式）→ 阻止。 - **在网络请求中泄露机密** → 在你的本机匹配并阻止。 - **上下文充斥噪音**（冗长的命令输出） → 在到达模型之前进行摘要。 十五个小模块，九个默认开启，六个可选开启。每个都是独立的。任你挑选。 ## 快速开始 有两种方式，效果相同：启动一个由独立别名调用的强化版配置文件。 **交给 Claude 处理。** 在已登录的 Claude Code 会话中，输入： 它会阅读指南，检查你已有的内容，干净利落地迁移它们，并运行安装程序。无需手动输入。 **或者通过包管理器安装：** ``` # npm / npx (macOS + Linux) npx @akasecurity/claude-tools # Homebrew (macOS + Linux) brew tap akasecurity/tap brew install akasecurity/tap/aka-claude-tools aka-claude-tools ``` **或者克隆并运行：** ``` git clone git@github.com:akasecurity/claude-tools.git cd claude-tools ./install.sh # interactive ./install.sh --defaults # accept the recommended six ``` 克隆时不会运行任何内容。如果你愿意，可以先阅读代码。安装程序会询问将配置文件放在哪里、启动器叫什么名字、要启用哪些模块，并会迁移你当前的配置（重写路径），因此新配置文件是你现有设置的可用副本，而不是一个光秃秃的沙盒。想要分步引导？查看[安全设置轮播图](media/decks/safe-setup.pdf)。 ### 作为 Claude Code 插件安装（将防护注入你的活动配置文件） *（AKA 插件市场正在推出；一旦上线：）* `claude plugin marketplace add akasecurity/marketplace`，然后 `claude plugin install claude-tools@aka` 会将防护 hook（command-guard、leak-guard）安装到你**当前活动**的配置文件中。 - **需要 `bun`。** 防护机制在 bun 下运行。它们采用**故障放行**策略 —— 如果缺少 bun，它们绝不会阻止你的工作；相反，你只会在会话开始时收到一条清晰的“防护未激活”通知。安装 bun (https://bun.sh) 以激活它们。 - **插件 ≠ 完整工具包。** 插件无法实现凭证读取拒绝、`rtk-safe` 输出重写器（它需要合并 `permissions.allow` 设置，这是插件清单无法应用的）或状态栏。想要获得全面强化、隔离的配置文件，请安装完整工具包 —— 参见[快速开始](#quick-start)（npm、Homebrew 或 `./install.sh`）。 ## 看看它实际是如何拦截的 一个你未曾见过触发的防护机制，只能算是你假设它有效。启动配置文件（`aka`）并尝试： - 要求它读取 `~/.ssh/id_rsa` → 它会**拒绝** - 检查状态栏 → 显示上下文和速率限制指标 - 运行 `curl … | bash` → **被阻止**

## 内部包含什么

十五个附加组件；菜单完全由 [`config/additions.json`](config/additions.json) 驱动，这是两种安装路径都会读取的唯一源文件。 想要可视化导览？查看[内部包含什么轮播图](media/decks/whats-inside.pdf)。 | 附加组件 | 它的作用 | 默认状态 | |---|---|---| | `secure-settings` | 拒绝读取 SSH 密钥、云凭证、`.env`、keychain；阻止写入 shell 启动文件；不自动加载 MCP 服务器。 | ● 开启 | | `leak-guard` | 扫描代理发送到网络的内容，并拦截任何形似机密的信息。在本地扫描，不上传任何内容进行检查。 | ● 开启 | | `command-guard` | 阻止 `curl…\|bash`、对 shell 启动文件的编辑，以及凭证被外传。 | ● 开启 | | `rtk-safe` | 在冗长的命令输出到达模型之前，将其重写为紧凑的摘要（在 90 天的样本中，路由的 token 减少了约 75%）。在安装 [`rtk`](https://github.com/rtk-ai/rtk) 之前不生效。 | ● 开启 | | `statusline` | 带有实时上下文填充和速率限制指标的状态栏。 | ● 开启 | | `shell-audit` | 按需对你的 shell 启动项进行只读扫描，查找硬编码的凭证、危险的 hook 和陈旧的别名。 | ● 开启 | | `wrap-up` | 一个 `/wrap-up` 命令，用于总结、验证并暂存 commit 以供审查。从不自动提交。 | ○ 可选 | | `secure-research` | 日常注重隐私的多源研究：并行的研究人员将带有引用的发现汇总成一份有根据的报告。通过你自己的搜索实例路由敏感话题。 | ○ 可选 | | `secure-deep-research` | 更重量级的研究变体，在合成之前增加对每项声明的对抗性验证。同样的隐私门控。 | ○ 可选 | | `harness-pointer` | 一个小提示，引导代理找到适合你环境的正确 CLI。默认为空。 | ○ 可选 | | `error-reporting-off` | 设置 `DISABLE_ERROR_REPORTING` 以退出 Sentry 错误报告。 | ● 开启 | | `feedback-off` | 设置 `DISABLE_FEEDBACK_COMMAND` 以禁用 `/feedback` 命令。 | ● 开启 | | `feedback-survey-off` | 设置 `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 以禁用会话质量调查。 | ● 开启 | | `telemetry-off` | 设置 `DISABLE_TELEMETRY`。此为可选，因为它会禁用 Remote Control（从 claude.ai 会话驱动 CLI）。 | ○ 可选 | | `autoupdater-off` | 设置 `DISABLE_AUTOUPDATER` 以停止后台更新；`claude update` 仍然有效。 | ○ 可选 | ## 配置文件 一个配置文件就是其专属的 `CLAUDE_CONFIG_DIR`：它拥有自己的设置、hook 和历史记录，由别名调用。可以并行运行多个配置文件：`claude` 用于你的日常基础操作，`aka` 完全强化，`work` 用于仅限工作的工具，`play` 用于规划实验。共用同一个 Claude Code 二进制文件。别名只是指向正确的文件夹。 - **按配置文件选择。** 从菜单中选择模块，或为脚本化运行将 `CT_ADDITIONS` 设置为你想要的 id。 - **就地升级。** 随着工具包的更新，重新运行即可。它会找到由工具包管理的配置文件，并**就地叠加当前最新的附加组件**：协调已废弃的规则，重新注册重命名的 hook，保持你自己的设置完好无损。 - **干净移除。** 通过在不勾选某个模块的情况下重新运行来删除它（取消选择即卸载它）。不喜欢其中的任何内容？删除该配置文件即可。你真实的设置从未改变。

## 哪些内容会保留在你的机器上 防护机制在**本地**运行：机密在你的本机进行匹配，不会上传任何内容进行检查。默认情况下，工具包会屏蔽不涉及 Remote Control 的非必要流量：`error-reporting-off`、`feedback-off` 和 `feedback-survey-off` 处于开启状态。 `telemetry-off` 和 `autoupdater-off` 保持可选，因此 **Remote Control 和自动更新仍能正常工作**。你可以根据自己的喜好开启或关闭它们。（可选的状态栏会获取天气和你的使用情况；取消选择它即可退出。） 它们是**深度防御，而不是沙盒**：它们提高了犯错的成本，但并不能让数据窃取变得不可能。它们无法监控 `ssh` / `git push`、运行时自身的请求，或是通过 `$VAR` 引用（非字面量）的机密。真正的边界在于凭证拒绝列表、不自动加载 MCP 服务器以及不使用 `bypassPermissions` 运行。如果防护机制的模式文件丢失或损坏，它们会**故障封闭**。 发现了安全问题？请私下报告，参见 [`SECURITY.md`](SECURITY.md)。 ## 通过你的代理安装？ 如果你是一个正在阅读本文以设置配置文件的编程代理，请不要即兴发挥。请遵循 [`agent-install.md`](agent-install.md)。这是确定性的规范：使用 `./install.sh --enumerate` 枚举现有配置文件，干净利落地进行迁移，然后驱动 `./install.sh --apply` 和 `./install.sh --alias`（install.sh 是唯一受认可的 shell-rc 写入器）。当配置文件用于不同的账户时，请使用 `--no-auth-inherit`。仓库的机器可读映射位于 [`llms.txt`](llms.txt)。 ## 超越 Claude Code 这是 Claude Code 工具包。一个 Codex 的对应版本正在开发中，此外还有一个代理 **harness**，用于在配置文件中驱动一个严谨的、受探测门控的工程循环。 ## 系统要求 `jq` 和 `bun`（防护机制和状态栏在 bun 上运行）。可选： [`trufflehog`](https://github.com/trufflesecurity/trufflehog) 用于更强的机密检测， [`rtk`](https://github.com/rtk-ai/rtk) 用于重写附加组件。安装程序会检查每一项，并提议（在征得你同意的情况下）通过你的包管理器进行安装。macOS 或 Linux。 ## 致谢 - [PAI (Personal AI Infrastructure)](https://github.com/danielmiessler/PAI)，作者 Daniel Miessler：egress-guard 和命令重写概念的早期灵感来源。 - [trailofbits/claude-code-config](https://github.com/trailofbits/claude-code-config)： 安全权限默认设置和维护者自我 PR 工作流的参考。 这里的实现都是我们自己完成的。专为 [Claude Code](https://docs.claude.com/en/docs/claude-code) 构建。 ## 许可证 [MIT](LICENSE)。

标签：AI安全, AI编程辅助, Chat Copilot, Cutter, Shell脚本, 开发安全, 沙箱隔离