maxgfr/package-checker.sh
GitHub: maxgfr/package-checker.sh
一款零依赖的轻量级 shell 脚本，用于检测 Node.js/Bun/Deno 项目中的 vulnerable npm 依赖包。
Stars: 3 | Forks: 0
# package-checker.sh
一款灵活、轻量的 shell 脚本，用于检测存在漏洞的 npm 包。内置 GHSA 和 OSV 漏洞源，包含 200,000+ 条漏洞数据，也支持使用自定义数据库。
## 📦 概述
**package-checker.sh** 可扫描您的 JavaScript/TypeScript 项目中的漏洞依赖。支持 npm、Yarn、pnpm、Bun 和 Deno 项目。
### 核心功能
- **内置漏洞源**：包含 GHSA 和 OSV 源，涵盖 200,000+ 条 npm 漏洞（每 12 小时自动更新）
- **提供 Docker 镜像**：完整镜像（约 43MB，含数据源）或轻量镜像（约 27MB）
- **自定义数据源**：添加您自己的 JSON、CSV 或 PURL 漏洞列表
- **扫描器集成**：导入外部工具生成的 SARIF、SBOM 或 Trivy JSON
- **版本范围**：支持定义如 `>=1.0.0 <2.0.0` 的范围，无需列出每个版本
- **多包管理器支持**：全面支持 npm、Yarn (Classic & Berry/v2+)、pnpm、Bun 和 Deno
- **GitHub 集成**：直接从 GitHub 扫描整个组织或单个仓库
- **零依赖**：仅需 `bash`、`awk` 和 `curl`
- **灵活配置**：支持使用 CLI 参数或 `.package-checker.config.json` 配置文件
### 前置条件
- **bash** — Shell 解释器
- **awk** (gawk 或 mawk) — 通常已预装
- **curl** — 用于访问远程源和 GitHub API
- 或者使用 Docker 镜像（无需安装）
## 🚀 快速开始
### 方式 1：Homebrew 安装（推荐 macOS/Linux 使用）
安装和使用 `package-checker` 的最简单方法：
```
# 安装 package-checker
brew install maxgfr/tap/package-checker
# 直接使用（自动使用默认 GHSA feed）
package-checker
# 或显式指定 GHSA feed
package-checker --default-source-ghsa
# 或同时使用 GHSA 和 OSV feeds
package-checker --default-source-ghsa-osv
# 检查特定 package 版本
package-checker --package-name express --package-version 4.17.1
# 使用自定义漏洞文件扫描
package-checker --source custom-vulns.json
```
### 方式 2：一键安装并运行（最快）
配合您自己的漏洞数据，直接从网络运行：
```
# 使用远程漏洞源运行
curl -sS https://raw.githubusercontent.com/maxgfr/package-checker.sh/main/script.sh | bash -s -- --source https://raw.githubusercontent.com/maxgfr/package-checker.sh/refs/heads/main/data/ghsa.purl
# 或使用本地源文件
curl -sS https://raw.githubusercontent.com/maxgfr/package-checker.sh/main/script.sh | bash -s -- --source ./vulns.json
```
### 方式 3：使用 Docker
获取内置漏洞源最简单的方法：
```
# 扫描当前目录（自动使用默认 GHSA feed）
docker run -v $(pwd):/workspace ghcr.io/maxgfr/package-checker.sh:latest
# 或显式使用 GHSA feed
docker run -v $(pwd):/workspace ghcr.io/maxgfr/package-checker.sh:latest --default-source-ghsa
# 或同时使用 GHSA 和 OSV feeds 以获得全面覆盖
docker run -v $(pwd):/workspace ghcr.io/maxgfr/package-checker.sh:latest --default-source-ghsa-osv
# 扫描特定子目录
docker run -v $(pwd):/workspace ghcr.io/maxgfr/package-checker.sh:latest /workspace/my-project --default-source-ghsa-osv
# 配合您自己的数据文件使用
docker run -v $(pwd):/workspace ghcr.io/maxgfr/package-checker.sh:latest --source my-vulns.json
```
### 基本用法示例
```
# 扫描当前目录（自动使用默认 GHSA source）
package-checker
# 扫描特定目录（相对或绝对路径）
package-checker ./my-project
package-checker /absolute/path/to/project
# 同时使用 GHSA 和 OSV sources 以获得全面覆盖
package-checker --default-source-ghsa-osv
# 仅使用 OSV source 而非默认 GHSA
package-checker --default-source-osv
# 检查特定 package 版本
package-checker --package-name express --package-version 4.17.1
# 使用版本范围检查
package-checker --package-name lodash --package-version '^4.17.0'
# 使用自定义漏洞文件扫描
package-checker --source custom-vulns.json
# 使用自定义 source 扫描特定文件夹
package-checker ./subfolder --source custom-vulns.json
# 多 sources（内置 + 自定义）
package-checker --default-source-ghsa-osv --source custom-vulns.csv
# 使用配置文件
package-checker --config .package-checker.config.json
# 扫描 GitHub organization
package-checker --default-source-ghsa-osv --github-org myorg --github-token $GITHUB_TOKEN
```
## 👀 命令行选项
```
ARGUMENTS:
PATH Directory to scan (default: current directory)
Can be relative (./my-project) or absolute (/path/to/project)
OPTIONS:
-h, --help Show help message
-s, --source SOURCE Vulnerability source (repeatable for multiple sources)
--default-source-ghsa Use default GHSA source (default if no source specified)
--default-source-osv Use default OSV source
--default-source-ghsa-osv Use both default GHSA and OSV sources (recommended for comprehensive coverage)
-f, --format FORMAT Data format: json, csv, purl, sarif, sbom-cyclonedx, or trivy-json (auto-detected from extension)
--csv-columns COLS CSV columns: "name,versions" or "1,2"
--package-name NAME Check vulnerability for a specific package name
--package-version VER Check specific version (requires --package-name)
-c, --config FILE Path to configuration file
--no-config Skip loading configuration file
--export-json FILE Export vulnerability results to JSON format (default: vulnerabilities.json)
--export-csv FILE Export vulnerability results to CSV format (default: vulnerabilities.csv)
--github-org ORG GitHub organization to scan
--github-repo owner/repo Single GitHub repository to scan
--github-token TOKEN GitHub token (or use GITHUB_TOKEN env var)
--github-output DIR Output directory for fetched files (default: ./packages)
--github-only Only fetch from GitHub, skip local analysis
--create-multiple-issues Create one GitHub issue per vulnerable package (requires --github-token)
--create-single-issue Create a single consolidated issue with all vulnerabilities (requires --github-token)
--fetch-all DIR Fetch all vulnerability feeds (osv.purl, ghsa.purl) to specified directory
--fetch-osv FILE Fetch OSV vulnerability feed to specified file
--fetch-ghsa FILE Fetch GHSA vulnerability feed to specified file
--only-package-json Scan only package.json files (skip lockfiles)
--only-lockfiles Scan only lockfiles (skip package.json files)
--lockfile-types TYPES Comma-separated list of lockfile types to scan (npm, yarn, pnpm, bun, deno)
```
## ⚙️ 数据格式与配置
package-checker.sh 支持多种漏洞数据格式：
### 支持的格式
**内置源（推荐）：**
- `data/ghsa.purl` - GitHub Security Advisories（约 5,000 条漏洞）
- `data/osv.purl` - Open Source Vulnerabilities（约 207,000 条漏洞）
**自定义格式：**
- **JSON** - 带版本范围的简单键值格式
- **CSV** - 表格格式
- **PURL** - Package URL 标准格式
- **SARIF** - 静态分析结果（Trivy, Semgrep, CodeQL）
- **SBOM CycloneDX** - 软件物料清单
- **Trivy JSON** - 原生 Trivy 输出格式
### 快速示例
**JSON 格式：**
```
{
"express": {
"versions": ["4.16.0", "4.16.1"],
"versions_range": [">=4.0.0 <4.17.21"]
}
}
```
**CSV 格式：**
```
name,versions
express,4.16.0
lodash,">=4.17.0 <4.17.21"
```
**PURL 格式：**
```
pkg:npm/lodash@4.17.20
pkg:npm/express@>=4.0.0 <4.17.21
pkg:npm/@babel/traverse@7.23.0
```
**配置文件 (`.package-checker.config.json`)：**
```
{
"sources": [
{
"source": "https://example.com/vulnerabilities.json",
"name": "Company Security Database"
}
],
"options": {
"ignore_paths": ["node_modules", ".yarn", ".git", "dist"]
}
}
```
完整的格式规范请参阅 [数据格式文档](docs/data-formats.md)。
### 扫描内容
**Lockfiles**（精确版本匹配）：
- `package-lock.json`, `npm-shrinkwrap.json` (npm)
- `yarn.lock` (Yarn Classic & Yarn Berry/v2+)
- `pnpm-lock.yaml` (pnpm)
- `bun.lock` (Bun)
- `deno.lock` (Deno)
**package.json**（依赖检查）：
- `dependencies`, `devDependencies`, `optionalDependencies`, `peerDependencies`
### 过滤文件类型
默认情况下，package-checker **同时**扫描 lockfiles 和 package.json 文件。您可以控制扫描内容：
**仅扫描 package.json 文件：**
```
# 跳过所有 lockfiles，仅扫描 package.json
package-checker --source vulns.json --only-package-json
```
**仅扫描 lockfiles：**
```
# 跳过 package.json 文件，仅扫描 lockfiles
package-checker --source vulns.json --only-lockfiles
```
**扫描特定类型的 lockfile：**
```
# 仅扫描 yarn.lock 文件
package-checker --source vulns.json --lockfile-types yarn
# 仅扫描 npm 和 yarn lockfiles（跳过 pnpm, bun, deno）
package-checker --source vulns.json --lockfile-types npm,yarn
# 与 --only-lockfiles 结合使用
package-checker --source vulns.json --only-lockfiles --lockfile-types yarn
```
可用的 lockfile 类型：`npm`, `yarn`, `pnpm`, `bun`, `deno`
### 导出结果
您可以将扫描结果导出为 JSON 或 CSV 格式，以便进一步分析、报告或与其他工具集成。
**导出为 JSON：**
```
# 使用自定义文件名导出
package-checker --source vulns.json --export-json results.json
```
**导出为 CSV：**
```
# 使用自定义文件名导出
package-checker --source vulns.json --export-csv results.csv
```
**同时导出两种格式：**
```
package-checker --source vulns.json --export-json output.json --export-csv output.csv
```
**JSON 导出格式：**
JSON 导出包含详细的漏洞元数据信息：
```
{
"vulnerabilities": [
{
"package": "express@4.16.0",
"file": "./package-lock.json",
"severity": "medium",
"ghsa": "GHSA-rv95-896h-c2vc",
"cve": "CVE-2022-24999",
"source": "ghsa"
}
],
"summary": {
"total_unique_vulnerabilities": 5,
"total_occurrences": 12
}
}
```
**CSV 导出格式：**
CSV 导出以表格格式包含相同的元数据：
```
package,file,severity,ghsa,cve,source
express@4.16.0,./package-lock.json,medium,GHSA-rv95-896h-c2vc,CVE-2022-24999,ghsa
lodash@4.17.20,./package-lock.json,high,GHSA-p6mc-m468-83gw,CVE-2020-8203,ghsa
```
**注意：**
- 导出内容仅包含发现漏洞的包
- 当漏洞数据库中存在相应信息时，将包含元数据字段
- 有关向漏洞源添加元数据的详细信息，请参阅 [数据格式文档](docs/data-formats.md)
## 🔄 CI/CD 集成
使用可复用的 GitHub Actions 工作流实现零配置漏洞扫描：
```
name: Security Check
on:
push:
branches: [ main ]
pull_request:
workflow_dispatch:
schedule:
- cron: '0 0 * * 1' # Weekly on Monday
jobs:
vulnerability-check:
uses: maxgfr/package-checker.sh/.github/workflows/reusable-check.yml@main
with:
use-osv: true # Add OSV in addition to default GHSA
fail-on-vulnerabilities: true
```
**优势：**
- 无需安装或配置
- 默认使用内置 GHSA 源（每 12 小时自动更新，包含 200,000+ 条漏洞）
- 可选添加 OSV 源以获得更全面的覆盖
- 支持 npm、Yarn、pnpm、Bun 和 Deno 项目
- 在 PR 检查中自动生成安全报告
更多示例以及其他 CI 系统（GitLab CI 等），请参阅 [CI/CD 集成文档](docs/ci.md)。
## 🧑💻 GitHub 集成
**扫描整个组织：**
```
package-checker --github-org myorg --github-token ghp_xxx --source vulns.json
```
**扫描单个仓库：**
```
# 公开 repo（无需 token）
package-checker --github-repo owner/repo --source vulns.json
# 私有 repo（需要 token）
package-checker --github-repo owner/private-repo --github-token ghp_xxx --source vulns.json
```
**仅获取（不进行分析）：**
```
package-checker --github-org myorg --github-token ghp_xxx --github-only --github-output ./packages
```
**自动为漏洞创建 GitHub Issues：**
```
# 为每个有漏洞的 package 创建一个 issue
package-checker --github-org myorg --github-token ghp_xxx --source vulns.json --create-multiple-issues
# 创建包含所有漏洞的单个汇总 issue
package-checker --github-repo owner/repo --github-token ghp_xxx --source vulns.json --create-single-issue
```
**Issue 创建模式：**
| 标志 | 描述 |
|------|-------------|
| `--create-multiple-issues` | 为**每个有漏洞的包创建一个 Issue**，包含详细的漏洞信息 |
| `--create-single-issue` | 创建**一个合并的 Issue**，在单个报告中包含所有漏洞 |
两种模式均包含：
- 带有视觉指示器的严重级别 (🔴 Critical, 🟠 High, 🟡 Medium, 🟢 Low)
- GHSA 公告和 CVE 详情链接
- 受影响的文件和版本
- 修复建议
- 自动标记 `security`、`vulnerability` 和 `dependencies` 标签
**注意：** 两个标志都需要具有 `repo` 权限的 GitHub token 才能创建 Issue。
## 😎 直接查询包
您**无需数据源或扫描项目**即可检查特定的包或版本是否存在漏洞：
```
# 检查特定版本是否有漏洞
package-checker --package-name next --package-version 16.0.3
# 使用版本范围检查
package-checker --package-name lodash --package-version '^4.17.0'
# 列出 package 在您项目中的所有出现位置
package-checker --package-name express
```
此功能会在内部创建一个虚拟 PURL 并在您的项目中扫描它。
**使用场景：**
- 安装前检查：“在我执行 `npm install` 之前，这个版本安全吗？”
- 快速查询：“正在使用这个包的哪些版本？”
- 安全研究：“这个有漏洞的包在我的代码库的什么位置？”
- 版本范围测试：“`^4.17.0` 是否覆盖了有漏洞的版本？”
**支持的版本范围：**
- 精确版本：`1.2.3`
- 大于/小于：`>=1.0.0 <2.0.0`
- 波浪号范围：`~1.2.3` (等同于 `>=1.2.3 <1.3.0`)
- 插入号范围：`^1.2.3` (等同于 `>=1.2.3 <2.0.0`)
- 通配符：`*` (匹配任何版本)
## 📚 文档与资源
更多详细信息，请参阅 [`docs/`](docs/) 目录：
- **[为什么选择 package-checker.sh？](docs/why.md)** — 了解此工具存在的原因及其如何补充其他漏洞扫描器
- **[Docker 使用指南](docs/docker.md)** — 使用 Docker 镜像的完整指南
- **[数据格式](docs/data-formats.md)** — JSON、CSV、PURL 格式的完整规范
- **[漏洞源](docs/vulnerability-feeds.md)** — 内置 GHSA/OSV 源指南及生成自定义源
- **[漏洞扫描工具](docs/vulnerability-scanning-tools.md)** — Trivy、Grype、Syft、OSV-Scanner 及其他工具指南
- **[配置](docs/configuration.md)** — 详细配置参考
- **[GitHub 集成](docs/github.md)** — 高级 GitHub 扫描功能
- **[CI/CD 集成](docs/ci.md)** — GitHub Actions、GitLab CI 等示例
- **[测试](docs/testing.md)** — 测试指南、固件和示例
- **[贡献](docs/contributing.md)** — 开发工作流、提交规范和版本管理
### 应用场景
- **安全团队**：维护内部漏洞数据库
- **合规性**：执行公司特定的安全策略
- **CI/CD 流水线**：自动化漏洞检查
- **应急响应**：安全事件期间的快速扫描
- **供应链安全**：监控跨多个项目的依赖项
## 📄 许可证
MIT 许可证 — 详情请参阅 [`LICENSE`](LICENSE) 文件。
**有问题或遇到问题？** 请在 [GitHub](https://github.com/maxgfr/package-checker.sh/issues) 上提交 Issue。
标签：Bun, Cutter, Deno, GHSA, GNU通用公共许可证, IP 地址批量处理, JavaScript安全, LNA, Node.js, NPM包安全, OSV, SARIF, SBOM, Shell脚本, TypeScript, Vercel, 子域名暴力破解, 安全可观测性, 安全插件, 应用安全, 文档安全, 暗色界面, 版本控制, 硬件无关, 系统独立性, 自动化检测, 请求拦截, 零依赖