arnica/depsguard

# depsguard [](https://github.com/arnica/depsguard/actions/workflows/ci.yml) [](https://github.com/arnica/depsguard/actions/workflows/audit.yml) [](https://crates.io/crates/depsguard) [](LICENSE) [](https://blog.rust-lang.org/2023/11/16/Rust-1.74.0.html) ``` _ _ __| | ___ _ __ ___ __ _ _ _ __ _ _ __ __| | / _` |/ _ \ '_ \/ __|/ _` | | | |/ _` | '__/ _` | | (_| | __/ |_) \__ \ (_| | |_| | (_| | | | (_| | \__,_|\___| .__/|___/\__, |\__,_|\__,_|_| \__,_| |_| |___/ ``` 守护你的依赖项免受供应链攻击。**单一静态二进制文件，零 Rust crate 依赖。** 由 **[[arnica](https://arnica.io)]** 提供 ## 目录 - [概述](#overview) - [安装](#install) - [用法](#usage) - [检查内容](#what-gets-checked) - [配置文件位置](#config-file-locations) - [备份与恢复](#backups-and-restore) - [工作原理](#how-it-works) - [故障排除](#troubleshooting) - [帮助与反馈](#help--feedback) - [许可证](#license) ## 概述 DepsGuard 会检测你机器上的 **npm**、**pnpm**、**yarn**、**bun** 和 **uv**，读取它们的配置文件，并将它们与推荐的供应链设置进行比较，还可以**交互式地应用修复**。它还会扫描仓库中的 **Renovate** 和 **Dependabot** 配置。它从不运行包安装；它只编辑你批准的配置文件，并在修改前写入**备份**。 ### 关键特性 - 交互式 TUI：扫描、审查、切换修复、应用 - `scan` 子命令用于只读报告 - `restore` 子命令用于选择备份并回滚文件 - 跨平台支持：Linux、macOS、Windows - 无捆绑的第三方 Rust crate（仅 stdlib + 少量用于终端的平台 FFI） ### 技术栈 | 领域 | 详情 | |------|------| | 语言 | Rust（MSRV **1.74**，详见 `Cargo.toml`） | | CLI / TUI | `src/main.rs`、`src/ui.rs`、`src/term.rs` | | 配置逻辑 | `src/manager.rs`、`src/fix.rs` | | 网站 | 位于 `docs/` 的静态站点（与二进制文件分离） | ## 安装 ### 预构建二进制文件 每个 [GitHub Release](https://github.com/arnica/depsguard/releases) 包含以下平台的归档文件： - Linux：`x86_64`（glibc）、`x86_64`（musl）、`aarch64`（glibc） - macOS：Intel 和 Apple Silicon - Windows：包含 `depsguard.exe` 的 `x86_64` ZIP 下载对应平台的归档包，解压后将二进制文件加入你的 `PATH`。 使用对应的 `.sha256` 文件验证完整性。 ### 按平台安装 #### Linux（通过 APT 的 Debian/Ubuntu） ``` sudo install -d -m 0755 /etc/apt/keyrings curl -fsSL https://depsguard.com/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/depsguard.gpg echo "deb [signed-by=/etc/apt/keyrings/depsguard.gpg] https://depsguard.com/apt stable main" | sudo tee /etc/apt/sources.list.d/depsguard.list >/dev/null sudo apt update sudo apt install depsguard ``` #### macOS（Intel / Apple Silicon） ``` # Homebrew tap brew tap arnica/depsguard https://github.com/arnica/depsguard brew install depsguard ``` #### Windows ``` # WinGet winget install Arnica.DepsGuard # Scoop scoop bucket add depsguard https://github.com/arnica/depsguard scoop install depsguard ``` 或者通过 PowerShell 手动下载： ``` $zip = "$env:TEMP\\depsguard.zip" Invoke-WebRequest -Uri "https://github.com/arnica/depsguard/releases/latest/download/depsguard-x86_64-pc-windows-msvc.zip" -OutFile $zip Expand-Archive -LiteralPath $zip -DestinationPath "$env:TEMP\\depsguard" -Force Copy-Item "$env:TEMP\\depsguard\\depsguard.exe" "$HOME\\AppData\\Local\\Microsoft\\WindowsApps\\depsguard.exe" -Force depsguard.exe --help ``` ### crates.io ``` cargo install depsguard ``` 需要带有 `cargo` 的 [Rust 工具链](https://rustup.rs/)。 ### 包管理器（当由你的供应商发布时） 如果你的组织通过 Homebrew、Scoop 或 WinGet 分发 DepsGuard，请使用它们的说明。**设置或自动化这些渠道**（Homebrew 核心仓库 PR、bucket、WinGet PR、CI 密钥）属于维护者文档；请参考 *发布与分发* 下的 [`AGENTS.md`](AGENTS.md)。 #### 应用商店 / 包管理器 | 渠道 | Linux | macOS | Windows | 安装命令 | |------|-------|-------|---------|----------| | APT（自定义仓库） | 是 | 否 | 否 | 添加仓库后运行 `sudo apt install depsguard` | | crates.io | 是 | 是 | 是 | `cargo install depsguard` | | Homebrew（自定义 tap） | 是 | 是 | 否 | `brew tap arnica/depsguard https://github.com/arnica/depsguard && brew install depsguard` | | Scoop（自定义 bucket） | 否 | 否 | 是 | `scoop bucket add depsguard https://github.com/arnica/depsguard && scoop install depsguard` | | WinGet | 否 | 否 | 是 | `winget install Arnica.DepsGuard` | ### 从源码构建 ``` git clone https://github.com/arnica/depsguard.git cd depsguard cargo build --release ``` 生成二进制文件 `target/release/depsguard`（Windows 上为 `.exe`）。需要 **Rust 1.74+**。 ## 用法 ``` depsguard # interactive: scan, choose fixes, apply depsguard scan # report only; no writes depsguard --no-search # skip recursive file search, check local configs only depsguard restore # restore from a previous backup depsguard --help # CLI help ``` ### 使用方法 1. **安装** — 选择上方对应你平台的方式。 2. **运行** `depsguard` 启动交互式 TUI。它会扫描系统并显示发现结果表格。按任意键继续到修复选择器。仓库级配置发现从当前目录开始并向下搜索。使用 `depsguard scan` 进行只读报告，或使用 `depsguard --no-search` 跳过递归文件搜索，仅检查用户级配置。 3. **导航与选择** — 使用 `↑` `↓` 在列表中移动（`^u` / `^d` 翻页）。按 `Space` 切换修复的启用或禁用。使用快速筛选键按文件批量选择：`a` 全部、`n` .npmrc、`u` uv.toml 等 — 按一次选中，再次取消选中，第三次清除筛选。按 `f` 仅显示当前选中的修复。 4. **预览** — 按 `d` 查看将更改内容的差异，再决定是否提交。 5. **应用** — 按 `Enter` 应用选中的修复。会在写入任何文件前创建时间戳备份。 6. **重新扫描** — 应用修复后 DepsGuard 会自动重新扫描，以便验证是否全部通过。 7. **恢复** — 随时运行 `depsguard restore` 从备份中恢复。按 `q` 或 `Esc` 退出。 ## 检查内容 | 包管理器 | 配置文件 | 设置 | 目标 | 原因 | |----------|----------|------|------|------| | npm | `~/.npmrc` | `min-release-age` | `7`（天） | 延迟新发布（需要 npm >= 11.10） | | npm/pnpm | `~/.npmrc` | `ignore-scripts` | `true` | 降低安装脚本风险 | | pnpm | `~/.npmrc` | `minimum-release-age` | `10080`（分钟） | 延迟新版本 7 天（需要 pnpm >= 10.16） | | pnpm | 全局 `rc`（pnpm <= 10） | `minimum-release-age` | `10080`（分钟） | 延迟新版本 7 天（需要 pnpm >= 10.16） | | pnpm | 全局 `rc`（pnpm <= 10） | `block-exotic-subdeps` | `true` | 阻止不受信的传递依赖（需要 pnpm >= 10.26） | | pnpm | 全局 `rc`（pnpm <= 10） | `trust-policy` | `no-downgrade` | 阻止来源降级（需要 pnpm >= 10.21） | | pnpm | 全局 `rc`（pnpm <= 10） | `strict-dep-builds` | `true` | 对未审核的构建脚本失败（需要 pnpm >= 10.3） | | pnpm | 全局 `rc`（pnpm <= 10） | `ignore-scripts` | `true` | 阻止恶意安装脚本 | | pnpm | 全局 `config.yaml`（pnpm >= 11） | `minimumReleaseAge` | `10080（分钟） | 延迟新版本 7 天 | | pnpm | 全局 `config.yaml`（pnpm >= 11） | `blockExoticSubdeps` | `true` | 阻止不受信的传递依赖 | | yarn | `.yarnrc.yml` | `npmMinimalAgeGate` | `7d` | 延迟新版本 7 天（需要 yarn >= 4.10） | | pnpm | `pnpm-workspace.yaml` | `minimumReleaseAge` | `10080`（分钟） | 延迟新版本 7 天（需要 pnpm >= 10.16） | | pnpm | `pnpm-workspace.yaml` | `strictDepBuilds` | `true` | 对未审核的构建脚本失败（需要 pnpm >= 10.3） | | pnpm | `pnpm-workspace.yaml` | `trustPolicy` | `no-downgrade` | 阻止来源降级（需要 pnpm >= 10.21） | | pnpm | `pnpm-workspace.yaml` | `blockExoticSubdeps` | `true` | 阻止不受信的传递依赖（需要 pnpm >= 10.26） | | bun | `~/.bunfig.toml` | `install.minimumReleaseAge` | `604800`（秒） | 约 7 天延迟 | | uv | `uv.toml` | `exclude-newer` | `7 days` | 延迟新发布（需要 uv >= 0.9.17） | | renovate | `renovate.json` 等 | `minimumReleaseAge` | `7` 天 | 延迟依赖更新 PR 7 天 | | dependabot | `.github/dependabot.yml` | `cooldown.default-days` | `7` | 延迟依赖更新 PR 7 天 | ## 配置文件位置 | 包管理器 | Linux | macOS | Windows | |----------|-------|-------|---------| | npm/pnpm | `~/.npmrc` | `~/.npmrc` | `%USERPROFILE%\.npmrc` | | pnpm 全局 | `$XDG_CONFIG_HOME/pnpm/rc` 或 `~/.config/pnpm/rc` | `$XDG_CONFIG_HOME/pnpm/rc` 或 `~/Library/Preferences/pnpm/rc` | `%LOCALAPPDATA%\pnpm\config\rc` | | yarn | `~/.yarnrc.yml` | `~/.yarnrc.yml` | `%USERPROFILE%\.yarnrc.yml` | | pnpm | `pnpm-workspace.yaml` | `pnpm-workspace.yaml` | `pnpm-workspace.yaml` | | bun | `$XDG_CONFIG_HOME/.bunfig.toml` 或 `~/.bunfig.toml` | `$XDG_CONFIG_HOME/.bunfig.toml` 或 `~/.bunfig.toml` | `%USERPROFILE%\.bunfig.toml` | | uv | `$XDG_CONFIG_HOME/uv/uv.toml` 或 `~/.config/uv/uv.toml` | `$XDG_CONFIG_HOME/uv/uv.toml` 或 `~/.config/uv/uv.toml` | `%APPDATA%\uv\uv.toml` | | renovate | `renovate.json`、`.renovaterc`、`.github/renovate.json` 等 |（相同） |（相同） | | dependabot | `.github/dependabot.yml` |（相同） |（相同） | 用户级配置文件从标准位置读取（包括支持 XDG 路径的情况）。仓库级配置文件从当前目录向下搜索，跳过已知大型目录（`node_modules`、`.git`、`target`、`Library`、`.cache` 等）以保持扫描速度。`.npmrc`、`.yarnrc.yml`、`pnpm-workspace.yaml`、Renovate 配置和 Dependabot 配置都会被搜索。pnpm 设置可能位于 `~/.npmrc`、pnpm 全局配置文件（pnpm <= 10 为 `rc`，pnpm >= 11 为 `config.yaml`）或 `pnpm-workspace.yaml`；DepsGuard 会独立检查这三个位置。如果存在多个用户级 uv 或 bun 配置文件（例如同时存在 XDG 路径和家目录路径），DepsGuard 会分别扫描每个存在的文件，而不是合并它们。当 `~/.npmrc` 缺失时，DepsGuard 会使用 pnpm 的全局配置路径，以便直接创建配置文件。 ## 备份与恢复 在修改文件之前，DepsGuard 会将备份写入 `~/.depsguard/backups/`。 运行 `depsguard restore` 列出备份并恢复一个。 ## 工作原理 ``` src/ main.rs CLI args, run loop term.rs Raw mode + input (Unix termios / Windows console FFI) manager.rs Detection, scanning, recommendations fix.rs Read/write .npmrc, TOML, YAML; backup/restore ui.rs Banner, tables, selector ``` - **零第三方 crate** — 出于安全考虑有意为之；如需更改策略，请参考 `AGENTS.md`。 - **颜色** 使用 ANSI 序列；现代 Windows 终端（例如 Windows Terminal）也支持。 ## 故障排除 | 症状 | 解决方法 | |------|----------| | `depsguard: command not found` | 确保安装目录已在 `PATH` 中，或使用二进制文件的完整路径。 | | 写入配置时权限错误 | DepsGuard 仅编辑你的用户目录中的文件；以普通用户运行，而非提升权限（除非这些文件归管理员所有）。 | | Windows 上按键无响应 | 使用 **Windows Terminal** 或其他支持 VT 的终端；旧版 `cmd.exe` 可能无法处理所有按键。 | | pnpm 工作区缺失 | 确保 `pnpm-workspace.yaml` 位于你的家目录树中；布局非常规时可能无法被发现。 | | `cargo install` 失败 | 通过 [rustup](https://rustup.rs/) 安装 Rust，并使用 **≥ 1.74** 版本。 | ## 帮助与反馈 - [报告错误或请求功能](https://github.com/arnica/depsguard/issues) - [报告安全漏洞](https://github.com/arnica/depsguard/security/advisories/new)（请参考 [`SECURITY.md`](SECURITY.md)） - 开发工作流请参考 [`AGENTS.md`](AGENTS.md) ## 许可证 MIT **链接：** [仓库](https://github.com/arnica/depsguard) · [文档站点](https://depsguard.com)

标签：bun, CI, Dependabot, GitHub Advanced Security, npm, pnpm, Renovate, Rust, uv, yarn, 二进制发布, 交互式TUI, 依赖安全, 包管理器, 可视化界面, 备份恢复, 安全加固, 开源工具, 扫描修复, 统一API, 网络流量审计, 软件供应链, 通知系统, 配置文件修复, 零依赖, 静态二进制