Skip to content
← All posts
· Delta1 Labs ObfuscationNebulagRPC

Obfuscating code-first gRPC without breaking routes

In code-first gRPC (protobuf-net.Grpc) there is no .proto file — the service contract is a .NET interface, and the library derives the wire route `/package.Service/Method` from the interface's namespace, its type name, and each method name at runtime. Rename the interface or a method and the HTTP/2 path changes, so clients hit a route the server no longer serves and every call fails UNIMPLEMENTED, with no compile error. DTO members behave the opposite way: protobuf serializes by the numeric `[ProtoMember]` tag, so those identifiers rename freely. This post reads exactly how the route is computed, why `[Service]` and `[Operation]` let you pin the wire names while renaming the identifiers, and how to write a nebula.config.json keep-list that protects the implementation and DTO internals while leaving routing intact.

A code-first gRPC service has no .proto file, so it is tempting to think there is no external contract to protect — the whole thing is just C# interfaces and DTOs. But the contract did not disappear; it moved into metadata the runtime reads by reflection, and a blind rename pass will quietly rewrite it.

In protobuf-net.Grpc the service contract is a .NET interface decorated with a couple of attributes, and the DTOs are ordinary classes with [ProtoMember] tags. There is no code-generation step and no .proto to check in. That convenience hides a sharp edge for obfuscation: the gRPC route a client calls — the /package.Service/Method path carried in the HTTP/2 :path header — is not written anywhere you can see. The library computes it at bind time from the interface’s namespace, its type name and the method name. Rename any of those three and you have silently changed your public wire contract, with a clean compile and a server that starts fine and then answers every real call with UNIMPLEMENTED.

The fix is the same discipline every reflection-driven framework demands: find the names that are read as strings on the wire, pin exactly those, and let everything behind them rename.

What is on the wire and what is not

Two different naming systems meet in a code-first gRPC service, and they behave in opposite ways under renaming. Routing is derived from identifiers; serialization is governed by numeric tags. Getting this distinction right is the entire job.

CONTRACT (identifiers)namespace Shop.Contractsinterface ICalculator Multiply(req)these three names areread to build the routeDERIVATION (bind time)strip leading I →Calculatorprepend namespace →Shop.Contracts.Calculatormethod name = operationHTTP/2 :path/Shop.Contracts.Calculator /Multiplyrename a name → route movesRename ICalculator or Multiply and the route changes; the client's old path returns UNIMPLEMENTED.DTO member names never appear here — they are carried as numeric protobuf field tags (next figure).
The gRPC route is computed from the interface namespace, type name and method name at bind time — it is a derived string the renamer can change.

Here is the contract. It is just an interface and two DTOs — no generated code anywhere:

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; }
}

The server registers the implementation against the interface, and the client builds a proxy from the same interface:

// 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 });

Nothing in that code mentions the route /Shop.Contracts.Calculator/Multiply. Both ends derive it independently from ICalculator.

How the route is actually derived

When protobuf-net.Grpc binds ICalculator, its service binder turns the contract type into a service name. The logic is small enough to state exactly: take the type name, strip a leading I if the next character is upper-case, and prepend the namespace.

// 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"
}

The operation name defaults to the method name, Multiply. gRPC then composes the HTTP/2 path as /{service}/{operation}:

/Shop.Contracts.Calculator/Multiply

That string is the contract. It is built from three pieces of metadata — namespace, type name, method name — none of which the compiler treats as load-bearing. Rename ICalculator to a and the service becomes Shop.Contracts.a; move it to a renamed namespace and the prefix changes; rename Multiply to b and the operation changes. Each produces a different path, and a client built against the original contract keeps sending the original one. The server has no handler at the old route, so the stream closes with:

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

No build error, no startup error — the service hosts happily on the new route while every existing caller misses it.

Why DTO members are the opposite

The request and reply bodies are the reassuring half of the story. protobuf-net does not serialize by member name; it serializes by the integer tag you declare in [ProtoMember(n)]. The name is purely for your C# code.

BEFORE[ProtoMember(1)] double Resultidentifier: Result · tag: 1AFTER RENAME[ProtoMember(1)] double aidentifier: a · tag: 1 (unchanged)WIRE BYTES (identical)field 1, type fixed64 → 09 ..tag = (1 << 3) | 1 = 0x09the field NUMBER is the contract;the member NAME is never sent
Protobuf identifies fields by tag number, so renaming Result to a leaves the wire bytes untouched — DTO members rename freely.

Because the wire key is 1, not Result, Nebula can rename the property to a, rename the DTO type MultiplyReply to anything (the type name is never transmitted either), and the bytes on the wire are byte-for-byte identical. The only rule is that the [ProtoMember] numbers must stay fixed — and they do, because they are integer literals inside an attribute, not identifiers. The same applies to enums, which travel as their numeric value.

So the contract surface you must protect is precisely: the service interface’s type name, its namespace, and its method names. Nothing else.

Pinning the wire names

There are two ways to keep the route stable. The first is a keep-list that tells Nebula not to rename the contract interfaces. The second, and the better one, is to state the wire names explicitly so the identifiers are free again.

With protobuf-net.Grpc you set them on the contract itself:

using ProtoBuf.Grpc.Configuration;

namespace Shop.Contracts;

[Service("shop.Calculator")]                 // wire service name is fixed here…
public interface ICalculator                 // …so this identifier may rename
{
    [Operation("Multiply")]                  // …and so may this one
    ValueTask<MultiplyReply> Multiply(MultiplyRequest request, CallContext ctx = default);
}

Now the binder reads shop.Calculator and Multiply straight from the attribute values and never looks at the metadata names, so the route is /shop.Calculator/Multiply no matter what the obfuscator calls the interface or the method. This is worth doing independent of obfuscation: it pins your public gRPC surface so a routine rename or a namespace move cannot shift it.

The keep-list in nebula.config.json

If you have not annotated the contract with explicit names, pin the derived names by keeping the contract interfaces. Everything else — the implementation, the DTOs, internal services — sweeps into renaming:

{
  "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" }
    ]
  }
}

The first rule matches the contract interfaces by the conventional I… prefix and keeps both the type names (so the namespace-plus-name service string is preserved) and their public method names, while members: "public" lets any non-public members inside the interface’s own scope still rename. The second rule renames everything else in Shop.Contracts — crucially the DTO types and their members, which are safe because they travel as numeric tags. The third rule renames the whole server assembly: CalculatorService, your validators, internal stores and DI registrations all get full renaming, control-flow obfuscation and string encryption. The implementation class name is never on the wire — binding happens through the interface — so it is free to go.

If you did annotate every contract with [Service]/[Operation], you can drop the keep rule entirely and let the interfaces rename too, because the wire names now live in attribute literals Nebula preserves. For the occasional single method that is an exception, an attribute on the exact member is more precise than a config pattern and lives next to the code:

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

Run the protection as part of the release build, against the published output:

nebula protect --config nebula.config.json

Nebula’s renaming, control-flow and string-encryption passes are available on the free tier for evaluation; the heavier protections such as method virtualization are part of Nebula Pro. See the Nebula docs for the full rule syntax, and /products/nebula for the tiers.

Caveats and when it breaks

The subtle failure mode is the one where it seems to work. If your client and server both reference the same obfuscated contract assembly, both derive the same renamed route and calls succeed in testing — then break the day a client is rebuilt from the original package, a non-.NET consumer calls in with grpcurl, or you obfuscate one side and not the other. The route is only stable because two builds happened to agree; that is not a contract. Pin the wire names with [Service]/[Operation] and the agreement becomes a guarantee.

Two more honest limits. First, reflection or server-reflection endpoints that advertise your service list will advertise the renamed names if you kept the derived naming — fine if you own both ends, surprising if a tool introspects you. Second, these rules cover the contract surface only; if you drive routing or serialization through any other string-keyed reflection in your own code, that string is load-bearing too and belongs on the keep-list.

The rule underneath all of it is the same one every reflection-driven framework obeys: a name is load-bearing exactly when something outside the CLR’s own token resolution reads it as a string. In code-first gRPC that set is small and knowable — the service interface’s type name, its namespace, and its method names — and the request and reply members are deliberately not in it, because protobuf keys them by number. Pin those few names, or state them outright with [Service] and [Operation], and Nebula renames the implementation, the DTO internals and the business logic freely, protecting your own shipped service without ever moving a route a client depends on.

Try Nebula.NET

Harden your .NET code in minutes — start with the free edition.