扫描机
用于生产级安全扫描仪 阿宝 与 npm 注册的 GitHub 咨询数据库 在安装时检测 npm 包中已知的弱点.
GitHub 咨询数据库是什么 ?
这个 GitHub 咨询数据库 为开源项目提供安全脆弱性信息。 这是:
- 权威: 由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 密钥或注册 - 完全自由使用,除安装外,零设置.
# Install as a dev dependency
bun add -d @bun-security-scanner/npm
配置
1. 启用扫描仪
添加到您的 bunfig.toml数字 :
[install.security]
scanner = "@bun-security-scanner/npm"
2. 可选:配置选项
扫描仪可以通过环境变量配置:
# 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
如何运作
安全扫描过程
- 软件包检测: Bun 安装时提供软件包信息
- 智能复制: 消除重复软件包@ version results
- 批量查询: 使用 npm 登记簿
/npm/v1/security/advisories/bulk结束点 - Gzip 压缩: 压缩请求的有效载荷以达到最佳性能
- 版本匹配: 使用 Bun 的组合以匹配易被攻击的版本范围
- 咨询组: 创建可采取行动的安全咨询
咨询级别
扫描仪根据npm重度生成两种安全建议:
致命( 安装受阻)
- 严重性数字 :
critical或者说high - 行动: 安装立即被屏蔽
- 实例:远程代码执行,特权升级,数据曝光
警告( 用户提示)
- 严重性数字 :
moderate, (中文(简体) ),low,或info - 行动: 提示用户继续或取消
- 类型: 介绍互动选择
- 非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
NPM_SCANNER_LOG_LEVEL=debug bun install
# Test with a known vulnerable package
bun add [email protected]
# -> Should trigger security advisory
配置示例
# 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
关键设计原则
- 关注的分离:每个模块都有一个单一、明确界定的责任
- 隔离错误: 一个组件的故障不会连结到其他组件
- 性能优化: 批量处理、分解和gzip压缩
- 观察性:用于调试和监测的全面记录
- 类型安全: 包含运行时间验证的全类型脚本覆盖
与其他扫描仪的比较
| 特性 | 扫描机 | 包子扫描器 |
|---|---|---|
| 数据库 | npm/ GitHub 咨询 | 谷歌 OSV.dev |
| 提供者 | 微软/ GitHub | 谷歌 |
| 压缩 | 原生 gzip | 无 |
| API 调用 | 单一批量请求 | 批量 + 个人细节 |
| 生态系统 | 以 npm 为焦点 | 多生态系统 |
| 信托模式 | npm 官方来源 | 合计来源 |
测试
# 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/npm.git
cd npm
bun install
bun run build
捐款
我们不接受拉动请求,因为这一一揽子计划得到了积极维护。 然而,我们赞赏开发人员报告错误或建议特性来自 打开一个问题。 。 。 .
API 参考
npm 审计整合
扫描仪与 npm 登记册批量咨询终点集成 :
- POST /-/npm/v1/ 安保/咨询/邮包: gzip 压缩的批量咨询查询
请求格式 :
{
"package-name": ["1.0.0", "2.0.0"],
"another-package": ["3.0.0"]
}
反应格式 :
{
"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 安全顾问报告假阳性
调试模式
启用全面的调试输出 :
NPM_SCANNER_LOG_LEVEL=debug bun install your-package
这表明:
- 套件复制统计
- API 请求/答复详情
- 咨询匹配决定
- 业绩时间安排信息
许可证
麻省理工学院的执照 - 看 自由主义 详细文件.
承认
- GitHub 咨询数据库: 维持综合脆弱性数据库
- npm 团队:建立强有力的咨询基础设施
- Bun 团队:用于创新的安全扫描器API
相关项目
- Bun 安全扫描器 API
- GitHub 咨询数据库
- 包子扫描器 - 使用谷歌OSV.dev的替代扫描仪
上次更新时间:2025年11月5日 版本: 1.0.0 (中文(简体) )
这个扫描仪为更喜欢使用由GitHub提供动力的npm官方咨询数据库的开发者提供了替代信任模型.