面向 Claude Code 的更安全依赖管理

当 Claude 等 AI 编程助手向你的项目添加包时，它们往往会选择听起来合适的版本——而不会检查该包是否存在已知安全漏洞、是否仍在积极维护，或者包名是否与恶意仿冒包仅有一字之差。

safer-dependencies 是 Claude Code 的安全层：它位于 Claude 与你的清单文件之间，自动执行安全检查：存在漏洞的安装会在运行前被拒绝，写入清单的危险版本会在写入后立即在磁盘上被纠正。它会检测并修复有风险的依赖——CVE、仿冒包（typosquats）、已弃用包和版本过旧问题，以及对全新发布版本的冷却期——覆盖 npm、PyPI、RubyGems、Maven、Go、Rust 和 PHP（Composer）。有关具体覆盖范围，请参阅 CAPABILITIES.md。

新手入门？ GETTING-STARTED.md 可在大约五分钟内带你从零开始完成安装。

安全与隐私： 请参阅 SECURITY.md（漏洞披露）、PRIVACY.md（数据外发、无遥测）以及 CAPABILITIES.md（该工具防御什么、不防御什么）。

许可证（源代码可用——非 OSI“开源”）： 可免费用于自身目的的使用和修改，包括营利性/公司内部使用以及构建你销售的产品。仅当你要将软件本身商业化时才需要单独的付费许可证——即销售它、将其打包进销售的产品或服务中，或向第三方有偿提供其功能（包括托管/SaaS/API）。再分发和衍生作品必须保留许可证并注明本项目来源。请参阅 LICENSE（第 4 节为商业限制）；商业许可证申请请通过 github.com/robert-auger。

快速开始

GETTING-STARTED.md 可在大约五分钟内带你从零开始完成安装——包括前置条件、交互式安装和验证。如需完整的安装参考（全局/项目/手动安装、Windows 特定说明、权限白名单、更新和卸载），请参阅 INSTALLATION.md。

日常使用： 钩子安装完成后无需运行任何命令——safer-dependencies 会在后台自动工作。当 Claude 添加或安装包时，它会标记有风险的依赖并将存在漏洞的版本就地升级为安全版本——并在已知存在漏洞的安装运行前就将其阻止——因此不安全的包会在无需你主动要求的情况下被捕获并纠正。你仍可随时直接调用它：“[email protected] 安全吗？”、“检查 safer-dependencies 设置” 或 “显示 safer-dependencies 统计信息”。

功能说明

当 Claude 即将向你的项目添加包时，safer-dependencies 会拦截并运行 5 项检查：

来源 —— 官方注册表、仿冒包检测（npm/PyPI/RubyGems/Maven/crates.io）、包年龄
版本年龄 —— 选择发布于 7 天以上（冷却窗口）的最新稳定版本
漏洞扫描 —— OSV API，并在可用时使用生态系统原生工具（npm audit、pip-audit、bundle audit）
哈希固定完整性 —— 对于带有 --hash=sha256:... 固定的 PyPI requirements.txt 行，声明的哈希会与 PyPI 发布的哈希进行验证；不匹配会发出警告
已弃用与过时包 —— 已知已弃用的包（例如 paperclip、request、pycrypto、github.com/dgrijalva/jwt-go）会立即被硬阻止并给出建议替代品；超过 2 年没有稳定版本的包会收到建议性的 STALE: 警告。被硬阻止的包会从清单中移除，Claude 将询问如何处理；仅过时的包会保留在原处。

如果发现问题，Claude 会发出警告，并可能回退到更安全的版本。所有检查都会记录到 ~/.claude/safer-dependencies-audit-YYYY-MM.log（每个自然月一个文件）。

触发条件

该技能在 Claude 执行以下操作时自动触发：

清单 / 安装操作

在 package.json、requirements.txt、Gemfile、pom.xml、build.gradle、Cargo.toml、go.mod 或任何其他受支持的清单中添加或更新包
为清单中尚未声明的包写入 import、require 或 use
生成或更新锁文件（仅检查新增/变更条目）
通过 Bash 运行包管理器安装（npm install、bundle install、poetry install、uv sync、go mod tidy 等）——安装前审计命令参数，安装后审计生成的锁文件
写入嵌入了固定包管理器安装步骤的 Dockerfile 或 CI 工作流（.github/workflows/*.yml 等）

选择与推荐问题

库/框架比较：“我应该用 axios 还是 node-fetch？”、“moment 还是 dayjs？”、“X 和 Y 哪个更好？”
推荐请求：“Python 有什么好的 HTTP 客户端？”、“推荐一个 Go 的日志库”、“Node 中哪个包处理 CSV？”
版本选择：“我应该用哪个版本的 Django？”、“最新的稳定版 Flask？”

使用意图表达（添加前）

“我想用 FastAPI 做这个”、“我在考虑添加 Celery”、“我们打算用 Prisma 作为 ORM”、“我们用 Tailwind 吧”

包健康与信任问题

“moment.js 还在维护吗？”、“这个 gem 还在活跃开发吗？”、“X 被弃用了吗？”、“X 到达生命周期终点了吗？”、“我能信任这个包吗？”、“faker 上次更新是什么时候？”

脚手架命令

npx create-react-app、npm create vite@latest、django-admin startproject、rails new、cargo new + cargo add、“引导一个新的 FastAPI 项目”

隐式包添加（暗示新依赖的功能请求）

“为应用添加 Redis 缓存”、“连接 Postgres”、“添加 JWT 认证”、“编写发送邮件的代码”——当清单中尚无该功能的包时触发

迁移与移植

“从 requests 迁移到 httpx”、“从 CRA 迁移到 Vite”、“从 moment 移植到 date-fns”——审计引入的包

它不会在以下情况触发：

标准库导入（os、fs、java.util.* 等）
未被更改的已声明依赖
关于包内部工作原理的学术讨论（“解释 React 的 reconciler”、“webpack 的模块解析是如何工作的？”）——比较和选择类问题仍会触发
安装操作系统级应用、运行时或 IDE 扩展（Python 本身、Docker、Homebrew、VS Code 扩展）

仓库内容

这是一个技能 + 钩子捆绑包，而非单个技能文件。完整安装会部署以下组件：

文件	作用
`skills/safer-dependencies.md`	技能（安装后为 `SKILL.md`）。描述审计流程，并包含用于安装/统计的管理模式。
`skills/safer-dependencies-shim.sh`	`PostToolUse:Write`/`Edit` 钩子——审计清单和锁文件写入，并就地自动纠正存在漏洞的版本（拦截模式）。
`skills/safer-dependencies-pretooluse-bash.sh`	`PreToolUse:Bash` 钩子——对包管理器安装命令进行安装前 OSV 审计；在安装运行前拒绝存在漏洞的具体固定版本（安装前模式）。
`skills/safer-dependencies-posttooluse-bash.sh`	`PostToolUse:Bash` 钩子——Bash 命令执行后的安装后审计；捕获新写入锁文件中的传递性 CVE、通过 `sed`/`jq`/脚本编辑的清单，以及普通 `pip install` 的解析环境（安装后模式）。
`skills/safer-dependencies-pretooluse-agent.sh` + `skills/safer-dependencies-posttooluse-agent.sh`	`PreToolUse:Agent` + `PostToolUse:Agent` 钩子对——弥补子代理覆盖缺口。模式 2–4 仅对根会话的工具调用触发，因此子代理写入的任何清单都会绕过它们。代理后模式会在每次 Agent 工具调用返回后审计子代理写入的内容（代理后模式）。
`skills/scripts/`	共享 Python 库（`safedep/`）以及所有钩子使用的独立解析器脚本。
`skills/scripts/safer_dependencies_manager.py`	用于交互式安装、使用统计和设置验证的管理模块。

仅技能文件是不够的——没有钩子，自动调用取决于 Claude 是否决定使用该技能。请安装全部五个组件以获得完整覆盖；许多技能和斜杠命令会在内部派发子代理，因此即使你从不显式生成子代理，代理后钩子对也很重要。（有关为何仅靠技能无法保证覆盖的说明，请参阅 FAQ.md。）

支持的生态系统

生态系统	清单	锁文件
npm	`package.json`	`package-lock.json`、`yarn.lock`、`pnpm-lock.yaml`
PyPI	`requirements.txt`、`pyproject.toml`、`Pipfile`、`setup.py`、`setup.cfg`	`Pipfile.lock`、`poetry.lock`、`uv.lock`
RubyGems	`Gemfile`、`*.gemspec`	`Gemfile.lock`
Maven	`pom.xml`、`build.gradle`、`libs.versions.toml`	--
Go	`go.mod`	`go.sum`
Rust	`Cargo.toml`	`Cargo.lock`
PHP（Composer）	`composer.json`	`composer.lock`

安装

刚接触该项目？请从 GETTING-STARTED.md 开始。简要版本：```bash git clone https://github.com/robert-auger/safer-dependencies /tmp/safer-dependencies python3 /tmp/safer-dependencies/skills/scripts/safer_dependencies_manager.py interactive_install

安装程序会提示选择作用范围（全局 vs 项目）以及要启用哪些钩子，然后为你写入 `settings.json`——既包含钩子条目，**也**包含权限白名单，让该技能的检查命令在每次审计时无需审批提示即可运行。

其他与安装相关的内容都位于 **[INSTALLATION.md](https://github.com/robert-auger/safer-dependencies/blob/main/INSTALLATION.md)** 中，这是安装机制的唯一参考文档：手动逐文件安装（全局和项目级）、Windows 特定说明、Post-Agent 钩子、[权限白名单](https://github.com/robert-auger/safer-dependencies/blob/main/INSTALLATION.md#permissions-allowlist)、验证安装、更新、固定到发布标签以及卸载。

安装完成后，日常管理可通过自然语言与 Claude 交互——`install safer-dependencies`（重新运行/更改钩子）、`show safer-dependencies stats`、`check safer-dependencies setup`——或通过 `/safer-dependencies` 菜单。更新也可以在会话内完成：`/safer-dependencies update` 应用最新版本（`update --check` 为试运行，`update --rollback` 用于回滚）；信任模型请参阅 [INSTALLATION.md](https://github.com/robert-auger/safer-dependencies/blob/main/INSTALLATION.md#in-session-self-updater-safer-dependencies-update)。

> **平台说明：** 支持 macOS、Linux 和 Windows。Windows 需要 Git for Windows（提供 bash）以及位于 `PATH` 上的 Python 3——无需 WSL。迄今为止的实操测试主要集中在 **macOS 和 Windows** 上；Linux 支持由自动化 CI 矩阵进行验证。

### 配置

安装后有两项内容可配置：

safer-dependencies v0.6.0