@involvex/bun-scanner 1.0.0

package/.github/workflows/test.yml

@@ -0,0 +1,26 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Run tests
+        run: bun test

package/.prettierrc

@@ -0,0 +1,11 @@
+{
+	"$schema": "http://json.schemastore.org/prettierrc",
+	"singleQuote": true,
+	"semi": true,
+	"printWidth": 100,
+	"trailingComma": "all",
+	"arrowParens": "avoid",
+	"bracketSpacing": false,
+	"useTabs": true,
+	"quoteProps": "consistent"
+}

package/README.md

@@ -0,0 +1,108 @@
+<img src="https://bun.com/logo.png" height="36" />
+
+# Bun Security Scanner Template
+
+A template for creating a security scanner for Bun's package installation
+process. Security scanners scan packages against your threat intelligence feeds
+and control whether installations proceed based on detected threats.
+
+📚 [**Full documentation**](https://bun.com/docs/install/security-scanner-api)
+
+## How It Works
+
+When packages are installed via Bun, your security scanner:
+
+1. **Receives** package information (name, version)
+2. **Queries** your threat intelligence API
+3. **Validates** the response data
+4. **Categorizes** threats by severity
+5. **Returns** advisories to control installation (empty array if safe)
+
+### Advisory Levels
+
+- **Fatal** (`level: 'fatal'`): Installation stops immediately
+  - Examples: malware, token stealers, backdoors, critical vulnerabilities
+- **Warning** (`level: 'warn'`): User prompted for confirmation
+  - In TTY: User can choose to continue or cancel
+  - Non-TTY: Installation automatically cancelled
+  - Examples: protestware, adware, deprecated packages
+
+All advisories are always displayed to the user regardless of level.
+
+### Error Handling
+
+If your `scan` function throws an error, it will be gracefully handled by Bun, but the installation process **will be cancelled** as a defensive precaution.
+
+### Validation
+
+When fetching threat feeds over the network, use schema validation  
+(e.g., Zod) to ensure data integrity. Invalid responses should fail immediately
+rather than silently returning empty advisories.
+
+```typescript
+import {z} from 'zod';
+
+const ThreatFeedItemSchema = z.object({
+	package: z.string(),
+	version: z.string(),
+	url: z.string().nullable(),
+	description: z.string().nullable(),
+	categories: z.array(z.enum(['backdoor', 'botnet' /* ... */])),
+});
+```
+
+### Useful Bun APIs
+
+Bun provides several built-in APIs that are particularly useful for security scanner:
+
+- [**Security scanner API Reference**](https://bun.com/docs/install/security-scanner-api): Complete API documentation for security scanners
+- [**`Bun.semver.satisfies()`**](https://bun.com/docs/api/semver): Essential for checking if package versions match vulnerability ranges. No external dependencies needed.
+
+  ```typescript
+  if (Bun.semver.satisfies(version, '>=1.0.0 <1.2.5')) {
+  	// Version is vulnerable
+  }
+  ```
+
+- [**`Bun.hash`**](https://bun.com/docs/api/hashing#bun-hash): Fast hashing for package integrity checks
+- [**`Bun.file`**](https://bun.com/docs/api/file-io): Efficient file I/O, could be used for reading local threat databases
+
+## Testing
+
+This template includes tests for a known malicious package version.
+Customize the test file as needed.
+
+```bash
+bun test
+```
+
+## Publishing Your Provider
+
+Publish your security scanner to npm:
+
+```bash
+bun publish
+```
+
+Users can now install your provider and add it to their `bunfig.toml` configuration.
+
+To test locally before publishing, use [`bun link`](https://bun.sh/docs/cli/link):
+
+```bash
+# In your provider directory
+bun link
+
+# In your test project
+bun link @acme/bun # this is the name in package.json of your provider
+```
+
+## Contributing
+
+This is a template repository. Fork it and customize for your organization's
+security requirements.
+
+## Support
+
+For docs and questions, see the [Bun documentation](https://bun.com/docs/install/security-scanner-api) or [Join our Discord](https://bun.com/discord).
+
+For template issues, please open an issue in this repository.

package/package.json

@@ -0,0 +1,25 @@
+{
+	"name": "@involvex/bun-scanner",
+	"description": "Bun security scanner ",
+	"version": "1.0.0",
+	"author": "involvex",
+	"license": "MIT",
+	"exports": {
+		"./package.json": "./package.json",
+		".": "./src/index.ts"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/involvex/involvex-bun-scan"
+	},
+	"keywords": [
+		"bun",
+		"security",
+		"provider"
+	],
+	"devDependencies": {
+		"@types/bun": "^1.3.5",
+		"prettier": "^3.7.4",
+		"typescript": "^5.9.3"
+	}
+}

package/scanner.test.ts

@@ -0,0 +1,115 @@
+import {expect, test} from 'bun:test';
+import {scanner} from './src/index.ts';
+
+/////////////////////////////////////////////////////////////////////////////////////
+//  This test file is mostly just here to get you up and running quickly. It's
+//  likely you'd want to improve or remove this, and add more coverage for your
+//  own code.
+/////////////////////////////////////////////////////////////////////////////////////
+
+test('Scanner should warn about known malicious packages', async () => {
+	const advisories = await scanner.scan({
+		packages: [
+			{
+				name: 'event-stream',
+				version: '3.3.6', // This was a known incident in 2018 - https://blog.npmjs.org/post/180565383195/details-about-the-event-stream-incident
+				requestedRange: '^3.3.0',
+				tarball: 'https://registry.npmjs.org/event-stream/-/event-stream-3.3.6.tgz',
+			},
+		],
+	});
+
+	expect(advisories.length).toBeGreaterThan(0);
+	const advisory = advisories[0]!;
+	expect(advisory).toBeDefined();
+
+	expect(advisory).toMatchObject({
+		level: 'fatal',
+		package: 'event-stream',
+		url: expect.any(String),
+		description: expect.any(String),
+	});
+});
+
+test('There should be no advisories if no packages are being installed', async () => {
+	const advisories = await scanner.scan({packages: []});
+	expect(advisories.length).toBe(0);
+});
+
+test('Safe packages should return no advisories', async () => {
+	const advisories = await scanner.scan({
+		packages: [
+			{
+				name: 'lodash',
+				version: '4.17.21',
+				requestedRange: '^4.17.0',
+				tarball: 'https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz',
+			},
+		],
+	});
+	expect(advisories.length).toBe(0);
+});
+
+test('Should handle multiple packages with mixed security status', async () => {
+	const advisories = await scanner.scan({
+		packages: [
+			{
+				name: 'event-stream',
+				version: '3.3.6', // malicious
+				requestedRange: '^3.3.0',
+				tarball: 'https://registry.npmjs.org/event-stream/-/event-stream-3.3.6.tgz',
+			},
+			{
+				name: 'lodash',
+				version: '4.17.21', // safe
+				requestedRange: '^4.17.0',
+				tarball: 'https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz',
+			},
+		],
+	});
+
+	expect(advisories.length).toBe(1);
+	expect(advisories[0]?.package).toBe('event-stream');
+});
+
+test('Should differentiate between versions of the same package', async () => {
+	const maliciousVersion = await scanner.scan({
+		packages: [
+			{
+				name: 'event-stream',
+				version: '3.3.6', // malicious version
+				requestedRange: '3.3.6',
+				tarball: 'https://registry.npmjs.org/event-stream/-/event-stream-3.3.6.tgz',
+			},
+		],
+	});
+
+	const safeVersion = await scanner.scan({
+		packages: [
+			{
+				name: 'event-stream',
+				version: '4.0.0', // safe version
+				requestedRange: '4.0.0',
+				tarball: 'https://registry.npmjs.org/event-stream/-/event-stream-4.0.0.tgz',
+			},
+		],
+	});
+
+	expect(maliciousVersion.length).toBeGreaterThan(0);
+	expect(safeVersion.length).toBe(0);
+});
+
+test('Should handle scoped packages correctly', async () => {
+	const advisories = await scanner.scan({
+		packages: [
+			{
+				name: '@types/node',
+				version: '20.0.0',
+				requestedRange: '^20.0.0',
+				tarball: 'https://registry.npmjs.org/@types/node/-/node-20.0.0.tgz',
+			},
+		],
+	});
+
+	expect(advisories.length).toBe(0);
+});

package/src/index.ts

@@ -0,0 +1,74 @@
+// This is just an example interface of mock data. You can change this to the
+// type of your actual threat feed (or ideally use a good schema validation
+// library to infer your types from).
+interface ThreatFeedItem {
+	package: string;
+	range: string;
+	url: string | null;
+	description: string | null;
+	categories: Array<'protestware' | 'adware' | 'backdoor' | 'malware' | 'botnet'>;
+}
+
+async function fetchThreatFeed(packages: Bun.Security.Package[]): Promise<ThreatFeedItem[]> {
+	// In a real provider you would probably replace this mock data with a
+	// fetch() to your threat feed, validating it with Zod or a similar library.
+
+	const myPretendThreatFeed: ThreatFeedItem[] = [
+		{
+			package: 'event-stream',
+			range: '>=3.3.6 <4.0.0', // Matches 3.3.6 and above but less than 4.0.0
+			url: 'https://blog.npmjs.org/post/180565383195/details-about-the-event-stream-incident',
+			description: 'event-stream is a malicious package',
+			categories: ['malware'],
+		},
+		// ...
+	];
+
+	return myPretendThreatFeed.filter(item => {
+		return packages.some(
+			p => p.name === item.package && Bun.semver.satisfies(p.version, item.range),
+		);
+	});
+}
+
+export const scanner: Bun.Security.Scanner = {
+	version: '1', // This is the version of Bun security scanner implementation. You should keep this set as '1'
+	async scan({packages}) {
+		const feed = await fetchThreatFeed(packages);
+
+		// Iterate over reported threats and return an array of advisories. This
+		// could be longer, shorter or equal length of the input packages array.
+		// Whatever you return will be shown to the user.
+
+		const results: Bun.Security.Advisory[] = [];
+
+		for (const item of feed) {
+			// Advisory levels control installation behavior:
+			// - All advisories are always shown to the user regardless of level
+			// - Fatal: Installation stops immediately (e.g., backdoors, botnets)
+			// - Warning: User prompted in TTY, auto-cancelled in non-TTY (e.g., protestware, adware)
+
+			const isFatal =
+				item.categories.includes('malware') ||
+				item.categories.includes('backdoor') ||
+				item.categories.includes('botnet');
+
+			const isWarning =
+				item.categories.includes('protestware') || item.categories.includes('adware');
+
+			if (!isFatal && !isWarning) continue;
+
+			// Besides the .level property, the other properties are just here
+			// for display to the user.
+			results.push({
+				level: isFatal ? 'fatal' : 'warn',
+				package: item.package,
+				url: item.url,
+				description: item.description,
+			});
+		}
+
+		// Return an empty array if there are no advisories!
+		return results;
+	},
+};

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+	"compilerOptions": {
+		"lib": ["ESNext"],
+		"target": "ESNext",
+		"module": "Preserve",
+		"moduleDetection": "force",
+		"jsx": "react-jsx",
+		"allowJs": true,
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+		"noEmit": true,
+		"strict": true,
+		"skipLibCheck": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedIndexedAccess": true,
+		"noImplicitOverride": true,
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noPropertyAccessFromIndexSignature": false
+	}
+}