Skip to content
← Alle Beiträge
· Delta1 Labs ObfuscationNebulagRPC

Code-First-gRPC obfuskieren ohne Routen zu zerstören

Bei Code-First-gRPC (protobuf-net.Grpc) gibt es keine .proto-Datei: Der Service-Vertrag ist eine .NET-Schnittstelle, und die Bibliothek leitet die Wire-Route `/package.Service/Method` zur Laufzeit aus dem Namespace der Schnittstelle, ihrem Typnamen und dem Namen jeder Methode ab. Benennt man die Schnittstelle oder eine Methode um, ändert sich der HTTP/2-Pfad, sodass Clients eine Route treffen, die der Server nicht mehr bedient, und jeder Aufruf mit UNIMPLEMENTED fehlschlägt — ohne Compile-Fehler. DTO-Member verhalten sich genau umgekehrt: protobuf serialisiert über das numerische `[ProtoMember]`-Tag, daher lassen sich diese Bezeichner problemlos umbenennen. Dieser Beitrag zeigt genau, wie die Route berechnet wird, warum `[Service]` und `[Operation]` die Wire-Namen fixieren, während die Bezeichner umbenannt werden, und wie man eine Keep-List in nebula.config.json schreibt, die Implementierung und DTO-Interna schützt und das Routing intakt lässt.

Ein Code-First-gRPC-Service hat keine .proto-Datei, daher ist man versucht zu glauben, es gebe keinen externen Vertrag zu schützen — das Ganze sei nur C#-Schnittstellen und DTOs. Aber der Vertrag ist nicht verschwunden; er ist in Metadaten gewandert, die die Laufzeit per Reflexion liest, und ein blinder Umbenennungslauf schreibt sie ohne Warnung um.

In protobuf-net.Grpc ist der Service-Vertrag eine .NET-Schnittstelle, dekoriert mit ein paar Attributen, und die DTOs sind gewöhnliche Klassen mit [ProtoMember]-Tags. Es gibt keinen Codegenerierungsschritt und keine .proto zum Einchecken. Dieser Komfort verbirgt eine scharfe Kante für die Obfuskation: Die gRPC-Route, die ein Client aufruft — der im HTTP/2-:path-Header getragene Pfad /package.Service/Method — steht nirgends sichtbar geschrieben. Die Bibliothek berechnet sie zum Bindungszeitpunkt aus dem Namespace der Schnittstelle, ihrem Typnamen und dem Methodennamen. Benennen Sie eines der drei um, und Sie haben Ihren öffentlichen Wire-Vertrag stillschweigend geändert — mit sauberem Build und einem Server, der gut startet und dann jeden echten Aufruf mit UNIMPLEMENTED beantwortet.

Das Heilmittel ist dieselbe Disziplin, die jedes reflexionsgesteuerte Framework verlangt: Finden Sie die Namen, die auf der Leitung als Strings gelesen werden, fixieren Sie genau diese und lassen Sie alles dahinter umbenennen.

Was auf der Leitung ist und was nicht

In einem Code-First-gRPC-Service treffen zwei verschiedene Namenssysteme aufeinander, und sie verhalten sich beim Umbenennen gegensätzlich. Das Routing wird aus Bezeichnern abgeleitet; die Serialisierung wird durch numerische Tags bestimmt. Diese Unterscheidung richtig zu treffen, ist die ganze Aufgabe.

VERTRAG (Bezeichner)namespace Shop.Contractsinterface ICalculator Multiply(req)diese drei Namen werdenfür die Route gelesenABLEITUNG (bei Bindung)führendes I entfernen →CalculatorNamespace voranstellen →Shop.Contracts.CalculatorMethodenname = OperationHTTP/2 :path/Shop.Contracts.Calculator /MultiplyName umbenennen → Route wandertICalculator oder Multiply umbenennen und die Route ändert sich; der alte Pfad des Clients liefert UNIMPLEMENTED.DTO-Membernamen erscheinen hier nicht — sie reisen als numerische protobuf-Tags (nächste Abbildung).
Die gRPC-Route wird bei der Bindung aus Namespace, Typnamen und Methodennamen der Schnittstelle berechnet — ein abgeleiteter String, den der Umbenenner ändern kann.

Hier ist der Vertrag. Es sind nur eine Schnittstelle und zwei DTOs, nirgends generierter Code:

using System.Threading.Tasks;
using ProtoBuf;
using ProtoBuf.Grpc;

namespace Shop.Contracts;

[ServiceContract]
public interface ICalculator
{
    ValueTask<MultiplyReply> Multiply(MultiplyRequest request, CallContext ctx = default);
}

[ProtoContract]
public class MultiplyRequest
{
    [ProtoMember(1)] public double X { get; set; }
    [ProtoMember(2)] public double Y { get; set; }
}

[ProtoContract]
public class MultiplyReply
{
    [ProtoMember(1)] public double Result { get; set; }
}

Der Server registriert die Implementierung gegen die Schnittstelle, und der Client baut einen Proxy aus derselben Schnittstelle:

// Server
app.MapGrpcService<CalculatorService>();   // CalculatorService : ICalculator

// Client
var channel = GrpcChannel.ForAddress("https://localhost:5001");
var calc = channel.CreateGrpcService<ICalculator>();
var reply = await calc.Multiply(new MultiplyRequest { X = 6, Y = 7 });

Nichts in diesem Code erwähnt die Route /Shop.Contracts.Calculator/Multiply. Beide Enden leiten sie unabhängig aus ICalculator ab.

Wie die Route tatsächlich abgeleitet wird

Wenn protobuf-net.Grpc ICalculator bindet, verwandelt sein Service-Binder den Vertragstyp in einen Service-Namen. Die Logik ist klein genug, um sie exakt anzugeben: Nimm den Typnamen, entferne ein führendes I, falls das nächste Zeichen großgeschrieben ist, und stelle den Namespace voran.

// Equivalent to ProtoBuf.Grpc's ServiceBinder.GetDefaultName(Type).
static string GetServiceName(Type contract)
{
    var name = contract.Name;                      // "ICalculator"
    if (contract.IsInterface && name.Length > 1
        && name[0] == 'I' && char.IsUpper(name[1]))
        name = name.Substring(1);                  // "Calculator"
    return contract.Namespace + "." + name;        // "Shop.Contracts.Calculator"
}

Der Operationsname entspricht standardmäßig dem Methodennamen, Multiply. gRPC setzt dann den HTTP/2-Pfad als /{service}/{operation} zusammen:

/Shop.Contracts.Calculator/Multiply

Dieser String ist der Vertrag. Er wird aus drei Metadaten-Teilen gebaut — Namespace, Typname, Methodenname — von denen keiner vom Compiler als tragend behandelt wird. Benennen Sie ICalculator in a um, wird der Service zu Shop.Contracts.a; verschieben Sie ihn in einen umbenannten Namespace, ändert sich das Präfix; benennen Sie Multiply in b um, ändert sich die Operation. Jede Änderung ergibt einen anderen Pfad, und ein gegen den Originalvertrag kompilierter Client sendet weiter den originalen. Der Server hat auf der alten Route keinen Handler, also schließt der Stream mit:

Status(StatusCode="Unimplemented", Detail="Service is unimplemented.")

Kein Compile-Fehler, kein Startfehler: Der Service wird auf der neuen Route fröhlich gehostet, während jeder bestehende Aufrufer sie verfehlt.

Warum DTO-Member das Gegenteil sind

Die Request- und Reply-Körper sind die beruhigende Hälfte der Geschichte. protobuf-net serialisiert nicht nach Membernamen; es serialisiert nach dem Integer-Tag, das Sie in [ProtoMember(n)] deklarieren. Der Name ist rein für Ihren C#-Code da.

VORHER[ProtoMember(1)] double ResultBezeichner: Result · Tag: 1NACH UMBENENNUNG[ProtoMember(1)] double aBezeichner: a · Tag: 1 (unverändert)WIRE-BYTES (identisch)Feld 1, Typ fixed64 → 09 ..tag = (1 << 3) | 1 = 0x09die Feld-NUMMER ist der Vertrag;der Member-NAME wird nie gesendet
Protobuf identifiziert Felder per Tag-Nummer, daher lässt das Umbenennen von Result in a die Wire-Bytes unberührt — DTO-Member benennen sich frei um.

Da der Wire-Schlüssel 1 ist, nicht Result, kann Nebula die Eigenschaft in a umbenennen, den DTO-Typ MultiplyReply in irgendetwas umbenennen (der Typname wird ebenfalls nie übertragen), und die Bytes auf der Leitung sind byte-für-byte identisch. Die einzige Regel ist, dass die [ProtoMember]-Nummern fest bleiben müssen — und das tun sie, weil es Integer-Literale innerhalb eines Attributs sind, keine Bezeichner. Dasselbe gilt für Enums, die als ihr numerischer Wert reisen.

Die zu schützende Vertragsoberfläche ist also genau: der Typname der Service-Schnittstelle, ihr Namespace und die Namen ihrer Methoden. Nichts weiter.

Die Wire-Namen fixieren

Es gibt zwei Wege, die Route stabil zu halten. Der erste ist eine Keep-List, die Nebula anweist, die Vertragsschnittstellen nicht umzubenennen. Der zweite und bessere ist, die Wire-Namen explizit anzugeben, damit die Bezeichner wieder frei sind.

Mit protobuf-net.Grpc setzen Sie sie am Vertrag selbst:

using ProtoBuf.Grpc.Configuration;

namespace Shop.Contracts;

[Service("shop.Calculator")]                 // der Wire-Name wird hier fixiert…
public interface ICalculator                 // …sodass dieser Bezeichner umbenannt werden darf
{
    [Operation("Multiply")]                  // …und dieser auch
    ValueTask<MultiplyReply> Multiply(MultiplyRequest request, CallContext ctx = default);
}

Jetzt liest der Binder shop.Calculator und Multiply direkt aus den Attributwerten und schaut nie auf die Metadaten-Namen, also ist die Route /shop.Calculator/Multiply, egal wie der Obfuskator die Schnittstelle oder die Methode nennt. Das lohnt sich unabhängig von der Obfuskation: Es fixiert Ihre öffentliche gRPC-Oberfläche, sodass eine routinemäßige Umbenennung oder ein Namespace-Umzug sie nicht verschieben kann.

Die Keep-List in nebula.config.json

Wenn Sie den Vertrag nicht mit expliziten Namen annotiert haben, fixieren Sie die abgeleiteten Namen, indem Sie die Vertragsschnittstellen behalten. Alles andere — die Implementierung, die DTOs, die internen Services — geht in die Umbenennung:

{
  "schemaVersion": 1,
  "inputs": [
    "bin/Release/net8.0/Shop.Server.dll",
    "bin/Release/net8.0/Shop.Contracts.dll"
  ],
  "outputDirectory": "protected",

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

  "renaming": {
    "rules": [
      { "pattern": "Shop.Contracts.I*", "action": "keep", "members": "public" },
      { "pattern": "Shop.Contracts.*",  "action": "rename" },
      { "pattern": "Shop.Server.*",     "action": "rename" }
    ]
  }
}

Die erste Regel matcht die Vertragsschnittstellen über das konventionelle I…-Präfix und behält sowohl die Typnamen (sodass der Service-String aus Namespace-plus-Name erhalten bleibt) als auch ihre öffentlichen Methodennamen, während members: "public" jedes nicht-öffentliche Member im Geltungsbereich der Schnittstelle selbst weiter umbenennen lässt. Die zweite Regel benennt alles andere in Shop.Contracts um — vor allem die DTO-Typen und ihre Member, die sicher sind, weil sie als numerische Tags reisen. Die dritte Regel benennt die gesamte Server-Assembly um: CalculatorService, Ihre Validatoren, internen Stores und DI-Registrierungen erhalten vollständige Umbenennung, Kontrollfluss-Obfuskation und String-Verschlüsselung. Der Name der Implementierungsklasse ist nie auf der Leitung — die Bindung erfolgt über die Schnittstelle — also darf er verschwinden.

Wenn Sie jeden Vertrag mit [Service]/[Operation] annotiert haben, können Sie die Keep-Regel ganz streichen und auch die Schnittstellen umbenennen lassen, weil die Wire-Namen nun in Attribut-Literalen leben, die Nebula bewahrt. Für die einzelne Methode, die eine Ausnahme ist, ist ein Attribut am exakten Member präziser als ein Konfigurationsmuster und lebt neben dem Code:

[Obfuscation(Feature = "renaming", Exclude = true, ApplyToMembers = false)]
ValueTask<MultiplyReply> Multiply(MultiplyRequest request, CallContext ctx = default);

Führen Sie den Schutz als Teil des Release-Builds gegen die veröffentlichte Ausgabe aus:

nebula protect --config nebula.config.json

Die Umbenennungs-, Kontrollfluss- und String-Verschlüsselungsläufe von Nebula sind in der kostenlosen Stufe zur Evaluierung verfügbar; die schwereren Schutzmaßnahmen wie Methoden-Virtualisierung gehören zu Nebula Pro. Siehe die Nebula-Dokumentation für die vollständige Regelsyntax und /products/nebula für die Stufen.

Vorbehalte und wann es bricht

Der subtile Fehlerfall ist der, in dem es zu funktionieren scheint. Referenzieren Client und Server dieselbe obfuskierte Vertrags-Assembly, leiten beide dieselbe umbenannte Route ab und die Aufrufe funktionieren im Test — und brechen an dem Tag, an dem ein Client aus dem Originalpaket neu kompiliert wird, ein Nicht-.NET-Konsument mit grpcurl hereinkommt oder Sie eine Seite obfuskieren und die andere nicht. Die Route ist nur stabil, weil zwei Builds zufällig übereinstimmten; das ist kein Vertrag. Fixieren Sie die Wire-Namen mit [Service]/[Operation], und die Übereinstimmung wird zur Garantie.

Zwei weitere ehrliche Grenzen. Erstens: Reflexions- oder Server-Reflection-Endpunkte, die Ihre Service-Liste bekanntgeben, geben die umbenannten Namen bekannt, wenn Sie die abgeleitete Namensgebung behalten haben — in Ordnung, wenn Sie beide Enden besitzen, überraschend, wenn ein Werkzeug Sie introspektiert. Zweitens: Diese Regeln decken nur die Vertragsoberfläche ab; wenn Sie Routing oder Serialisierung über irgendeine andere string-basierte Reflexion in Ihrem eigenen Code steuern, ist dieser String ebenfalls tragend und gehört auf die Keep-List.

Die Regel unter all dem ist dieselbe, der jedes reflexionsgesteuerte Framework gehorcht: Ein Name ist genau dann tragend, wenn etwas außerhalb der CLR-eigenen Token-Auflösung ihn als String liest. Bei Code-First-gRPC ist diese Menge klein und erkennbar — der Typname der Service-Schnittstelle, ihr Namespace und die Namen ihrer Methoden — und die Request- und Reply-Member gehören bewusst nicht dazu, weil protobuf sie per Nummer indiziert. Fixieren Sie diese wenigen Namen, oder geben Sie sie direkt mit [Service] und [Operation] an, und Nebula benennt Implementierung, DTO-Interna und Geschäftslogik frei um und schützt Ihren eigenen ausgelieferten Service, ohne je eine Route zu verschieben, von der ein Client abhängt.

Nebula.NET testen

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