penumbraforge/vexes

# vexes [](https://github.com/penumbraforge/vexes/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@penumbraforge/vexes) **跨生态系统的依赖安全扫描器。摇晃依赖树，看会掉下什么危险来。** 零依赖。纯 Node.js 实现。捕获真实的供应链攻击。 ``` # 立即尝试 — 无需安装 npx @penumbraforge/vexes scan ``` ``` $ vexes scan vexes v0.1.0 -- scanning dependencies Found 847 unique packages across 3 lockfile(s) ~ 847 packages checked in 2.1s (0 cached) -- CRITICAL -------------------------------------------------- axios 1.14.1 (npm) GHSA-xxxx -- Remote code execution via compromised dependency Fixed in: >= 1.14.2 https://osv.dev/vulnerability/GHSA-xxxx -- HIGH ------------------------------------------------------ lodash 4.17.20 (npm) GHSA-yyyy -- Prototype pollution in lodash Fixed in: >= 4.17.21 -------------------------------------------------- 2 vulnerabilities . 1 critical . 1 high in 847 packages across npm, pypi, cargo completed in 2.1s -------------------------------------------------- ``` ## 功能介绍 vexes 是一款超越传统漏洞库的依赖安全扫描器。它使用 **4层检测引擎** 来捕获基于特征检测的工具容易漏掉的供应链攻击： | 层级 | 检测方法 | 捕获目标 | |-------|-----------------|----------------| | **1. AST 分析** | 通过 acorn AST 解析 JS/Python 源代码 | `eval()`、`child_process.exec()`、凭证窃取、混淆代码、动态导入、`WebAssembly`、`setTimeout(string)`、DNS 数据泄露、原型链逃逸 | | **2. 依赖图** | 分析新增的依赖配置 | 幽灵依赖（全新发布的包）、循环暂存、域名仿冒、Unicode 同形字攻击 | | **3. 行为指纹** | 对比版本间的能力配置差异 | 一个实用工具库突然获得了网络访问+命令执行的能力 | | **4. Registry 元数据** | 分析发布历史、维护者和发布时间 | 账户劫持、快速连续发布、休眠包重新激活 | ## 经过验证的检测能力 红队测试套件重构了 **9 种真实攻击**，并证明 vexes 能够成功捕获它们： - **axios RAT** (2026年3月) -- 维护者账户被劫持，隐藏的依赖项中包含 RAT 投放器 - **Shai-Hulud 蠕虫** (2025年9月) -- 钓鱼获取凭证，通过 chalk/debug 实现自我复制的蠕虫病毒 - **event-stream** (2018年11月) -- 社会工程学攻击，针对比特币钱包的加密载荷 - **ua-parser-js** (2021年10月) -- 账户劫持，植入加密货币挖矿程序和密码窃取器 - **litellm/TeamPCP** (2026年3月) -- CI/CD 环境被攻陷，包含 K8s 横向移动的 3 阶段载荷 - **Typosquatting (域名仿冒)** -- `expresss`、`loadash`、`reqeusts` 及类似的名称混淆攻击 - **新型/假设性攻击** -- 基于 WASM 的载荷、DNS 数据泄露、能力升级 ## 安装说明 ``` # 全局安装 npm install -g @penumbraforge/vexes # 或直接运行 npx @penumbraforge/vexes scan # 或克隆并运行 git clone https://github.com/penumbraforge/vexes.git cd vexes && node bin/vexes.js scan --path /your/project ``` **环境要求：** Node.js >= 22.5.0（使用原生 SQLite 进行缓存，使用原生 fetch） ## 命令 ### `vexes scan` -- 漏洞扫描 从 lockfile 中枚举依赖项，查询 [OSV.dev](https://osv.dev)，并报告已知漏洞。 ``` vexes scan # Scan current directory vexes scan --path ./my-project # Scan a specific directory vexes scan --ecosystem npm # Scan only npm dependencies vexes scan --severity critical # Only show critical vulnerabilities vexes scan --fix # Show upgrade commands for each vuln vexes scan --json # Machine-readable JSON output vexes scan --cached # Use cached results (skip freshness check) ``` **支持的生态系统：** npm (package-lock.json, pnpm-lock.yaml, yarn.lock), PyPI (Pipfile.lock, poetry.lock, requirements.txt, pyproject.toml), Cargo (Cargo.lock), Go (go.sum), Ruby (Gemfile.lock), PHP (composer.lock), NuGet (packages.lock.json), Java (gradle.lockfile, pom.xml), Homebrew (Brewfile.lock.json, Brewfile) **退出代码：** `0` = 安全，`1` = 发现漏洞，`2` = 错误/扫描不完整 ### `vexes analyze` -- 深度行为分析 超越漏洞数据库的检测能力。下载 registry 元数据，对安装脚本运行 AST 分析，分析版本间的行为变化。 ``` vexes analyze # Analyze direct dependencies vexes analyze --deep # Download + AST-inspect actual tarball code vexes analyze --explain lodash # Detailed breakdown for one package vexes analyze --strict # Fail on any signal (for CI) vexes analyze -v # Show all signals including LOW vexes analyze --json # Machine-readable JSON output ``` **检测信号：** - `KNOWN_COMPROMISED` -- 包含已知的 OSV 漏洞 - `MAINTAINER_CHANGE` -- 发布账户发生变更（可能发生了账户劫持） - `POSTINSTALL_SCRIPT` -- 包含 install 生命周期脚本 - `RAPID_PUBLISH` -- 版本发布时间与前一个版本异常接近 - `VERSION_ANOMALY` -- 版本号大幅跳跃或休眠许久后突然发布 - `TYPOSQUAT` -- 名称与知名软件包高度相似（易混淆） - `PHANTOM_DEPENDENCY` -- 引入了全新的依赖（发布时间少于 7 天） - `CIRCULAR_STAGING` -- 新依赖与父级包属于同一发布账户 - `CAPABILITY_ESCALATION` -- 包在不同版本间获取了危险的能力 - `AST_DANGEROUS_PATTERN` -- 安装脚本中包含危险代码模式 - `TARBALL_DANGEROUS_PATTERN` -- 实际的包源代码中包含危险模式 - `HOMOGLYPH` -- 包名包含可疑的 Unicode 字符（零宽度字符、RTL 覆盖、非 ASCII 字符） - `MISSING_PROVENANCE` -- 缺少 Sigstore 来源证明 - `NO_REPOSITORY` -- 缺少源代码仓库链接 ### `vexes fix` -- 经过验证的修复建议 查找漏洞并生成**经过验证的**升级命令。每个推荐的版本都会与 OSV 进行交叉核对，以确保其自身不存在漏洞。 ``` vexes fix # Show fix recommendations vexes fix --json # Machine-readable output ``` ### `vexes guard` -- 安装前保护 拦截 `npm install` 命令，并在新更改的包**执行之前**对它们进行分析。通过对比 lockfile 差异来实现——无需网络代理。 ``` vexes guard -- npm install axios # Guard a specific install vexes guard --setup # Install shell wrappers (auto-guard) vexes guard --uninstall # Remove shell wrappers vexes guard --force -- npm install # Override HIGH warnings (CRITICAL still blocked) ``` **工作原理：** 1. 生成当前 lockfile 的快照 2. 运行 `npm install --package-lock-only --ignore-scripts`（模拟运行） 3. 对比 lockfile 差异，找出新增/更改的包 4. 对这些包运行行为分析 5. 如果是 CRITICAL（严重）级别则阻止安装，HIGH（高）级别则提示用户，安全则允许 6. 仅在获得批准后运行真实的安装过程 ### `vexes monitor` -- 持续监控 为 CI/CD 和开发提供的两种模式： ``` # CI 模式 -- 使用 GitHub Actions annotations 的一次性扫描 vexes monitor --ci # Default: fail on HIGH+ vexes monitor --ci --severity critical # Only fail on CRITICAL vexes monitor --ci --sarif # SARIF output for GitHub Advanced Security vexes monitor --ci --json # Machine-readable JSON # Watch 模式 -- 持续的本地监控 vexes monitor --watch # Watch lockfiles + poll OSV hourly vexes monitor --watch --interval 5 # Poll every 5 minutes ``` **GitHub Action：** ``` # .github/workflows/vexes.yml name: Dependency Security on: [push, pull_request] jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: penumbraforge/vexes@v0 with: command: scan severity: high ``` **或直接运行：** ``` - name: Security scan run: npx @penumbraforge/vexes monitor --ci --severity high # 将 SARIF 上传至 GitHub Advanced Security： - name: Security scan (SARIF) run: npx @penumbraforge/vexes monitor --ci --sarif > results.sarif - name: Upload SARIF uses: github/codeql-action/upload-sarif@v3 with: sarif_file: results.sarif ``` ## 配置说明 ### 项目配置：`.vexesrc.json` 放置在您的项目根目录中。程序会向上遍历目录树来查找它。 ``` { "ecosystems": ["npm", "pypi"], "severity": "high", "ignore": [], "analyze": { "signals": { "NO_REPOSITORY": "off", "POSTINSTALL_SCRIPT": "off" } }, "cache": { "dir": "~/.cache/vexes", "advisoryTtlMs": 3600000, "metadataTtlMs": 86400000 }, "output": { "color": "auto", "format": "text" } } ``` ### 用户配置：`~/.config/vexes/config.json` 格式相同。项目配置会覆盖用户配置。 ### 白名单 vexes 内置了包含合法 postinstall 脚本的软件包的白名单（esbuild、sharp、puppeteer 等）。来自这些包的信号会被**降低权重，而不是被抑制**——如果它们被植入恶意代码导致出现新的危险模式，依然会触发警报。 ## 架构 ``` bin/vexes.js CLI entrypoint, command router src/ cli/ parse-args.js Hand-rolled arg parser (zero deps) config.js Config loading with prototype pollution protection output.js Terminal output, ANSI colors, spinner, sanitization commands/ scan.js Vulnerability scanning via OSV analyze.js 4-layer behavioral analysis fix.js Verified fix recommendations guard.js Pre-install lockfile diffing monitor.js CI annotations, SARIF output, watch mode core/ constants.js URLs, thresholds, exit codes fetcher.js Single-point HTTP with retry/timeout/backoff logger.js Leveled logger with terminal injection protection allowlists.js Known-good packages, popular package sets parsers/ npm.js package-lock.json v1/v2/v3, package.json fallback pnpm.js pnpm-lock.yaml v6/v9 yarn.js yarn.lock v1 (classic) and v2+ (Berry) pypi.js requirements.txt (-r recursive), poetry.lock, Pipfile.lock, pyproject.toml cargo.js Cargo.lock go.js go.sum ruby.js Gemfile.lock php.js composer.lock dotnet.js packages.lock.json (NuGet) java.js gradle.lockfile, pom.xml brew.js Brewfile.lock.json, Brewfile advisories/ osv.js OSV.dev batch queries, CVSS v3.1 scoring, severity mapping npm-registry.js npm registry metadata + provenance attestations pypi-registry.js PyPI JSON API metadata analysis/ ast-inspector.js Acorn-based AST analysis (JS) + pattern matching (Python) signals.js Signal orchestrator, composite risk scoring dep-graph.js Dependency graph profiling, typosquat detection behavioral.js Capability fingerprinting, version diffing tarball-inspector.js Tarball download, tar parsing, source inspection diff.js Lockfile snapshot diffing provenance.js Sigstore provenance verification cache/ advisory-cache.js SQLite-backed cache with TTL, corruption recovery vendor/ acorn.mjs Vendored acorn parser (zero npm deps) test/ test-ast-inspector.js AST detection + false positive tests test-behavioral.js Behavioral profiling + diffing test-cache.js SQLite cache, TTL, corruption resilience test-dep-graph.js Typosquat detection test-parse-args.js Argument parser test-parsers.js All lockfile/manifest parsers test-redteam.js 9 real-world attack reconstructions test-robustness.js Input validation, edge cases, security ``` ## 安全设计原则 1. **异常时大声报错，而不是静默通过。** 在失败时静默报告安全的扫描器比无用更糟糕。如果查询失败，vexes 会以退出代码 2 退出并打印 `SCAN INCOMPLETE`。无效的生态系统会被直接拒绝，而不是静默地什么都不扫。 2. **零依赖。** 依赖链就是攻击面。vexes 没有任何外部依赖。Acorn 是直接拷贝源码提供的。SQLite 是 Node.js 内置的。 3. **终端注入保护。** 所有外部数据都经过全面的过滤器净化，涵盖 CSI 序列（带中间字节）、OSC（BEL 和 ST 终止符）、DCS/APC/PM/SOS 序列、C1 控制码 (0x80-0x9F) 和裸 ESC 字节。 4. **原型污染保护。** 配置文件合并时会拒绝 `__proto__`、`constructor` 和 `prototype` 键。 5. **命令注入防御。** guard 命令使用 `execFileSync`（不经过 shell）并配合已知包管理器的白名单。修复命令在显示前经过 Shell 转义处理。Guard 设置在安装时解析 vexes 二进制文件路径，而不是在运行时使用 `npx`。 6. **Gzip 炸弹 + SSRF 保护。** Tarball 下载强制执行流式大小限制、仅限 HTTPS 的 URL，以及 registry 主机白名单，以防止内存耗尽和 SSRF 攻击。 7. **缓存完整性。** 损坏的条目会被自动删除。降级的结果从不被缓存。TTL 数值会被限制，以防止基于配置的过期数据攻击（建议最多 7 天，元数据最多 30 天）。 8. **绝不推荐带有漏洞的修复版本。** `fix` 命令在展示每个推荐版本之前，都会与 OSV 进行交叉核对。 9. **严重信号不可禁用。** `KNOWN_COMPROMISED`、`PHANTOM_DEPENDENCY`、`CIRCULAR_STAGING` 和 `CAPABILITY_ESCALATION` 无法通过配置关闭——因为它们检测的是正在进行的主动攻击。 10. **白名单内的包依然会被检查。** 已知安全的包（esbuild、sharp 等）的信号只是降低权重，并没有被抑制。不管是否在白名单内，AST 分析都会在所有包上运行。 11. **Unicode 同形字检测。** 程序会检查包名中是否包含可用于伪装恶意软件包的不可见字符（零宽度空格、BIDI 覆盖）和非 ASCII 同形字。 12. **感知完整性的 lockfile 差异对比。** Guard 通过比较完整性哈希，可以检测出包的 tarball 在没有版本号变更的情况下被篡改的情况。 ## 许可证 Apache-2.0 ## 作者 Shadoe Myers ([@penumbraforge](https://github.com/penumbraforge))

标签：Cargo, DNS 解析, GNU通用公共许可证, Homebrew, IP 地址批量处理, MITM代理, Node.js, Node.js安全工具, npm, npm安全, PyPI, RAT检测, Typosquatting检测, 依赖图谱, 依赖安全检测, 加密, 漏洞扫描器, 网络安全, 自定义脚本, 行为指纹, 跨生态系统, 错误基检测, 隐私保护, 零依赖, 静态代码分析