@mlvscan/wasm-core 1.1.7 → 1.1.9

package/README.md

@@ -1,19 +1,190 @@
 # @mlvscan/wasm-core
 
-WebAssembly core for MLVScan – scanning Unity mods in the browser.
+[![npm](https://img.shields.io/npm/v/@mlvscan/wasm-core.svg?color=red)](https://www.npmjs.com/package/@mlvscan/wasm-core)
 
-## Local development (before publishing)
+WebAssembly scanning engine for [MLVScan](https://github.com/ifBars/MLVScan). Runs the full [MLVScan.Core](https://github.com/ifBars/MLVScan.Core) malware detection engine entirely in the browser — no server, no uploads, no tracking.
 
-1. Build the .NET WASM app from the `MLVScan.WASM` project folder:
-   ```bash
-   dotnet publish -c Release
-   ```
-2. Copy the built `_framework` into this package’s `dist` so the package is self-contained:
-   ```bash
-   npm run copy:framework
-   ```
-3. Consuming projects (e.g. MLVScan.Web.v2) can depend on this package via `"file:../MLVScan.Core/MLVScan.WASM/npm"` and run `npm install`. The web app will serve and copy `_framework` from `node_modules/@mlvscan/wasm-core/dist/_framework`.
+## Installation
 
-## Publish
+```bash
+npm install @mlvscan/wasm-core
+```
 
-Run `tsc` and `copy:framework` (after building the .NET project), then `npm pack` or publish to a registry.
+## Serving the Framework Files
+
+The package ships with a `dist/_framework` directory containing the .NET WASM runtime. **Your build tool must serve these files at runtime.** With Vite, use `vite-plugin-static-copy`:
+
+```ts
+// vite.config.ts
+import { viteStaticCopy } from 'vite-plugin-static-copy'
+
+export default {
+  plugins: [
+    viteStaticCopy({
+      targets: [{
+        src: 'node_modules/@mlvscan/wasm-core/dist/_framework',
+        dest: '.'
+      }]
+    })
+  ]
+}
+```
+
+Then initialize with `baseUrl: '/'` (the default).
+
+## Quick Start
+
+```ts
+import { initScanner, scanAssembly } from '@mlvscan/wasm-core'
+
+// Initialize once at app startup
+await initScanner({ baseUrl: '/' })
+
+// Scan a DLL from a file input
+const file = event.target.files[0]
+const bytes = new Uint8Array(await file.arrayBuffer())
+const result = await scanAssembly(bytes, file.name)
+
+console.log(`Found ${result.summary.totalFindings} issue(s)`)
+for (const finding of result.findings) {
+  console.log(`[${finding.severity}] ${finding.description} @ ${finding.location}`)
+}
+```
+
+## API Reference
+
+### `initScanner(options?)`
+
+Loads the .NET WASM runtime. Call once at app startup before scanning. Safe to call multiple times — subsequent calls are no-ops if already initialized.
+
+```ts
+await initScanner({
+  baseUrl: '/',             // Where _framework is served. Defaults to '/'.
+  useMock: false,           // Force mock mode (useful for testing). Defaults to false.
+  throwOnInitFailure: false // Throw instead of falling back to mock on load failure.
+})
+```
+
+If `throwOnInitFailure` is not set and WASM fails to load, the scanner silently falls back to mock mode (returning zero findings). Use `getScannerStatus()` to detect this.
+
+---
+
+### `scanAssembly(fileBytes, fileName)`
+
+Scans a .NET assembly and returns a [`ScanResult`](#scanresult). Auto-initializes if `initScanner` was not called first.
+
+```ts
+const result = await scanAssembly(bytes, 'MyMod.dll')
+```
+
+---
+
+### `scanAssemblyWithConfig(fileBytes, fileName, config)`
+
+Scans with explicit options for deeper analysis (call chains, data flows, developer guidance).
+
+```ts
+const result = await scanAssemblyWithConfig(bytes, 'MyMod.dll', {
+  developerMode: true,
+  enableCrossMethodAnalysis: true,
+  deepAnalysis: {
+    enableDeepAnalysis: true,
+    enableNetworkToExecutionCorrelation: true,
+  }
+})
+```
+
+---
+
+### Status & Utility
+
+| Function | Returns | Description |
+|---|---|---|
+| `isScannerReady()` | `boolean` | True when init has completed (real or mock). Use to gate the scan button. |
+| `isMockScanner()` | `boolean` | True when running in mock mode. |
+| `getScannerStatus()` | `ScannerStatus` | Full status snapshot — ready, mock, explicit mock, and init error. |
+| `getScannerVersion()` | `Promise<string>` | Scanner engine version (e.g. `"1.1.7"`). Returns `"1.0.0-mock"` in mock mode. |
+| `getSchemaVersion()` | `Promise<string>` | Result schema version (e.g. `"1.0.0"`). |
+| `getInitError()` | `Error \| null` | The error that caused WASM fallback, or null if healthy. |
+
+## Scan Modes
+
+The `scanMode` in [`ScanConfigInput`](#scanassemblywithconfig) controls the depth of analysis and what is included in the result:
+
+| Mode | Description |
+|---|---|
+| `summary` (default) | Fast scan. Returns findings with severity and location. |
+| `detailed` | Includes `callChains` — the execution path from entry point to suspicious code. |
+| `developer` | Includes `dataFlows` and `developerGuidance` with remediation suggestions. |
+
+## Handling WASM Load Failures
+
+If the WASM runtime fails to load (e.g. COOP/COEP headers not set, browser incompatibility), the scanner falls back to mock mode automatically. Check the status after init to show an appropriate message:
+
+```ts
+await initScanner({ baseUrl: '/' })
+
+const status = getScannerStatus()
+if (status.initError) {
+  console.warn('Scanner unavailable, results will be empty:', status.initError.message)
+}
+```
+
+To throw instead of falling back silently:
+
+```ts
+await initScanner({ baseUrl: '/', throwOnInitFailure: true })
+```
+
+## Type Reference
+
+### `ScanResult`
+
+The root object returned by all scan functions.
+
+```ts
+interface ScanResult {
+  schemaVersion: string
+  metadata: ScanMetadata       // Scanner version, timestamp, scan mode, platform
+  input: ScanInput             // File name, size, optional SHA-256
+  summary: ScanSummary         // Total findings and counts by severity
+  findings: Finding[]          // Individual security findings
+  callChains?: CallChain[]     // Detailed mode: execution paths
+  dataFlows?: DataFlowChain[]  // Developer mode: source-to-sink data flows
+  developerGuidance?: DeveloperGuidance[] // Developer mode: remediation suggestions
+}
+```
+
+### `Finding`
+
+```ts
+interface Finding {
+  ruleId?: string
+  description: string
+  severity: 'Low' | 'Medium' | 'High' | 'Critical'
+  location: string       // Type/method name or file:line
+  codeSnippet?: string
+}
+```
+
+### `ScannerStatus`
+
+```ts
+interface ScannerStatus {
+  ready: boolean
+  isMock: boolean
+  mockRequestedExplicitly: boolean
+  initError: Error | null
+}
+```
+
+For the full type definitions, see [`types.ts`](https://github.com/ifBars/MLVScan.Core/blob/main/MLVScan.WASM/npm/src/types.ts).
+
+## Related
+
+*   [MLVScan.Core](https://github.com/ifBars/MLVScan.Core) — The detection engine (NuGet package, CLI, WASM source)
+*   [MLVScan.Web](https://github.com/ifBars/MLVScan.Web) — React web app built on this package
+*   [MLVScan](https://github.com/ifBars/MLVScan) — MelonLoader/BepInEx plugin
+
+---
+*Licensed under GPL-3.0*

package/dist/_framework/blazor.boot.json

@@ -1,7 +1,7 @@
 {
   "mainAssemblyName": "MLVScan.WASM.dll",
   "resources": {
-    "hash": "sha256-jTAixhhqHmH6Js7hnz8TbIU8LPF6Av7QIkhdNfm8da8=",
+    "hash": "sha256-kQ8yXgo/2m62IeBvqmE2y/Rv5qnIhJ76+Mb2sd2UHtk=",
     "jsModuleNative": {
       "dotnet.native.js": "sha256-clxzGaAFwcQ6QWhwQ7dzpD9ktR/87yTache3B45gqoQ="
     },
@@ -9,7 +9,7 @@
       "dotnet.runtime.js": "sha256-TGUqQm2/C+r+yZ5BCjd72qyLw9wv0KPFKzKXk/giiyY="
     },
     "wasmNative": {
-      "dotnet.native.wasm": "sha256-fin1Zl1yIo6hXwrmCD6i3R0OLwYlXlPPBuP9GwGRhfQ="
+      "dotnet.native.wasm": "sha256-7LljILBN1AFf6EU6LHPYFSM546zEqe1EGl7AAP3pb1Q="
     },
     "wasmSymbols": {
       "dotnet.native.js.symbols": "sha256-mcn0xQOEP6bIrzi/nvTIsKV7ryyqIdVUtbOIC/EOcqI="
@@ -20,20 +20,20 @@
       "icudt_no_CJK.dat": "sha256-L7sV7NEYP37/Qr2FPCePo5cJqRgTXRwGHuwF5Q+0Nfs="
     },
     "assembly": {
-      "MLVScan.Core.wasm": "sha256-I6pReZ5whl4GsSwBOycEb5zMmcsiocjRQSFEUKSY+64=",
-      "MLVScan.WASM.wasm": "sha256-E3uY+sg1PROG3DaOEhgnwb3Qrwiol/wRsrpVKKnqMKs=",
-      "Mono.Cecil.wasm": "sha256-9nKX3pNgOOICbt5NYrpLzfr68C2NenjxIZRWMSm3+9s=",
-      "System.Collections.Concurrent.wasm": "sha256-63SVm6IOpVPPAswPtjPxNn+UVLmQVcVw/TsZkAERzZ0=",
-      "System.Collections.wasm": "sha256-suGbEYUofGw2k7rtWARZyGc4mKVUtVEV3TwUd3fZmmo=",
+      "MLVScan.Core.wasm": "sha256-n14Dpe9qxFK9DoeqYdYn3XdOfGlQ8tUR1214rLiCwgc=",
+      "MLVScan.WASM.wasm": "sha256-RPRKDzyd235JwUgdRljPx8P2308Dy8hid3msbRu1Azc=",
+      "Mono.Cecil.wasm": "sha256-+26bn77S22+aVO+7xKl2WP74xQjSYR0S8GP6mRWf9C8=",
+      "System.Collections.Concurrent.wasm": "sha256-pFhCmskR6dmKt18zv1jrGGR184LyXdz408BBMX4BBhg=",
+      "System.Collections.wasm": "sha256-TRwwb/PWxTAKfplBNqMkn14z5rNLvuy459MunrnseDo=",
       "System.IO.Compression.wasm": "sha256-zPnVmOjOHN/V1tNLjZurM9T/xj1LXcVlKv+emtlb3gA=",
-      "System.Linq.wasm": "sha256-9tHJX23oXTc36XpgjNVp5rHnx9pG+W2584qC0yZIJII=",
-      "System.Memory.wasm": "sha256-kNlcsfG/cVsoTKFZc2vbR+COjs4GUSwhQHlLCNkCqEg=",
-      "System.Private.CoreLib.wasm": "sha256-k4QAIYYtp+zKYAMwo5l55YeGDF4iEi70Q5M7PSB/uBc=",
+      "System.Linq.wasm": "sha256-1wPZ41jMHt8ciwhU3I4TFTqP5hLFGPgwv9ELOm1r4sc=",
+      "System.Memory.wasm": "sha256-csnkwt/JrsppyyW/C58TooGjK2jHvla7al1hV1pbTm4=",
+      "System.Private.CoreLib.wasm": "sha256-Zvoxo5D29MB/hBBw4MTVcRXUU77qT05R4VgGobV5ycw=",
       "System.Runtime.InteropServices.JavaScript.wasm": "sha256-knh9wD83/GTpX28IRzoUJy42zEAtXZdBUcckFTm6bzw=",
       "System.Security.Cryptography.wasm": "sha256-1yetTxYoa9Mv2JdPd07A9bKVQKSs1o/cCS66raJYlMQ=",
-      "System.Text.Encodings.Web.wasm": "sha256-0Yj+mrS4Z2sHQGjRimW4tqk281Rv2anm+6r0rfM+7x8=",
-      "System.Text.Json.wasm": "sha256-2eNYX3n7GnAmU/ijgyEEbIqVdeKYh9kjIVv4cA1Q3lc=",
-      "System.Text.RegularExpressions.wasm": "sha256-OhRvJc9wBjXcObymgRgCyOalu/X7h8WyZAGrSpsMgYg="
+      "System.Text.Encodings.Web.wasm": "sha256-nPDcUnKJT3K4bYAjeaZI+9dn3OmAWOVz87kkXfy7znA=",
+      "System.Text.Json.wasm": "sha256-AeaONG3Ex8c3fn8CGqF/3LBoWcM5ZFPr+ulSTe/PVRQ=",
+      "System.Text.RegularExpressions.wasm": "sha256-6xU3ws3QrP3va4o+lU66Gz4HOOB8fkyaR4hm51P5cJQ="
     },
     "vfs": {
       "runtimeconfig.bin": {

package/dist/index.d.ts

@@ -18,7 +18,7 @@
  * const result = await scanAssembly(dllBytes, 'MyMod.dll')
  * ```
  */
-import type { ScanResult } from './types';
+import type { ScanConfigInput, ScanResult } from './types';
 /**
  * Options for initializing the WASM scanner.
  *
@@ -81,6 +81,11 @@ export declare function initScanner(options?: ScannerInitOptions): Promise<void>
  * @throws When the scanner is not in mock mode but the WASM scan call fails.
  */
 export declare function scanAssembly(fileBytes: Uint8Array, fileName: string): Promise<ScanResult>;
+/**
+ * Scans an assembly with an explicit scan configuration (including deep analysis options).
+ * Use this for opt-in deep scans while keeping quick scan defaults for normal usage.
+ */
+export declare function scanAssemblyWithConfig(fileBytes: Uint8Array, fileName: string, config: ScanConfigInput): Promise<ScanResult>;
 /**
  * Returns whether the scanner is ready to use (initialization finished, either
  * with real WASM or mock). Use this to gate UI (e.g. enable "Scan" only when

package/dist/index.js

@@ -161,6 +161,35 @@ export async function scanAssembly(fileBytes, fileName) {
         throw new Error(`Scan failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
     }
 }
+/**
+ * Scans an assembly with an explicit scan configuration (including deep analysis options).
+ * Use this for opt-in deep scans while keeping quick scan defaults for normal usage.
+ */
+export async function scanAssemblyWithConfig(fileBytes, fileName, config) {
+    if (!scannerLoaded) {
+        await initScanner();
+    }
+    if (useMockScanner || !scannerExports) {
+        return {
+            ...mockScanResult,
+            input: {
+                fileName,
+                sizeBytes: fileBytes.length,
+            },
+        };
+    }
+    if (!scannerExports.MLVScan?.WASM?.ScannerExports) {
+        throw new Error('Scanner not properly initialized: MLVScan.WASM.ScannerExports not found');
+    }
+    try {
+        const configJson = JSON.stringify(config ?? {});
+        const resultJson = scannerExports.MLVScan.WASM.ScannerExports.ScanAssemblyWithConfig(fileBytes, fileName, configJson);
+        return JSON.parse(resultJson);
+    }
+    catch (error) {
+        throw new Error(`Scan with config failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
 /**
  * Returns whether the scanner is ready to use (initialization finished, either
  * with real WASM or mock). Use this to gate UI (e.g. enable "Scan" only when

package/dist/types.d.ts

@@ -119,3 +119,35 @@ export interface DeveloperGuidance {
     alternativeApis?: string[];
     isRemediable: boolean;
 }
+export interface DeepBehaviorAnalysisConfig {
+    enableDeepAnalysis?: boolean;
+    emitDiagnosticFindings?: boolean;
+    requireCorrelatedBaseFinding?: boolean;
+    deepScanOnlyFlaggedMethods?: boolean;
+    enableStringDecodeFlow?: boolean;
+    enableExecutionChainAnalysis?: boolean;
+    enableResourcePayloadAnalysis?: boolean;
+    enableDynamicLoadCorrelation?: boolean;
+    enableNativeInteropCorrelation?: boolean;
+    enableScriptHostLaunchAnalysis?: boolean;
+    enableEnvironmentPivotCorrelation?: boolean;
+    enableNetworkToExecutionCorrelation?: boolean;
+    maxInstructionsPerMethod?: number;
+    maxAnalysisTimeMsPerMethod?: number;
+    maxDeepMethodsPerAssembly?: number;
+    maxTrackedDataFlowEdgesPerMethod?: number;
+}
+export interface ScanConfigInput {
+    developerMode?: boolean;
+    enableCrossMethodAnalysis?: boolean;
+    maxCallChainDepth?: number;
+    enableReturnValueTracking?: boolean;
+    detectAssemblyMetadata?: boolean;
+    enableMultiSignalDetection?: boolean;
+    analyzeExceptionHandlers?: boolean;
+    analyzeLocalVariables?: boolean;
+    analyzePropertyAccessors?: boolean;
+    enableRecursiveResourceScanning?: boolean;
+    maxRecursiveResourceSizeMB?: number;
+    deepAnalysis?: DeepBehaviorAnalysisConfig;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mlvscan/wasm-core",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "description": "WebAssembly core for MLVScan - scanning Unity mods in the browser",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",