@nebzdev/bun-security-scanner 1.0.1 → 1.1.0

package/README.md

@@ -4,15 +4,17 @@
 [![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)
+![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/muneebs/bun-security-scanner?utm_source=oss&utm_medium=github&utm_campaign=muneebs%2Fbun-security-scanner&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
 
 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
+- ⚡ **Fast**: per-package lockfile cache (24h by default, configurable) 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
+- 🎯 **CVSS fallback**: falls back to score-based severity when a label isn't available
+- 🙈 **Ignore file**: suppress false positives and accepted risks with `.bun-security-ignore`
+- ⚙️ **Configurable**: tune behaviour via environment variables
 
 ---
 
@@ -31,15 +33,6 @@ 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
@@ -78,10 +71,10 @@ SNYK_ORG_ID=your-org-id
 
 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
+1. Filters non-resolvable versions — workspace, git, file, and path dependencies are skipped
+2. Checks the cache — packages seen within the cache TTL (24h by default) 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
 
 ---
 
@@ -89,7 +82,7 @@ When `bun install` runs, Bun calls the scanner with the full list of packages to
 
 | Level | Trigger | Bun behaviour |
 |-------|---------|---------------|
-| `fatal` | CRITICAL or HIGH severity; or CVSS score ≥ 7.0 | Installation halts |
+| `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 |
 
 ---
@@ -111,8 +104,10 @@ All options are set via environment variables — in your shell, or in a `.env`
 | `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_CACHE_TTL_MS` | `86400000` | Cache TTL in milliseconds (default: 24 hours) |
 | `OSV_TIMEOUT_MS` | `10000` | Per-request timeout in milliseconds |
 | `OSV_API_BASE` | `https://api.osv.dev/v1` | OSV API base URL |
+| `OSV_NO_IGNORE` | `false` | Disable `.bun-security-ignore` processing |
 
 ### Snyk backend
 
@@ -123,6 +118,7 @@ All options are set via environment variables — in your shell, or in a `.env`
 | `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_CACHE_TTL_MS` | `86400000` | Cache TTL in milliseconds (default: 24 hours) |
 | `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 |
@@ -131,10 +127,10 @@ All options are set via environment variables — in your shell, or in a `.env`
 
 ### 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.
+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
+# .env -- strict mode
 OSV_FAIL_CLOSED=true
 ```
 
@@ -142,14 +138,22 @@ 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.
+Results are cached per `package@version` in a lock file at the project root. Because a published package version is immutable, its vulnerability profile is stable within the cache window.
 
-| Backend | Lock file |
-|---------|-----------|
-| OSV | `.osv.lock` |
-| Snyk | `.snyk.lock` |
+| Backend | Lock file | TTL env var |
+|---------|-----------|-------------|
+| OSV | `.osv.lock` | `OSV_CACHE_TTL_MS` |
+| Snyk | `.snyk.lock` | `SNYK_CACHE_TTL_MS` |
 
-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.
+The default TTL is 24 hours. In CI environments where cold-start scan time is a concern, increase it:
+
+```sh
+# .env.ci
+OSV_CACHE_TTL_MS=604800000   # 7 days
+SNYK_CACHE_TTL_MS=604800000  # 7 days
+```
+
+The lock files are designed to be committed to git. Like 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
@@ -165,14 +169,74 @@ SNYK_NO_CACHE=true bun install
 
 ---
 
+## 🙈 Ignore file
+
+Not every advisory is actionable. A vulnerability may affect a code path your project doesn't use, have no fix available yet, or be a false positive. The `.bun-security-ignore` file lets you acknowledge these cases without blocking installs permanently.
+
+### Format
+
+```toml
+# .bun-security-ignore
+
+[[ignore]]
+package    = "lodash"
+advisories = ["GHSA-35jh-r3h4-6jhm"]
+reason     = "Only affects the cloneDeep path, which we do not use."
+expires    = "2026-12-31"   # optional -- re-surfaces automatically after this date
+
+[[ignore]]
+package    = "minimist"
+advisories = ["*"]           # wildcard -- suppress all advisories for this package
+reason     = "Transitive only, no direct usage, no fix available."
+```
+
+### Behaviour
+
+| Advisory level | Session type | Effect |
+|----------------|--------------|--------|
+| `fatal` matched | Interactive (no `CI=true`, stdin is a TTY) | Downgraded to `warn` — visible in output but no longer blocks the install |
+| `fatal` matched | CI / non-interactive | Suppressed entirely — logged to stderr but not returned |
+| `warn` matched | Any | Suppressed entirely — logged to stderr but not returned |
+
+All suppressions are logged to stderr so they remain visible in CI output. Ignored advisories are never silently swallowed.
+
+- `expires` -- entries re-activate at UTC midnight on the given date, so you're reminded when to reassess
+- `advisories = ["*"]` -- wildcard suppresses all advisories for the package
+- `reason` -- encouraged but not required; a notice is printed to stderr if omitted
+- `OSV_NO_IGNORE=true` -- disables all ignore file processing for strict environments
+- `BUN_SECURITY_IGNORE_FILE` -- override the default `.bun-security-ignore` path
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BUN_SECURITY_IGNORE_FILE` | `.bun-security-ignore` | Path to the ignore file |
+| `OSV_NO_IGNORE` | `false` | Disable all ignore file processing |
+
+### Committing the file
+
+The ignore file should be committed alongside your lockfile. It documents deliberate risk-acceptance decisions for your whole team and CI.
+
+---
+
 ## 🛠️ Development
 
 ### Setup
 
 ```sh
-git clone https://github.com/muneebs/bun-osv-scanner.git
-cd bun-osv-scanner
+git clone https://github.com/muneebs/bun-security-scanner.git
+cd bun-security-scanner
 bun install
+bunx lefthook install
+```
+
+### Local development
+
+Point `bunfig.toml` directly at the entry file using an absolute or relative path:
+
+```toml
+[install.security]
+scanner = "../bun-security-scanner/src/index.ts"
 ```
 
 ### Commands
@@ -189,17 +253,20 @@ bun run check:write   # Lint + format, auto-fix what it can
 ### Project structure
 
 ```
-bun-osv-scanner/
+bun-security-scanner/
 ├── src/
 │   ├── __tests__/     # Test suite (bun:test)
 │   ├── snyk/          # Snyk backend
-│   ├── cache.ts       # 24h lockfile cache
+│   ├── cache.ts       # Lockfile cache (configurable TTL)
 │   ├── 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
+│   ├── ignore.ts      # .bun-security-ignore loader and matcher
+│   ├── index.ts       # Entry point -- dispatches to OSV or Snyk
 │   ├── osv.ts         # OSV scanner implementation
+│   ├── scanner.ts     # Shared scanner factory (cache + ignore orchestration)
 │   └── severity.ts    # OSV level classification
+├── dist/              # Compiled output (published to npm)
 ├── bunfig.toml
 └── package.json
 ```
@@ -218,7 +285,7 @@ bun-osv-scanner/
 ## ⚠️ 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.
+- OSV aggregates GitHub Advisory, NVD, and other feeds, so 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.
 
@@ -233,6 +300,6 @@ 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)
+- [🐛 Issue tracker](https://github.com/muneebs/bun-security-scanner/issues)
 - [🔍 OSV database](https://osv.dev)
-- [📖 Bun security scanner docs](https://bun.com/docs/pm/security-scanner-api)
+- [📖 Bun security scanner docs](https://bun.com/docs/pm/security-scanner-api)

package/dist/index.js

@@ -0,0 +1,9 @@
+// @bun
+var Z=Bun.env.OSV_API_BASE??"https://api.osv.dev/v1",C=1000,K=Number(Bun.env.OSV_TIMEOUT_MS)||1e4,F=["ADVISORY","WEB","ARTICLE"],G=Bun.env.OSV_CACHE_FILE??".osv.lock",A=Number(Bun.env.OSV_CACHE_TTL_MS),L=Number.isFinite(A)&&A>=0?A:86400000,N=Bun.env.OSV_FAIL_CLOSED==="true",Y=Bun.env.OSV_NO_CACHE==="true";function O(f,$){let x=new AbortController,j=setTimeout(()=>x.abort(),K);return fetch(f,{...$,signal:x.signal}).finally(()=>clearTimeout(j))}function P(f){return/^v?\d+\.\d+/.test(f)}async function t(f){let $=[];for(let x=0;x<f.length;x+=C){let j=f.slice(x,x+C),z=await O(`${Z}/querybatch`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({queries:j.map((X)=>({version:X.version,package:{name:X.name,ecosystem:"npm"}}))})});if(!z.ok){let X=await z.text().catch(()=>"");throw Error(`OSV API ${z.status}: ${X||z.statusText}`)}let{results:B}=await z.json();$.push(...B)}return $}async function E(f){let $=await O(`${Z}/vulns/${f}`);if(!$.ok)return null;return $.json()}import{rename as zf}from"fs/promises";var jf=86400000;function Jf(f){if(typeof f!=="object"||f===null||Array.isArray(f))return!1;return Object.values(f).every(($)=>typeof $==="object"&&$!==null&&Array.isArray($.advisories)&&typeof $.cachedAt==="number")}async function w(f){try{let $=JSON.parse(await Bun.file(f).text());return Jf($)?$:{}}catch{return{}}}async function v(f,$){try{let x=`${$}.tmp`;await Bun.write(x,JSON.stringify(f,null,2)),await zf(x,$)}catch{}}function b(f,$=jf){return Date.now()-f.cachedAt<$}function I(f){if(!process.stderr.isTTY)return{update:(B)=>{},stop:()=>{}};let $=["\u280B","\u2819","\u2839","\u2838","\u283C","\u2834","\u2826","\u2827","\u2807","\u280F"],x=0,j=f;process.stderr.write(`${$[0]} ${j}`);let z=setInterval(()=>process.stderr.write(`\r${$[++x%$.length]} ${j}`),80);return{update(B){j=B},stop(){clearInterval(z),process.stderr.write("\r\x1B[2K")}}}var R=Bun.env.BUN_SECURITY_IGNORE_FILE??".bun-security-ignore",Xf=Bun.env.OSV_NO_IGNORE==="true";function mf(f){let x=Bun.TOML.parse(f).ignore;if(!Array.isArray(x))return[];let j=[];for(let z of x){if(typeof z!=="object"||z===null)continue;let B=z;if(typeof B.package!=="string"||!B.package)continue;let X=Array.isArray(B.advisories)?B.advisories.filter((D)=>typeof D==="string"):[],J={package:B.package,advisories:X};if(typeof B.reason==="string")J.reason=B.reason;if(typeof B.expires==="string")J.expires=B.expires;else if(B.expires instanceof Date)J.expires=B.expires.toISOString().slice(0,10);j.push(J)}return j}async function l(){if(Xf)return{entries:[]};let f;try{f=await Bun.file(R).text()}catch{return{entries:[]}}let $;try{$=mf(f)}catch(x){return process.stderr.write(`[@nebzdev/bun-security-scanner] Warning: failed to parse "${R}" \u2014 ${x instanceof Error?x.message:x}. All ignore entries will be skipped.
+`),{entries:[]}}for(let x of $)if(!x.reason)process.stderr.write(`[@nebzdev/bun-security-scanner] Warning: ignore entry for "${x.package}" has no reason \u2014 consider documenting why.
+`);return{entries:$}}function Df(f){if(!f.expires)return!0;let $=new Date(`${f.expires}T00:00:00Z`);return Date.now()<$.getTime()}function Hf(f){return f?.split("/").pop()?.toUpperCase()??""}function T(f,$){let x=Hf(f.url);for(let j of $.entries){if(j.package!==f.package)continue;if(!Df(j))continue;if(!(j.advisories.includes("*")||j.advisories.map((J)=>J.toUpperCase()).includes(x)))continue;let X=j.reason??"(no reason provided)";if(f.level==="fatal")return{action:"downgrade",reason:X};return{action:"drop",reason:X}}return{action:"keep"}}function S(f){return{version:"1",async scan({packages:$}){f.validateConfig?.();let x=$.filter((m)=>m.name&&P(m.version));if(x.length===0)return[];let[j,z]=await Promise.all([f.noCache?Promise.resolve({}):w(f.cacheFile),l()]),B=[],X=[];for(let m of x){let H=j[`${m.name}@${m.version}`];if(H&&b(H,f.ttl))B.push(...H.advisories);else X.push(m)}if(X.length===0)return V(B,z);let J=x.length-X.length,D=I(J>0?`Scanning ${X.length} packages via ${f.name} (${J} cached)...`:`Scanning ${x.length} packages via ${f.name}...`);try{let m=await f.fetchAdvisories(X,(H)=>D.update(H));D.stop();for(let[H,xf]of m)j[H]={advisories:xf,cachedAt:Date.now()};if(!f.noCache)v(j,f.cacheFile);return V([...B,...[...m.values()].flat()],z)}catch(m){if(D.stop(),f.failClosed)throw Error(`${f.name} scan failed: ${m instanceof Error?m.message:m}`);return process.stderr.write(`
+${f.name} scan failed (${m instanceof Error?m.message:m}), skipping.
+`),V(B,z)}}}}function V(f,$){if($.entries.length===0)return f;let x=process.env.CI!=="true"&&(process.stdin?.isTTY??!1),j=[];for(let z of f){let B=T(z,$);if(B.action==="keep")j.push(z);else if(B.action==="downgrade"&&x)process.stderr.write(`[@nebzdev/bun-security-scanner] Downgrading ${z.package} fatal advisory to warn (${z.url}) \u2014 ${B.reason}
+`),j.push({...z,level:"warn"});else process.stderr.write(`[@nebzdev/bun-security-scanner] Suppressing ${z.package} advisory (${z.url}) \u2014 ${B.reason}
+`)}return j}function _(f){let $=f.database_specific?.severity?.toUpperCase();if($==="CRITICAL"||$==="HIGH")return"fatal";if($==="MODERATE"||$==="LOW")return"warn";let x=f.database_specific?.cvss?.score;if(typeof x==="number")return x>=7?"fatal":"warn";return"warn"}function p(f){for(let $ of F){let x=f.references?.find((j)=>j.type===$);if(x)return x.url}return`https://osv.dev/vulnerability/${f.id}`}var U={name:"OSV",cacheFile:G,ttl:L,noCache:Y,failClosed:N,async fetchAdvisories(f,$){let x=await t(f),j=[];for(let B=0;B<f.length;B++)for(let{id:X}of x[B]?.vulns??[])j.push({pkg:f[B],vulnId:X});let z=new Map;for(let B of f)z.set(`${B.name}@${B.version}`,[]);if(j.length>0){let B=[...new Set(j.map((J)=>J.vulnId))],X=new Map;$(`Fetching details for ${B.length} ${B.length===1?"vulnerability":"vulnerabilities"}...`),await Promise.all(B.map(async(J)=>{let D=await E(J);if(D)X.set(J,D)}));for(let{pkg:J,vulnId:D}of j){let m=X.get(D);if(m)z.get(`${J.name}@${J.version}`)?.push({level:_(m),package:J.name,url:p(m),description:m.summary??m.id})}}return z}};var vf=S(U);var n=Bun.env.SNYK_API_BASE??"https://api.snyk.io/rest",g=Bun.env.SNYK_API_VERSION??"2024-04-29",u=Bun.env.SNYK_TOKEN,M=Bun.env.SNYK_ORG_ID,c=Number(Bun.env.SNYK_TIMEOUT_MS)||1e4,k=Bun.env.SNYK_FAIL_CLOSED==="true",y=Bun.env.SNYK_NO_CACHE==="true",Q=Number(Bun.env.SNYK_CONCURRENCY)||10,h=Math.min(Number(Bun.env.SNYK_RATE_LIMIT)||160,180),o=Bun.env.SNYK_CACHE_FILE??".snyk.lock",q=Number(Bun.env.SNYK_CACHE_TTL_MS),d=Number.isFinite(q)&&q>=0?q:86400000;class i{limit;timestamps=[];windowMs=60000;constructor(f){this.limit=f}async acquire(){let f=Date.now();while(this.timestamps.length>0&&f-this.timestamps[0]>=this.windowMs)this.timestamps.shift();if(this.timestamps.length<this.limit){this.timestamps.push(Date.now());return}let $=this.windowMs-(Date.now()-this.timestamps[0])+10;return await Bun.sleep($),this.acquire()}}var Sf=new i(h);function Uf(f,$){let x=new AbortController,j=setTimeout(()=>x.abort(),c);return fetch(f,{...$,signal:x.signal}).finally(()=>clearTimeout(j))}function s(){if(!u)throw Error("SNYK_TOKEN is required for the Snyk scanner");if(!M)throw Error("SNYK_ORG_ID is required for the Snyk scanner")}function Af(f,$){if(f.startsWith("@")){let x=f.indexOf("/",1),j=f.slice(1,x),z=f.slice(x+1);return`pkg:npm/${j}/${z}@${$}`}return`pkg:npm/${f}@${$}`}async function r(f,$,x=3){await Sf.acquire();let j=encodeURIComponent(Af(f,$)),z=`${n}/orgs/${M}/packages/${j}/issues?version=${g}&limit=1000`,B=await Uf(z,{headers:{Authorization:`token ${u}`,"Content-Type":"application/vnd.api+json"}});if(B.status===429&&x>0){let J=B.headers.get("Retry-After"),D=J?Number(J)*1000:60000;return await Bun.sleep(D),r(f,$,x-1)}if(B.status===404)return[];if(!B.ok){let J=await B.text().catch(()=>"");throw Error(`Snyk API ${B.status}: ${J||B.statusText}`)}let{data:X}=await B.json();return X??[]}async function a(f,$){let x=new Map,j=0;for(let z=0;z<f.length;z+=Q)await Promise.all(f.slice(z,z+Q).map(async(B)=>{let X=await r(B.name,B.version);x.set(`${B.name}@${B.version}`,X),$?.(++j,f.length)}));return x}function e(f){let $=f.attributes.effective_severity_level;return $==="critical"||$==="high"?"fatal":"warn"}function ff(f){return`https://security.snyk.io/vuln/${f.id}`}var W={name:"Snyk",cacheFile:o,ttl:d,noCache:y,failClosed:k,validateConfig:s,async fetchAdvisories(f,$){let x=await a(f,(z,B)=>{$(`Scanning packages via Snyk (${z}/${B})...`)}),j=new Map;for(let z of f){let B=`${z.name}@${z.version}`,X=x.get(B)??[];j.set(B,X.map((J)=>({level:e(J),package:z.name,url:ff(J),description:J.attributes.title})))}return j}};var cf=S(W);var Zf={osv:U,snyk:W},$f=(Bun.env.SCANNER_BACKEND??"osv").toLowerCase(),Bf=Zf[$f];if(!Bf)process.stderr.write(`[@nebzdev/bun-security-scanner] Unknown SCANNER_BACKEND "${$f}", falling back to osv.
+`);var df=S(Bf??U);export{df as scanner};

package/package.json

@@ -1,16 +1,15 @@
 {
   "name": "@nebzdev/bun-security-scanner",
   "description": "Bun security scanner powered by Google's OSV vulnerability database",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "author": "Muneeb Samuels",
   "license": "MIT",
   "exports": {
     "./package.json": "./package.json",
-    ".": "./src/index.ts"
+    ".": "./dist/index.js"
   },
   "files": [
-    "src",
-    "!src/__tests__",
+    "dist",
     "README.md"
   ],
   "keywords": [
@@ -22,16 +21,19 @@
     "vulnerability"
   ],
   "scripts": {
-    "publish:npm": "npm publish --access public",
+    "build": "bun run build.ts",
+    "publish:npm": "bun run build && 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"
+    "check:write": "biome check --write ./src",
+    "type-check": "tsc --noEmit"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.10",
     "@types/bun": "latest",
+    "lefthook": "^2.1.4",
     "typescript": "^5.0.0"
   }
 }

package/src/cache.ts

@@ -1,48 +0,0 @@
-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

@@ -1,72 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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

@@ -1,61 +0,0 @@
-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

@@ -1,81 +0,0 @@
-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

@@ -1,22 +0,0 @@
-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

@@ -1,137 +0,0 @@
-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

@@ -1,15 +0,0 @@
-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

@@ -1,38 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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}`;
-}