Bun OSV 扫描仪
用于生产级安全扫描仪 阿宝 与 OSV.dev (英语) (Open Source Vulnerabilitys)在安装过程中检测npm包中已知的弱点.
什么是OSV.dev? (英语)?
OSV.dev (英语) 是Google的开源脆弱性数据库,用于汇总和分发开源项目的脆弱性信息. 它规定:
- 全面覆盖: 多种来源(npm, PyPI, Go, Rust等)的易碎性
- 结构数据: 具有精确版本范围的机器可读脆弱性信息
- 实时更新: 不断更新最新安全咨询意见
- 权威来源:由Google和开源社区维护
特征
- 实时扫描: 安装时对照 OSV.dev 检查软件包
- 高性能: 高效的分批查询,智能分解
- 失败安全: 从未因扫描仪出错而屏蔽安装
- 结构化日志: 与背景资料相匹配的伐木水平
- 精确匹配: 精确的易碎性与包装版本相匹配
- 可配置: 所有设置的环境变量配置
- 测试良好: 综合测试套房,边缘病例覆盖
安装
不需要 API 密钥或注册 - 完全自由使用,除安装外,零设置.
# Install as a dev dependency
bun add -d @bun-security-scanner/osv
配置
1. 启用扫描仪
添加到您的 bunfig.toml数字 :
[install.security]
scanner = "@bun-security-scanner/osv"
2. 可选:配置选项
扫描仪可以通过环境变量配置:
# 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
如何运作
安全扫描过程
- 软件包检测: Bun 安装时提供软件包信息
- 智能复制: 消除重复软件包@ version results
- 批量查询:使用 OSV.dev 高效
/querybatch结束点 - 脆弱性: 精确匹配已安装的版本
- 严重性评估:分析CVSS的分数和具体数据库的严重程度
- 咨询组: 创建可采取行动的安全咨询
咨询级别
扫描仪可生成两种安全建议:
致命( 安装受阻)
- CVSS 分数: ≥ 7.0 (高度/标准)
- 数据库严重性: 临界或高度
- 行动: 安装立即被屏蔽
- 实例:远程代码执行,特权升级,数据曝光
警告( 用户提示)
- CVSS 分数: < 7.0 (中/低)
- 数据库严重性: 中、低或未说明
- 行动: 提示用户继续或取消
- 类型: 介绍互动选择
- 非TTY类: 安装自动取消
- 实例:拒绝服务、信息披露、贬值警告
处理错误哲学
扫描仪跟随 失败安全 办法:
- 网络错误不会阻碍安装
- 错误的反应被记录,但不要停止进程
- 扫描器崩溃返回空咨询阵列( 允许安装)
- 只有真正的安全威胁才能防止安装软件包
用法实例
基本用途
# Scanner runs automatically during installation
bun install express
# -> Checks express and all dependencies for vulnerabilities
bun add [email protected]
# -> May warn about known lodash vulnerabilities in older versions
发展用途
# Enable debug logging to see detailed scanning information
OSV_LOG_LEVEL=debug bun install
# Test with a known vulnerable package
bun add [email protected]
# -> Should trigger security advisory
配置示例
# 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
关键设计原则
- 关注的分离:每个模块都有一个单一、明确界定的责任
- 隔离错误: 一个组件的故障不会连结到其他组件
- 性能优化:批次处理、调试和同时提出的请求
- 观察性:用于调试和监测的全面记录
- 类型安全: 包含运行时间验证的全类型脚本覆盖
测试
# Run the test suite
bun test
# Run with coverage
bun test --coverage
# Type checking
bun run typecheck
# Linting
bun run lint
测试范围
- 已知的脆弱包检测
- 安全套件核查
- 多个一揽子方案
- 特定版本的脆弱性匹配
- 网络故障处理
- 边缘和出错条件
发展
来源建筑
git clone https://github.com/bun-security-scanner/osv.git
cd osv
bun install
bun run build
捐款
我们不接受拉动请求,因为这一一揽子计划得到了积极维护。 然而,我们赞赏开发人员报告错误或建议特性来自 打开一个问题。 。 。 .
见 捐款额 更多细节.
API 参考
OSV.dev 一体化
此扫描仪与以下 OSV.dev 端点相融合:
- POST /v1/克来格: 多个软件包的批次脆弱性查询
- POST /v1/克来: 有页码支持的单个软件包查询
完整 OSV.dev API 文档,访问: https://google.github.io/osv.dev/api/ 互联网档案馆的存檔,存档日期2013-12-21
配置参考
| 环境变量 | 默认 | 说明 |
|---|---|---|
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项目报告虚假阳性
调试模式
启用全面的调试输出 :
OSV_LOG_LEVEL=debug bun install your-package
这表明:
- 套件复制统计
- API 请求/答复详情
- 与脆弱性相匹配的决定
- 业绩时间安排信息
许可证
麻省理工学院的执照 - 看 自由主义 详细文件.
承认
- OSV.dev 团队: 维持综合脆弱性数据库
- Bun 团队:用于创新的安全扫描器API
相关项目
- Bun 安全扫描器 API
- OSV.dev (英语) - 开源脆弱性数据库
上次更新: 2025年11月6日 (中文(简体) ) 版本: 1.0.0 (中文(简体) )
该文件是一份活的文件,将随着项目的发展和新的特征而更新.