Verifying your .NET obfuscation in CI
A green build does not prove your .NET assembly is protected. Nebula.NET 2.2.0 emits a stable, versioned protection report on every build and ships `nebula verify`, a CI gate that fails the build with a dedicated exit code when the renaming, string encryption, control-flow or virtualization you asked for silently did not land.
Your release pipeline is green. The obfuscation step ran, printed no errors, and the signed package is sitting in your artifact store. So the code is protected — right?
A successful build only proves the obfuscator did not crash. It says nothing about whether the output is actually hardened. A keep rule that is one glob too wide, a feature that is not enabled on your edition, a config key you misspelled, or an input that was already processed will all produce a clean exit code and an assembly that is wide open. This is the silent fallback to no protection, and because nothing fails, it survives all the way to production.
Nebula.NET 2.2.0 closes that gap with two things that belong in every pipeline: a protection report emitted on every build, and nebula verify, a gate that fails the build when the transforms you asked for did not land.
The protection report
Every Nebula.NET build can emit a machine-readable summary of what it actually did. It is plain JSON with a versioned, stable schema, so you can parse it, archive it, and diff it across builds without worrying that the next release will reshuffle the fields.
Turn it on in your nebula.json:
{
"obfuscate": true,
"rename": true,
"stringEncryption": true,
"controlFlow": true,
"report": {
"enabled": true,
"path": "artifacts/nebula-report.json"
}
}
Or ask for it on the command line, which overrides the config and is handy in CI:
nebula protect MyApp.dll --report artifacts/nebula-report.json
Here is a real excerpt from a report for a Pro build:
{
"schemaVersion": "1.0",
"tool": { "name": "Nebula.NET", "version": "2.2.0", "edition": "Pro" },
"input": { "assembly": "MyApp.dll", "mvid": "2f1c8e0a-7b44-4d2e-9a6b-1e5d0c3f9a21" },
"output": { "assembly": "MyApp.dll", "mvid": "b9d4e7c2-0a31-4f88-ae10-6c2f7b4d1e90" },
"summary": {
"typesTotal": 412,
"methodsTotal": 3187,
"renamedMembers": 3904,
"renameRatio": 0.97,
"residualPublicTypes": 12
},
"transforms": [
{ "name": "rename", "requested": true, "applied": true, "typesAffected": 400, "methodsAffected": 3090 },
{ "name": "stringEncryption", "requested": true, "applied": true, "stringsEncrypted": 1884 },
{ "name": "controlFlow", "requested": true, "applied": true, "methodsAffected": 2731 },
{ "name": "virtualization", "requested": false, "applied": false }
],
"residualPublicSurface": [
"MyApp.PluginContract",
"MyApp.PluginContract.IPlugin",
"MyApp.Api.HealthController"
]
}
How to read it
A handful of fields tell you almost everything:
transforms[].requestedvsapplied— the single most important comparison. If you asked forcontrolFlowandappliedisfalse, your flattening did not happen. This is the fieldnebula verifykeys on.summary.renameRatio— the fraction of eligible members that were renamed. A healthy library build sits in the high 0.9s. If it drops to, say, 0.4, a keep rule is excluding far more than you intended.summary.residualPublicTypes/residualPublicSurface— the public API you deliberately left legible, because callers bind to it. This should be a short, familiar list: your plugin contracts, your public entry points. If a type you expected to be hidden shows up here, it is reachable through your public surface and was skipped on purpose — a signal to tighten your keep rules.output.mvid— the Module Version ID of the produced assembly. Because it changes on every real rewrite, it is a cheap tamper and freshness check: ifinput.mvidequalsoutput.mvid, nothing was rewritten at all.
On Pro and Enterprise, each transform also carries a per-type breakdown (which types were flattened, which methods were virtualized), so you can confirm your most sensitive methods specifically were covered rather than trusting an aggregate count. All editions emit the summary and the top-level transform results.
nebula verify — the CI gate
Reading the report by eye is fine once. In a pipeline you want a machine to do it on every build and stop the line when something is wrong. That is nebula verify.
Point it at the output assembly (or the report directly). It compares requested transforms against applied ones and exits non-zero if any requested transform did not land:
nebula verify MyApp.dll --report artifacts/nebula-report.json
The exit codes are stable and scriptable:
| Exit code | Meaning |
|---|---|
0 | Every requested transform was applied. Pass. |
3 | At least one requested transform did not land. Gate fail. |
1 | Usage or I/O error (missing file, unreadable report). |
Exit code 3 is dedicated to the one failure you actually care about — “you asked for protection and did not get it” — so you can distinguish a real protection regression from a broken invocation.
You can also assert specific transforms regardless of what the config requested, which is useful when a build profile must include a given layer:
nebula verify MyApp.dll --require rename,stringEncryption,controlFlow
Wiring it into a pipeline
In a shell-based CI step, the gate is one line — set -e and a non-zero exit do the rest:
# GitHub Actions
- name: Harden and verify
run: |
nebula protect src/bin/Release/net8.0/MyApp.dll \
--report artifacts/nebula-report.json
nebula verify src/bin/Release/net8.0/MyApp.dll \
--report artifacts/nebula-report.json
- name: Archive protection report
uses: actions/upload-artifact@v4
with:
name: nebula-report
path: artifacts/nebula-report.json
Prefer MSBuild? Make the gate part of the build graph so a skipped transform fails dotnet build:
<Target Name="VerifyProtection" AfterTargets="Nebula">
<Exec Command="nebula verify "$(TargetPath)" --report "$(OutDir)nebula-report.json"" />
</Target>
Because Exec fails the target on a non-zero exit code, an exit 3 from verify stops the build with the rest of your pipeline.
Archive it, then diff it
The report earns its keep over time. Upload nebula-report.json as a build artifact on every run and you get a protection history you can diff:
# Fail if this build renamed far fewer members than the last green build.
prev=$(jq '.summary.renameRatio' baseline-report.json)
curr=$(jq '.summary.renameRatio' artifacts/nebula-report.json)
awk -v p="$prev" -v c="$curr" 'BEGIN { exit !(c >= p - 0.05) }'
A build-to-build diff catches the slow regressions verify alone cannot: a keep rule someone widened last month, a new public type that quietly enlarged your residual surface, a transform that still applies but now covers 60% of methods instead of 95%. The transform either landed or it didn’t is a yes/no question; the ratios are a trend, and trends are where protection silently erodes.
One more guard: nebula doctor
Most silent-fallback failures trace back to a keep rule that is too broad. nebula doctor analyzes your configuration against the assembly and flags rules that match far more than they probably should:
nebula doctor MyApp.dll
It will tell you, for example, that keep: MyApp.* is holding 400 of 412 types legible — almost certainly not what you intended when you only meant to preserve a plugin contract. Run it when renameRatio looks low or residualPublicSurface is longer than you expected; it turns “why isn’t this being renamed?” into a direct answer.
Takeaway
Obfuscation that runs but does not apply is worse than no obfuscation, because it ships with a false sense of security. Nebula.NET 2.2.0 makes that failure impossible to miss: emit the protection report on every build so you can see exactly what landed, run nebula verify as a gate so a skipped transform fails the build on a dedicated exit code, archive and diff the report so slow erosion shows up as a trend, and keep nebula doctor handy when a keep rule is doing more than you asked. Protect the software you have the right to protect — and prove, on every build, that you actually did.
Try Nebula.NET
Harden your .NET code in minutes — start with the free edition.