bun-scan 1.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 rawtoast
+Copyright (c) 2025 maloma7
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,338 @@
+<!--
+Copyright (c) 2026 rawtoast. All rights reserved.
+Copyright (c) 2025 maloma7. All rights reserved.
+SPDX-License-Identifier: MIT
+-->
+
+# Bun-Scan
+
+A 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 packages during installation.
+
+[![npm version](https://img.shields.io/npm/v/bun-scan?color=dc2626)](https://npmjs.com/package/bun-scan)
+[![npm downloads](https://img.shields.io/npm/dm/bun-scan?color=dc2626)](https://npmjs.com/package/bun-scan)
+[![License: MIT](https://img.shields.io/badge/License-MIT-dc2626)](LICENSE)
+
+## What is OSV.dev?
+
+[OSV.dev](https://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
+
+## Features
+
+- **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
+- **Well Tested**: Comprehensive test suite with edge case coverage
+
+## Installation
+
+**No API keys or registration required** - completely free to use with zero setup beyond installation.
+
+```bash
+# Install as a dev dependency
+bun add -d bun-scan
+```
+
+## Configuration
+
+### 1. Enable the Scanner
+
+Add to your `bunfig.toml`:
+
+```toml
+[install.security]
+scanner = "bun-scan"
+```
+
+### 2. Optional: Ignore Specific Vulnerabilities
+
+Create a `.bun-scan.json` file in your project root to ignore specific vulnerabilities:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/rawtoast/bun-scan/master/schema/bun-scan.schema.json",
+  "packages": {
+    "hono": {
+      "vulnerabilities": ["CVE-2026-22818"],
+      "reason": "Project does not use JWT from hono"
+    }
+  }
+}
+```
+
+The scanner looks for `.osvignore.json` or `osv.config.json` in your project root.
+
+#### Ignore Configuration Options
+
+| Field                             | Description                                                               |
+| --------------------------------- | ------------------------------------------------------------------------- |
+| `ignore`                          | Array of vulnerability IDs to ignore globally (e.g., `["CVE-2024-1234"]`) |
+| `packages.<name>.vulnerabilities` | Vulnerability IDs to ignore for a specific package                        |
+| `packages.<name>.until`           | Expiration date (ISO 8601) for temporary ignores                          |
+| `packages.<name>.reason`          | Documentation of why the vulnerability is ignored                         |
+
+**Example: Global ignore**
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/rawtoast/bun-scan/master/schema/bun-scan.schema.json",
+  "ignore": ["CVE-2024-1234", "GHSA-xxxx-xxxx-xxxx"]
+}
+```
+
+**Example: Temporary ignore with expiration**
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/rawtoast/bun-scan/master/schema/bun-scan.schema.json",
+  "packages": {
+    "lodash": {
+      "vulnerabilities": ["CVE-2021-23337"],
+      "until": "2024-06-01",
+      "reason": "Temporary ignore while migration is in progress"
+    }
+  }
+}
+```
+
+### 3. Optional: Environment Variables
+
+The scanner can be configured via environment variables:
+
+```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
+```
+
+## How It Works
+
+### Security Scanning Process
+
+1. **Package Detection**: Bun provides package information during installation
+2. **Smart Deduplication**: Eliminates duplicate package@version queries
+3. **Batch Querying**: Uses OSV.dev's efficient `/querybatch` endpoint
+4. **Vulnerability Matching**: Precisely matches vulnerabilities to installed versions
+5. **Severity Assessment**: Analyzes CVSS scores and database-specific severity
+6. **Advisory Generation**: Creates actionable security advisories
+
+### Advisory Levels
+
+The scanner generates two types of security advisories:
+
+#### Fatal (Installation Blocked)
+
+- **CVSS Score**: ≥ 7.0 (High/Critical)
+- **Database Severity**: CRITICAL or HIGH
+- **Action**: Installation is immediately blocked
+- **Examples**: Remote code execution, privilege escalation, data exposure
+
+#### Warning (User Prompted)
+
+- **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
+
+### Error Handling Philosophy
+
+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
+
+## Usage Examples
+
+### Basic Usage
+
+```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
+```
+
+### Development Usage
+
+```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
+```
+
+### Configuration Examples
+
+```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
+```
+
+## Architecture
+
+The scanner is built with a modular, production-ready architecture:
+
+```
+src/
+├── index.ts              # Main scanner implementation
+├── client.ts             # OSV.dev API client with batch support
+├── processor.ts          # Vulnerability processing and advisory generation
+├── config.ts             # Ignore configuration loading and validation
+├── 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
+```
+
+### Key Design Principles
+
+1. **Separation of Concerns**: Each module has a single, well-defined responsibility
+2. **Error Isolation**: Failures in one component don't cascade to others
+3. **Performance Optimization**: Batch processing, deduplication, and concurrent requests
+4. **Observability**: Comprehensive logging for debugging and monitoring
+5. **Type Safety**: Full TypeScript coverage with runtime validation
+
+## Testing
+
+```bash
+# Run the test suite
+bun test
+
+# Run with coverage
+bun test --coverage
+
+# Type checking
+bun run typecheck
+
+# Linting
+bun run lint
+```
+
+### Test Coverage
+
+- Known vulnerable packages detection
+- Safe package verification
+- Multiple package scenarios
+- Version-specific vulnerability matching
+- Network failure handling
+- Edge cases and error conditions
+
+## Development
+
+### Building from Source
+
+```bash
+git clone https://github.com/rawtoast/bun-scan.git
+cd bun-scan
+bun install
+bun run build
+```
+
+## API Reference
+
+### OSV.dev Integration
+
+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/
+
+### Configuration Reference
+
+| 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) |
+
+## Troubleshooting
+
+### Common Issues
+
+**Scanner not running during installation?**
+
+- Verify `bunfig.toml` configuration
+- Check that the package is installed as a dev dependency
+- Enable debug logging: `OSV_LOG_LEVEL=debug bun install`
+
+**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
+- Use `.osvignore.json` to ignore vulnerabilities that don't apply to your project
+- Report false positives to the OSV.dev project
+
+### Debug Mode
+
+Enable comprehensive debug output:
+
+```bash
+OSV_LOG_LEVEL=debug bun install your-package
+```
+
+This shows:
+
+- Package deduplication statistics
+- API request/response details
+- Vulnerability matching decisions
+- Performance timing information
+
+## License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- **OSV.dev Team**: For maintaining the comprehensive vulnerability database
+- **Bun Team**: For the innovative Security Scanner API
+- **maloma7**: For the original implementation of the Bun OSV Scanner
+
+## Related Projects
+
+- [Bun Security Scanner API](https://bun.com/docs/install/security-scanner-api)
+- [OSV.dev](https://osv.dev/) - Open Source Vulnerabilities database
+
+---
+
+**Last Updated**: January 15, 2026
+
+_This documentation is a living document and will be updated as the project evolves and new features are added._