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.
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.
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.