dotnet-native-cli 0.6.0

dotnet-native-mcp

Status: V1 in progress. Thirteen MCP tools are live: load_native_binary, import_native_manifest, list_native_symbols, list_native_imports, resolve_symbols, extract_strings, get_size_breakdown, explain_retention, compare_native_binaries, disassemble, find_native_callers, get_r2r_header, list_r2r_runtime_functions. Standalone CLI verbs are also live: version, r2r, disasm, resolve, callers, symbols, imports, size, size-diff, strings, retention.

dotnet-native-mcp is tooling for navigating native .NET binaries — NativeAOT, R2R-only, single-file native — when ECMA-335 metadata is stripped or absent. You can use it either as an MCP server (dotnet-native-mcp) or as a standalone local CLI (dotnet-native-cli). It is designed as the third leg of a tooling triad with dotnet-assembly-mcp (managed metadata) and dotnet-diagnostics-mcp (live process events).

Why this exists

dotnet-diagnostics-mcp already attaches to NativeAOT processes and emits hotspot frames whose symbols are mangled ILC names (S_P_____...) and whose addresses point at native code. dotnet-assembly-mcp cannot answer queries on those frames — its load_assembly rejects NativeAOT binaries with module_load_failed: not a managed PE. Today, the LLM receives a hex address and a mangled symbol and has nowhere to take them.

This server closes the gap. It accepts the NativeFrame handoff (binary + symbol + address), demangles ILC symbols back to managed-looking names, disassembles the native code with Iced, and will read the sidecar artifacts ILC emits (.mstat, .map, DGML) when they are available.

Where it does not belong

• Managed metadata, IL, decompile-to-C#. That's dotnet-assembly-mcp.
• Live process attach, EventPipe / ETW collection. That's dotnet-diagnostics-mcp.
• Generic reverse engineering (full Ghidra-class decompilation, full dynamic instrumentation, kernel-mode debuggers). Out of scope by design.

Tool surface (13 tools, V1)

For crash logs or sampled stacks where dotnet-diagnostics-mcp is not in the loop, use load_native_binary once and then call resolve_symbols with a list of raw hex addresses. When you already have NativeFrame handoffs with mangled addresses, pass those address strings directly to resolve_symbols.

ReadyToRun coverage

get_r2r_header + list_r2r_runtime_functions cover every R2R section whose layout is structurally tractable — decodable from raw PE bytes alone — plus the MethodDefEntryPoints array, which a safe span-based port of the runtime's NativeFormat reader now decodes:

Out of scope — sections encoded with the runtime's NativeFormat native hashtables / nibble-compressed signature streams, or that embed an ECMA metadata blob we do not parse into managed metadata. Decoding them requires the NativeFormat hashtable reader plus Internal.TypeSystem type resolution — partly redundant with dotnet-assembly-mcp (which owns managed metadata):

InstanceMethodEntryPoints, InliningInfo*, ProfileDataInfo, PgoInstrumentationData, AttributePresence, CrossModuleInlineInfo, the remaining *Map sections, DelayLoadMethodCallThunks, ExceptionInfo, and DebugInfo. The ManifestMetadata (112) blob is located (offset/size/version/streams) for handoff but its managed metadata is decoded by dotnet-assembly-mcp.

Sidecar tier (V1+)

ILC emits structured sidecars on request:

.mstat parsing answers "what blew up my AOT binary"; DGML reachability answers "why was this type or method kept?".

CLI

The standalone CLI consumes DotnetNativeMcp.Core directly, without any MCP package dependency. It mirrors the server's native-binary capabilities for local shell workflows and ships in two release forms:

• NuGet global tool: dotnet tool install -g dotnet-native-cli
• Self-contained single-file archives: dotnet-native-cli-<version>-<rid>.tar.gz / .zip

The root command exposes help plus a global --output json|table switch (default json) and a repeatable --allow <path> trusted-root option that feeds the shared PathAccessPolicy. See docs/cli.md for the full CLI contract, including exit codes and allow-list behavior.

# install as a global tool
dotnet tool install -g dotnet-native-cli
dotnet-native-cli version --output table

# or run directly from source while developing
dotnet run --project src/DotnetNativeMcp.Cli -- --help

# NativeAOT fixture used by the native-image examples below
sample_aot=tests/DotnetNativeMcp.Core.Tests/bin/Release/net10.0/fixtures/SampleAot/SampleAot
sample_aot_dir=tests/DotnetNativeMcp.Core.Tests/bin/Release/net10.0/fixtures/SampleAot

# R2R managed PE published alongside SampleAot
sample_r2r=tests/fixtures/SampleAot/bin/Release/net10.0/linux-x64/System.Private.CoreLib.dll
sample_r2r_dir=tests/fixtures/SampleAot/bin/Release/net10.0/linux-x64

dotnet-native-cli version --output table
dotnet-native-cli r2r header "$sample_r2r" --allow "$sample_r2r_dir" --output table
dotnet-native-cli r2r runtime-functions "$sample_r2r" --allow "$sample_r2r_dir" --limit 5
dotnet-native-cli disasm "$sample_aot" --allow "$sample_aot_dir" --address 0x401000 --max-instructions 16 --output table
dotnet-native-cli resolve "$sample_aot" --allow "$sample_aot_dir" --address 0x401000 --address 0x401010
dotnet-native-cli callers "$sample_aot" --allow "$sample_aot_dir" --address 0x401000 --image "$sample_aot"
dotnet-native-cli symbols "$sample_aot" --allow "$sample_aot_dir" --limit 10 --output table
dotnet-native-cli imports "$sample_aot" --allow "$sample_aot_dir" --kind libraries --output table
dotnet-native-cli size "$sample_aot" --allow "$sample_aot_dir" --group-by type --top-n 10
dotnet-native-cli size-diff "$sample_aot" "$sample_aot" --allow "$sample_aot_dir" --mstat-group-by category --top-n 5
dotnet-native-cli strings "$sample_aot" --allow "$sample_aot_dir" --min-length 8 --limit 20
dotnet-native-cli retention "$sample_aot" --allow "$sample_aot_dir" --target SampleAot.Program --output table

Install

MCP server

# stdio (local MCP client)
dotnet tool install -g dotnet-native-mcp
dotnet-native-mcp --stdio

# HTTP (sidecar / multi-client)
docker run --rm -p 8789:8080 \
  -v /path/to/binaries:/binaries:ro \
  ghcr.io/pedrosakuma/dotnet-native-mcp:latest

Standalone CLI release archives

Each GitHub release also includes self-contained single-file archives for the CLI and the server:

• dotnet-native-cli-<version>-<rid>.tar.gz / .zip
• dotnet-native-mcp-<version>-<rid>.tar.gz / .zip

Default port: 8789. Slot picked to continue the convention started by dotnet-diagnostics-mcp (8787) and dotnet-assembly-mcp (8788).

Running the triad with Docker Compose

To bring up all three servers together (diagnostics on 8787, assembly on 8788, native on 8789):

export BINARIES_DIR=/path/to/your/nativeaot/binaries
export ASSEMBLIES_DIR=/path/to/your/managed/assemblies
docker compose -f deploy/docker-compose.yml up -d

See docs/compose.md for the full guide: env vars, bearer-token setup, MCP client configuration, and how to attach to live processes.

Verifying releases

Every release artifact (NuGet package and self-contained binary archive) is published with a SLSA build provenance attestation generated by actions/attest-build-provenance and signed by Sigstore via GitHub's OIDC issuer. The attestation proves the artifact was built by this repository on a specific commit by GitHub-hosted runners — no separate cert to install, no key to rotate.

Verify with the GitHub CLI. The --signer-workflow and --source-ref flags bind verification to the exact release workflow file and tag, so an attestation produced by a different workflow in the same repository (e.g. a hypothetical CI workflow added in a PR) cannot pass these checks:

# Server NuGet package
gh attestation verify dotnet-native-mcp.0.5.4.nupkg \
  --repo pedrosakuma/dotnet-native-mcp \
  --signer-workflow pedrosakuma/dotnet-native-mcp/.github/workflows/release.yml \
  --source-ref refs/tags/v0.5.4

# CLI NuGet package
gh attestation verify dotnet-native-cli.0.5.4.nupkg \
  --repo pedrosakuma/dotnet-native-mcp \
  --signer-workflow pedrosakuma/dotnet-native-mcp/.github/workflows/release.yml \
  --source-ref refs/tags/v0.5.4

# CLI single-file archive
gh attestation verify dotnet-native-cli-0.5.4-linux-x64.tar.gz \
  --repo pedrosakuma/dotnet-native-mcp \
  --signer-workflow pedrosakuma/dotnet-native-mcp/.github/workflows/release.yml \
  --source-ref refs/tags/v0.5.4

# Server single-file archive
gh attestation verify dotnet-native-mcp-0.5.4-linux-x64.tar.gz \
  --repo pedrosakuma/dotnet-native-mcp \
  --signer-workflow pedrosakuma/dotnet-native-mcp/.github/workflows/release.yml \
  --source-ref refs/tags/v0.5.4

For maximum strictness, also pin to the exact release commit with --source-digest <commit-sha> (look it up on the release page).

A passing verification confirms the build came from pedrosakuma/dotnet-native-mcp, on the expected tag, produced by .github/workflows/release.yml.

Disk cache

find_native_callers maintains a persistent on-disk xref index so large NativeAOT binaries are scanned only once across server restarts.

Authentication

HTTP transport supports optional bearer-token auth. Leave it unset for local/dev back-compat; set either NATIVE_MCP_BEARER_TOKEN or NativeMcp:BearerToken to require Authorization: Bearer <token> on every /mcp request. /health remains open. STDIO transport stays unauthenticated.

export NATIVE_MCP_BEARER_TOKEN="replace-me"
dotnet-native-mcp

Loopback-or-token invariant

The HTTP transport enforces a startup-time safety check: if any configured URL binds to a non-loopback address (anything other than 127.0.0.1, ::1, or localhost) and no bearer token is configured, the server refuses to start. This prevents accidentally exposing the MCP tool surface — which can open arbitrary files on the host — to anyone on the network.

To bind to a non-loopback address you must either:

1. Set a bearer token (NATIVE_MCP_BEARER_TOKEN / NativeMcp:BearerToken / MCP_BEARER_TOKEN), or
2. Explicitly opt out with NativeMcp:AllowUnauthenticatedNonLoopback=true — only safe when a trusted reverse proxy in front of the server enforces authentication.

The check inspects Urls, ASPNETCORE_URLS, HTTP_PORTS / HTTPS_PORTS (and the ASPNETCORE_* aliases), and Kestrel:Endpoints:*:Url configuration sources.

Trusted-path allowlist (untrusted path hints)

Filesystem paths arrive off the wire from an LLM and are treated as untrusted display hints, per the handoff contract. Every path passed to load_native_binary, import_native_manifest, disassemble (imagePath / ilMapPath) and the sidecar overrides (mstatPath / dgmlPath) is canonicalised — .. flattened and symlinks / junctions resolved to their true target — before any file is opened.

Enforcement is opt-in. Configure at least one trusted root to restrict opens to that subtree (anything outside is refused with path_not_allowed):

# any of these turns enforcement on
export NATIVE_MCP_ALLOWED_ROOTS="/binaries:/app/assemblies"   # PATH-separator list
export BINARIES_DIR=/binaries                                  # single root (Compose tier)
# or NativeMcp:AllowedBinaryRoots in appsettings.json / config

When enforcing, the NuGet global packages cache, the .NET shared framework, and the system temp directory are always allowed in addition to your roots so handed-off binaries and staged sidecars keep resolving. Until a root is configured the server stays permissive (paths are still canonicalised) and logs a one-time startup warning.

Resource limits

To bound memory use and adversarial inputs, the server applies the following caps:

Error responses

Errors returned to MCP clients are sanitised: NativeError.Detail never carries Exception.ToString() stack traces, and absolute filesystem paths supplied by the caller are reduced to their file name. Full exception detail (including the original path and stack trace) is logged server-side via the SanitisedError.Sink hook (defaulting to System.Diagnostics.Trace) so operators can still investigate parse failures.

Building blocks

• Iced — MIT, .NET-native x86/x64 disassembler.
• System.Reflection.PortableExecutable — for PE headers and section reads.
• System.IO.Pipelines — for streaming reads of large native binaries.
• A small ELF reader (Linux NativeAOT binaries are ELF).
• (V1) Capstone P/Invoke for ARM64 disassembly.

License

MIT.