A production-grade security scanner for Bun that integrates with OSV.dev (Open Source Vulnerabilities) to detect known vulnerabilities in npm packages during installation.
OSV.dev is Google's open source vulnerability database that aggregates and distributes vulnerability information for open source projects. It provides:
- Comprehensive Coverage: Vulnerabilities from multiple sources (npm, PyPI, Go, Rust, etc.)
- Structured Data: Machine-readable vulnerability information with precise version ranges
- Real-time Updates: Continuously updated with the latest security advisories
- Authoritative Source: Maintained by Google and the open source community
- Real-time Scanning: Checks packages against OSV.dev during installation
- High Performance: Efficient batch queries with smart deduplication
- Fail-safe: Never blocks installations due to scanner errors
- Structured Logging: Configurable logging levels with contextual information
- Precise Matching: Accurate vulnerability-to-package version matching
- Configurable: Environment variable configuration for all settings
- Allowlist (Ignore Rules): Ignore by advisory ID (CVE/GHSA/OSV) or package (optionally with version range); ignored issues are demoted to warnings and annotated with bold red “[ignored]”
- Well Tested: Comprehensive test suite with edge case coverage
No API keys or registration required - completely free to use with zero setup beyond installation.
# Install as a dev dependency
bun add -d bun-osv-scannerAdd to your bunfig.toml:
[install.security]
scanner = "bun-osv-scanner"The scanner can be configured via environment variables:
# Core scanner config
export OSV_LOG_LEVEL=info
export OSV_API_BASE_URL=https://api.osv.dev/v1
export OSV_TIMEOUT_MS=30000
export OSV_DISABLE_BATCH=false
# Ignore / allowlist config
# Ignore by package (name or name@range)
export BUN_OSV_IGNORE_PKG="ip@* lodash@<4.17.21"
# Ignore by advisory id(s)
export BUN_OSV_IGNORE_ADVISORY="CVE-2024-29415 GHSA-xxxx-xxxx-xxxx"
# Load extra rules from a file (JSON with { "ignore": [...] } or an array)
export BUN_OSV_IGNORE_FILE="$PWD/security/ignore.json"
# Show ignored advisories as warnings (1/true to show, 0/false to hide). Default: 1
export BUN_OSV_SHOW_IGNORED=1You can allow specific vulnerabilities or packages while still seeing them in the output.
- Matches advisories by ID (CVE/GHSA/OSV) or by package name (optionally with a semver range).
- Ignored advisories won’t block installs. By default they’re shown as warnings, annotated with a bold red “[ignored]”.
- Expiring rules are supported via an ISO date (rules past
expiresare ignored). - Rules are merged from (in order):
.bun-osv.json,package.json→bunOsv.ignore,BUN_OSV_IGNORE_FILE, and environment variables.
Project-level file (.bun-osv.json):
{
"ignore": [
{ "advisory": "CVE-2024-29415", "reason": "accepted risk", "expires": "2026-01-01" },
{ "package": "ip", "range": "*", "reason": "legacy env" },
{ "package": "lodash", "range": "<4.17.21", "reason": "pending upgrade" }
]
}package.json alternative:
{
"name": "your-project",
"bunOsv": {
"ignore": [
{ "package": "left-pad", "range": "*" }
]
}
}Notes on matching:
- Advisory IDs are matched across known fields and within URLs/references (e.g., an NVD link containing “CVE-2024-29415”).
- Package names are case-insensitive; if version information isn’t available, name-only rules still apply.
- Coloring respects
NO_COLOR. Without it, “[ignored]” is bold red.
- Package Detection: Bun provides package information during installation
- Smart Deduplication: Eliminates duplicate package@version queries
- Batch Querying: Uses OSV.dev's efficient
/querybatchendpoint - Vulnerability Matching: Precisely matches vulnerabilities to installed versions
- Severity Assessment: Analyzes CVSS scores and database-specific severity
- Advisory Generation: Creates actionable security advisories
- Ignore Rule Application: Filters advisories using allowlist rules; ignored ones are demoted to warning level and annotated “[ignored]” (if
BUN_OSV_SHOW_IGNORED=1)
The scanner generates two types of security advisories:
- CVSS Score: ≥ 7.0 (High/Critical)
- Database Severity: CRITICAL or HIGH
- Action: Installation is immediately blocked
- Examples: Remote code execution, privilege escalation, data exposure
- CVSS Score: < 7.0 (Medium/Low)
- Database Severity: MEDIUM, LOW, or unspecified
- Action: User is prompted to continue or cancel
- TTY: Interactive choice presented
- Non-TTY: Installation automatically cancelled
- Examples: Denial of service, information disclosure, deprecation warnings
Ignored advisories
- When a rule matches, the advisory is treated as a warning and annotated “[ignored]” so it remains visible without blocking the install (behavior controlled by
BUN_OSV_SHOW_IGNORED).
The scanner follows a fail-safe approach:
- Network errors don't block installations
- Malformed responses are logged but don't halt the process
- Scanner crashes return empty advisory arrays (allows installation)
- Only genuine security threats should prevent package installation
# 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# Ignore a specific advisory (CVE)
export BUN_OSV_IGNORE_ADVISORY="CVE-2024-29415"
bun install
# Ignore a package regardless of version
export BUN_OSV_IGNORE_PKG="ip@*"
bun install
# Hide ignored advisories completely (instead of showing as warnings)
export BUN_OSV_SHOW_IGNORED=0
bun install# 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 installThe scanner is built with a modular, production-ready architecture:
src/
├── api/
│ └── client.ts # OSV.dev API client with batch support
├── scanner/
│ └── processor.ts # Vulnerability processing and advisory generation
├── utils/
│ ├── retry.ts # Robust retry logic with exponential backoff
│ ├── semver.ts # OSV semver range matching
│ └── severity.ts # CVSS and severity assessment
├── constants.ts # Centralized configuration management
├── logger.ts # Structured logging with configurable levels
├── schema.ts # Zod schemas for OSV API responses
├── types.ts # TypeScript type definitions
└── index.ts # Main scanner implementation
- Separation of Concerns: Each module has a single, well-defined responsibility
- Error Isolation: Failures in one component don't cascade to others
- Performance Optimization: Batch processing, deduplication, and concurrent requests
- Observability: Comprehensive logging for debugging and monitoring
- Type Safety: Full TypeScript coverage with runtime validation
# Run the test suite
bun test
# Run with coverage
bun test --coverage
# Type checking
bun run typecheck
# Linting
bun run lint- Known vulnerable packages detection
- Safe package verification
- Multiple package scenarios
- Version-specific vulnerability matching
- Network failure handling
- Edge cases and error conditions
git clone https://github.com/whjvenyl/bun-osv-scanner.git
cd bun-osv-scanner
bun install
bun run buildWe do not accept pull requests as this package is actively maintained. However, we appreciate if developers report bugs or suggest features by opening an issue.
See CONTRIBUTING.md for more details.
This scanner integrates with the following OSV.dev endpoints:
- POST /v1/querybatch: Batch vulnerability queries for multiple packages
- POST /v1/query: Individual package queries with pagination support
For complete OSV.dev API documentation, visit: https://google.github.io/osv.dev/api/
| Environment Variable | Default | Description |
|---|---|---|
OSV_LOG_LEVEL |
info |
Logging level: debug, info, warn, error |
OSV_API_BASE_URL |
https://api.osv.dev/v1 |
OSV API base URL |
OSV_TIMEOUT_MS |
30000 |
Request timeout in milliseconds |
OSV_DISABLE_BATCH |
false |
Disable batch queries (use individual queries) |
BUN_OSV_IGNORE_PKG |
— | Space/comma-separated package tokens to ignore (e.g., ip@* lodash@<4.17.21) |
BUN_OSV_IGNORE_ADVISORY |
— | Space/comma-separated advisory IDs to ignore (CVE-/GHSA-/OSV-) |
BUN_OSV_IGNORE_FILE |
— | Path to JSON file containing ignore rules |
BUN_OSV_SHOW_IGNORED |
1 |
If 1/true, show ignored advisories as warnings; if 0/false, hide them |
Scanner not running during installation?
- Verify
bunfig.tomlconfiguration - Check that the package is installed as a dev dependency
- Enable debug logging:
OSV_LOG_LEVEL=debug bun install
Ignore rule doesn’t apply?
- Ensure the rule file is in the project being installed (or set
BUN_OSV_IGNORE_FILE). - Enable debug logs to see “Loaded N ignore rules”.
- Match by CVE/GHSA if the advisory uses a URL (e.g., NVD link). Example:
{ "advisory": "CVE-2024-29415" }. - Package rules are case-insensitive;
"range": "*"ignores all versions. - Check
expireshasn’t passed.
Network timeouts?
- Increase timeout:
OSV_TIMEOUT_MS=60000 - Check internet connectivity to osv.dev
- Consider corporate firewall restrictions
Too many false positives?
- OSV.dev data is authoritative - verify vulnerabilities manually
- Check if you're using an outdated package version
- Report false positives to the OSV.dev project
Enable comprehensive debug output:
OSV_LOG_LEVEL=debug bun install your-packageThis shows:
- Package deduplication statistics
- API request/response details
- Vulnerability matching decisions (including ignore-rule matches)
- Performance timing information
MIT License - see the LICENSE file for details.
- OSV.dev Team: For maintaining the comprehensive vulnerability database
- Bun Team: For the innovative Security Scanner API
- Bun Security Scanner API
- OSV.dev - Open Source Vulnerabilities database
Last Updated: September 12, 2025
Version: 1.0.0
This documentation is a living document and will be updated as the project evolves and new features are added.