@nebzdev/bun-security-scanner 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muneeb Samuels
+
+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,238 @@
+# bun-security-scanner
+
+[![npm version](https://badge.fury.io/js/%40nebzdev%2Fbun-security-scanner.svg)](https://badge.fury.io/js/%40nebzdev%2Fbun-security-scanner)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Powered by OSV](https://img.shields.io/badge/powered%20by-OSV-4285F4.svg)](https://osv.dev)
+[![Powered by Snyk](https://img.shields.io/badge/powered%20by-Snyk-4C4A73.svg)](https://snyk.io)
+
+A [Bun security scanner](https://bun.com/docs/pm/security-scanner-api) that checks your dependencies against vulnerability databases before they get installed. Uses [Google's OSV database](https://osv.dev) by default — no API keys required.
+
+- 🔍 **Automatic scanning**: runs transparently on every `bun install`
+- ⚡ **Fast**: 24-hour per-package lockfile cache means repeat installs skip the network entirely
+- 🔀 **Two backends**: OSV (free, no setup) or Snyk (commercial, broader coverage)
+- 🔒 **Fail-open by default**: a downed API never blocks your install
+- 🎯 **CVSS fallback**: uses score-based severity when a label isn't available
+- 🛠️ **Configurable**: tune behaviour via environment variables
+
+---
+
+## 📦 Installation
+
+```sh
+bun add -d @nebzdev/bun-security-scanner
+```
+
+Then register it in your project's `bunfig.toml`:
+
+```toml
+[install.security]
+scanner = "@nebzdev/bun-security-scanner"
+```
+
+That's it. The scanner runs automatically on the next `bun install`.
+
+### Local development
+
+Point `bunfig.toml` directly at the entry file using an absolute or relative path:
+
+```toml
+[install.security]
+scanner = "../bun-osv-scanner/src/index.ts"
+```
+
+---
+
+## 🔀 Backends
+
+The scanner ships with two backends, controlled by the `SCANNER_BACKEND` environment variable.
+
+### OSV (default)
+
+Queries [Google's OSV database](https://osv.dev) — free, no credentials required.
+
+```toml
+[install.security]
+scanner = "@nebzdev/bun-security-scanner"
+```
+
+### Snyk
+
+Queries [Snyk's vulnerability database](https://security.snyk.io) — commercial, often surfaces issues earlier. Requires a Snyk account.
+
+```toml
+# bunfig.toml
+[install.security]
+scanner = "@nebzdev/bun-security-scanner"
+```
+
+```sh
+# .env
+SCANNER_BACKEND=snyk
+SNYK_TOKEN=your-token
+SNYK_ORG_ID=your-org-id
+```
+
+---
+
+## 🛡️ How it works
+
+When `bun install` runs, Bun calls the scanner with the full list of packages to be installed. The scanner:
+
+1. **Filters** non-resolvable versions — workspace, git, file, and path dependencies are skipped
+2. **Checks the cache** — packages seen within the last 24 hours skip the network entirely
+3. **Queries the backend** for any uncached packages
+4. **Returns advisories** to Bun, which surfaces them as warnings or fatal errors
+
+---
+
+## ⚠️ Advisory levels
+
+| Level | Trigger | Bun behaviour |
+|-------|---------|---------------|
+| `fatal` | CRITICAL or HIGH severity; or CVSS score ≥ 7.0 | Installation halts |
+| `warn` | MODERATE or LOW severity; or CVSS score < 7.0 | User is prompted; auto-cancelled in CI |
+
+---
+
+## ⚙️ Configuration
+
+All options are set via environment variables — in your shell, or in a `.env` file at the project root (Bun loads it automatically).
+
+### Shared
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SCANNER_BACKEND` | `osv` | Backend to use: `osv` or `snyk` |
+
+### OSV backend
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OSV_FAIL_CLOSED` | `false` | Throw on network error instead of failing open |
+| `OSV_NO_CACHE` | `false` | Always query OSV fresh, bypassing the local cache |
+| `OSV_CACHE_FILE` | `.osv.lock` | Path to the cache file |
+| `OSV_TIMEOUT_MS` | `10000` | Per-request timeout in milliseconds |
+| `OSV_API_BASE` | `https://api.osv.dev/v1` | OSV API base URL |
+
+### Snyk backend
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SNYK_TOKEN` | — | **Required.** Snyk API token |
+| `SNYK_ORG_ID` | — | **Required.** Snyk organization ID |
+| `SNYK_FAIL_CLOSED` | `false` | Throw on network error instead of failing open |
+| `SNYK_NO_CACHE` | `false` | Always query Snyk fresh, bypassing the local cache |
+| `SNYK_CACHE_FILE` | `.snyk.lock` | Path to the cache file |
+| `SNYK_TIMEOUT_MS` | `10000` | Per-request timeout in milliseconds |
+| `SNYK_RATE_LIMIT` | `160` | Max requests per minute (hard cap: 180) |
+| `SNYK_CONCURRENCY` | `10` | Max concurrent connections |
+| `SNYK_API_BASE` | `https://api.snyk.io/rest` | Regional endpoint override |
+| `SNYK_API_VERSION` | `2024-04-29` | Snyk REST API version date |
+
+### Fail-open vs fail-closed
+
+By default the scanner **fails open**: if the backend is unreachable the scan is skipped and installation proceeds normally. Set `OSV_FAIL_CLOSED=true` or `SNYK_FAIL_CLOSED=true` to invert this.
+
+```sh
+# .env — strict mode
+OSV_FAIL_CLOSED=true
+```
+
+---
+
+## 🗄️ Cache
+
+Results are cached per `package@version` in a lock file at the project root with a 24-hour TTL. Because a published package version is immutable, its vulnerability profile is stable within that window.
+
+| Backend | Lock file |
+|---------|-----------|
+| OSV | `.osv.lock` |
+| Snyk | `.snyk.lock` |
+
+The files are designed to be **committed to git** — similar to a lockfile, committing them means your team and CI share the cache from day one without waiting for a warm-up scan.
+
+```sh
+git add .osv.lock   # or .snyk.lock
+```
+
+To force a fresh scan:
+
+```sh
+OSV_NO_CACHE=true bun install
+# or
+SNYK_NO_CACHE=true bun install
+```
+
+---
+
+## 🛠️ Development
+
+### Setup
+
+```sh
+git clone https://github.com/muneebs/bun-osv-scanner.git
+cd bun-osv-scanner
+bun install
+```
+
+### Commands
+
+```sh
+bun test              # Run all tests
+bun run lint          # Lint source files
+bun run format        # Check formatting
+bun run format:write  # Auto-fix formatting
+bun run check         # Lint + format check together
+bun run check:write   # Lint + format, auto-fix what it can
+```
+
+### Project structure
+
+```
+bun-osv-scanner/
+├── src/
+│   ├── __tests__/     # Test suite (bun:test)
+│   ├── snyk/          # Snyk backend
+│   ├── cache.ts       # 24h lockfile cache
+│   ├── client.ts      # OSV API client
+│   ├── config.ts      # OSV constants and env vars
+│   ├── display.ts     # TTY progress spinner
+│   ├── index.ts       # Entry point — dispatches to OSV or Snyk
+│   ├── osv.ts         # OSV scanner implementation
+│   └── severity.ts    # OSV level classification
+├── bunfig.toml
+└── package.json
+```
+
+### Backend comparison
+
+| | OSV | Snyk |
+|---|---|---|
+| API key required | No | Yes |
+| Batch endpoint | Yes (1000/req) | No (per-package, 180 req/min) |
+| Coverage | Community feeds + GitHub Advisory | Snyk's proprietary database |
+| Cache file | `.osv.lock` | `.snyk.lock` |
+
+---
+
+## ⚠️ Limitations
+
+- Only scans npm packages with concrete semver versions. `workspace:`, `file:`, `git:`, and range-only specifiers are skipped.
+- OSV aggregates GitHub Advisory, NVD, and other feeds — coverage may lag slightly behind a vulnerability's public disclosure.
+- The OSV batch API has a hard limit of 1,000 queries per request. Larger projects are split across multiple requests automatically.
+- Snyk's per-package endpoint is rate-limited to 180 req/min. At that rate, a project with 2,000+ packages will take several minutes on the first scan.
+
+---
+
+## 📄 License
+
+MIT © [Muneeb Samuels](https://github.com/muneebs)
+
+---
+
+## 🔗 Links
+
+- [📦 npm](https://www.npmjs.com/package/@nebzdev/bun-security-scanner)
+- [🐛 Issue tracker](https://github.com/muneebs/bun-osv-scanner/issues)
+- [🔍 OSV database](https://osv.dev)
+- [📖 Bun security scanner docs](https://bun.com/docs/pm/security-scanner-api)

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@nebzdev/bun-security-scanner",
+  "description": "Bun security scanner powered by Google's OSV vulnerability database",
+  "version": "1.0.1",
+  "author": "Muneeb Samuels",
+  "license": "MIT",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/__tests__",
+    "README.md"
+  ],
+  "keywords": [
+    "bun",
+    "security",
+    "osv",
+    "snyk",
+    "scanner",
+    "vulnerability"
+  ],
+  "scripts": {
+    "publish:npm": "npm publish --access public",
+    "lint": "biome lint ./src",
+    "format": "biome format ./src",
+    "format:write": "biome format --write ./src",
+    "check": "biome check ./src",
+    "check:write": "biome check --write ./src"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.10",
+    "@types/bun": "latest",
+    "typescript": "^5.0.0"
+  }
+}

package/src/cache.ts

@@ -0,0 +1,48 @@
+import { rename } from 'node:fs/promises';
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+export interface CacheEntry {
+  advisories: Bun.Security.Advisory[];
+  cachedAt: number;
+}
+
+type Cache = Record<string, CacheEntry>;
+
+function isValidCache(data: unknown): data is Cache {
+  if (typeof data !== 'object' || data === null || Array.isArray(data))
+    return false;
+  return Object.values(data).every(
+    (entry) =>
+      typeof entry === 'object' &&
+      entry !== null &&
+      Array.isArray((entry as CacheEntry).advisories) &&
+      typeof (entry as CacheEntry).cachedAt === 'number'
+  );
+}
+
+export async function readCache(cacheFile: string): Promise<Cache> {
+  try {
+    const data: unknown = JSON.parse(await Bun.file(cacheFile).text());
+    return isValidCache(data) ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+export async function writeCache(
+  cache: Cache,
+  cacheFile: string
+): Promise<void> {
+  try {
+    // Write to a temp file first, then rename — prevents partial-write corruption
+    // if the process is killed or two installs run concurrently.
+    const tmp = `${cacheFile}.tmp`;
+    await Bun.write(tmp, JSON.stringify(cache, null, 2));
+    await rename(tmp, cacheFile);
+  } catch {}
+}
+
+export function isFresh(entry: CacheEntry): boolean {
+  return Date.now() - entry.cachedAt < CACHE_TTL_MS;
+}

package/src/client.ts

@@ -0,0 +1,72 @@
+import { FETCH_TIMEOUT_MS, OSV_API_BASE, OSV_BATCH_SIZE } from './config';
+
+export interface OsvBatchResponse {
+  results: Array<{
+    vulns?: Array<{ id: string; modified: string }>;
+    next_page_token?: string;
+  }>;
+}
+
+export interface OsvVulnerability {
+  id: string;
+  summary?: string;
+  references?: Array<{ type: string; url: string }>;
+  severity?: Array<{ type: string; score: string }>;
+  database_specific?: {
+    severity?: string;
+    cvss?: { score?: number };
+    [key: string]: unknown;
+  };
+}
+
+function fetchWithTimeout(
+  url: string,
+  options?: RequestInit
+): Promise<Response> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  return fetch(url, { ...options, signal: controller.signal }).finally(() =>
+    clearTimeout(timer)
+  );
+}
+
+// workspace:, file:, git:, and range specifiers cause a 400 for the whole batch.
+export function isResolvable(version: string): boolean {
+  return /^v?\d+\.\d+/.test(version);
+}
+
+export async function batchQuery(
+  packages: Bun.Security.Package[]
+): Promise<OsvBatchResponse['results']> {
+  const results: OsvBatchResponse['results'] = [];
+
+  for (let i = 0; i < packages.length; i += OSV_BATCH_SIZE) {
+    const chunk = packages.slice(i, i + OSV_BATCH_SIZE);
+    const res = await fetchWithTimeout(`${OSV_API_BASE}/querybatch`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        queries: chunk.map((p) => ({
+          version: p.version,
+          package: { name: p.name, ecosystem: 'npm' },
+        })),
+      }),
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      throw new Error(`OSV API ${res.status}: ${body || res.statusText}`);
+    }
+
+    const { results: chunkResults } = (await res.json()) as OsvBatchResponse;
+    results.push(...chunkResults);
+  }
+
+  return results;
+}
+
+export async function fetchVuln(id: string): Promise<OsvVulnerability | null> {
+  const res = await fetchWithTimeout(`${OSV_API_BASE}/vulns/${id}`);
+  if (!res.ok) return null;
+  return res.json() as Promise<OsvVulnerability>;
+}

package/src/config.ts

@@ -0,0 +1,11 @@
+export const OSV_API_BASE = Bun.env.OSV_API_BASE ?? 'https://api.osv.dev/v1';
+// Hard limit enforced by the OSV API — exceeding it returns 400 "Too many queries".
+export const OSV_BATCH_SIZE = 1000;
+export const FETCH_TIMEOUT_MS = Number(Bun.env.OSV_TIMEOUT_MS) || 10_000;
+export const PREFERRED_REF_TYPES = ['ADVISORY', 'WEB', 'ARTICLE'] as const;
+export const CACHE_FILE = Bun.env.OSV_CACHE_FILE ?? '.osv.lock';
+export const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+// When true, network failures throw and cancel installation rather than failing open.
+export const FAIL_CLOSED = Bun.env.OSV_FAIL_CLOSED === 'true';
+export const NO_CACHE = Bun.env.OSV_NO_CACHE === 'true';

package/src/display.ts

@@ -0,0 +1,24 @@
+export function startSpinner(message: string) {
+  if (!process.stderr.isTTY)
+    return { update: (_: string) => {}, stop: () => {} };
+
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let i = 0;
+  let current = message;
+
+  process.stderr.write(`${frames[0]} ${current}`);
+  const interval = setInterval(
+    () => process.stderr.write(`\r${frames[++i % frames.length]} ${current}`),
+    80
+  );
+
+  return {
+    update(msg: string) {
+      current = msg;
+    },
+    stop() {
+      clearInterval(interval);
+      process.stderr.write('\r\x1b[2K');
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+import { backend as osvBackend } from './osv';
+import { type Backend, createScanner } from './scanner';
+import { backend as snykBackend } from './snyk/index';
+
+const registry: Record<string, Backend> = {
+  osv: osvBackend,
+  snyk: snykBackend,
+};
+
+const backendName = (Bun.env.SCANNER_BACKEND ?? 'osv').toLowerCase();
+const selected = registry[backendName];
+
+if (!selected) {
+  process.stderr.write(
+    `[@nebzdev/bun-security-scanner] Unknown SCANNER_BACKEND "${backendName}", falling back to osv.\n`
+  );
+}
+
+export const scanner: Bun.Security.Scanner = createScanner(
+  selected ?? osvBackend
+);

package/src/osv.ts

@@ -0,0 +1,61 @@
+import type { OsvVulnerability } from './client';
+import { batchQuery, fetchVuln } from './client';
+import { CACHE_FILE, FAIL_CLOSED, NO_CACHE } from './config';
+import { type Backend, createScanner } from './scanner';
+import { advisoryUrl, severityLevel } from './severity';
+
+const backend: Backend = {
+  name: 'OSV',
+  cacheFile: CACHE_FILE,
+  noCache: NO_CACHE,
+  failClosed: FAIL_CLOSED,
+
+  async fetchAdvisories(packages, onStatus) {
+    const batchResults = await batchQuery(packages);
+
+    const affected: Array<{ pkg: Bun.Security.Package; vulnId: string }> = [];
+    for (let i = 0; i < packages.length; i++) {
+      for (const { id } of batchResults[i]?.vulns ?? []) {
+        affected.push({ pkg: packages[i], vulnId: id });
+      }
+    }
+
+    const result = new Map<string, Bun.Security.Advisory[]>();
+    for (const pkg of packages) {
+      result.set(`${pkg.name}@${pkg.version}`, []);
+    }
+
+    if (affected.length > 0) {
+      const uniqueIds = [...new Set(affected.map((a) => a.vulnId))];
+      const vulnById = new Map<string, OsvVulnerability>();
+
+      onStatus(
+        `Fetching details for ${uniqueIds.length} ${uniqueIds.length === 1 ? 'vulnerability' : 'vulnerabilities'}...`
+      );
+
+      await Promise.all(
+        uniqueIds.map(async (id) => {
+          const vuln = await fetchVuln(id);
+          if (vuln) vulnById.set(id, vuln);
+        })
+      );
+
+      for (const { pkg, vulnId } of affected) {
+        const vuln = vulnById.get(vulnId);
+        if (vuln) {
+          result.get(`${pkg.name}@${pkg.version}`)?.push({
+            level: severityLevel(vuln),
+            package: pkg.name,
+            url: advisoryUrl(vuln),
+            description: vuln.summary ?? vuln.id,
+          });
+        }
+      }
+    }
+
+    return result;
+  },
+};
+
+export { backend };
+export const scanner = createScanner(backend);

package/src/scanner.ts

@@ -0,0 +1,81 @@
+import { isFresh, readCache, writeCache } from './cache';
+import { isResolvable } from './client';
+import { startSpinner } from './display';
+
+export interface Backend {
+  readonly name: string;
+  readonly cacheFile: string;
+  readonly noCache: boolean;
+  readonly failClosed: boolean;
+  validateConfig?(): void;
+  fetchAdvisories(
+    packages: Bun.Security.Package[],
+    onStatus: (message: string) => void
+  ): Promise<Map<string, Bun.Security.Advisory[]>>;
+}
+
+export function createScanner(backend: Backend): Bun.Security.Scanner {
+  return {
+    version: '1',
+
+    async scan({ packages }) {
+      backend.validateConfig?.();
+
+      const queryable = packages.filter(
+        (p) => p.name && isResolvable(p.version)
+      );
+      if (queryable.length === 0) return [];
+
+      const cache = backend.noCache ? {} : await readCache(backend.cacheFile);
+
+      const cachedAdvisories: Bun.Security.Advisory[] = [];
+      const toQuery: Bun.Security.Package[] = [];
+
+      for (const pkg of queryable) {
+        const entry = cache[`${pkg.name}@${pkg.version}`];
+        if (entry && isFresh(entry)) {
+          cachedAdvisories.push(...entry.advisories);
+        } else {
+          toQuery.push(pkg);
+        }
+      }
+
+      if (toQuery.length === 0) return cachedAdvisories;
+
+      const hitCount = queryable.length - toQuery.length;
+      const spinner = startSpinner(
+        hitCount > 0
+          ? `Scanning ${toQuery.length} packages via ${backend.name} (${hitCount} cached)...`
+          : `Scanning ${queryable.length} packages via ${backend.name}...`
+      );
+
+      try {
+        const advisoryMap = await backend.fetchAdvisories(toQuery, (msg) =>
+          spinner.update(msg)
+        );
+
+        spinner.stop();
+
+        for (const [key, advisories] of advisoryMap) {
+          cache[key] = { advisories, cachedAt: Date.now() };
+        }
+        if (!backend.noCache) void writeCache(cache, backend.cacheFile);
+
+        return [...cachedAdvisories, ...[...advisoryMap.values()].flat()];
+      } catch (err) {
+        spinner.stop();
+
+        if (backend.failClosed) {
+          throw new Error(
+            `${backend.name} scan failed: ${err instanceof Error ? err.message : err}`
+          );
+        }
+
+        process.stderr.write(
+          `\n${backend.name} scan failed (${err instanceof Error ? err.message : err}), skipping.\n`
+        );
+        return cachedAdvisories;
+      }
+    },
+  };
+}

package/src/severity.ts

@@ -0,0 +1,22 @@
+import type { OsvVulnerability } from './client';
+import { PREFERRED_REF_TYPES } from './config';
+
+export function severityLevel(vuln: OsvVulnerability): 'fatal' | 'warn' {
+  const s = vuln.database_specific?.severity?.toUpperCase();
+  if (s === 'CRITICAL' || s === 'HIGH') return 'fatal';
+  if (s === 'MODERATE' || s === 'LOW') return 'warn';
+
+  // Fallback: numeric CVSS score (≥7.0 = HIGH/CRITICAL threshold).
+  const score = vuln.database_specific?.cvss?.score;
+  if (typeof score === 'number') return score >= 7.0 ? 'fatal' : 'warn';
+
+  return 'warn';
+}
+
+export function advisoryUrl(vuln: OsvVulnerability): string {
+  for (const type of PREFERRED_REF_TYPES) {
+    const ref = vuln.references?.find((r) => r.type === type);
+    if (ref) return ref.url;
+  }
+  return `https://osv.dev/vulnerability/${vuln.id}`;
+}

package/src/snyk/client.ts

@@ -0,0 +1,137 @@
+import {
+  CONCURRENCY,
+  FETCH_TIMEOUT_MS,
+  RATE_LIMIT,
+  SNYK_API_BASE,
+  SNYK_API_VERSION,
+  SNYK_ORG_ID,
+  SNYK_TOKEN,
+} from './config';
+
+export interface SnykIssue {
+  id: string;
+  attributes: {
+    title: string;
+    type: string;
+    effective_severity_level: 'critical' | 'high' | 'medium' | 'low';
+    description?: string;
+    problems?: Array<{ id: string; source: string }>;
+  };
+}
+
+interface SnykResponse {
+  data: SnykIssue[];
+  links?: { next?: string };
+}
+
+// Sliding window rate limiter — tracks request timestamps within the last minute.
+class RateLimiter {
+  private readonly timestamps: number[] = [];
+  private readonly windowMs = 60_000;
+
+  constructor(private readonly limit: number) {}
+
+  async acquire(): Promise<void> {
+    const now = Date.now();
+    while (
+      this.timestamps.length > 0 &&
+      now - this.timestamps[0] >= this.windowMs
+    ) {
+      this.timestamps.shift();
+    }
+    if (this.timestamps.length < this.limit) {
+      this.timestamps.push(Date.now());
+      return;
+    }
+    // Wait until the oldest request falls outside the window, then retry.
+    const waitMs = this.windowMs - (Date.now() - this.timestamps[0]) + 10;
+    await Bun.sleep(waitMs);
+    return this.acquire();
+  }
+}
+
+const rateLimiter = new RateLimiter(RATE_LIMIT);
+
+function fetchWithTimeout(
+  url: string,
+  options?: RequestInit
+): Promise<Response> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  return fetch(url, { ...options, signal: controller.signal }).finally(() =>
+    clearTimeout(timer)
+  );
+}
+
+export function validateConfig(): void {
+  if (!SNYK_TOKEN)
+    throw new Error('SNYK_TOKEN is required for the Snyk scanner');
+  if (!SNYK_ORG_ID)
+    throw new Error('SNYK_ORG_ID is required for the Snyk scanner');
+}
+
+function buildPurl(name: string, version: string): string {
+  // Scoped packages: @scope/name -> pkg:npm/scope/name@version (PURL spec §7)
+  if (name.startsWith('@')) {
+    const slash = name.indexOf('/', 1);
+    const scope = name.slice(1, slash);
+    const pkg = name.slice(slash + 1);
+    return `pkg:npm/${scope}/${pkg}@${version}`;
+  }
+  return `pkg:npm/${name}@${version}`;
+}
+
+async function fetchPackageIssues(
+  name: string,
+  version: string,
+  retries = 3
+): Promise<SnykIssue[]> {
+  await rateLimiter.acquire();
+
+  const purl = encodeURIComponent(buildPurl(name, version));
+  const url = `${SNYK_API_BASE}/orgs/${SNYK_ORG_ID}/packages/${purl}/issues?version=${SNYK_API_VERSION}&limit=1000`;
+
+  const res = await fetchWithTimeout(url, {
+    headers: {
+      Authorization: `token ${SNYK_TOKEN}`,
+      'Content-Type': 'application/vnd.api+json',
+    },
+  });
+
+  if (res.status === 429 && retries > 0) {
+    const retryAfter = res.headers.get('Retry-After');
+    const waitMs = retryAfter ? Number(retryAfter) * 1000 : 60_000;
+    await Bun.sleep(waitMs);
+    return fetchPackageIssues(name, version, retries - 1);
+  }
+
+  if (res.status === 404) return [];
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`Snyk API ${res.status}: ${body || res.statusText}`);
+  }
+
+  const { data } = (await res.json()) as SnykResponse;
+  return data ?? [];
+}
+
+export async function batchFetchIssues(
+  packages: Bun.Security.Package[],
+  onProgress?: (completed: number, total: number) => void
+): Promise<Map<string, SnykIssue[]>> {
+  const results = new Map<string, SnykIssue[]>();
+  let completed = 0;
+
+  for (let i = 0; i < packages.length; i += CONCURRENCY) {
+    await Promise.all(
+      packages.slice(i, i + CONCURRENCY).map(async (pkg) => {
+        const issues = await fetchPackageIssues(pkg.name, pkg.version);
+        results.set(`${pkg.name}@${pkg.version}`, issues);
+        onProgress?.(++completed, packages.length);
+      })
+    );
+  }
+
+  return results;
+}

package/src/snyk/config.ts

@@ -0,0 +1,15 @@
+export const SNYK_API_BASE =
+  Bun.env.SNYK_API_BASE ?? 'https://api.snyk.io/rest';
+export const SNYK_API_VERSION = Bun.env.SNYK_API_VERSION ?? '2024-04-29';
+export const SNYK_TOKEN = Bun.env.SNYK_TOKEN;
+export const SNYK_ORG_ID = Bun.env.SNYK_ORG_ID;
+export const FETCH_TIMEOUT_MS = Number(Bun.env.SNYK_TIMEOUT_MS) || 10_000;
+export const FAIL_CLOSED = Bun.env.SNYK_FAIL_CLOSED === 'true';
+export const NO_CACHE = Bun.env.SNYK_NO_CACHE === 'true';
+// Max concurrent connections (independent of rate limit)
+export const CONCURRENCY = Number(Bun.env.SNYK_CONCURRENCY) || 10;
+// Requests per minute — hard ceiling is 180; default leaves headroom
+export const RATE_LIMIT = Math.min(Number(Bun.env.SNYK_RATE_LIMIT) || 160, 180);
+
+export const CACHE_FILE = Bun.env.SNYK_CACHE_FILE ?? '.snyk.lock';
+export const CACHE_TTL_MS = 24 * 60 * 60 * 1000;

package/src/snyk/index.ts

@@ -0,0 +1,38 @@
+import { type Backend, createScanner } from '../scanner';
+import { batchFetchIssues, validateConfig } from './client';
+import { CACHE_FILE, FAIL_CLOSED, NO_CACHE } from './config';
+import { advisoryUrl, severityLevel } from './severity';
+
+const backend: Backend = {
+  name: 'Snyk',
+  cacheFile: CACHE_FILE,
+  noCache: NO_CACHE,
+  failClosed: FAIL_CLOSED,
+  validateConfig,
+
+  async fetchAdvisories(packages, onStatus) {
+    const issueMap = await batchFetchIssues(packages, (done, total) => {
+      onStatus(`Scanning packages via Snyk (${done}/${total})...`);
+    });
+
+    const result = new Map<string, Bun.Security.Advisory[]>();
+    for (const pkg of packages) {
+      const key = `${pkg.name}@${pkg.version}`;
+      const issues = issueMap.get(key) ?? [];
+      result.set(
+        key,
+        issues.map((issue) => ({
+          level: severityLevel(issue),
+          package: pkg.name,
+          url: advisoryUrl(issue),
+          description: issue.attributes.title,
+        }))
+      );
+    }
+
+    return result;
+  },
+};
+
+export { backend };
+export const scanner = createScanner(backend);

package/src/snyk/severity.ts

@@ -0,0 +1,10 @@
+import type { SnykIssue } from './client';
+
+export function severityLevel(issue: SnykIssue): 'fatal' | 'warn' {
+  const level = issue.attributes.effective_severity_level;
+  return level === 'critical' || level === 'high' ? 'fatal' : 'warn';
+}
+
+export function advisoryUrl(issue: SnykIssue): string {
+  return `https://security.snyk.io/vuln/${issue.id}`;
+}