Developer CLI tool for MLVScan - scan MelonLoader mods during development with remediation guidance
$ dotnet add package MLVScan.DevCLIDeveloper CLI tool for MLVScan - scan MelonLoader mods during development with remediation guidance.
Install as a global .NET tool:
dotnet tool install --global MLVScan.DevCLI
Or install locally in your project:
dotnet new tool-manifest # if you don't have one already
dotnet tool install MLVScan.DevCLI
The DevCLI can be built using either the published NuGet package (default) or a local copy of MLVScan.Core for development.
By default, the build uses the published MLVScan.Core package from NuGet:
dotnet build -c Release
To use a local copy of MLVScan.Core (e.g., when developing new features or testing changes):
dotnet build -c Release -p:LocalCoreBuild=true
This switches the reference from the NuGet package to a local project reference at ../MLVScan.Core/MLVScan.Core.csproj.
Note: The NuGet package build requires a published version of MLVScan.Core that includes the DTOs (v1.1.5+). Until then, use -p:LocalCoreBuild=true for local development.
If installed as a global .NET tool:
dotnet tool update --global MLVScan.DevCLI
Or if installed locally in your project:
dotnet tool update MLVScan.DevCLI
Scan a mod DLL and get developer-friendly output:
mlvscan-dev MyMod.dll
Get machine-readable JSON output in legacy format:
mlvscan-dev MyMod.dll --json
Or use the new standardized schema format (recommended):
mlvscan-dev MyMod.dll --format schema
The schema format follows MLVScan Schema v1.0.0, which is compatible with the web UI and other MLVScan tools.
Exit with error code 1 if findings of High or Critical severity are found:
mlvscan-dev MyMod.dll --fail-on High
Show all findings, even those without developer guidance:
mlvscan-dev MyMod.dll --verbose
Add MLVScan checks to your build process by adding this to your .csproj:
Note: The output of the DevCLI may be hidden when using the dotnet CLI. Use an IDE like Visual Studio or Rider to see the full output of the DevCLI.
<Target Name="MLVScanCheck" AfterTargets="Build">
<Exec Command="dotnet mlvscan-dev $(TargetPath)" />
</Target>
<Target Name="MLVScanCheck" AfterTargets="Build">
<Exec Command="dotnet mlvscan-dev $(TargetPath) --fail-on High" />
</Target>
<Target Name="MLVScanCheck" AfterTargets="Build">
<Exec Command="dotnet mlvscan-dev $(TargetPath) --format schema > mlvscan-report.json" />
</Target>
Note: Use --format schema for the standardized output format, or --json for the legacy format.
Here's a complete example of a mod project with MLVScan integration:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netstandard2.1</TargetFramework>
<AssemblyName>MyAwesomeMod</AssemblyName>
</PropertyGroup>
<!-- Your mod dependencies -->
<ItemGroup>
<PackageReference Include="MelonLoader" Version="0.6.1" />
</ItemGroup>
<!-- MLVScan Developer Tool -->
<ItemGroup>
<PackageReference Include="MLVScan.DevCLI" Version="1.0.0">
<PrivateAssets>all</PrivateAssets>
<IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>
</ItemGroup>
<!-- Run MLVScan after every build -->
<Target Name="MLVScanCheck" AfterTargets="Build" Condition="'$(Configuration)' == 'Debug'">
<Exec Command="dotnet mlvscan-dev "$(TargetPath)""
ContinueOnError="true"
IgnoreExitCode="true" />
</Target>
<!-- Fail release builds if critical issues found -->
<Target Name="MLVScanCheckRelease" AfterTargets="Build" Condition="'$(Configuration)' == 'Release'">
<Exec Command="dotnet mlvscan-dev "$(TargetPath)" --fail-on Critical" />
</Target>
</Project>
Usage:
mlvscan-dev <assembly-path> [options]
Arguments:
<assembly-path> Path to the .dll file to scan
Options:
-o, --format <format> Output format: console (default), json (legacy), schema (MLVScan Schema v1.0.0)
-j, --json Output results as JSON (legacy format, use --format schema for new format)
-f, --fail-on <value> Exit with error code 1 if findings >= severity (Low/Medium/High/Critical)
-v, --verbose Show all findings, not just those with developer guidance
-h, --help Show help information
--version Show version information
MLVScan Developer Report
========================
Assembly: MyMod.dll
Findings: 2
[High] Detected executable write near persistence-prone directory
Rule: PersistenceRule
Occurrences: 1
Developer Guidance:
For mod settings, use MelonPreferences. For save data, use the game's
save system or Application.persistentDataPath with .json extension.
📚 https://melonwiki.xyz/#/modders/preferences
Suggested APIs: MelonPreferences.CreateEntry<T>
Locations:
• MyMod.SaveManager.SaveSettings:42
─────────────────────────────────────────
{
"assemblyName": "MyMod.dll",
"totalFindings": 2,
"findings": [
{
"ruleId": "PersistenceRule",
"description": "Detected executable write near persistence-prone directory",
"severity": "High",
"location": "MyMod.SaveManager.SaveSettings:42",
"codeSnippet": "...",
"guidance": {
"remediation": "For mod settings, use MelonPreferences...",
"documentationUrl": "https://melonwiki.xyz/#/modders/preferences",
"alternativeApis": ["MelonPreferences.CreateEntry<T>"],
"isRemediable": true
}
}
]
}
Using --format schema outputs the standardized MLVScan Schema v1.0.0 format:
{
"schemaVersion": "1.0.0",
"metadata": {
"scannerVersion": "1.1.5",
"timestamp": "2026-01-29T12:34:56.789Z",
"scanMode": "developer",
"platform": "cli"
},
"input": {
"fileName": "MyMod.dll",
"sizeBytes": 45678,
"sha256Hash": "a1b2c3d4..."
},
"summary": {
"totalFindings": 2,
"countBySeverity": {
"High": 2
},
"triggeredRules": ["PersistenceRule"]
},
"findings": [
{
"id": "f1a2b3c4d5e6",
"ruleId": "PersistenceRule",
"description": "Detected executable write near persistence-prone directory",
"severity": "High",
"location": "MyMod.SaveManager.SaveSettings:42",
"codeSnippet": "..."
}
],
"developerGuidance": [
{
"ruleId": "PersistenceRule",
"remediation": "For mod settings, use MelonPreferences...",
"documentationUrl": "https://melonwiki.xyz/#/modders/preferences",
"alternativeApis": ["MelonPreferences.CreateEntry<T>"],
"isRemediable": true
}
]
}
This format is compatible with the MLVScan web UI and other ecosystem tools.
name: Build and Scan
on: [push, pull_request]
jobs:
build:
runs-on: windows-latest
steps:
- uses: actions/checkout@v3
- name: Setup .NET
uses: actions/setup-dotnet@v3
with:
dotnet-version: '8.0.x'
- name: Install MLVScan.DevCLI
run: dotnet tool install --global MLVScan.DevCLI
- name: Build
run: dotnet build -c Release
- name: Scan for issues
run: mlvscan-dev ./bin/Release/netstandard2.1/MyMod.dll --json > scan-results.json
- name: Upload scan results
uses: actions/upload-artifact@v3
with:
name: mlvscan-results
path: scan-results.json
stages:
- build
- scan
build:
stage: build
script:
- dotnet build -c Release
artifacts:
paths:
- bin/Release/
scan:
stage: scan
script:
- dotnet tool install --global MLVScan.DevCLI
- mlvscan-dev ./bin/Release/netstandard2.1/MyMod.dll --json > scan-results.json
- mlvscan-dev ./bin/Release/netstandard2.1/MyMod.dll --fail-on Critical
artifacts:
reports:
mlvscan: scan-results.json
Each finding may include:
If IsRemediable is false, the pattern has no safe alternative and should not be used in MelonLoader mods.
A: The scan typically takes 1-2 seconds for most mods. You can disable it in Debug builds or use ContinueOnError="true" to make it non-blocking.
A: The developer guidance will help you understand why something was flagged and how to fix it. If you believe it's a legitimate false positive, you can:
A: Yes! The tool works on compiled DLLs and doesn't require source code access.
MIT License - See LICENSE file for details