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

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

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

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

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

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

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

## 中文简介

Bun 项目的OSV脆弱性扫描仪

## 安装

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

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

## README

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

# Bun OSV 扫描仪

用于生产级安全扫描仪 [阿宝](https://bun.sh/) 与 [OSV.dev (英语)](https://osv.dev/) (Open Source Vulnerabilitys)在安装过程中检测npm包中已知的弱点.

[![npm version](https://img.shields.io/npm/v/@bun-security-scanner/osv?color=dc2626)](https://npmjs.com/package/@bun-security-scanner/osv) [![npm downloads](https://img.shields.io/npm/dm/@bun-security-scanner/osv?color=dc2626)](https://npmjs.com/package/@bun-security-scanner/osv) [![License: MIT](https://img.shields.io/badge/License-MIT-dc2626)](https://npmcn.com/package/%40bun-security-scanner/osv/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/) [![Secured with Lefthook](https://img.shields.io/badge/Secured_with-Lefthook-dc2626?style=flat&logo=lefthook&logoColor=dc2626)](https://lefthook.dev/)

## 什么是OSV.dev? (英语)?

[OSV.dev (英语)](https://osv.dev/) 是Google的开源脆弱性数据库,用于汇总和分发开源项目的脆弱性信息. 它规定:

-   **全面覆盖**: 多种来源(npm, PyPI, Go, Rust等)的易碎性
-   **结构数据**: 具有精确版本范围的机器可读脆弱性信息
-   **实时更新**: 不断更新最新安全咨询意见
-   **权威来源**:由Google和开源社区维护

## 特征

-   **实时扫描**: 安装时对照 OSV.dev 检查软件包
-   **高性能**: 高效的分批查询,智能分解
-   **失败安全**: 从未因扫描仪出错而屏蔽安装
-   **结构化日志**: 与背景资料相匹配的伐木水平
-   **精确匹配**: 精确的易碎性与包装版本相匹配
-   **可配置**: 所有设置的环境变量配置
-   **测试良好**: 综合测试套房,边缘病例覆盖

## 安装

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

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

## 配置

### 1\. 启用扫描仪

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

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

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

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

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

# Custom OSV API base URL (optional)
export OSV_API_BASE_URL=https://api.osv.dev/v1

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

# Disable batch queries (default: false)
export OSV_DISABLE_BATCH=false
```

## 如何运作

### 安全扫描过程

1.  **软件包检测**: Bun 安装时提供软件包信息
2.  **智能复制**: 消除重复软件包@ version results
3.  **批量查询**:使用 OSV.dev 高效 `/querybatch` 结束点
4.  **脆弱性**: 精确匹配已安装的版本
5.  **严重性评估**:分析CVSS的分数和具体数据库的严重程度
6.  **咨询组**: 创建可采取行动的安全咨询

### 咨询级别

扫描仪可生成两种安全建议:

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

-   **CVSS 分数**: ≥ 7.0 (高度/标准)
-   **数据库严重性**: 临界或高度
-   **行动**: 安装立即被屏蔽
-   **实例**:远程代码执行,特权升级,数据曝光

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

-   **CVSS 分数**: < 7.0 (中/低)
-   **数据库严重性**: 中、低或未说明
-   **行动**: 提示用户继续或取消
-   **类型**: 介绍互动选择
-   **非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
OSV_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
OSV_TIMEOUT_MS=60000 bun install

# Use custom OSV instance (advanced)
OSV_API_BASE_URL=https://api.custom-osv.dev/v1 bun install
```

## 建筑

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

```
src/
├── index.ts              # Main scanner implementation
├── client.ts             # OSV.dev API client with batch support
├── processor.ts          # Vulnerability processing and advisory generation
├── cli.ts                # CLI interface for testing
├── schema.ts             # Zod schemas for OSV API responses
├── constants.ts          # Centralized configuration management
├── logger.ts             # Structured logging with configurable levels
├── retry.ts              # Robust retry logic with exponential backoff
├── semver.ts             # OSV semver range matching
├── severity.ts           # CVSS and severity assessment
└── types.ts              # TypeScript type definitions
```

### 关键设计原则

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

## 测试

```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/osv.git
cd osv
bun install
bun run build
```

### 捐款

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

见 [捐款额](https://npmcn.com/package/%40bun-security-scanner/osv/CONTRIBUTING.md) 更多细节.

## API 参考

### OSV.dev 一体化

此扫描仪与以下 OSV.dev 端点相融合:

-   **POST /v1/克来格**: 多个软件包的批次脆弱性查询
-   **POST /v1/克来**: 有页码支持的单个软件包查询

完整 OSV.dev API 文档,访问: [https://google.github.io/osv.dev/api/ 互联网档案馆的存檔,存档日期2013-12-21](https://google.github.io/osv.dev/api/)

### 配置参考

| 环境变量 | 默认 | 说明 |
| --- | --- | --- |
| `OSV_LOG_LEVEL` | `info` | 日志级别:调试、信息、警告、错误 |
| `OSV_API_BASE_URL` | `https://api.osv.dev/v1` | OSV API 基础 URL |
| `OSV_TIMEOUT_MS` | `30000` | 请求超时( 毫秒) |
| `OSV_DISABLE_BATCH` | `false` | 禁用批次查询( 使用单个查询) |

## 解决问题

### 共同问题

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

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

**网络超时?**

-   增加超时 : `OSV_TIMEOUT_MS=60000`
-   检查互联网连接到 osv.dev
-   考虑公司防火墙限制

**太多假阳性?**

-   OSV.dev数据是权威的 - 手动验证弱点
-   检查您是否使用过时的软件包版本
-   向OSV.dev项目报告虚假阳性

### 调试模式

启用全面的调试输出 :

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

这表明:

-   套件复制统计
-   API 请求/答复详情
-   与脆弱性相匹配的决定
-   业绩时间安排信息

## 许可证

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

## 承认

-   **OSV.dev 团队**: 维持综合脆弱性数据库
-   **Bun 团队**:用于创新的安全扫描器API

## 相关项目

-   [Bun 安全扫描器 API](https://bun.com/docs/install/security-scanner-api)
-   [OSV.dev (英语)](https://osv.dev/) - 开源脆弱性数据库

* * *

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

_该文件是一份活的文件,将随着项目的发展和新的特征而更新._

## 常见问题

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

Bun 项目的OSV脆弱性扫描仪

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

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

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

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

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

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

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

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

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

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

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

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