{"_id":"@bun-security-scanner/osv","name":"@bun-security-scanner/osv","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@bun-security-scanner/osv","version":"1.0.0","description":"OSV vulnerability scanner for Bun projects","author":{"name":"maloma7"},"license":"MIT","type":"module","types":"./src/index.ts","exports":"./src/index.ts","packageManager":"bun@1.3.0","engines":{"bun":">=1.0.0"},"keywords":["bun","osv","security","security-scanner","vulnerability","vulnerability-scanner","scanner","audit","dependencies"],"homepage":"https://osv.bun-security-scanner.com","repository":{"type":"git","url":"git+https://github.com/bun-security-scanner/osv.git"},"bugs":{"url":"https://github.com/bun-security-scanner/osv/issues"},"funding":{"type":"github","url":"https://github.com/sponsors/bun-security-scanner"},"scripts":{"dev":"bun run typecheck --watch","build":"bun run check","test":"bun test","lint":"bunx @biomejs/biome check .","lint:fix":"bunx @biomejs/biome check --write .","format":"bunx @biomejs/biome format --write .","typecheck":"bunx tsc --noEmit","clean":"rm -rf dist build node_modules/.cache","check":"bun run lint && bun run typecheck && bun run test","prepare":"bunx lefthook install"},"dependencies":{"zod":"^4.1.12"},"devDependencies":{"@biomejs/biome":"^2.3.4","@commitlint/cli":"^20.1.0","@commitlint/config-conventional":"^20.0.0","@semantic-release/changelog":"^6.0.3","@semantic-release/git":"^10.0.1","@tsconfig/bun":"^1.0.9","@types/bun":"^1.3.1","conventional-changelog-conventionalcommits":"^9.1.0","lefthook":"^2.0.2","semantic-release":"^25.0.1","typescript":"^5.9.3"},"gitHead":"483bc8fee26af57430d363b33ee8a54cbe9ece7d","_id":"@bun-security-scanner/osv@1.0.0","_nodeVersion":"24.11.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-hHtsD2VyaF5JGCzJp3pGXykgNyOFQUuG8qJ7TJ5OfNl7xfPO2AnER1aGx/PzvLFJVJI6Qsj+oUt/5vpcdMK8oQ==","shasum":"f1a7698e3d076253ed09236a1deea977dbefe732","tarball":"https://registry.npmjs.org/@bun-security-scanner/osv/-/osv-1.0.0.tgz","fileCount":16,"unpackedSize":72686,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bun-security-scanner%2fosv@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD09umxAQgNXXpZMpQGf7fdrQJ4H/BviyDecNrc5SceRgIhALPMqv0YInqackuSE/HuwYIT2X/2RCixsGtzmVxnkpm2"}]},"_npmUser":{"name":"maloma7","email":"admin@solytude.com"},"directories":{},"maintainers":[{"name":"maloma7","email":"admin@solytude.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/osv_1.0.0_1762437475774_0.81915573291478"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-06T13:57:55.699Z","1.0.0":"2025-11-06T13:57:55.980Z","modified":"2025-11-06T13:57:56.472Z"},"maintainers":[{"name":"maloma7","email":"admin@solytude.com"}],"description":"OSV vulnerability scanner for Bun projects","homepage":"https://osv.bun-security-scanner.com","keywords":["bun","osv","security","security-scanner","vulnerability","vulnerability-scanner","scanner","audit","dependencies"],"repository":{"type":"git","url":"git+https://github.com/bun-security-scanner/osv.git"},"author":{"name":"maloma7"},"bugs":{"url":"https://github.com/bun-security-scanner/osv/issues"},"license":"MIT","readme":"<!--\nCopyright (c) 2025 maloma7. All rights reserved.\nSPDX-License-Identifier: MIT\n-->\n\n<img src=\"docs/icons/logo.svg\" width=\"100%\" alt=\"Bun OSV Scanner\" />\n\n# Bun OSV Scanner\n\nA production-grade security scanner for [Bun](https://bun.sh/) that integrates with [OSV.dev](https://osv.dev/) (Open Source Vulnerabilities) to detect known vulnerabilities in npm packages during installation.\n\n[![npm version](https://img.shields.io/npm/v/@bun-security-scanner/osv?color=dc2626)](https://npmjs.com/package/@bun-security-scanner/osv)\n[![npm downloads](https://img.shields.io/npm/dm/@bun-security-scanner/osv?color=dc2626)](https://npmjs.com/package/@bun-security-scanner/osv)\n[![License: MIT](https://img.shields.io/badge/License-MIT-dc2626)](LICENSE)\n[![Built with Claude](https://img.shields.io/badge/Built_with-Claude-dc2626?style=flat&logo=claude&logoColor=dc2626)](https://anthropic.com/claude-code)\n[![Checked with Biome](https://img.shields.io/badge/Checked_with-Biome-dc2626?style=flat&logo=biome&logoColor=dc2626)](https://biomejs.dev)\n[![Secured with Lefthook](https://img.shields.io/badge/Secured_with-Lefthook-dc2626?style=flat&logo=lefthook&logoColor=dc2626)](https://lefthook.dev/)\n\n## What is OSV.dev?\n\n[OSV.dev](https://osv.dev/) is Google's open source vulnerability database that aggregates and distributes vulnerability information for open source projects. It provides:\n\n- **Comprehensive Coverage**: Vulnerabilities from multiple sources (npm, PyPI, Go, Rust, etc.)\n- **Structured Data**: Machine-readable vulnerability information with precise version ranges\n- **Real-time Updates**: Continuously updated with the latest security advisories\n- **Authoritative Source**: Maintained by Google and the open source community\n\n## Features\n\n- **Real-time Scanning**: Checks packages against OSV.dev during installation\n- **High Performance**: Efficient batch queries with smart deduplication\n- **Fail-safe**: Never blocks installations due to scanner errors\n- **Structured Logging**: Configurable logging levels with contextual information\n- **Precise Matching**: Accurate vulnerability-to-package version matching\n- **Configurable**: Environment variable configuration for all settings\n- **Well Tested**: Comprehensive test suite with edge case coverage\n\n## Installation\n\n**No API keys or registration required** - completely free to use with zero setup beyond installation.\n\n```bash\n# Install as a dev dependency\nbun add -d @bun-security-scanner/osv\n```\n\n## Configuration\n\n### 1. Enable the Scanner\n\nAdd to your `bunfig.toml`:\n\n```toml\n[install.security]\nscanner = \"@bun-security-scanner/osv\"\n```\n\n### 2. Optional: Configuration Options\n\nThe scanner can be configured via environment variables:\n\n```bash\n# Logging level (debug, info, warn, error)\nexport OSV_LOG_LEVEL=info\n\n# Custom OSV API base URL (optional)\nexport OSV_API_BASE_URL=https://api.osv.dev/v1\n\n# Request timeout in milliseconds (default: 30000)\nexport OSV_TIMEOUT_MS=30000\n\n# Disable batch queries (default: false)\nexport OSV_DISABLE_BATCH=false\n```\n\n## How It Works\n\n### Security Scanning Process\n\n1. **Package Detection**: Bun provides package information during installation\n2. **Smart Deduplication**: Eliminates duplicate package@version queries\n3. **Batch Querying**: Uses OSV.dev's efficient `/querybatch` endpoint\n4. **Vulnerability Matching**: Precisely matches vulnerabilities to installed versions\n5. **Severity Assessment**: Analyzes CVSS scores and database-specific severity\n6. **Advisory Generation**: Creates actionable security advisories\n\n### Advisory Levels\n\nThe scanner generates two types of security advisories:\n\n#### Fatal (Installation Blocked)\n- **CVSS Score**: ≥ 7.0 (High/Critical)\n- **Database Severity**: CRITICAL or HIGH\n- **Action**: Installation is immediately blocked\n- **Examples**: Remote code execution, privilege escalation, data exposure\n\n#### Warning (User Prompted)\n- **CVSS Score**: < 7.0 (Medium/Low)\n- **Database Severity**: MEDIUM, LOW, or unspecified\n- **Action**: User is prompted to continue or cancel\n- **TTY**: Interactive choice presented\n- **Non-TTY**: Installation automatically cancelled\n- **Examples**: Denial of service, information disclosure, deprecation warnings\n\n### Error Handling Philosophy\n\nThe scanner follows a **fail-safe** approach:\n- Network errors don't block installations\n- Malformed responses are logged but don't halt the process\n- Scanner crashes return empty advisory arrays (allows installation)\n- Only genuine security threats should prevent package installation\n\n## Usage Examples\n\n### Basic Usage\n\n```bash\n# Scanner runs automatically during installation\nbun install express\n# -> Checks express and all dependencies for vulnerabilities\n\nbun add lodash@4.17.20\n# -> May warn about known lodash vulnerabilities in older versions\n```\n\n### Development Usage\n\n```bash\n# Enable debug logging to see detailed scanning information\nOSV_LOG_LEVEL=debug bun install\n\n# Test with a known vulnerable package\nbun add event-stream@3.3.6\n# -> Should trigger security advisory\n```\n\n### Configuration Examples\n\n```bash\n# Increase timeout for slow networks\nOSV_TIMEOUT_MS=60000 bun install\n\n# Use custom OSV instance (advanced)\nOSV_API_BASE_URL=https://api.custom-osv.dev/v1 bun install\n```\n\n## Architecture\n\nThe scanner is built with a modular, production-ready architecture:\n\n```\nsrc/\n├── index.ts              # Main scanner implementation\n├── client.ts             # OSV.dev API client with batch support\n├── processor.ts          # Vulnerability processing and advisory generation\n├── cli.ts                # CLI interface for testing\n├── schema.ts             # Zod schemas for OSV API responses\n├── constants.ts          # Centralized configuration management\n├── logger.ts             # Structured logging with configurable levels\n├── retry.ts              # Robust retry logic with exponential backoff\n├── semver.ts             # OSV semver range matching\n├── severity.ts           # CVSS and severity assessment\n└── types.ts              # TypeScript type definitions\n```\n\n### Key Design Principles\n\n1. **Separation of Concerns**: Each module has a single, well-defined responsibility\n2. **Error Isolation**: Failures in one component don't cascade to others\n3. **Performance Optimization**: Batch processing, deduplication, and concurrent requests\n4. **Observability**: Comprehensive logging for debugging and monitoring\n5. **Type Safety**: Full TypeScript coverage with runtime validation\n\n## Testing\n\n```bash\n# Run the test suite\nbun test\n\n# Run with coverage\nbun test --coverage\n\n# Type checking\nbun run typecheck\n\n# Linting\nbun run lint\n```\n\n### Test Coverage\n\n- Known vulnerable packages detection\n- Safe package verification  \n- Multiple package scenarios\n- Version-specific vulnerability matching\n- Network failure handling\n- Edge cases and error conditions\n\n## Development\n\n### Building from Source\n\n```bash\ngit clone https://github.com/bun-security-scanner/osv.git\ncd osv\nbun install\nbun run build\n```\n\n### Contributing\n\nWe 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](https://github.com/bun-security-scanner/osv/issues/new).\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for more details.\n\n## API Reference\n\n### OSV.dev Integration\n\nThis scanner integrates with the following OSV.dev endpoints:\n\n- **POST /v1/querybatch**: Batch vulnerability queries for multiple packages\n- **POST /v1/query**: Individual package queries with pagination support\n\nFor complete OSV.dev API documentation, visit: https://google.github.io/osv.dev/api/\n\n### Configuration Reference\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `OSV_LOG_LEVEL` | `info` | Logging level: debug, info, warn, error |\n| `OSV_API_BASE_URL` | `https://api.osv.dev/v1` | OSV API base URL |\n| `OSV_TIMEOUT_MS` | `30000` | Request timeout in milliseconds |\n| `OSV_DISABLE_BATCH` | `false` | Disable batch queries (use individual queries) |\n\n## Troubleshooting\n\n### Common Issues\n\n**Scanner not running during installation?**\n- Verify `bunfig.toml` configuration\n- Check that the package is installed as a dev dependency\n- Enable debug logging: `OSV_LOG_LEVEL=debug bun install`\n\n**Network timeouts?**\n- Increase timeout: `OSV_TIMEOUT_MS=60000`\n- Check internet connectivity to osv.dev\n- Consider corporate firewall restrictions\n\n**Too many false positives?**\n- OSV.dev data is authoritative - verify vulnerabilities manually\n- Check if you're using an outdated package version\n- Report false positives to the OSV.dev project\n\n### Debug Mode\n\nEnable comprehensive debug output:\n\n```bash\nOSV_LOG_LEVEL=debug bun install your-package\n```\n\nThis shows:\n- Package deduplication statistics\n- API request/response details  \n- Vulnerability matching decisions\n- Performance timing information\n\n## License\n\nMIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- **OSV.dev Team**: For maintaining the comprehensive vulnerability database\n- **Bun Team**: For the innovative Security Scanner API\n\n## Related Projects\n\n- [Bun Security Scanner API](https://bun.com/docs/install/security-scanner-api)\n- [OSV.dev](https://osv.dev/) - Open Source Vulnerabilities database\n\n---\n\n**Last Updated**: November 6, 2025\n**Version**: 1.0.0\n\n*This documentation is a living document and will be updated as the project evolves and new features are added.*","readmeFilename":"README.md","_rev":"1-a0a76269f708d5a2741810c3fdec6dd4"}