# Obfuscating a .NET global tool without breaking commands


A .NET global tool — a console app you `dotnet pack` with `PackAsTool` and install with `dotnet tool install -g` — is one of the easier things to protect, for a reason that is worth understanding before you touch any config. It is a NuGet package, like a library, but unlike a library **nobody compiles against it**. There is no public API contract to preserve. The only thing on the other side of the package is a shell invoking an executable. That single fact changes how aggressively you can rename, and this post walks through protecting the tool end to end: what you can rename (almost everything), the handful of names that genuinely have to survive, how the command surface stays intact even as the classes behind it vanish, and how to fold it into `dotnet pack` so every release ships protected.

## Why a tool is not a library

When you obfuscate a shipped library, the governing rule is *keep the public API* — consumers reference your public types and members by name, so renaming them breaks their build. A global tool has no such consumers. Its package contains an assembly and a manifest; a user types `mytool build --release` and the runtime launches your entry point. Nothing links against `MyTool.RootCommandBuilder` or `MyTool.Handlers.BuildHandler`, so there is no reason to leave those names readable.

So the first setting is a deliberate omission:

```json
{
  "schemaVersion": 1,
  "inputs": [ "bin/Release/MyTool.1.4.0.nupkg" ],
  "outputDirectory": "protected",

  "preservePublicApi": false,

  "encryptStrings": true,
  "controlFlowObfuscation": true,

  "renaming": {
    "rules": [
      { "pattern": "MyTool.*", "action": "rename" }
    ]
  }
}
```

`preservePublicApi: false` is the opposite of the library default, and it is correct here: let the renamer rewrite `public` command classes, handlers and option builders exactly as it rewrites internal helpers. The single broad `rename` rule sweeps the whole `MyTool.*` namespace. There is one name this must *not* clobber — the entry point — and that is handled below, not by a keep rule.

## The one name that has to survive: the entry point

A global tool package carries a `DotnetToolSettings.xml` manifest that tells the .NET tool host which command name maps to which assembly:

```xml
<DotNetCliTool Version="1">
  <Commands>
    <Command Name="mytool" EntryPoint="MyTool.dll" Runner="dotnet" />
  </Commands>
</DotNetCliTool>
```

The entry point is pinned by **assembly and module name** (`MyTool.dll`) and the CLR finds `Main` through the assembly's entry-point token in the PE header — not by looking up a type called `Program`. That matters: Nebula preserves the assembly name and rewrites the entry-point token to follow the renamed method, so your `Program.Main` can become `a.b` and the tool still launches. You do **not** need a keep rule for `Program`. What you must not do is rename the *assembly* or drop the manifest — and because you hand Nebula the whole `.nupkg`, it keeps the manifest and the assembly identity for you.

<figure class="my-8"><svg viewBox="0 0 700 250" role="img" aria-label="Pipeline: dotnet pack with PackAsTool produces MyTool.nupkg containing tools/net8.0/any/MyTool.dll and DotnetToolSettings.xml. Nebula takes that package, renames and encrypts the assemblies inside while preserving the assembly name, the entry-point token and the manifest, and emits a protected MyTool.nupkg. dotnet tool install -g then installs it and the mytool command runs." style="width:100%;height:auto"><defs><style>.bx{fill:#eef4ff;stroke:#8eb4ff}.nb{fill:#fff7ed;stroke:#fdba74}.ok{fill:#ecfdf5;stroke:#6ee7b7}.t{font:600 13px system-ui;fill:#0f172a}.s{font:11px system-ui;fill:#475569}.a{stroke:#64748b;stroke-width:1.5;fill:none;marker-end:url(#ah)}</style><marker id="ah" markerWidth="9" markerHeight="9" refX="7" refY="4" orient="auto"><path d="M0 0 L8 4 L0 8 z" fill="#64748b"/></marker></defs><rect class="bx" x="12" y="60" width="150" height="120" rx="8"/><text class="t" x="28" y="84">dotnet pack</text><text class="s" x="28" y="106">PackAsTool=true</text><text class="s" x="28" y="134">MyTool.nupkg</text><text class="s" x="28" y="152">· MyTool.dll</text><text class="s" x="28" y="170">· DotnetToolSettings.xml</text><line class="a" x1="162" y1="120" x2="252" y2="120"/><rect class="nb" x="254" y="52" width="186" height="136" rx="8"/><text class="t" x="270" y="78">Nebula.NET</text><text class="s" x="270" y="102">rename public + internal</text><text class="s" x="270" y="122">encrypt strings / flatten</text><text class="s" x="270" y="146">keep assembly name</text><text class="s" x="270" y="164">keep entry-point token</text><text class="s" x="270" y="182">keep manifest</text><line class="a" x1="440" y1="120" x2="530" y2="120"/><rect class="ok" x="532" y="60" width="156" height="120" rx="8"/><text class="t" x="548" y="84">protected .nupkg</text><text class="s" x="548" y="112">dotnet tool install -g</text><text class="s" x="548" y="138">$ mytool build</text><text class="s" x="548" y="160">runs — classes are gone,</text><text class="s" x="548" y="176">verbs still parse</text></svg></figure>

## The command surface is made of strings, not names

The instinct that stops people obfuscating a tool aggressively is the fear that renaming the command classes will change the verbs users type. It will not, and the reason is structural. In `System.CommandLine` — and in essentially every CLI framework — the command and option names are **string literals you pass to constructors**, not the names of the types that build them:

```csharp
var build = new Command("build", "Compile the project");
var release = new Option<bool>("--release", "Build in Release configuration");
build.AddOption(release);
build.SetHandler(ctx => BuildHandler.Run(ctx));
```

Rename the class this lives in from `RootCommandBuilder` to `a`, rename `BuildHandler` to `b`, and the literals `"build"`, `"--release"` and the help text are untouched — they are data in the method body, not metadata identifiers. The parser still produces the exact same `mytool build --release` surface. Better still, with `encryptStrings` on, those literals are no longer sitting in the string heap for someone to grep: they are decrypted on demand when the command tree is built. So renaming hides *how* the tool is wired, string encryption hides the *vocabulary*, and the user-facing CLI is byte-for-byte identical.

Here is what a handler looks like after protection, decompiled. Before:

```csharp
internal static class BuildHandler
{
    public static int Run(InvocationContext ctx)
    {
        bool release = ctx.ParseResult.GetValueForOption(ReleaseOption);
        return Compiler.Invoke(release ? "Release" : "Debug");
    }
}
```

After renaming, control-flow flattening and string encryption, the same method decompiles to a dispatcher loop over a `b.c(...)` call with the `"Release"` / `"Debug"` literals replaced by calls into the string-decryption routine — the logic is intact and runs identically, but the method reads as generated noise with no recognizable names or constants.

## Watch the same seams you would anywhere

"Rename everything" has the same handful of exceptions any .NET app does — the places where something resolves a name as a string at runtime. In a tool they are usually few, but check for them:

- **Configuration binding.** If your tool reads settings through `IConfiguration` and `Configure<TOptions>`, the bound property names must survive. Keep those option classes' public property names, or bind explicitly.
- **Serialized output.** If the tool emits JSON that scripts parse — `mytool list --json` — those DTO property names are a contract with your users' pipelines, even though no code compiles against them. Pin them with `[JsonPropertyName("...")]` so the wire names stop depending on the C# names, as in [pinning a JSON contract](https://delta1labs.com/blog/obfuscate-system-text-json-jsonpropertyname-contract/).
- **Reflection and DI scanning.** A tool that discovers commands by scanning for a naming convention (every type ending in `Command`) breaks when those names rename. Prefer explicit registration; where you cannot, keep what the scan matches. The full treatment is in [obfuscating assembly scanning and DI](https://delta1labs.com/blog/obfuscate-assembly-scanning-dependency-injection/).

The discipline for all of these is the same minimal-keep-list discipline covered in [building a Nebula keep-list](https://delta1labs.com/blog/nebula-keep-list-rename-exclusions/): keep only the leaf name something reads as a string, never the namespace around it.

## Fold it into dotnet pack

The clean place to protect a tool is right after it is packed, so the artifact that leaves your build is already protected and your source is untouched. Mark the project as a tool as usual:

```xml
<PropertyGroup>
  <PackAsTool>true</PackAsTool>
  <ToolCommandName>mytool</ToolCommandName>
  <PackageId>MyTool</PackageId>
  <Version>1.4.0</Version>
</PropertyGroup>
```

Then run Nebula against the packed package in your release pipeline:

```bash
dotnet pack -c Release
nebula --config nebula.config.json
```

The protected `MyTool.1.4.0.nupkg` lands in `protected/`, carrying its manifest and entry point, ready to `dotnet nuget push`. For a fully hands-off setup you can hook the obfuscation into MSBuild so it runs after `Pack` automatically — see [MSBuild & CI](https://delta1labs.com/docs/nebula/msbuild/) — and gate it to Release so your inner-loop `dotnet run` stays fast and debuggable.

## Prove it

Install the protected package into a throwaway environment and exercise it as a user would: `dotnet tool install -g --add-source ./protected MyTool`, then run your real commands — `mytool build --release`, `mytool list --json` — and confirm the verbs parse, the options bind and the output is unchanged. Then open the DLL from inside the protected package in [Glass.NET](https://delta1labs.com/products/glass), the free static decompiler, and confirm the other half: your command classes and handlers read as `a`, `b`, `c`, the string heap no longer contains your verbs and help text, and the entry point still resolves. Over-renaming shows up as a broken command at runtime; under-protecting shows up as readable logic in the decompiler. When both checks pass, the tool your users install does exactly what it always did, and reveals almost nothing about how.

[Download Nebula.NET free](https://delta1labs.com/download?product=nebula) and protect your next `dotnet tool` release.

