Skip to content

Architecture

Jump to bottom
ifBars edited this page Feb 5, 2026 · 4 revisions

Architecture Overview

MLVScan is built on a modular, cross-platform architecture that separates concerns and enables code reuse across multiple platforms.

System Architecture

graph TD
    Core[MLVScan.Core<br/><i>NuGet Package</i>]:::core

    subgraph Platforms
        ML[MLVScan<br/><i>MelonLoader Plugin</i>]:::impl
        BepIn5[MLVScan<br/><i>BepInEx 5.x Patcher</i>]:::impl
        BepIn6M[MLVScan<br/><i>BepInEx 6.x Mono</i>]:::impl
        BepIn6I[MLVScan<br/><i>BepInEx 6.x IL2CPP</i>]:::impl
        CLI[MLVScan.DevCLI<br/><i>.NET Tool</i>]:::impl
        Web[MLVScan.Web<br/><i>Blazor WASM</i>]:::impl
    end

    Core -->|"Provides Engine"| ML
    Core -->|"Provides Engine"| BepIn5
    Core -->|"Provides Engine"| BepIn6M
    Core -->|"Provides Engine"| BepIn6I
    Core -->|"Provides Engine"| CLI
    Core -->|"Provides Engine"| Web

    classDef core fill:#6a00ff,stroke:#333,stroke-width:2px,color:white;
    classDef impl fill:#00c853,stroke:#333,stroke-width:2px,color:white;
    classDef planned fill:#eeeeee,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5,color:#666;
Loading

Component Breakdown

1. MLVScan (MelonLoader Plugin)

Repository: github.com/ifBars/MLVScan

Purpose: Runtime mod scanner for MelonLoader-based games

Key Components:

  • Core.cs - Main plugin entry point
  • ServiceFactory.cs - Creates platform-specific services
  • ConfigManager.cs - Handles MelonPreferences configuration
  • ModScanner.cs - Orchestrates scanning of installed mods
  • ModDisabler.cs - Safely disables suspicious mods
  • Adapters/ - MelonLoader-specific implementations

Responsibilities:

  • Initialize scanning on game startup
  • Manage SHA256 whitelist via MelonPreferences
  • Disable suspicious mods before they load
  • Generate detailed reports
  • Provide MelonLoader console output

2. MLVScan.DevCLI (Developer CLI Tool)

Repository: github.com/ifBars/MLVScan.DevCLI

NuGet Package: nuget.org/packages/MLVScan.DevCLI

Purpose: Command-line tool for mod developers to scan builds during development

Key Components:

  • Program.cs - CLI entry point using System.CommandLine
  • Models.cs - JSON serialization DTOs for scan output
  • DevScanResult - Result model with findings and guidance

Key Features:

  • Developer-friendly console output with remediation guidance
  • JSON output format for CI/CD integration
  • Build failure support based on severity threshold (--fail-on)
  • Verbose mode for comprehensive analysis
  • MSBuild target integration for automatic post-build scanning

Responsibilities:

  • Scan compiled mod DLLs during development
  • Provide actionable developer guidance for findings
  • Support CI/CD pipelines with machine-readable output
  • Enable build-time security checks
  • Document safe alternatives to suspicious patterns

Developer Guidance System:

Each finding includes structured guidance:

  • Remediation: Step-by-step fix instructions
  • DocumentationUrl: Links to relevant documentation (e.g., MelonWiki)
  • AlternativeApis: Safe API alternatives to use instead
  • IsRemediable: Whether a safe alternative exists

3. MLVScan.Core (Shared Engine)

Repository: github.com/ifBars/MLVScan.Core

NuGet Package: nuget.org/packages/MLVScan.Core

Purpose: Platform-agnostic IL analysis and malware detection

Key Components:

Abstractions Layer

  • IScanLogger - Logging abstraction
  • IAssemblyResolverProvider - Platform-specific assembly resolution
  • IScanRule - Detection rule interface

Models

  • ScanConfig - Configuration options
  • ScanFinding - Detection results
  • Severity - Threat level enumeration
  • MethodSignals - Multi-signal tracking
  • Rules/ - 17+ detection rule implementations

Services

  • AssemblyScanner - Main scanning orchestrator
  • TypeScanner - Type-level analysis
  • MethodScanner - Method-level analysis
  • InstructionAnalyzer - IL instruction-level analysis
  • ReflectionDetector - Reflection-based attack detection
  • SignalTracker - Multi-signal pattern tracking
  • StringPatternDetector - String encoding detection

RuleFactory

  • CreateDefaultRules() - Centralized rule creation

Responsibilities:

  • Deep IL code analysis using Mono.Cecil
  • Pattern detection across 17+ rule types
  • Multi-signal detection to reduce false positives
  • Platform-agnostic scanning
  • Extensible rule system

4. MLVScan.Web (Web Scanner)

Repository: github.com/ifBars/MLVScan.Web

Purpose: Browser-based mod scanner for pre-installation verification

Technology: Blazor WebAssembly (C# in browser)

Key Features:

  • Upload mod files for scanning
  • Client-side analysis (no file upload to server)
  • Same detection engine as MelonLoader version
  • Real-time scan results
  • No installation required

Use Cases:

  • Pre-screen mods before installation
  • Verify mod safety without MelonLoader
  • Share scan results via URL
  • Community verification tool

5. MLVScan (BepInEx 5.x Patcher)

Repository: github.com/ifBars/MLVScan

Purpose: Runtime mod scanner for BepInEx 5.x-based games

Key Components:

  • BepInEx/5/BepInEx5Patcher.cs - Preloader patcher entry point
  • BepInEx/BepInExPluginScanner.cs - Orchestrates scanning of installed plugins
  • BepInEx/BepInExPluginDisabler.cs - Safely disables suspicious plugins
  • BepInEx/BepInExConfigManager.cs - Handles BepInEx configuration
  • BepInEx/Adapters/ - BepInEx-specific implementations

Responsibilities:

  • Initialize scanning during BepInEx preloader phase (before Chainloader)
  • Manage SHA256 whitelist via BepInEx config
  • Disable suspicious plugins before they load
  • Generate detailed reports
  • Provide BepInEx console/log output

6. MLVScan (BepInEx 6.x Mono Plugin)

Repository: github.com/ifBars/MLVScan

Purpose: Runtime mod scanner for BepInEx 6.x Mono-based games

Key Components:

  • BepInEx/6/Mono/BepInEx6MonoPatcher.cs - Plugin entry point
  • BepInEx/BepInExPluginScanner.cs - Orchestrates scanning of installed plugins
  • BepInEx/BepInExPluginDisabler.cs - Safely disables suspicious plugins
  • BepInEx/BepInExConfigManager.cs - Handles BepInEx configuration
  • BepInEx/Adapters/ - BepInEx-specific implementations

Responsibilities:

  • Initialize scanning during plugin initialization
  • Manage SHA256 whitelist via BepInEx config
  • Disable suspicious plugins
  • Generate detailed reports
  • Provide BepInEx console/log output

7. MLVScan (BepInEx 6.x IL2CPP Plugin)

Repository: github.com/ifBars/MLVScan

Purpose: Runtime mod scanner for BepInEx 6.x IL2CPP-based games

Key Components:

  • BepInEx/6/IL2CPP/BepInEx6IL2CppPatcher.cs - Plugin entry point
  • BepInEx/BepInExPluginScanner.cs - Orchestrates scanning of installed plugins
  • BepInEx/BepInExPluginDisabler.cs - Safely disables suspicious plugins
  • BepInEx/BepInExConfigManager.cs - Handles BepInEx configuration
  • BepInEx/Adapters/ - BepInEx-specific implementations

Responsibilities:

  • Initialize scanning during plugin initialization
  • Manage SHA256 whitelist via BepInEx config
  • Disable suspicious plugins
  • Generate detailed reports
  • Provide BepInEx console/log output

Data Flow

Scanning Process

1. Game Launch / File Upload / CLI Execution
         │
         ▼
2. MLVScan Plugin / MLVScan.Web / MLVScan.DevCLI Initializes
         │
         ▼
3. Enumerate Mod Files / Load Target Assembly
         │
         ▼
4. For Each Mod:
   ├─► Calculate SHA256 Hash
   ├─► Check Whitelist
   │   ├─► Whitelisted? → Skip
   │   └─► Not Whitelisted? → Continue
   │
   ├─► MLVScan.Core.AssemblyScanner.Scan()
   │   ├─► Load Assembly with Mono.Cecil
   │   ├─► TypeScanner: Analyze Types
   │   ├─► MethodScanner: Analyze Methods
   │   │   └─► InstructionAnalyzer: Analyze IL Instructions
   │   │       └─► Apply 17+ Detection Rules
   │   │           └─► SignalTracker: Multi-signal Detection
   │   │
   │   └─► Return ScanFinding[]
   │
   ├─► Aggregate Findings by Severity
   │
   └─► High Severity? → Disable Mod
                      → Generate Report

Detection Rule Architecture

Rule Interface

public interface IScanRule
{
    string Description { get; }
    Severity Severity { get; }
    bool IsSuspicious(MethodReference method);
}

Rule Categories

  1. Critical Severity

    • Shell32Rule (Windows shell execution)
    • LoadFromStreamRule (Dynamic assembly loading)
    • DataExfiltrationRule (Network data sending)
    • PersistenceRule (Auto-run mechanisms)
    • COMReflectionAttackRule (COM-based attacks)

  2. High Severity

    • ProcessStartRule (Process execution)
    • ReflectionRule (Reflection-based invocation)
    • RegistryRule (Registry manipulation)
    • EncodedStringLiteralRule (Numeric-encoded strings)
    • DllImportRule (Native code imports)

  3. Medium Severity

    • Base64Rule (Base64 encoding/decoding)
    • HexStringRule (Hex string patterns)
    • ByteArrayManipulationRule (Byte array operations)

  4. Low Severity

    • EnvironmentPathRule (Environment variable access)

Multi-Signal Detection

To reduce false positives, MLVScan tracks multiple signals within the same context:

  • Method-level signals: Multiple suspicious patterns in one method
  • Type-level signals: Patterns spread across a class
  • Contextual analysis: Benign operations only flagged when combined with others

Example: Base64 decoding alone doesn't trigger a finding, but Base64 + Process.Start does.

Platform Abstraction

Assembly Resolution

Different platforms resolve game assemblies differently:

// MelonLoader
public class MelonLoaderResolverProvider : IAssemblyResolverProvider
{
    public IAssemblyResolver CreateResolver()
    {
        // Add MelonLoader's Managed directory
    }
}

// Web
public class WebResolverProvider : IAssemblyResolverProvider
{
    public IAssemblyResolver CreateResolver()
    {
        // Use default resolver (no game assemblies needed)
    }
}

Logging

// MelonLoader
public class MelonLoaderLogger : IScanLogger
{
    public void Log(string message) => MelonLogger.Msg(message);
}

// Web
public class BlazorLogger : IScanLogger
{
    public void Log(string message) => Console.WriteLine(message);
}

Configuration System

MLVScan (MelonLoader)

Uses MelonPreferences:

[MLVScan]
WhitelistedHashes = [...]
DisableThreshold = Medium
DumpFullIlReports = false

MLVScan.Core

Platform-agnostic ScanConfig:

var config = new ScanConfig
{
    EnableMultiSignalDetection = true,
    DetectAssemblyMetadata = true
};

Extensibility

Adding New Rules

  1. Create class implementing IScanRule in MLVScan.Core
  2. Add to RuleFactory.CreateDefaultRules()
  3. Rules automatically used by all platforms

Adding New Platforms

  1. Reference MLVScan.Core NuGet package
  2. Implement IAssemblyResolverProvider for your platform
  3. Implement IScanLogger for your platform
  4. Create platform-specific entry point
  5. Call AssemblyScanner.Scan()

Example: MLVScan.DevCLI demonstrates this pattern with a console-based logger and default resolver.

Dependencies

MLVScan (MelonLoader)

  • MelonLoader (via assembly reference)
  • MLVScan.Core (NuGet)

MLVScan.DevCLI

  • System.CommandLine (CLI parsing)
  • MLVScan.Core (NuGet)
  • MLVScan (for developer mode features)

MLVScan.Core

  • Mono.Cecil (IL analysis)
  • System.Security.Cryptography (SHA256)

MLVScan.Web

  • Blazor WebAssembly
  • MLVScan.Core (NuGet)

Performance Considerations

  • Lazy Loading: Only scans when needed
  • Hash Caching: Avoids re-scanning whitelisted mods
  • Early Exit: Stops scanning if whitelist match found
  • Parallel Processing: Can scan multiple mods concurrently (platform-dependent)

Security Model

Trust Boundaries

  1. MLVScan.Core: No network, no file I/O (pure analysis)
  2. MLVScan Plugin: Trusted platform code (file I/O for scanning)
  3. Whitelist: User-controlled trust decisions

SHA256 Verification

  • Cryptographically secure (collision-resistant)
  • Tamper-evident
  • Content-based (filename-independent)

Related Pages

Clone this wiki locally