# @bun-security-scanner/npm 中文文档

规范地址：https://npmcn.com/package/%40bun-security-scanner/npm/

版本：1\.0\.0
npm 元数据更新时间：2025-11-06T13:25:40.826Z
中文译文更新时间：2026-11-08T19:38:43.506Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bun-security-scanner/npm
原文对照：https://npmcn.com/package/%40bun-security-scanner/npm/?lang=original
项目主页：https://npm.bun-security-scanner.com/
源码仓库：https://github.com/bun-security-scanner/npm

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：52.6 kB，15 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2025-11-06T13:25:39.843Z
- 最新版本发布：2025-11-06T13:25:40.218Z
- 近 30 天下载量：5557（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 0 个）

## 中文简介

npm 使用 GitHub 咨询数据库为 Bun 项目进行的注册脆弱性扫描仪

## 安装

```sh
npm install @bun-security-scanner/npm
```

也可以使用：`pnpm add @bun-security-scanner/npm`、`yarn add @bun-security-scanner/npm`、`bun add @bun-security-scanner/npm`

## README

![Bun npm Scanner](https://npmcn.com/package/%40bun-security-scanner/npm/docs/icons/logo.svg)

# 扫描机

用于生产级安全扫描仪 [阿宝](https://bun.sh/) 与 npm 注册的 [GitHub 咨询数据库](https://github.com/advisories) 在安装时检测 npm 包中已知的弱点.

[![npm version](https://img.shields.io/npm/v/@bun-security-scanner/npm?color=dc2626)](https://npmjs.com/package/@bun-security-scanner/npm) [![npm downloads](https://img.shields.io/npm/dm/@bun-security-scanner/npm?color=dc2626)](https://npmjs.com/package/@bun-security-scanner/npm) [![License: MIT](https://img.shields.io/badge/License-MIT-dc2626)](https://npmcn.com/package/%40bun-security-scanner/npm/LICENSE) [![Built with Claude](https://img.shields.io/badge/Built_with-Claude-dc2626?style=flat&logo=claude&logoColor=dc2626)](https://anthropic.com/claude-code) [![Checked with Biome](https://img.shields.io/badge/Checked_with-Biome-dc2626?style=flat&logo=biome&logoColor=dc2626)](https://biomejs.dev/)

## GitHub 咨询数据库是什么 ?

这个 [GitHub 咨询数据库](https://github.com/advisories) 为开源项目提供安全脆弱性信息。 这是:

-   **权威**: 由GitHub和开源安全社区维护
-   **综合**: 包括npm安保顾问和其他来源
-   **最新数据**: 不断更新最新安全咨询意见
-   **npm 的官方数据库**: 使用相同的数据库 `bun audit` 或者说 `npm audit`

## 为什么要用这个扫描仪?

**替代信任模式**:不同于其他依赖Google的OSV.dev数据库的扫描仪,此扫描仪使用由GitHub的咨询数据库提供动力的npm注册的官方脆弱性数据库. 该条规定:

-   **直接来源**: 直接查询npm注册(registry.npmjs.org)
-   **微软/GitHub 基础设施**: 使用微软/ GitHub 而不是 Google 的数据主权
-   **官方 npm 数据**: 使用与 `npm audit` 财务报告和审定财务报表 `bun audit`
-   **土著融合**:Leverages Bun的内置gzip压缩和性能特性

## 特征

-   **实时扫描**: 安装时对照 npm 注册检查软件包
-   **GitHub 咨询数据库**: 使用 npm 的官方脆弱性数据库
-   **高性能**: 有 gzip 压缩的高效批量查询
-   **失败安全**: 从未因扫描仪出错而屏蔽安装
-   **结构化日志**: 与背景资料相匹配的伐木水平
-   **精确匹配**: 使用 semver 精确的易发性与包装版本匹配
-   **可配置**: 所有设置的环境变量配置
-   **无依赖**: 只使用 Bun 内置特性和 Zod 验证

## 安装

**不需要 API 密钥或注册** - 完全自由使用,除安装外,零设置.

```bash
# Install as a dev dependency
bun add -d @bun-security-scanner/npm
```

## 配置

### 1\. 启用扫描仪

添加到您的 `bunfig.toml`数字 :

```toml
[install.security]
scanner = "@bun-security-scanner/npm"
```

### 2\. 可选:配置选项

扫描仪可以通过环境变量配置:

```bash
# Logging level (debug, info, warn, error)
export NPM_SCANNER_LOG_LEVEL=info

# Custom npm registry URL (optional)
export NPM_SCANNER_REGISTRY_URL=https://registry.npmjs.org

# Request timeout in milliseconds (default: 30000)
export NPM_SCANNER_TIMEOUT_MS=30000
```

## 如何运作

### 安全扫描过程

1.  **软件包检测**: Bun 安装时提供软件包信息
2.  **智能复制**: 消除重复软件包@ version results
3.  **批量查询**: 使用 npm 登记簿 `/npm/v1/security/advisories/bulk` 结束点
4.  **Gzip 压缩**: 压缩请求的有效载荷以达到最佳性能
5.  **版本匹配**: 使用 Bun 的组合以匹配易被攻击的版本范围
6.  **咨询组**: 创建可采取行动的安全咨询

### 咨询级别

扫描仪根据npm重度生成两种安全建议:

#### 致命( 安装受阻)

-   **严重性**数字 : `critical` 或者说 `high`
-   **行动**: 安装立即被屏蔽
-   **实例**:远程代码执行,特权升级,数据曝光

#### 警告( 用户提示)

-   **严重性**数字 : `moderate`, (中文(简体) ), `low`,或 `info`
-   **行动**: 提示用户继续或取消
-   **类型**: 介绍互动选择
-   **非TTY类**: 安装自动取消
-   **实例**:拒绝服务、信息披露、贬值警告

### 处理错误哲学

扫描仪跟随 **失败安全** 办法:

-   网络错误不会阻碍安装
-   错误的反应被记录,但不要停止进程
-   扫描器崩溃返回空咨询阵列( 允许安装)
-   只有真正的安全威胁才能防止安装软件包

## 用法实例

### 基本用途

```bash
# Scanner runs automatically during installation
bun install express
# -> Checks express and all dependencies for vulnerabilities

bun add lodash@4.17.20
# -> May warn about known lodash vulnerabilities in older versions
```

### 发展用途

```bash
# Enable debug logging to see detailed scanning information
NPM_SCANNER_LOG_LEVEL=debug bun install

# Test with a known vulnerable package
bun add event-stream@3.3.6
# -> Should trigger security advisory
```

### 配置示例

```bash
# Increase timeout for slow networks
NPM_SCANNER_TIMEOUT_MS=60000 bun install

# Use custom registry (advanced)
NPM_SCANNER_REGISTRY_URL=https://registry.custom.com bun install
```

## 建筑

扫描仪采用模块化、可生产的结构:

```
src/
├── index.ts              # Main scanner implementation
├── client.ts             # npm registry API client with gzip support
├── processor.ts          # Advisory processing and Bun advisory generation
├── cli.ts                # CLI interface for testing
├── schema.ts             # Zod schemas for npm audit API responses
├── constants.ts          # Centralized configuration management
├── logger.ts             # Structured logging with configurable levels
├── retry.ts              # Robust retry logic with exponential backoff
├── severity.ts           # npm severity mapping and assessment
└── types.ts              # TypeScript type definitions
```

### 关键设计原则

1.  **关注的分离**:每个模块都有一个单一、明确界定的责任
2.  **隔离错误**: 一个组件的故障不会连结到其他组件
3.  **性能优化**: 批量处理、分解和gzip压缩
4.  **观察性**:用于调试和监测的全面记录
5.  **类型安全**: 包含运行时间验证的全类型脚本覆盖

## 与其他扫描仪的比较

| 特性 | 扫描机 | 包子扫描器 |
| --- | --- | --- |
| **数据库** | npm/ GitHub 咨询 | 谷歌 OSV.dev |
| **提供者** | 微软/ GitHub | 谷歌 |
| **压缩** | 原生 gzip | 无 |
| **API 调用** | 单一批量请求 | 批量 + 个人细节 |
| **生态系统** | 以 npm 为焦点 | 多生态系统 |
| **信托模式** | npm 官方来源 | 合计来源 |

## 测试

```bash
# Run the test suite
bun test

# Run with coverage
bun test --coverage

# Type checking
bun run typecheck

# Linting
bun run lint
```

## 发展

### 来源建筑

```bash
git clone https://github.com/bun-security-scanner/npm.git
cd npm
bun install
bun run build
```

### 捐款

我们不接受拉动请求,因为这一一揽子计划得到了积极维护。 然而,我们赞赏开发人员报告错误或建议特性来自 [打开一个问题](https://github.com/bun-security-scanner/npm/issues/new)。 。 。 .

## API 参考

### npm 审计整合

扫描仪与 npm 登记册批量咨询终点集成 :

-   **POST /-/npm/v1/ 安保/咨询/邮包**: gzip 压缩的批量咨询查询

请求格式 :

```json
{
  "package-name": ["1.0.0", "2.0.0"],
  "another-package": ["3.0.0"]
}
```

反应格式 :

```json
{
  "advisory-id": {
    "id": "GHSA-xxxx-xxxx-xxxx",
    "title": "Vulnerability title",
    "name": "package-name",
    "severity": "high",
    "vulnerable_versions": ">=1.0.0 <2.0.0",
    "url": "https://github.com/advisories/GHSA-xxxx-xxxx-xxxx",
    "overview": "Detailed description..."
  }
}
```

### 配置参考

| 环境变量 | 默认 | 说明 |
| --- | --- | --- |
| `NPM_SCANNER_LOG_LEVEL` | `info` | 日志级别:调试、信息、警告、错误 |
| `NPM_SCANNER_REGISTRY_URL` | `https://registry.npmjs.org` | npm 注册基址 |
| `NPM_SCANNER_TIMEOUT_MS` | `30000` | 请求超时( 毫秒) |

## 解决问题

### 共同问题

**安装时没有运行扫描器吗 ?**

-   校验 `bunfig.toml` 配置
-   检查该软件包是否被安装为 dev 依赖
-   启用调试记录 : `NPM_SCANNER_LOG_LEVEL=debug bun install`

**网络超时?**

-   增加超时 : `NPM_SCANNER_TIMEOUT_MS=60000`
-   请检查access-date=中的日期值 (帮助) 互联网连接 register.npmjs.org
-   考虑公司防火墙限制

**太多假阳性?**

-   npm咨询数据库数据是权威的 - 手动验证弱点
-   检查您是否使用过时的软件包版本
-   向 GitHub 安全顾问报告假阳性

### 调试模式

启用全面的调试输出 :

```bash
NPM_SCANNER_LOG_LEVEL=debug bun install your-package
```

这表明:

-   套件复制统计
-   API 请求/答复详情
-   咨询匹配决定
-   业绩时间安排信息

## 许可证

麻省理工学院的执照 - 看 [自由主义](https://npmcn.com/package/%40bun-security-scanner/npm/LICENSE) 详细文件.

## 承认

-   **GitHub 咨询数据库**: 维持综合脆弱性数据库
-   **npm 团队**:建立强有力的咨询基础设施
-   **Bun 团队**:用于创新的安全扫描器API

## 相关项目

-   [Bun 安全扫描器 API](https://bun.com/docs/install/security-scanner-api)
-   [GitHub 咨询数据库](https://github.com/advisories)
-   [包子扫描器](https://github.com/bun-security-scanner/osv) - 使用谷歌OSV.dev的替代扫描仪

* * *

**上次更新**时间:2025年11月5日 **版本**: 1.0.0 (中文(简体) )

_这个扫描仪为更喜欢使用由GitHub提供动力的npm官方咨询数据库的开发者提供了替代信任模型._

## 常见问题

### @bun-security-scanner/npm 是什么？

npm 使用 GitHub 咨询数据库为 Bun 项目进行的注册脆弱性扫描仪

### 如何安装 @bun-security-scanner/npm？

在项目目录运行 npm install @bun-security-scanner/npm，或使用 pnpm add / yarn add / bun add。

### @bun-security-scanner/npm 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bun-security-scanner/npm 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bun-security-scanner/npm 可以商用吗？

@bun-security-scanner/npm 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bun-security-scanner/npm 的下载量有多少？

根据 npm 官方下载统计，@bun-security-scanner/npm 在 2026/10/09 – 2026/11/07 这 30 天内被下载 5,557 次，日均约 185 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bun-security-scanner/npm 还在维护吗？

最新版本 1\.0\.0 发布于 2025/11/06（1 年前）；至今共发布 1 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/11/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。