@browsertotal/scanner 2.0.0

package/README.md

@@ -0,0 +1,366 @@
+<img src="https://browsertotal.com/icons/logo.svg" alt="BrowserTotal Logo" width="200" />
+
+# @browsertotal/scanner
+
+Scan URLs, browser extensions, IDE plugins, and packages for security threats using [BrowserTotal.com](https://browsertotal.com).
+
+This package uses Puppeteer to automate browser interactions with BrowserTotal's analysis tools. It leverages a custom event system (`#automationEvent=true`) to receive complete scan results including AI/LLM analysis.
+
+## Supported Platforms
+
+| Platform | Method | Description |
+|----------|--------|-------------|
+| **URLs** | `scanUrl()` | Scan any URL for security threats |
+| **Chrome** | `scanExtension()` | Chrome Web Store extensions |
+| **Firefox** | `scanExtension()` | Firefox Add-ons |
+| **Edge** | `scanExtension()` | Microsoft Edge Add-ons |
+| **Opera** | `scanExtension()` | Opera Add-ons |
+| **Safari** | `scanExtension()` | Safari Extensions |
+| **Brave** | `scanExtension()` | Brave Extensions |
+| **VS Code** | `scanVSCodeExtension()` | Visual Studio Marketplace extensions |
+| **Open VSX** | `scanOpenVSXExtension()` | Open VSX Registry extensions |
+| **JetBrains** | `scanJetBrainsPlugin()` | IntelliJ, PyCharm, WebStorm plugins |
+| **npm** | `scanNpmPackage()` | npm packages |
+| **PyPI** | `scanPyPIPackage()` | Python packages |
+| **WordPress** | `scanWordPressPlugin()` | WordPress plugins |
+| **Hugging Face** | `scanHuggingFace()` | Hugging Face models/spaces |
+| **AppSource** | `scanAppSourceAddin()` | Microsoft AppSource add-ins |
+| **PowerShell** | `scanPowerShellModule()` | PowerShell Gallery modules |
+| **Salesforce** | `scanSalesforceApp()` | Salesforce AppExchange apps |
+
+## Installation
+
+```bash
+npm install @browsertotal/scanner
+```
+
+## Usage
+
+### Scanning URLs
+
+```typescript
+import { BrowserTotalScanner } from '@browsertotal/scanner';
+
+const scanner = new BrowserTotalScanner();
+
+const result = await scanner.scanUrl('https://example.com');
+console.log(result.status); // 'safe' | 'suspicious' | 'malicious' | 'unknown' | 'error'
+console.log(result.threats);
+console.log(result.raw); // Full analysis data including LLM results
+
+await scanner.close();
+```
+
+### Scanning Browser Extensions
+
+```typescript
+import { BrowserTotalScanner } from '@browsertotal/scanner';
+
+const scanner = new BrowserTotalScanner();
+
+// Chrome extension
+const chromeResult = await scanner.scanExtension('cjpalhdlnbpafiamejdnhcphjbkeiagm', 'chrome');
+
+// Firefox add-on
+const firefoxResult = await scanner.scanExtension('ublock-origin', 'firefox');
+
+// Edge extension
+const edgeResult = await scanner.scanExtension('extension-id', 'edge');
+
+await scanner.close();
+```
+
+### Scanning VS Code Extensions
+
+```typescript
+import { BrowserTotalScanner } from '@browsertotal/scanner';
+
+const scanner = new BrowserTotalScanner();
+
+// VS Code Marketplace extension (publisher.extension-name format)
+const result = await scanner.scanVSCodeExtension('ms-python.python');
+console.log(result.name);
+console.log(result.status);
+console.log(result.permissions);
+
+await scanner.close();
+```
+
+### Scanning JetBrains Plugins
+
+```typescript
+import { BrowserTotalScanner } from '@browsertotal/scanner';
+
+const scanner = new BrowserTotalScanner();
+
+// JetBrains plugin by ID
+const result = await scanner.scanJetBrainsPlugin('7495'); // Rainbow Brackets
+console.log(result.status);
+
+await scanner.close();
+```
+
+### Scanning npm Packages
+
+```typescript
+import { BrowserTotalScanner } from '@browsertotal/scanner';
+
+const scanner = new BrowserTotalScanner();
+
+const result = await scanner.scanNpmPackage('lodash');
+console.log(result.status);
+console.log(result.version);
+console.log(result.dependencies);
+
+await scanner.close();
+```
+
+### Scanning PyPI Packages
+
+```typescript
+import { BrowserTotalScanner } from '@browsertotal/scanner';
+
+const scanner = new BrowserTotalScanner();
+
+const result = await scanner.scanPyPIPackage('requests');
+console.log(result.status);
+console.log(result.version);
+
+await scanner.close();
+```
+
+### Scanning WordPress Plugins
+
+```typescript
+import { BrowserTotalScanner } from '@browsertotal/scanner';
+
+const scanner = new BrowserTotalScanner();
+
+const result = await scanner.scanWordPressPlugin('akismet');
+console.log(result.status);
+
+await scanner.close();
+```
+
+### Generic Platform Scanning
+
+Use `scanByPlatform()` for dynamic platform selection:
+
+```typescript
+import { BrowserTotalScanner } from '@browsertotal/scanner';
+
+const scanner = new BrowserTotalScanner();
+
+// Scan any platform dynamically
+const result = await scanner.scanByPlatform('lodash', 'npmjs');
+const result2 = await scanner.scanByPlatform('extension-id', 'chrome');
+const result3 = await scanner.scanByPlatform('ms-python.python', 'vscode');
+
+await scanner.close();
+```
+
+### Convenience Functions
+
+For one-off scans without managing the scanner lifecycle:
+
+```typescript
+import {
+  scanUrl,
+  scanExtension,
+  scanVSCodeExtension,
+  scanJetBrainsPlugin,
+  scanNpmPackage,
+  scanPyPIPackage,
+  scanWordPressPlugin
+} from '@browsertotal/scanner';
+
+// One-off URL scan
+const urlResult = await scanUrl('https://example.com');
+
+// One-off browser extension scan
+const extResult = await scanExtension('extension-id', 'chrome');
+
+// One-off VS Code extension scan
+const vscodeResult = await scanVSCodeExtension('ms-python.python');
+
+// One-off npm package scan
+const npmResult = await scanNpmPackage('express');
+
+// One-off PyPI package scan
+const pypiResult = await scanPyPIPackage('django');
+```
+
+### Progress Tracking
+
+```typescript
+import { BrowserTotalScanner } from '@browsertotal/scanner';
+
+const scanner = new BrowserTotalScanner();
+
+const result = await scanner.scanNpmPackage('express', (progress) => {
+  console.log(`[${progress.phase}] ${progress.message}`);
+});
+
+await scanner.close();
+```
+
+### Configuration Options
+
+```typescript
+import { BrowserTotalScanner } from '@browsertotal/scanner';
+
+const scanner = new BrowserTotalScanner({
+  headless: true,        // Run browser in headless mode (default: true)
+  timeout: 120000,       // Timeout in milliseconds (default: 420000)
+  waitForResults: true,  // Wait for scan to complete (default: true)
+  disableAI: true,       // Skip AI/LLM analysis for faster scans (default: true)
+  userDataDir: '/tmp/browser', // Custom browser profile directory
+});
+```
+
+### Authentication
+
+The scanner uses a Proof of Work challenge-response system that works automatically in headless browsers. No API key is required - the computational proof of work prevents abuse while allowing automated access.
+
+The scanner will automatically:
+1. Request a challenge from the server
+2. Solve the Proof of Work challenge
+3. Submit analysis results with the solution for verification
+
+## How It Works
+
+The scanner uses a special automation mode that:
+
+1. Appends `#automationEvent=true` to scan URLs
+2. BrowserTotal's UI detects this parameter and dispatches a `scan_result` custom event when analysis completes
+3. Puppeteer captures this event to get the full scan results
+
+This approach ensures you get the complete analysis data, including:
+- Static analysis results
+- LLM/AI analysis results
+- Risk scores and threat assessments
+- Permission analysis (for extensions)
+- Dependency analysis (for packages)
+- Vulnerability findings
+
+## API Reference
+
+### `BrowserTotalScanner`
+
+#### Constructor Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `headless` | `boolean` | `true` | Run browser in headless mode |
+| `timeout` | `number` | `420000` | Timeout in milliseconds |
+| `waitForResults` | `boolean` | `true` | Wait for scan results before returning |
+| `disableAI` | `boolean` | `true` | Skip AI/LLM analysis for faster scans |
+| `userDataDir` | `string` | `undefined` | Custom browser profile directory |
+
+#### Methods
+
+##### URL Scanning
+- `scanUrl(url: string, onProgress?: ProgressCallback): Promise<UrlScanResult>`
+
+##### Browser Extensions
+- `scanExtension(extensionId: string, store?: BrowserStore, onProgress?: ProgressCallback): Promise<ExtensionScanResult>`
+
+##### IDE Extensions
+- `scanVSCodeExtension(extensionId: string, onProgress?: ProgressCallback): Promise<ExtensionScanResult>`
+- `scanOpenVSXExtension(extensionId: string, onProgress?: ProgressCallback): Promise<ExtensionScanResult>`
+- `scanJetBrainsPlugin(pluginId: string, onProgress?: ProgressCallback): Promise<ExtensionScanResult>`
+
+##### Package Managers
+- `scanNpmPackage(packageName: string, onProgress?: ProgressCallback): Promise<PackageScanResult>`
+- `scanPyPIPackage(packageName: string, onProgress?: ProgressCallback): Promise<PackageScanResult>`
+- `scanPowerShellModule(moduleName: string, onProgress?: ProgressCallback): Promise<PackageScanResult>`
+
+##### Other Platforms
+- `scanWordPressPlugin(pluginSlug: string, onProgress?: ProgressCallback): Promise<ExtensionScanResult>`
+- `scanHuggingFace(modelId: string, onProgress?: ProgressCallback): Promise<ExtensionScanResult>`
+- `scanAppSourceAddin(addinId: string, onProgress?: ProgressCallback): Promise<ExtensionScanResult>`
+- `scanSalesforceApp(appId: string, onProgress?: ProgressCallback): Promise<ExtensionScanResult>`
+
+##### Generic
+- `scanByPlatform(identifier: string, platform: Platform | BrowserStore, onProgress?: ProgressCallback): Promise<ExtensionScanResult | PackageScanResult>`
+
+##### Lifecycle
+- `close(): Promise<void>` - Closes the browser instance
+
+### Types
+
+#### `BrowserStore`
+
+```typescript
+type BrowserStore = 'chrome' | 'firefox' | 'edge' | 'opera' | 'safari' | 'brave';
+```
+
+#### `Platform`
+
+```typescript
+type Platform =
+  | 'vscode'
+  | 'openvsx'
+  | 'jetbrains'
+  | 'npmjs'
+  | 'pypi'
+  | 'wordpress'
+  | 'huggingface'
+  | 'appsource'
+  | 'powershellgallery'
+  | 'salesforce';
+```
+
+#### `UrlScanResult`
+
+```typescript
+interface UrlScanResult {
+  url: string;
+  status: 'safe' | 'suspicious' | 'malicious' | 'unknown' | 'error';
+  score?: number;
+  threats?: ThreatInfo[];
+  categories?: string[];
+  scanUrl: string;
+  timestamp: Date;
+  raw?: Record<string, unknown>; // Full scan data including LLM results
+}
+```
+
+#### `ExtensionScanResult`
+
+```typescript
+interface ExtensionScanResult {
+  extensionId: string;
+  name?: string;
+  status: 'safe' | 'suspicious' | 'malicious' | 'unknown' | 'error';
+  score?: number;
+  permissions?: string[];
+  threats?: ThreatInfo[];
+  scanUrl: string;
+  timestamp: Date;
+  raw?: Record<string, unknown>; // Full scan data including LLM results
+}
+```
+
+#### `PackageScanResult`
+
+```typescript
+interface PackageScanResult {
+  packageName: string;
+  platform: string;
+  name?: string;
+  version?: string;
+  status: 'safe' | 'suspicious' | 'malicious' | 'unknown' | 'error';
+  score?: number;
+  dependencies?: Record<string, string>;
+  threats?: ThreatInfo[];
+  scanUrl: string;
+  timestamp: Date;
+  raw?: Record<string, unknown>; // Full scan data including LLM results
+}
+```
+
+## Requirements
+
+- Node.js 18+
+- Puppeteer (installed automatically)

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { BrowserTotalScanner } from './scanner.js';
+export { ScannerOptions, UrlScanResult, ExtensionScanResult, PackageScanResult, ThreatInfo, ScanProgress, ProgressCallback, BrowserStore, Platform, } from './types.js';
+import type { ScannerOptions, UrlScanResult, ExtensionScanResult, PackageScanResult, BrowserStore } from './types.js';
+export declare function scanUrl(url: string, options?: ScannerOptions): Promise<UrlScanResult>;
+export declare function scanExtension(extensionId: string, store?: BrowserStore, options?: ScannerOptions): Promise<ExtensionScanResult>;
+export declare function scanVSCodeExtension(extensionId: string, options?: ScannerOptions): Promise<ExtensionScanResult>;
+export declare function scanJetBrainsPlugin(pluginId: string, options?: ScannerOptions): Promise<ExtensionScanResult>;
+export declare function scanNpmPackage(packageName: string, options?: ScannerOptions): Promise<PackageScanResult>;
+export declare function scanPyPIPackage(packageName: string, options?: ScannerOptions): Promise<PackageScanResult>;
+export declare function scanWordPressPlugin(pluginSlug: string, options?: ScannerOptions): Promise<ExtensionScanResult>;

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.BrowserTotalScanner=void 0,exports.scanUrl=scanUrl,exports.scanExtension=scanExtension,exports.scanVSCodeExtension=scanVSCodeExtension,exports.scanJetBrainsPlugin=scanJetBrainsPlugin,exports.scanNpmPackage=scanNpmPackage,exports.scanPyPIPackage=scanPyPIPackage,exports.scanWordPressPlugin=scanWordPressPlugin;var scanner_js_1=require("./scanner.js");async function scanUrl(n,a){const{BrowserTotalScanner:s}=await import("./scanner.js"),e=new s(a);try{return await e.scanUrl(n)}finally{await e.close()}}async function scanExtension(n,a="chrome",s){const{BrowserTotalScanner:e}=await import("./scanner.js"),r=new e(s);try{return await r.scanExtension(n,a)}finally{await r.close()}}async function scanVSCodeExtension(n,a){const{BrowserTotalScanner:s}=await import("./scanner.js"),e=new s(a);try{return await e.scanVSCodeExtension(n)}finally{await e.close()}}async function scanJetBrainsPlugin(n,a){const{BrowserTotalScanner:s}=await import("./scanner.js"),e=new s(a);try{return await e.scanJetBrainsPlugin(n)}finally{await e.close()}}async function scanNpmPackage(n,a){const{BrowserTotalScanner:s}=await import("./scanner.js"),e=new s(a);try{return await e.scanNpmPackage(n)}finally{await e.close()}}async function scanPyPIPackage(n,a){const{BrowserTotalScanner:s}=await import("./scanner.js"),e=new s(a);try{return await e.scanPyPIPackage(n)}finally{await e.close()}}async function scanWordPressPlugin(n,a){const{BrowserTotalScanner:s}=await import("./scanner.js"),e=new s(a);try{return await e.scanWordPressPlugin(n)}finally{await e.close()}}Object.defineProperty(exports,"BrowserTotalScanner",{enumerable:!0,get:function(){return scanner_js_1.BrowserTotalScanner}});

package/dist/scanner.d.ts

@@ -0,0 +1,30 @@
+import { ScannerOptions, UrlScanResult, ExtensionScanResult, PackageScanResult, ProgressCallback, BrowserStore, Platform } from './types.js';
+export declare class BrowserTotalScanner {
+    private options;
+    private browser;
+    constructor(options?: ScannerOptions);
+    private buildHashParams;
+    private ensureBrowser;
+    private reportProgress;
+    scanUrl(url: string, onProgress?: ProgressCallback): Promise<UrlScanResult>;
+    scanExtension(extensionId: string, store?: BrowserStore, onProgress?: ProgressCallback): Promise<ExtensionScanResult>;
+    scanVSCodeExtension(extensionId: string, onProgress?: ProgressCallback): Promise<ExtensionScanResult>;
+    scanOpenVSXExtension(extensionId: string, onProgress?: ProgressCallback): Promise<ExtensionScanResult>;
+    scanJetBrainsPlugin(pluginId: string, onProgress?: ProgressCallback): Promise<ExtensionScanResult>;
+    scanNpmPackage(packageName: string, onProgress?: ProgressCallback): Promise<PackageScanResult>;
+    scanPyPIPackage(packageName: string, onProgress?: ProgressCallback): Promise<PackageScanResult>;
+    scanWordPressPlugin(pluginSlug: string, onProgress?: ProgressCallback): Promise<ExtensionScanResult>;
+    scanHuggingFace(modelId: string, onProgress?: ProgressCallback): Promise<ExtensionScanResult>;
+    scanAppSourceAddin(addinId: string, onProgress?: ProgressCallback): Promise<ExtensionScanResult>;
+    scanPowerShellModule(moduleName: string, onProgress?: ProgressCallback): Promise<PackageScanResult>;
+    scanSalesforceApp(appId: string, onProgress?: ProgressCallback): Promise<ExtensionScanResult>;
+    scanByPlatform(identifier: string, platform: Platform | BrowserStore, onProgress?: ProgressCallback): Promise<ExtensionScanResult | PackageScanResult>;
+    private scanGenericExtension;
+    private scanGenericPackage;
+    private waitForScanResultEvent;
+    private mapUrlEventResult;
+    private mapExtensionEventResult;
+    private mapPackageEventResult;
+    private mapStatus;
+    close(): Promise<void>;
+}

package/dist/scanner.js

@@ -0,0 +1 @@
+"use strict";var __importDefault=this&&this.__importDefault||function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(exports,"__esModule",{value:!0}),exports.BrowserTotalScanner=void 0;const puppeteer_1=__importDefault(require("puppeteer")),BASE_URL=process.env.BROWSERTOTAL_URL||"https://browsertotal.com",DEFAULT_TIMEOUT=42e4,BROWSER_STORE_MAP={chrome:"google",firefox:"mozilla",edge:"microsoft",opera:"opera",safari:"safari",brave:"brave"},PLATFORM_PATH_MAP={vscode:"vscode",openvsx:"openvsx",jetbrains:"jetbrains",npmjs:"npmjs",pypi:"pypi",wordpress:"wordpress",huggingface:"huggingface",appsource:"appsource",powershellgallery:"powershellgallery",salesforce:"salesforce"};function toHex(e){return Array.from(e).map(e=>e.charCodeAt(0).toString(16).padStart(2,"0")).join("")}class BrowserTotalScanner{options;browser=null;constructor(e={}){this.options={headless:e.headless??!0,timeout:e.timeout??42e4,waitForResults:e.waitForResults??!0,disableAI:e.disableAI??!0,userDataDir:e.userDataDir}}buildHashParams(){const e=["automationEvent=true"];return this.options.disableAI&&e.push("disableAI=true"),"#"+e.join("&")}async ensureBrowser(){return this.browser||(this.browser=await puppeteer_1.default.launch({headless:this.options.headless,args:["--no-sandbox","--disable-setuid-sandbox"],userDataDir:this.options.userDataDir})),this.browser}reportProgress(e,s){e&&e(s)}async scanUrl(e,s){const t=await this.ensureBrowser(),n=await t.newPage();try{this.reportProgress(s,{phase:"initializing",message:"Starting URL scan..."});const t=toHex(e),a=`${BASE_URL}/analysis/urls/${t}${this.buildHashParams()}`;this.reportProgress(s,{phase:"navigating",message:`Navigating to ${a}`});const r=this.waitForScanResultEvent(n,"url");if(await n.goto(a,{waitUntil:"networkidle2",timeout:this.options.timeout}),this.reportProgress(s,{phase:"scanning",message:"Waiting for scan results..."}),this.options.waitForResults){const t=await r;if(t)return this.reportProgress(s,{phase:"complete",message:"Scan complete"}),this.mapUrlEventResult(t,e,a)}throw this.reportProgress(s,{phase:"complete",message:"Scan error"}),new Error("Scan error")}finally{await n.close()}}async scanExtension(e,s="chrome",t){const n=`${BASE_URL}/analysis/live/store/${BROWSER_STORE_MAP[s]||s}/${e}${this.buildHashParams()}`;return this.scanGenericExtension(e,n,`${s} extension`,t)}async scanVSCodeExtension(e,s){const t=`${BASE_URL}/analysis/live/store/vscode/${e}${this.buildHashParams()}`;return this.scanGenericExtension(e,t,"VS Code extension",s)}async scanOpenVSXExtension(e,s){const t=`${BASE_URL}/analysis/live/store/openvsx/${e}${this.buildHashParams()}`;return this.scanGenericExtension(e,t,"Open VSX extension",s)}async scanJetBrainsPlugin(e,s){const t=`${BASE_URL}/analysis/live/store/jetbrains/${e}${this.buildHashParams()}`;return this.scanGenericExtension(e,t,"JetBrains plugin",s)}async scanNpmPackage(e,s){const t=`${BASE_URL}/analysis/live/store/npmjs/${encodeURIComponent(e)}${this.buildHashParams()}`;return this.scanGenericPackage(e,"npmjs",t,"npm package",s)}async scanPyPIPackage(e,s){const t=`${BASE_URL}/analysis/live/store/pypi/${encodeURIComponent(e)}${this.buildHashParams()}`;return this.scanGenericPackage(e,"pypi",t,"PyPI package",s)}async scanWordPressPlugin(e,s){const t=`${BASE_URL}/analysis/live/store/wordpress/${encodeURIComponent(e)}${this.buildHashParams()}`;return this.scanGenericExtension(e,t,"WordPress plugin",s)}async scanHuggingFace(e,s){const t=`${BASE_URL}/analysis/live/store/huggingface/${encodeURIComponent(e)}${this.buildHashParams()}`;return this.scanGenericExtension(e,t,"Hugging Face model",s)}async scanAppSourceAddin(e,s){const t=`${BASE_URL}/analysis/live/store/appsource/${e}${this.buildHashParams()}`;return this.scanGenericExtension(e,t,"AppSource add-in",s)}async scanPowerShellModule(e,s){const t=`${BASE_URL}/analysis/live/store/powershellgallery/${encodeURIComponent(e)}${this.buildHashParams()}`;return this.scanGenericPackage(e,"powershellgallery",t,"PowerShell module",s)}async scanSalesforceApp(e,s){const t=`${BASE_URL}/analysis/live/store/salesforce/${e}${this.buildHashParams()}`;return this.scanGenericExtension(e,t,"Salesforce app",s)}async scanByPlatform(e,s,t){if(s in BROWSER_STORE_MAP)return this.scanExtension(e,s,t);switch(s){case"vscode":return this.scanVSCodeExtension(e,t);case"openvsx":return this.scanOpenVSXExtension(e,t);case"jetbrains":return this.scanJetBrainsPlugin(e,t);case"npmjs":return this.scanNpmPackage(e,t);case"pypi":return this.scanPyPIPackage(e,t);case"wordpress":return this.scanWordPressPlugin(e,t);case"huggingface":return this.scanHuggingFace(e,t);case"appsource":return this.scanAppSourceAddin(e,t);case"powershellgallery":return this.scanPowerShellModule(e,t);default:throw new Error(`Unsupported platform: ${s}`)}}async scanGenericExtension(e,s,t,n){const a=await this.ensureBrowser(),r=await a.newPage();try{this.reportProgress(n,{phase:"initializing",message:`Starting ${t} scan...`}),this.reportProgress(n,{phase:"navigating",message:`Navigating to ${s}`});const a=this.waitForScanResultEvent(r,"extension");if(await r.goto(s,{waitUntil:"networkidle2",timeout:this.options.timeout}),this.reportProgress(n,{phase:"scanning",message:`Waiting for ${t} analysis...`}),this.options.waitForResults){const t=await a;if(t)return this.reportProgress(n,{phase:"complete",message:"Scan complete"}),this.mapExtensionEventResult(t,e,s)}throw this.reportProgress(n,{phase:"complete",message:"Scan error"}),new Error("Scan error")}finally{await r.close()}}async scanGenericPackage(e,s,t,n,a){const r=await this.ensureBrowser(),i=await r.newPage();try{this.reportProgress(a,{phase:"initializing",message:`Starting ${n} scan...`}),this.reportProgress(a,{phase:"navigating",message:`Navigating to ${t}`});const r=this.waitForScanResultEvent(i,"extension");if(await i.goto(t,{waitUntil:"networkidle2",timeout:this.options.timeout}),this.reportProgress(a,{phase:"scanning",message:`Waiting for ${n} analysis...`}),this.options.waitForResults){const n=await r;if(n)return this.reportProgress(a,{phase:"complete",message:"Scan complete"}),this.mapPackageEventResult(n,e,s,t)}throw this.reportProgress(a,{phase:"complete",message:"Scan error"}),new Error("Scan error")}finally{await i.close()}}async waitForScanResultEvent(e,s){return new Promise(t=>{const n=setTimeout(()=>{console.log("[Scanner] Timeout waiting for scan_result event"),t(null)},this.options.timeout);e.exposeFunction("__browsertotalScanResult",e=>{clearTimeout(n),e?.type===s?(console.log("[Scanner] Received scan_result event:",e.type),t(e)):(console.log("[Scanner] Received wrong event type:",e?.type,"expected:",s),t(null))}).catch(()=>{}),e.evaluateOnNewDocument("\n        window.addEventListener('scan_result', function(event) {\n          console.log('[BrowserTotal] scan_result event fired');\n          if (typeof window.__browsertotalScanResult === 'function') {\n            window.__browsertotalScanResult(event.detail);\n          }\n        });\n      ").catch(()=>{e.evaluate("\n          window.addEventListener('scan_result', function(event) {\n            console.log('[BrowserTotal] scan_result event fired (late binding)');\n            if (typeof window.__browsertotalScanResult === 'function') {\n              window.__browsertotalScanResult(event.detail);\n            }\n          });\n        ").catch(()=>{})})})}mapUrlEventResult(e,s,t){const n=e.data||{};return{url:s,status:this.mapStatus(e.status,n.riskLevel),score:n.score,threats:n.threats?.map(e=>({type:"string"==typeof e?e:e.type||e.description,severity:e.severity||"medium",description:e.description}))||n.vulnerabilities?.map(e=>({type:e.type||e.vulnerability||e.description,severity:e.severity||"medium",description:e.description})),categories:n.categories,scanUrl:t.replace(/#.*$/,""),timestamp:new Date(e.timestamp||Date.now()),raw:e}}mapExtensionEventResult(e,s,t){const n=e.data||{};return{extensionId:s,name:n.name,status:this.mapStatus(e.status,n.riskLevel),score:n.score,permissions:n.permissions,threats:n.threats?.map(e=>({type:"string"==typeof e?e:e.type||e.description,severity:e.severity||"medium",description:e.description}))||n.vulnerabilities?.map(e=>({type:e.type||e.vulnerability||e.description,severity:e.severity||"medium",description:e.description})),scanUrl:t.replace(/#.*$/,""),timestamp:new Date(e.timestamp||Date.now()),raw:e}}mapPackageEventResult(e,s,t,n){const a=e.data||{};return{packageName:s,platform:t,name:a.name,version:a.version,status:this.mapStatus(e.status,a.riskLevel),score:a.score,dependencies:a.dependencies,threats:a.threats?.map(e=>({type:"string"==typeof e?e:e.type||e.description,severity:e.severity||"medium",description:e.description}))||a.vulnerabilities?.map(e=>({type:e.type||e.vulnerability||e.description,severity:e.severity||"medium",description:e.description})),scanUrl:n.replace(/#.*$/,""),timestamp:new Date(e.timestamp||Date.now()),raw:e}}mapStatus(e,s){if("error"===e)return"error";const t=(s||"").toLowerCase();return"critical"===t||"malicious"===t?"malicious":"high"===t||"suspicious"===t?"suspicious":"safe"===t||"low"===t||"clean"===t?"safe":"medium"===t?"suspicious":"unknown"}async close(){this.browser&&(await this.browser.close(),this.browser=null)}}exports.BrowserTotalScanner=BrowserTotalScanner;

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+export interface ScannerOptions {
+    headless?: boolean;
+    timeout?: number;
+    waitForResults?: boolean;
+    disableAI?: boolean;
+    userDataDir?: string;
+}
+export type BrowserStore = 'chrome' | 'firefox' | 'edge' | 'opera' | 'safari' | 'brave';
+export type Platform = 'vscode' | 'openvsx' | 'jetbrains' | 'npmjs' | 'pypi' | 'wordpress' | 'huggingface' | 'appsource' | 'powershellgallery' | 'salesforce';
+export interface ThreatInfo {
+    type: string;
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    description?: string;
+}
+export interface UrlScanResult {
+    url: string;
+    status: 'safe' | 'suspicious' | 'malicious' | 'unknown' | 'error';
+    score?: number;
+    threats?: ThreatInfo[];
+    categories?: string[];
+    scanUrl: string;
+    timestamp: Date;
+    raw?: Record<string, unknown>;
+}
+export interface ExtensionScanResult {
+    extensionId: string;
+    name?: string;
+    status: 'safe' | 'suspicious' | 'malicious' | 'unknown' | 'error';
+    score?: number;
+    permissions?: string[];
+    threats?: ThreatInfo[];
+    scanUrl: string;
+    timestamp: Date;
+    raw?: Record<string, unknown>;
+}
+export interface PackageScanResult {
+    packageName: string;
+    platform: string;
+    name?: string;
+    version?: string;
+    status: 'safe' | 'suspicious' | 'malicious' | 'unknown' | 'error';
+    score?: number;
+    dependencies?: Record<string, string>;
+    threats?: ThreatInfo[];
+    scanUrl: string;
+    timestamp: Date;
+    raw?: Record<string, unknown>;
+}
+export interface ScanProgress {
+    phase: 'initializing' | 'navigating' | 'scanning' | 'extracting' | 'complete';
+    message: string;
+}
+export type ProgressCallback = (progress: ScanProgress) => void;

package/dist/types.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@browsertotal/scanner",
+  "version": "2.0.0",
+  "description": "Scan URLs and extensions using BrowserTotal.com",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SeraphicSecurity/BrowserTotal"
+  },
+  "homepage": "https://browsertotal.com",
+  "bugs": {
+    "url": "https://github.com/SeraphicSecurity/BrowserTotal/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:prod": "tsc && npm run minify",
+    "minify": "terser dist/index.js -o dist/index.js -c -m && terser dist/scanner.js -o dist/scanner.js -c -m && terser dist/types.js -o dist/types.js -c -m",
+    "dev": "tsc --watch",
+    "test": "tsx test.ts",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build:prod"
+  },
+  "keywords": [
+    "browsertotal",
+    "security",
+    "scanner",
+    "extension",
+    "url",
+    "malware",
+    "browser",
+    "vscode",
+    "npm",
+    "pypi",
+    "chrome",
+    "firefox"
+  ],
+  "author": "BrowserTotal <support@browsertotal.com>",
+  "license": "MIT",
+  "dependencies": {
+    "puppeteer": "^24.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "terser": "^5.37.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}