patchstack/connect
GitHub: patchstack/connect
Patchstack 官方的 JavaScript/Node.js 依赖漏洞监控连接器，通过扫描 lockfile 并上报包清单来实现持续的依赖项漏洞匹配与预警。
Stars: 1 | Forks: 0
# @patchstack/connect
将 JavaScript / Node.js 应用连接到 [Patchstack](https://patchstack.com) 以进行持续的漏洞监控。它会扫描您的 `package-lock.json` 并报告已安装的包，以便 Patchstack 将其与自身的漏洞数据库进行匹配，并在需要修补时通知您。
关于此代码库如何融入更广泛的 Patchstack 生态系统（`saas`、`hub`、`patchstack-website`、`patchstack-connect`），请参阅 [`patchstack/saas` → `docs/ecosystem.md`](https://github.com/patchstack/saas/blob/main/docs/ecosystem.md)。
## 安装提示词（针对 AI 编程工具）
将此提示词复制并粘贴到任何 AI 编程助手中（Cursor、v0、Bolt、Lovable、Claude Code 等）：
## 快速开始（零配置）
```
npm install --save-dev @patchstack/connect
npx @patchstack/connect scan
```
这样就行了。首次 `scan`：
1. 读取您的 lockfile（参见*支持的 lockfile*）。
2. 在**没有** UUID 的情况下将包列表 POST 到 Patchstack。
3. Patchstack 会配置一个新站点并返回其 UUID。
4. 连接器将 UUID 写入 `.patchstackrc.json`，以便下一次 `scan` 针对同一站点。
5. 连接器会打印一个认领 URL —— 在浏览器中打开它即可将新站点附加到您的 Patchstack 账户。您可以随时使用 `npx @patchstack/connect status` 重新显示该 URL。
然后将其接入构建流程：
```
// package.json
{
"scripts": {
"prebuild": "patchstack-connect scan"
}
}
```
## 快速开始（现有站点）
如果您已经在 Patchstack 控制面板中创建了“Application”（应用程序）站点，请预先填充 UUID：
```
npm install --save-dev @patchstack/connect
npx @patchstack/connect init
npx @patchstack/connect scan
```
## CLI
```
patchstack-connect scan [options] Scan the lockfile and POST to Patchstack.
If no UUID is configured the server provisions
one and the connector persists it.
patchstack-connect init Optional: pre-seed .patchstackrc.json with
an existing site UUID
patchstack-connect status [options] Show current configuration
patchstack-connect help Print help
Options (for scan and status):
--site-uuid Override the configured site UUID
--endpoint Override the API endpoint
--dry-run (scan only) Print the payload without posting
```
## 配置
优先级（最高者优先）：
1. CLI 标志（`--site-uuid`、`--endpoint`）
2. 环境变量
3. 当前目录下的 `.patchstackrc.json`
环境变量：
- `PATCHSTACK_SITE_UUID` — 来自您 Patchstack 控制面板的站点 UUID
- `PATCHSTACK_ENDPOINT` — 覆盖 API endpoint（默认为 `https://api.patchstack.com/monitor/pulse/manifest`）
- `PATCHSTACK_TIMEOUT_MS` — 请求超时时间（以毫秒为单位，默认为 `30000`）
`.patchstackrc.json` 示例：
```
{
"siteUuid": "550e8400-e29b-41d4-a716-446655440000"
}
```
站点 UUID 是唯一的凭证。拥有该 UUID 即被授予为该站点提交清单的权限，因此请像对待 API token 一样处理它：不要将其放在公开的代码仓库中，并且在 CI 环境中优先使用环境变量。
## 编程式 API
```
import { scanAndReport } from '@patchstack/connect';
const result = await scanAndReport();
console.log(result.response.stored ? 'Reported' : 'Unchanged');
```
同时也导出了底层的组件：`scanLockfile`、`buildWirePayload`、`postManifest`、`resolveConfig`。
## 发送的内容
```
{
"ecosystem": "npm",
"packages": [
{ "name": "axios", "version": "1.6.0" },
{ "name": "lodash", "version": "4.17.15" },
{ "name": "lodash", "version": "4.17.21" }
]
}
```
这就是完整的 payload。不包含源代码、环境变量或文件路径 —— 仅有来自您 lockfile 的包名称和版本。具有不同版本的同名包会被保留，这样就不会遗漏传递性漏洞。
## 支持的 lockfile
- ✅ `package-lock.json` (npm v6 / v2 / v3) — 直接解析
- ✅ `pnpm-lock.yaml` (pnpm v5 / v6 / v7 / v8 / v9) — 直接解析
- ✅ `yarn.lock` (yarn classic v1 和 yarn berry v2+) — 直接解析
- ✅ `bun.lockb` (二进制) — 通过遍历 `node_modules/` 解析包列表
- ✅ `bun.lock` (文本) — 采用相同的回退机制；后续将支持直接解析
如果同时存在 Bun lockfile 和 `node_modules/`，连接器将遍历 `node_modules/` 以枚举已安装的包。请在扫描前运行 `bun install`（或 `npm install`），以便填充该目录。
### 过期的 lockfile
每个被扫描的源都会与 `package.json` 进行验证：如果选定的 lockfile 缺少 `package.json` 中声明的依赖，它将被视为陈旧文件（例如，在由 bun 管理的项目中由一次性 `npm install` 生成的 `package-lock.json`），连接器会回退到下一个源 —— 最终遍历已安装事实的 `node_modules/` —— 并打印一条警告，指出该过期文件的名称。删除过期的 lockfile 即可消除该警告。如果不这样做，当真实的依赖集发生偏离时，清单和构建指纹将悄无声息地停止更新。
## 开发
```
npm install
npm run typecheck
npm test
npm run build
```
### Manifest endpoint 测试
要将当前的 lockfile 清单 POST 到本地的 Patchstack API endpoint 并配置新站点：
```
bun run test:manifest -- --endpoint http://localhost:8000/monitor/pulse/manifest
```
响应应包含新的站点 UUID。要重新测试现有站点，请显式传入该 UUID：
```
bun run test:manifest -- --endpoint http://localhost:8000/monitor/pulse/manifest --site-uuid YOUR_REAL_UUID
```
使用 `--dry-run` 可以在不进行 POST 的情况下预览 payload。
## 发布流程
Pull request 会在 GitHub Actions 中运行类型检查、测试、构建、包验证以及生产环境依赖审计。
当发布 GitHub Release 时会触发发布流程。Release 标签必须与 `package.json` 中的包版本相匹配，并带有前缀 `v`。例如，`package.json` 版本 `0.2.0` 必须使用标签 `v0.2.0` 发布；否则工作流将在发布前失败。
要发布一个版本：
1. 提升包版本，例如 `npm version 0.2.0 --no-git-tag-version`。
2. 提交 `package.json` 和 `package-lock.json`。
3. 将版本提升合并到 `main` 分支。
4. 创建并发布标记为 `v0.2.0` 的 GitHub Release。
5. `Publish` 工作流会验证包，然后运行 `npm publish --provenance --access public`。
在首次发布之前，请为此包配置 npm trusted publishing：
1. 将 `.github/workflows/publish.yml` 合并到 `main`。
2. 在 npmjs.com 上打开 `@patchstack/connect` 包设置。
3. 在 **Trusted publishing** 中，选择 **GitHub Actions**。
4. 配置：
- 组织/用户：`patchstack`
- 仓库：`connect`
- 工作流文件名：`publish.yml`
- 环境名称：`npm`
5. 在 GitHub 仓库设置中，创建一个 `npm` 环境。可选但建议的操作：要求对该环境进行人工审批。
请勿为此工作流向 GitHub secrets 添加 npm 发布 token。Trusted publishing 使用 GitHub OIDC 短期凭证。在首次 trusted publishing 成功后，npm 建议将包发布访问权限设置为需要双重身份验证并禁用 token。
## 许可证
MIT
标签：CMS安全, DevSecOps, GNU通用公共许可证, JavaScript, LNA, MITM代理, Node.js, 上游代理, 依赖管理, 数据可视化, 暗色界面, 漏洞监控, 自动化攻击