Skip to content

Whitelisting

Jump to bottom
Haze4269 edited this page Dec 28, 2025 · 1 revision

SHA256 Hash-Based Whitelisting

MLVScan uses SHA256 cryptographic hashes to whitelist trusted mods, providing superior security compared to filename-based whitelisting.

Why SHA256 Hashes?

Security Benefits

  1. Tamper Detection: Any modification to a mod file changes its hash
  2. Filename Independence: Renaming a file doesn't affect its hash
  3. Authenticity Verification: Confirms you have the exact same file
  4. Collision Resistance: Virtually impossible to create a malicious file with the same hash

Comparison: Filename vs Hash-Based

Feature Filename-Based SHA256 Hash-Based
Security Low - easily spoofed High - cryptographically secure
Tamper Detection None Immediate
Rename Protection No Yes
Version Control Poor Excellent

How to Whitelist a Mod

Step 1: Find the SHA256 Hash

When MLVScan flags a mod, it displays the hash in the console and report:

[MLVScan] SUSPICIOUS MOD: MyMod.dll
[MLVScan] SHA256 Hash: 3918e1454e05de4dd3ace100d8f4d53936c9b93694dbff5bcc0293d689cb0ab7

The hash is also included in the generated report file.

Step 2: Verify the Mod is Safe

⚠️ CRITICAL: Do not whitelist without verification!

Before whitelisting:

  1. Ask the Community: Join the Modding Discord and ask in the MLVScan thread
  2. Check the Report: Review the detailed scan report to understand what was flagged
  3. Use LLM Analysis: Copy the generated prompt file to ChatGPT for analysis (see reports folder)
  4. Verify Source: Ensure the mod came from a trusted source (NexusMods, Thunderstore)
  5. Check Author: Research the mod author's reputation

Step 3: Add to Whitelist

  1. Open MelonPreferences.cfg in your game directory
  2. Find the [MLVScan] section
  3. Add the hash to WhitelistedHashes

Example Configuration:

[MLVScan]
WhitelistedHashes = ["3918e1454e05de4dd3ace100d8f4d53936c9b93694dbff5bcc0293d689cb0ab7", "8e6dd1943c80e2d1472a9dc2c6722226d961027a7ec20aab9ad8f1184702d138", "d47eb6eabd3b6e3b742c7d9693651bc3a61a90dcbe838f9a4276953089ee4951"]

Format Notes:

  • Use the full 64-character hash
  • Separate multiple hashes with commas
  • Hashes can be in any case (uppercase/lowercase)
  • Keep hashes inside the array brackets []

Step 4: Restart Your Game

Changes to MelonPreferences.cfg require a game restart to take effect.

Default Whitelist

MLVScan includes a default whitelist for common mods with known false positives:

Currently Whitelisted by Default

Mod Hash Reason
CustomTV (Mono) 3918e145... Uses legitimate data loading
CustomTV (IL2CPP) 8e6dd194... Uses legitimate data loading
UnityExplorer (Mono) d47eb6ea... Debugging tool with reflection
UnityExplorer (IL2CPP) cfe43c0d... Debugging tool with reflection

Managing Your Whitelist

Removing a Hash

To remove a mod from your whitelist:

  1. Open MelonPreferences.cfg
  2. Find the hash in the WhitelistedHashes array
  3. Delete the hash (and its comma)
  4. Save and restart

Clearing All Whitelists

To start fresh:

[MLVScan]
WhitelistedHashes = []

On next launch, MLVScan will re-initialize the default whitelist.

Exporting Your Whitelist

You can share your whitelist with others by copying the WhitelistedHashes line. This helps build community trust for known-safe mods.

Verifying a Hash Manually

You can verify a mod's SHA256 hash using system tools:

Windows (PowerShell)

Get-FileHash -Algorithm SHA256 "path\to\mod.dll"

Linux/Mac

sha256sum /path/to/mod.dll

Online Tools

Use trusted hash calculators, but never upload mod files to untrusted sites.

Best Practices

✅ Do:

  • Verify hashes match before whitelisting
  • Share safe hashes with the community
  • Keep a backup of your whitelist
  • Review the scan report before whitelisting
  • Ask the community if unsure

❌ Don't:

  • Whitelist without verifying the source
  • Blindly trust hashes from unknown sources
  • Whitelist just to make warnings go away
  • Share hashes of unverified mods

Understanding False Positives

Common reasons for false positives:

  1. Legitimate Reflection: Some mods use reflection for valid purposes
  2. Debugging Tools: Development tools trigger multiple detection rules
  3. Data Loading: Loading custom content can appear suspicious
  4. Obfuscation: Some developers obfuscate code, triggering encoding rules

MLVScan uses multi-signal detection to reduce false positives, but some legitimate mods may still be flagged.

Security Implications

What Whitelisting Does

  • Bypasses ALL security checks for the whitelisted mod
  • Trusts the mod completely - no rescanning on updates
  • Permanent until removed - stays whitelisted across game sessions

What Whitelisting Doesn't Do

  • Doesn't verify safety - you must verify before whitelisting
  • Doesn't protect against updates - if the mod updates, the hash changes
  • Doesn't scan dependencies - other files loaded by the mod aren't checked

Staying Safe

Remember:

  1. Whitelisting is powerful but dangerous if misused
  2. Always verify with the community first
  3. Keep your whitelist minimal
  4. Review flagged mods carefully
  5. When in doubt, don't whitelist

Related Pages

Clone this wiki locally