Obfusquer des grains Orleans sans casser le routage du cluster
Orleans route chaque appel de grain via des chaînes du manifeste du cluster : un GrainInterfaceType et un GrainType dérivés par défaut des noms de vos types .NET. Renommez un grain et l'identité se déplace, orphelinant l'état persisté et cassant les appels inter-silos. Voici comment découpler l'identité avec [Alias]/[GrainType] tout en obfusquant agressivement.
Une application Orleans est un candidat solide à l’obfuscation et facile à casser. Les grains sont le produit — les acteurs à état qui contiennent votre logique de tarification, de règlement, de mise en correspondance ou de détection de fraude et s’exécutent sans interface sur un serveur que vous ne contrôlez peut-être pas — et la quasi-totalité de ce code peut être renommée, chiffrée dans les chaînes et virtualisée librement. Mais Orleans comporte une couture dans laquelle une passe naïve tombe de plein fouet, et le mode de défaillance est du genre silencieux : le cluster démarre, un client se connecte, un appel est distribué, et le grain qui l’a traité hier n’est soudain plus enregistré, ou son état persisté a disparu. Rien dans votre propre code n’a levé d’exception ; Orleans n’a simplement pas trouvé ce que vous avez renommé.
La cause est spécifique à la manière dont Orleans décide ce qu’est un grain, et une fois que vous la voyez, la solution tient en une poignée d’attributs. Cet article traite de ce mécanisme — comment Orleans dérive l’identité d’un grain de son type, où ces identités voyagent, et comment protéger l’intérieur précieux avec Nebula.NET tout en laissant les identités exactement là où le cluster les attend.
En bref
- Orleans route par des chaînes du manifeste du cluster, pas par l’identité du type .NET : un
GrainInterfaceType(quelle interface) et unGrainType(quelle classe de grain), tous deux dérivés par défaut des noms de vos types. - Un
GrainIdcommence par leGrainType, donc il indexe l’état persisté et les reminders. Changez leGrainTypeet cet état devient orphelin. - La sérialisation est numérique — le sérialiseur moderne encode les champs par leur balise
[Id(n)], donc renommer les champs est sûr. Seule l’identité du type (son[Alias]ou son nom complet) dépend du nom. - La solution robuste consiste à découpler l’identité du symbole : figez
[GrainType],[GrainInterfaceType]et[Alias]vers des chaînes fixes, puis renommez les types librement. - Tout ce qui se trouve derrière le grain — services, auxiliaires, algorithmes — est renommé, chiffré et virtualisé sans rien à conserver.
Pourquoi obfusquer une application Orleans
Les classes de grain sont là où vit votre propriété intellectuelle : la méthode qui note une transaction, la machine à états qui règle une opération, l’acteur qui recalcule un prix quand le marché bouge. Ce code est déployé sous forme de DLL sur un hôte de silo — souvent un que votre client exploite — et quiconque a accès au fichier peut l’ouvrir dans un décompilateur et le relire sous forme de C# propre. La couche des grains est aussi là où se concentrent les constantes sensibles : URL d’endpoints internes, identifiants de partenaires, matériel de signature, noms de fournisseurs. Augmenter le coût de relecture de votre propre logique déployée depuis ce binaire est exactement le cas légitime de l’obfuscation.
Comment Orleans construit l’identité d’un grain
Voici une interface de grain ordinaire, son implémentation et un type d’état sérialisable, chacun annoté à la manière moderne d’Orleans :
namespace Contoso.Trading.Abstractions;
public interface IOrderGrain : IGrainWithStringKey
{
Task<decimal> Settle(decimal amount);
}
namespace Contoso.Trading.Grains;
public sealed class OrderGrain : Grain, IOrderGrain
{
private readonly IPersistentState<OrderState> _state;
public OrderGrain([PersistentState("order")] IPersistentState<OrderState> state)
=> _state = state;
public async Task<decimal> Settle(decimal amount)
{
// propriétaire — la raison d'être de ce grain
var net = _state.State.ApplySettlement(amount);
await _state.WriteStateAsync();
return net;
}
}
[GenerateSerializer]
public sealed class OrderState
{
[Id(0)] public decimal Balance { get; set; }
[Id(1)] public int Version { get; set; }
public decimal ApplySettlement(decimal amount) { /* ... */ return Balance; }
}
Un appelant résout le grain par interface et l’invoque :
var grain = client.GetGrain<IOrderGrain>("order-7b1e");
var net = await grain.Settle(149.95m);
Rien dans cet appel ne nomme un silo, une adresse ou une clé de routage. Orleans déduit tout de l’identité du type exprimée sous forme de chaînes. Deux chaînes, précisément, calculées à partir de vos types et publiées dans le manifeste du cluster que partagent tous les silos et clients :
- Un
GrainInterfaceTypepourIOrderGrain— dérivé par défaut du nom de l’interface ("ordergrain"plus la désambiguïsation de l’espace de noms). Il indique au cluster quel contrat un appel cible, et c’est ainsi que la référence de grain générée d’un client est mise en correspondance avec une implémentation quelque part dans le cluster. - Un
GrainTypepourOrderGrain— dérivé par défaut du nom de la classe ("ordergrain"). Il nomme quelle classe de grain doit être activée pour traiter l’appel, et il gouverne le placement.
L’appel lui-même devient un message portant le GrainInterfaceType, un identifiant de méthode et un GrainId cible. Et le GrainId est le discret : c’est GrainType + / + votre clé —
ordergrain/order-7b1e
— donc la chaîne GrainType est littéralement le préfixe de l’identité sous laquelle Orleans place l’activation, stocke [PersistentState] et enregistre les reminders. Le fournisseur de stockage écrit OrderState sous une clé construite à partir de ce GrainId. Changez le GrainType et chaque ligne écrite précédemment pointe vers un grain que le cluster ne connaît plus.
Ce qui ne dépend pas du nom : la sérialisation
Un soulagement se cache dans OrderState. Le sérialiseur moderne d’Orleans est numérique : le générateur de code émet un sérialiseur qui lit et écrit le champ 0, le champ 1, etc., indexé par la balise [Id(n)] — jamais par le nom du champ. Après obfuscation, le symbole du champ Balance et le sérialiseur généré qui le référence sont renommés ensemble, au sein du même assembly, et les octets filaires restent numérotés. Ainsi, renommer les propriétés d’un type [GenerateSerializer] est tout à fait sûr, tant que les balises [Id(n)] demeurent. La seule partie dépendant du nom est la référence de type que le sérialiseur écrit pour que le destinataire sache quoi construire — et celle-ci utilise l’[Alias] du type ou, à défaut, son nom complet.
La solution robuste : découpler l’identité du symbole
L’instinct naïf est de placer dans la keep-list chaque type de grain et sérialisable. Cela fonctionne, mais laisse lisibles les classes les plus précieuses de votre assembly. Le meilleur mouvement est de rendre l’identité d’Orleans indépendante du nom du type .NET, afin que le symbole soit libre d’être détruit tandis que le manifeste continue d’annoncer une chaîne fixe. Trois attributs y parviennent :
namespace Contoso.Trading.Abstractions;
[GrainInterfaceType("order")] // fige l'identité de l'interface
public interface IOrderGrain : IGrainWithStringKey
{
[Alias("settle")] // fige l'identité de la méthode
Task<decimal> Settle(decimal amount);
}
[GrainType("order")] // fige l'identité du grain + préfixe du GrainId
public sealed class OrderGrain : Grain, IOrderGrain { /* ... */ }
[GenerateSerializer, Alias("order-state")] // fige l'identité du type sérialisé
public sealed class OrderState
{
[Id(0)] public decimal Balance { get; set; }
[Id(1)] public int Version { get; set; }
}
Une fois cela en place, le cluster annonce "order", met en correspondance les appels sur "order", construit les GrainId commençant par "order" et écrit l’état sous "order" — tout cela indépendamment de la manière dont les classes sont nommées. Nebula.NET est désormais libre de renommer OrderGrain en a, IOrderGrain en b, Settle en c et OrderState en d, et rien sur le fil ni dans le stockage ne bouge.
Note de migration : figez chaque identité à la valeur par défaut actuelle d’abord — la chaîne que la compilation non obfusquée annonçait déjà — afin que les
GrainId, reminders et état persisté existants se résolvent sans changement. Ce n’est qu’après avoir confirmé que rien n’a bougé que vous devriez obfusquer. Figer vers une nouvelle chaîne est une migration de données, pas une étape d’obfuscation.
La keep-list (quand vous ne pouvez pas ajouter d’attributs)
Si vous obfusquez un assembly de grains dont vous ne possédez pas le code source, ou si vous ne pouvez tout simplement pas toucher les types, repliez-vous sur la conservation des identités par nom. Modélisez les interfaces de grain sous un seul espace de noms et nebula.config.json se lit ainsi :
{
"schemaVersion": 1,
"inputs": [
"publish/Contoso.Trading.Grains.dll",
"publish/Contoso.Trading.Abstractions.dll"
],
"outputDirectory": "protected",
"preservePublicApi": false,
"encryptStrings": true,
"controlFlowObfuscation": true,
"renaming": {
"rules": [
{ "pattern": "Contoso.Trading.Abstractions.*", "action": "keep", "scope": "type-and-members" },
{ "pattern": "*State", "action": "keep", "scope": "type" },
{ "pattern": "Contoso.Trading.*", "action": "rename" }
]
}
}
La première règle fige chaque interface de grain et ses méthodes (le nom de la méthode alimente l’identité de la méthode). La seconde conserve les types d’état sérialisables par nom afin que leur référence de type par défaut survive — un substitut plus grossier d’[Alias]. Tout le reste — classes de grain, services, auxiliaires — est renommé. Le chiffrement des chaînes et l’obfuscation du flux de contrôle s’appliquent partout, y compris aux types conservés, car ni l’un ni l’autre ne touche aux noms. Cela protège moins que l’approche par attributs, car les noms des classes de grain fuitent ; préférez les attributs chaque fois que vous pouvez éditer le code.
L’audit : ce qui bouge, ce qui ne bouge pas
Parcourez chaque identité qui quitte l’assembly, et le plan s’écrit tout seul.
- Types d’interface de grain et leurs méthodes — construisent le
GrainInterfaceTypeet les identités de méthode qu’un client et chaque silo mettent en correspondance. Figez avec[GrainInterfaceType]+[Alias], ou conservez par nom. - Classes de grain — construisent le
GrainType, qui préfixe chaqueGrainIdet indexe l’état persisté et les reminders. Figez avec[GrainType], ou conservez par nom. - Types
[GenerateSerializer]— identifiés sur le fil par alias ou nom complet ; les champs identifiés par[Id(n)], pas par nom. Figez le type avec[Alias]et conservez les balises[Id]; les champs se renomment librement. - Intérieurs des classes de grain — le corps de
Settle, les auxiliaires privés, les services qu’il invoque. Résolus au sein du processus par l’injection de dépendances et l’identité de type ; rien sur le fil ne les nomme. Renommez, chiffrez, virtualisez. - Noms de fournisseurs et de stockage —
"order"dans[PersistentState("order")], espaces de noms de streams, littéraux de chaîne. Des données que vous reproduisez à l’exécution ; le chiffrement des chaînes laisse intacte la valeur d’exécution. Aucune action requise.
Une seule surface à figer, donc — les identités du grain et de l’interface — et tout l’intérieur est terrain libre.
Protéger l’intérieur
Figer une identité ne signifie pas laisser quoi que ce soit de lisible. Les chaînes du manifeste restent stables tandis que tout ce qui se trouve derrière le grain s’obscurcit. Le chiffrement des chaînes masque les URL internes, les identifiants et les noms de fournisseur que la couche des grains accumule. Les transformations les plus fortes — virtualisation de code et chiffrement de méthode complète, toutes deux des fonctionnalités Pro dans Nebula.NET — s’appliquent aux joyaux de la couronne : les méthodes de règlement, de notation ou de tarification, appliquées à cette poignée de méthodes plutôt qu’à tout l’assembly :
[GrainType("order")]
public sealed class OrderGrain : Grain, IOrderGrain
{
[Obfuscation(Feature = "virtualization")] // Pro — l'algorithme, pas la tuyauterie
public async Task<decimal> Settle(decimal amount) { /* ... */ return 0m; }
}
Le renommage et l’obfuscation du flux de contrôle s’exécutent largement en dessous, transformant le reste des intérieurs des grains en symboles dénués de sens et en branches enchevêtrées tandis que l’identité par laquelle le cluster route reste exactement où elle était.
Intégrer la protection dans la compilation
Protégez la sortie publiée, et uniquement sur le serveur de compilation pour que le débogage local reste rapide et lisible :
dotnet publish Contoso.Trading.Silo -c Release -o publish
nebula protect --config nebula.config.json
<Target Name="NebulaProtect" AfterTargets="Publish"
Condition="'$(CI)' == 'true'">
<Exec Command="nebula protect --config nebula.config.json" />
</Target>
Distribuez le dossier protected/, pas le dossier de publication brut. nebula protect renvoie un code de sortie non nul en cas d’échec, de sorte qu’une étape de protection cassée fait échouer la compilation au lieu de distribuer un silo qui a renommé un grain par lequel le reste du cluster route encore.
Vérifier que cela fonctionne vraiment
Les tests unitaires ne détecteront pas ceci : un TestCluster qui construit des grains dans un seul processus à partir du même binaire voit des identités cohérentes et passe même lorsque l’identité se déplacerait à travers un déploiement réel et hétérogène. Deux vérifications le détectent. D’abord, exécutez-le contre un cluster multi-silos construit à partir des DLL protégés, idéalement avec un silo encore sur la compilation précédente pour imiter une mise à jour progressive, et confirmez qu’un appel client se place et qu’un grain s’active. Un appel qui ne trouve pas de type de grain enregistré, ou un grain dont l’état persisté précédemment revient vide, est la signature exacte d’une identité déplacée — comparez le GrainType/GrainInterfaceType qu’annonce le manifeste à ce qu’attend l’autre silo.
Ensuite, ouvrez l’assembly distribué dans un décompilateur et lisez-le comme le fera un attaquant. Glass.NET est le compagnon gratuit, exclusivement statique, pour cette passe : chargez le DLL protégé, confirmez que les chaînes [GrainType("order")], [GrainInterfaceType("order")] et [Alias] sont toujours présentes — elles doivent l’être, pour correspondre au manifeste — puis confirmez qu’il ne reste rien à lire dans l’OrderGrain renommé ni dans les services qu’il invoque.
À retenir
Orleans identifie un grain par des chaînes — un GrainInterfaceType et un GrainType, dérivés par défaut des noms de vos types .NET, publiés dans le manifeste du cluster et mis en correspondance entre silos et clients. Le GrainType préfixe aussi chaque GrainId, donc il indexe l’état persisté et les reminders. Renommez un grain et l’identité se déplace sur un silo fraîchement compilé : l’appel ne peut être placé et l’ancien état devient orphelin, sans que rien dans votre code ne lève d’exception. La sérialisation, heureusement, est numérique — des balises [Id(n)], pas des noms de champ — donc renommer les champs est sûr. Figez les identités avec [GrainType], [GrainInterfaceType] et [Alias] aux valeurs que la compilation non obfusquée annonçait déjà, et le symbole est libre d’être détruit : confiez tout l’intérieur du grain à Nebula.NET pour renommer, chiffrer les chaînes et virtualiser, puis montez un cluster multi-silos protégé, observez le bon grain s’activer, et lisez le DLL distribué pour confirmer que la logique qui se trouvait derrière a disparu.
Essayez Nebula.NET
Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.