Skip to content
← Alle Beiträge
· Delta1 Labs ObfuscationNebula.NET

Ihre .NET-Obfuskierung in der CI verifizieren

Ein grüner Build ist kein Beweis, dass Ihre .NET-Assembly geschützt ist. Nebula.NET 2.2.0 erzeugt bei jedem Build einen stabilen, versionierten Schutzbericht und liefert `nebula verify` — eine CI-Schranke, die den Build mit einem eigenen Exit-Code fehlschlagen lässt, wenn Umbenennung, String-Verschlüsselung, Kontrollfluss oder Virtualisierung, die Sie angefordert haben, stillschweigend nicht angewendet wurden.

Ihre Release-Pipeline ist grün. Der Obfuskierungsschritt lief, gab keine Fehler aus, und das signierte Paket liegt in Ihrem Artefaktspeicher. Also ist der Code jetzt geschützt — oder?

Ein erfolgreicher Build beweist nur, dass der Obfuskator nicht abgestürzt ist. Er sagt nichts darüber, ob die Ausgabe tatsächlich gehärtet ist. Eine keep-Regel mit einem Glob zu viel, eine Funktion, die in Ihrer Edition nicht aktiviert ist, ein falsch geschriebener Konfigurationsschlüssel oder eine bereits verarbeitete Eingabe — alle erzeugen einen sauberen Exit-Code und eine weit offene Assembly. Das ist der stille Rückfall auf keinen Schutz, und weil nichts fehlschlägt, überlebt er bis in die Produktion.

Nebula.NET 2.2.0 schließt diese Lücke mit zwei Dingen, die in jede Pipeline gehören: einem Schutzbericht, der bei jedem Build erzeugt wird, und nebula verify, einer Schranke, die den Build fehlschlagen lässt, wenn die angeforderten Transformationen nicht angewendet wurden.

Der Schutzbericht

Jeder Nebula.NET-Build kann eine maschinenlesbare Zusammenfassung dessen erzeugen, was er tatsächlich getan hat. Es ist reines JSON mit einem versionierten, stabilen Schema, sodass Sie es parsen, archivieren und über Builds hinweg vergleichen können, ohne zu befürchten, dass das nächste Release die Felder umstellt.

Aktivieren Sie ihn in Ihrer nebula.json:

{
  "obfuscate": true,
  "rename": true,
  "stringEncryption": true,
  "controlFlow": true,
  "report": {
    "enabled": true,
    "path": "artifacts/nebula-report.json"
  }
}

Oder fordern Sie ihn auf der Kommandozeile an, was die Konfiguration überschreibt und in der CI praktisch ist:

nebula protect MyApp.dll --report artifacts/nebula-report.json

Hier ein echter Auszug aus einem Bericht für einen 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"
  ]
}

So lesen Sie ihn

Eine Handvoll Felder verrät Ihnen fast alles:

  • transforms[].requested gegenüber applied — der wichtigste Vergleich. Wenn Sie controlFlow angefordert haben und applied false ist, hat Ihre Verflachung nicht stattgefunden. Auf dieses Feld stützt sich nebula verify.
  • summary.renameRatio — der Anteil der infrage kommenden Mitglieder, die umbenannt wurden. Ein gesunder Bibliotheks-Build liegt im oberen 0,9er-Bereich. Fällt er auf, sagen wir, 0,4, schließt eine keep-Regel weit mehr aus, als Sie beabsichtigt hatten.
  • summary.residualPublicTypes / residualPublicSurface — die öffentliche API, die Sie bewusst lesbar gelassen haben, weil Aufrufer an sie binden. Das sollte eine kurze, vertraute Liste sein: Ihre Plugin-Verträge, Ihre öffentlichen Einstiegspunkte. Taucht hier ein Typ auf, den Sie verborgen erwartet hatten, ist er über Ihre öffentliche Oberfläche erreichbar und wurde absichtlich übersprungen — ein Signal, Ihre keep-Regeln enger zu fassen.
  • output.mvid — die Module Version ID der erzeugten Assembly. Da sie sich bei jedem echten Umschreiben ändert, ist sie eine günstige Manipulations- und Frische-Prüfung: Ist input.mvid gleich output.mvid, wurde überhaupt nichts umgeschrieben.

In Pro und Enterprise trägt jede Transformation zusätzlich eine Aufschlüsselung pro Typ (welche Typen verflacht, welche Methoden virtualisiert wurden), sodass Sie bestätigen können, dass gerade Ihre sensibelsten Methoden abgedeckt wurden, statt sich auf eine aggregierte Zählung zu verlassen. Alle Editionen erzeugen die Zusammenfassung und die Transformationsergebnisse der obersten Ebene.

nebula verify — die CI-Schranke

Den Bericht einmal mit bloßem Auge zu lesen, ist in Ordnung. In einer Pipeline soll eine Maschine das bei jedem Build tun und die Linie anhalten, wenn etwas nicht stimmt. Dafür gibt es nebula verify.

Richten Sie es auf die Ausgabe-Assembly (oder direkt auf den Bericht). Es vergleicht angeforderte mit angewendeten Transformationen und endet mit einem Exit-Code ungleich null, wenn eine angeforderte Transformation nicht angewendet wurde:

nebula verify MyApp.dll --report artifacts/nebula-report.json

Die Exit-Codes sind stabil und skriptfähig:

Exit-CodeBedeutung
0Jede angeforderte Transformation wurde angewendet. Bestanden.
3Mindestens eine angeforderte Transformation wurde nicht angewendet. Schranke fehlgeschlagen.
1Nutzungs- oder E/A-Fehler (fehlende Datei, unlesbarer Bericht).

Exit-Code 3 ist dem einen Fehler gewidmet, der Sie wirklich interessiert — „Sie haben Schutz angefordert und ihn nicht bekommen” — sodass Sie eine echte Schutzregression von einem kaputten Aufruf unterscheiden können.

Sie können auch bestimmte Transformationen erzwingen, unabhängig davon, was die Konfiguration angefordert hat — nützlich, wenn ein Build-Profil eine bestimmte Schicht enthalten muss:

nebula verify MyApp.dll --require rename,stringEncryption,controlFlow
nebula protectbauen + härtenSchutzberichtangefordert vs angewendetnebula verifyvergleichen + Exit-CodeExit 0 — weiteralles angewendetExit 3 — Fehlschlageine Transformation übersprungen

In eine Pipeline einhängen

In einem shell-basierten CI-Schritt ist die Schranke eine einzige Zeile — set -e und ein Exit ungleich null erledigen den 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

Lieber MSBuild? Machen Sie die Schranke zum Teil des Build-Graphen, damit eine übersprungene Transformation dotnet build fehlschlagen lässt:

<Target Name="VerifyProtection" AfterTargets="Nebula">
  <Exec Command="nebula verify &quot;$(TargetPath)&quot; --report &quot;$(OutDir)nebula-report.json&quot;" />
</Target>

Da Exec das Ziel bei einem Exit-Code ungleich null fehlschlagen lässt, stoppt ein Exit 3 von verify den Build zusammen mit dem Rest Ihrer Pipeline.

Archivieren, dann vergleichen

Der Bericht zahlt sich über die Zeit aus. Laden Sie nebula-report.json bei jedem Lauf als Build-Artefakt hoch, und Sie erhalten eine Schutzhistorie, die Sie vergleichen können:

# Fehlschlag, wenn dieser Build weit weniger Mitglieder umbenannt hat als der letzte grüne 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) }'

Ein Vergleich von Build zu Build fängt die langsamen Regressionen ab, die verify allein nicht kann: eine keep-Regel, die jemand letzten Monat verbreitert hat, einen neuen öffentlichen Typ, der Ihre Restoberfläche still vergrößert hat, eine Transformation, die zwar noch angewendet wird, aber jetzt 60 % der Methoden abdeckt statt 95 %. Ob die Transformation angewendet wurde oder nicht, ist eine Ja-oder-Nein-Frage; die Verhältnisse sind ein Trend, und Trends sind der Ort, an dem Schutz still erodiert.

Eine Schranke mehr: nebula doctor

Die meisten Fehler des stillen Rückfalls lassen sich auf eine zu breite keep-Regel zurückführen. nebula doctor analysiert Ihre Konfiguration gegen die Assembly und meldet Regeln, die auf weit mehr passen, als sie wahrscheinlich sollten:

nebula doctor MyApp.dll

Es wird Ihnen zum Beispiel sagen, dass keep: MyApp.* 400 von 412 Typen lesbar hält — ganz sicher nicht das, was Sie beabsichtigten, als Sie nur einen Plugin-Vertrag erhalten wollten. Führen Sie es aus, wenn renameRatio niedrig wirkt oder residualPublicSurface länger ist als erwartet; es verwandelt „warum wird das nicht umbenannt?” in eine direkte Antwort.

Fazit

Obfuskierung, die läuft, aber nicht angewendet wird, ist schlimmer als keine Obfuskierung, denn sie wird mit einem falschen Gefühl von Sicherheit ausgeliefert. Nebula.NET 2.2.0 macht diesen Fehler unübersehbar: Erzeugen Sie den Schutzbericht bei jedem Build, um genau zu sehen, was angewendet wurde, führen Sie nebula verify als Schranke aus, damit eine übersprungene Transformation den Build mit einem eigenen Exit-Code fehlschlagen lässt, archivieren und vergleichen Sie den Bericht, damit langsame Erosion als Trend sichtbar wird, und halten Sie nebula doctor bereit, wenn eine keep-Regel mehr tut als angefordert. Schützen Sie die Software, die zu schützen Sie berechtigt sind — und beweisen Sie bei jedem Build, dass Sie es wirklich getan haben.

Nebula.NET testen

Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.