MLVScan.DevCLI 1.3.1

MLVScan.DevCLI

Scan .NET mod assemblies from the command line or during a build. MLVScan reports suspicious behavior, known malware families, and guidance for reviewing findings.

Install

.NET tool

Install the CLI globally:

dotnet tool install --global MLVScan.DevCLI

To update it:

dotnet tool update --global MLVScan.DevCLI

For a project-local installation, create a tool manifest if your project does not already have one, then install the tool:

dotnet new tool-manifest
dotnet tool install MLVScan.DevCLI

Run a local installation with dotnet tool run mlvscan -- followed by the scan arguments. Use dotnet tool restore after cloning a project with a tool manifest.

Windows executable

Download mlvscan-win-x64.zip from GitHub Releases, extract it, and run mlvscan.exe from the extracted folder:

.\mlvscan.exe info --format json

Scan an assembly

mlvscan MyMod.dll

The console report shows the overall disposition, findings, and any matched threat families. Findings may include remediation advice, documentation links, call chains, or data-flow evidence.

Start with the disposition and Blocking Recommended value. Findings are supporting evidence; neither a sensitive API nor its raw severity means the implementation must be rewritten. Suspicious with blockingRecommended: false requests review without recommending a block. Verified restart flows can receive this advisory result while their process-execution findings remain visible.

Developer guidance offers optional APIs or workflows when they preserve the required behavior. Check target-runtime support. For example, a direct executable launch is not a drop-in replacement for a Steam URI or a helper that waits for shutdown. Native interop, encoding, file I/O, and dynamic loading can all be legitimate. If the behavior is necessary and misclassified, share the schema report, scanner version, and relevant source with the maintainer so detection can improve. Do not rewrite code solely to silence a rule. Review reports for private paths or URLs before sharing them.

Use --verbose to include advanced diagnostics:

mlvscan MyMod.dll --verbose

JSON output

Use the schema format for scripts and CI:

mlvscan MyMod.dll --format schema > scan-results.json

The report includes disposition, threatFamilies, findings, and scan metadata. The legacy JSON format remains available with --format json or --json.

Deeper analysis

If a scan reaches an analysis limit, use retry to run deeper analysis when needed:

mlvscan MyMod.dll --scan-mode retry --format schema

Use --scan-mode deep to apply the larger analysis budgets from the start. These include process value recovery work, depth, and alternative limits. When recovery reaches a limit, the console shows a retry hint and --verbose / schema output includes the ValueResolutionBudget diagnostic. Recovered candidates remain available to detection; unresolved values are not treated as safe. Deep mode is still finite and cannot recover every runtime value. Deeper scans can take longer and may still need manual review if an analysis limit is reached.

Use in a build

To fail a build when the disposition is Suspicious or KnownThreat:

mlvscan MyMod.dll --fail-on-disposition Suspicious

The command returns exit code 1 when the threshold is met. Without a failure threshold, a completed scan returns 0 even if it reports findings. Scan errors also return 1.

This classification threshold also fails for advisory Suspicious results, even when blockingRecommended is false. It is intentionally stricter than the loader's blocking recommendation. Automation that follows that recommendation should consume disposition.blockingRecommended from --format schema instead. Exit semantics have not changed.

For workflows that use finding severity, --fail-on High fails on High or Critical findings.

MSBuild

Install MLVScan as a local tool in your project, then add this target to your .csproj:

<Target Name="MLVScanCheck" AfterTargets="Build">
  <Exec Command="dotnet tool run mlvscan -- &quot;$(TargetPath)&quot; --fail-on-disposition Suspicious" />
</Target>

Run dotnet tool restore before building on a new machine or in CI.

GitHub Actions

This example builds a project and scans its assembly. Replace MyMod.csproj and the DLL path with your project's paths.

name: Build and scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-dotnet@v5
        with:
          dotnet-version: '8.0.x'
      - name: Install MLVScan
        run: dotnet tool install --global MLVScan.DevCLI
      - name: Build
        run: dotnet build MyMod.csproj -c Release
      - name: Scan
        run: mlvscan ./bin/Release/netstandard2.1/MyMod.dll --format schema --fail-on-disposition Suspicious > scan-results.json
      - name: Save report
        if: always()
        uses: actions/upload-artifact@v6
        with:
          name: scan-results
          path: scan-results.json

Command reference

mlvscan <assembly-path> [options]
mlvscan info [--format text|json]
mlvscan --schema-version

Review a result

Start with the disposition and any threat-family matches, then read the supporting findings. Severity describes individual findings; it is not the overall verdict. Review incomplete analysis and uncertain findings before deciding what to do with an assembly.

The CLI scans compiled assemblies, so source code is not required. If you suspect a false positive, report it with the scan output and enough context to explain the assembly's intended behavior.

Support

• Report an issue
• Join the Discord

License

GPL-3.0-or-later.