Obfusquer une tâche MSBuild personnalisée sans la casser
Une tâche MSBuild personnalisée est l'image miroir d'un générateur de code source. Le compilateur trouve un générateur par attribut, vous pouvez donc renommer toute la classe librement ; MSBuild trouve une tâche par la chaîne littérale du nom de type écrite dans un élément UsingTask, et lit ses paramètres à partir des noms de propriétés publiques, si bien que les deux forment un contrat externe rigide que le renommage ne doit pas toucher. Cet article examine ce que le moteur MSBuild réfléchit réellement lorsqu'il exécute votre tâche, trace la ligne exacte entre la petite surface figée et la logique précieuse qui se renomme sans encombre, et montre la configuration de Nebula ainsi que la compilation de vérification qui détecte le seul mode de défaillance qui soit silencieux.
Si vous avez déjà obscurci un générateur de code source Roslyn, vous connaissez la fin heureuse : le compilateur trouve les générateurs par l’attribut [Generator], jamais par le nom, vous pouvez donc renommer la classe, son espace de noms et chaque aide sans rien de particulier à configurer. Une tâche MSBuild personnalisée est exactement l’image miroir de cela, et il vaut la peine de comprendre pourquoi avant de pointer un obscurcisseur dessus, car la défaillance qu’elle produit est silencieuse.
MSBuild ne trouve pas votre tâche par un attribut. Il la trouve par une chaîne contenant le nom du type que quelqu’un a écrite dans un élément UsingTask, et il définit les entrées de la tâche en réfléchissant sur les noms de propriétés publiques correspondant aux attributs du fichier de build. Les deux sont du texte dans un fichier .targets — le vôtre, ou celui du projet de votre consommateur — et le texte d’un fichier de build n’est pas réécrit quand votre renommeur choisit a pour la classe et b pour la propriété. Renommez-les et la build ne trouve pas votre tâche, ou la trouve et abandonne silencieusement chaque entrée. La bonne nouvelle, exactement comme avec un générateur, c’est que la surface figée est petite et précise, et que le code qui vous importe vraiment de cacher n’en fait pas partie.
Ce sur quoi le moteur réfléchit lorsqu’il exécute votre tâche
Voici une tâche minimale et réelle — la forme que vous distribuez dans un paquet NuGet d’outillage :
using Microsoft.Build.Framework;
using Microsoft.Build.Utilities;
namespace Acme.Build;
public sealed class ValidateManifest : Task // Task : ITask
{
[Required]
public string ManifestPath { get; set; } = "";
public int MaxEntries { get; set; } = 1000;
[Output]
public string Fingerprint { get; set; } = "";
public override bool Execute()
{
var report = ManifestInspector.Analyze(ManifestPath, MaxEntries); // the valuable part
Fingerprint = report.Fingerprint;
if (report.HasErrors)
Log.LogError("ACMEB001: manifest failed validation: {0}", report.Summary);
return !Log.HasLoggedErrors;
}
}
Et voici comment un consommateur l’invoque — soit via votre build/Acme.Build.targets empaqueté, soit écrit à la main dans son propre projet :
<UsingTask TaskName="Acme.Build.ValidateManifest"
AssemblyFile="$(MSBuildThisFileDirectory)..\tasks\Acme.Build.dll" />
<Target Name="CheckManifest" BeforeTargets="Build">
<ValidateManifest ManifestPath="$(ManifestFile)" MaxEntries="500">
<Output TaskParameter="Fingerprint" PropertyName="ManifestHash" />
</ValidateManifest>
</Target>
Lorsque MSBuild atteint cette cible, il fait quelque chose de très précis. Il charge Acme.Build.dll, appelle assembly.GetType("Acme.Build.ValidateManifest") en utilisant la chaîne exacte de TaskName, l’instancie avec Activator.CreateInstance, puis — pour chaque attribut XML de l’élément <ValidateManifest> — il recherche une propriété publique assignable du même nom et lui affecte la valeur (convertie de type). Il exécute Execute(). Ensuite, pour chaque <Output>, il lit une propriété publique en lecture par le nom indiqué dans TaskParameter. Trois endroits distincts de cette séquence consomment des noms comme données : le nom du type, les noms des propriétés d’entrée et les noms des propriétés de sortie. Aucun ne survit à un renommeur qui ne sait pas qu’ils sont porteurs.
Ce qui est figé, et pourquoi
Le nom du type de la tâche est une chaîne dans UsingTask
TaskName="Acme.Build.ValidateManifest" est une chaîne littérale, et MSBuild la résout avec GetType. Si Nebula renomme la classe en Acme.Build.a, l’appel à GetType renvoie null et la build échoue avec “The ‘ValidateManifest’ task was not found.” Il y a ici une solution tentante mais erronée : puisque vous distribuez le fichier .targets à côté du DLL dans votre propre paquet, vous pourriez renommer les deux de façon synchronisée et les garder cohérents. Résistez-y. Les consommateurs écrivent aussi <UsingTask> à la main, les articles de blog citent le nom de votre tâche et votre propre documentation le fige. Le nom public du type de la tâche est une API. Figez-le, et figez l’espace de noms avec lui.
Les noms des propriétés publiques sont le contrat des paramètres
ManifestPath, MaxEntries et Fingerprint ne sont pas des propriétés ordinaires — ce sont les paramètres de la tâche, et MSBuild les lie par nom à des attributs XML écrits dans des fichiers de projet de consommateurs que vous ne verrez jamais. C’est la même situation que System.Text.Json liant par noms de propriété ou Dapper mappant des colonnes : les noms de propriétés publiques sont un contrat de câble, pas un détail d’implémentation. Renommez ManifestPath et l’attribut ManifestPath="..." de la build se lie silencieusement à rien ; votre vérification [Required] lève un déroutant “required parameter not set” alors que l’auteur l’a clairement défini. Conservez chaque propriété publique assignable/lisible qui apparaît comme paramètre de la tâche. Notez l’asymétrie avec le corps de la classe : les noms sont figés, mais les corps des méthodes et chaque membre privé ne le sont pas.
La surface d’ITask
Execute est l’implémentation de l’interface ITask.Execute (vous l’obtenez via la classe de base Task), donc le renommage préserve automatiquement son emplacement dans la v-table — MSBuild l’appelle via l’interface, pas par chaîne. Les propriétés BuildEngine et HostObject sont des membres d’interface définis par le moteur ; elles sont préservées pour la même raison. Les seules règles sont les habituelles : ne supprimez pas l’implémentation de l’interface, ne changez pas la signature et gardez public le constructeur public sans paramètre (le moteur appelle Activator.CreateInstance).
Un détail facile à manquer : le code de diagnostic "ACMEB001" est un contrat public. Les équipes le cherchent avec grep, le suppriment en CI et l’aiguillent dans des analyseurs de journaux. Le chiffrement des chaînes convient — la valeur est reconstruite avant que LogError ne l’émette — mais la valeur de la chaîne ne doit pas être altérée.
Ce qui se renomme sans encombre
Tout ce qui compte. ManifestInspector.Analyze, les types de modèle qu’il renvoie, chaque aide privée, l’analyse syntaxique, le fingerprinting, le moteur de règles — rien de cela n’est nommé dans un fichier de build, donc tout se renomme, et c’est exactement la logique qui mérite d’être protégée. Une tâche est généralement une coquille fine et amie de la réflexion enveloppant un corps de travail réel ; la coquille est figée et le travail est libre. Comme avec un générateur, la grande majorité de l’assembly s’obscurcit comme n’importe quelle autre bibliothèque. Vous figez une porte, pas une maison.
La subtilité : vous possédez les .targets, les consommateurs possèdent les attributs
Il est utile de séparer les deux sources de texte. La chaîne du nom de type dans UsingTask vit généralement dans vos build/*.targets empaquetés, elle est donc en principe sous votre contrôle. Les attributs avec noms de propriété (ManifestPath="...") vivent dans le projet du consommateur et dans votre documentation publique — entièrement hors de votre contrôle. Cela signifie que même si vous étiez prêt à renommer de façon synchronisée la seule chaîne que vous possédez, vous ne pourriez toujours pas toucher aux noms des propriétés, qui constituent de toute façon l’essentiel de la surface figée. Le modèle honnête est : traitez toute la surface de la tâche portant un nom externe comme une API publique, figez-la dans la configuration et laissez le corps au renommeur.
La configuration de Nebula
En termes de Nebula, c’est un profil de bibliothèque qui fige la surface à nom externe de la tâche et laisse filer tout le reste :
{
"rename": {
"enabled": true,
"autoDetect": true,
"keep": [
{
"type": "Acme.Build.ValidateManifest",
"members": "public",
"reason": "MSBuild GetType()s this exact name from UsingTask and binds task parameters to its public property names"
}
]
},
"strings": { "encrypt": true },
"preserve": [
{ "interfaceImpl": "Microsoft.Build.Framework.ITask" }
],
"controlFlow": { "enabled": true, "exclude": [ "*ValidateManifest.Execute*" ] }
}
Conserver toute la surface publique du type de la tâche — plutôt que d’énumérer chaque propriété — est délibéré : c’est robuste au cas où quelqu’un ajouterait un paramètre plus tard en oubliant de mettre à jour la liste keep, ce qui est la cause classique d’un paramètre qui cesse silencieusement de se lier après un refactoring. autoDetect protège déjà l’implémentation d’ITask ; l’entrée explicite preserve est une ceinture et des bretelles. Exclure Execute de l’aplatissement de flux de contrôle est un choix de performance mineur (la tâche peut s’exécuter à chaque build incrémentale) et ne coûte aucune protection, car Execute est un répartiteur fin — le vrai travail est dans ManifestInspector, qui reste entièrement transformé.
Exécutez-le dans le cadre de votre pipeline d’empaquetage :
nebula protect --config nebula.json --in bin/Release/Acme.Build.dll --out dist/Acme.Build.dll
Vérifiez avec une vraie build, pas avec un chargement
Le mode de défaillance ici est silencieux, donc vérifier en chargeant le DLL ne prouve rien. Vous devez exécuter MSBuild contre l’assembly obscurci et faire des assertions sur le comportement :
# point a throwaway project's UsingTask at dist/Acme.Build.dll
dotnet build tests/TaskHarness/TaskHarness.csproj -t:CheckManifest -v:normal
Trois choses doivent tenir : la tâche se résout (pas de “task was not found”), les entrées se lient (un manifeste délibérément mauvais produit ACMEB001, prouvant que ManifestPath et MaxEntries sont arrivés) et le [Output] revient ($(ManifestHash) n’est pas vide en aval). Si un paramètre est resté non lié, vous verrez une exécution à valeurs par défaut plutôt qu’un plantage — c’est précisément pourquoi le harnais fait des assertions sur les valeurs produites, pas seulement sur le code de sortie.
À retenir
Une tâche MSBuild personnalisée est l’image miroir du générateur : le compilateur trouve un générateur par attribut et vous laisse tout renommer, tandis que MSBuild trouve une tâche par une chaîne littérale du nom de type et lie ses paramètres par nom de propriété publique, ce qui fait des deux un contrat externe rigide. Figez la surface publique du type de la tâche — le nom du type et chaque propriété qui apparaît comme paramètre de la tâche — conservez l’emplacement ITask/Execute et le constructeur public, et laissez intactes les valeurs des chaînes de codes de diagnostic. Laissez ensuite Nebula renommer et transformer tout le corps, là où vit votre véritable logique d’outillage. Vérifiez en exécutant une vraie cible contre le DLL obscurci et en faisant des assertions sur les entrées et sorties liées, car la seule manière dont cela casse est en silence.
Essayez Nebula.NET
Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.