Ofuscar una tarea personalizada de MSBuild sin romperla
Una tarea personalizada de MSBuild es la imagen especular de un generador de código fuente. El compilador encuentra un generador por atributo, de modo que puedes renombrar toda la clase libremente; MSBuild encuentra una tarea por la cadena literal del nombre del tipo escrita en un elemento UsingTask, y lee sus parámetros a partir de los nombres de propiedades públicas, por lo que ambos son un contrato externo rígido que el renombrado no debe tocar. Este artículo examina qué refleja realmente el motor de MSBuild cuando ejecuta tu tarea, traza la línea exacta entre la pequeña superficie fijada y la lógica valiosa que se renombra sin problemas, y muestra la configuración de Nebula y la compilación de verificación que detecta el único modo de fallo que es silencioso.
Si alguna vez has ofuscado un generador de código fuente de Roslyn, conoces el final feliz: el compilador encuentra los generadores por el atributo [Generator], nunca por el nombre, así que puedes renombrar la clase, su espacio de nombres y cada ayudante sin nada especial que configurar. Una tarea personalizada de MSBuild es exactamente la imagen especular de eso, y vale la pena entender por qué antes de apuntar un ofuscador hacia ella, porque el fallo que produce es silencioso.
MSBuild no encuentra tu tarea por un atributo. La encuentra por una cadena con el nombre del tipo que alguien escribió en un elemento UsingTask, y establece las entradas de la tarea reflejando sobre los nombres de propiedades públicas que coinciden con atributos del archivo de compilación. Ambos son texto en un archivo .targets — el tuyo, o el del proyecto de tu consumidor — y el texto de un archivo de compilación no se reescribe cuando tu renombrador elige a para la clase y b para la propiedad. Renómbralos y la compilación no encuentra tu tarea, o la encuentra y descarta silenciosamente cada entrada. La buena noticia, exactamente igual que con un generador, es que la superficie fijada es pequeña y específica, y el código que de verdad te importa ocultar no está en ella.
Qué refleja el motor cuando ejecuta tu tarea
Aquí tienes una tarea mínima y real — la forma que distribuyes en un paquete NuGet de herramientas:
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;
}
}
Y así es como un consumidor la invoca — ya sea a través de tu build/Acme.Build.targets empaquetado, o escrito a mano en su propio proyecto:
<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>
Cuando MSBuild llega a ese target hace algo muy concreto. Carga Acme.Build.dll, llama a assembly.GetType("Acme.Build.ValidateManifest") usando la cadena exacta de TaskName, lo instancia con Activator.CreateInstance y luego — por cada atributo XML del elemento <ValidateManifest> — busca una propiedad pública asignable con el mismo nombre y le asigna el valor (convertido de tipo). Ejecuta Execute(). Después, por cada <Output> lee una propiedad pública de lectura por el nombre indicado en TaskParameter. Tres lugares distintos de esa secuencia consumen nombres como datos: el nombre del tipo, los nombres de las propiedades de entrada y los nombres de las propiedades de salida. Ninguno sobrevive a un renombrador que no sepa que son estructurales.
Qué está fijado, y por qué
El nombre del tipo de la tarea es una cadena en UsingTask
TaskName="Acme.Build.ValidateManifest" es un literal de cadena, y MSBuild lo resuelve con GetType. Si Nebula renombra la clase a Acme.Build.a, la llamada a GetType devuelve null y la compilación falla con “The ‘ValidateManifest’ task was not found.” Aquí hay una solución tentadora pero equivocada: como distribuyes el archivo .targets junto al DLL en tu propio paquete, podrías renombrar ambos de forma sincronizada y mantenerlos coherentes. Resístete. Los consumidores también escriben <UsingTask> a mano, los artículos citan el nombre de tu tarea y tu propia documentación lo deja fijo. El nombre público del tipo de la tarea es API. Fíjalo, y fija el espacio de nombres con él.
Los nombres de las propiedades públicas son el contrato de parámetros
ManifestPath, MaxEntries y Fingerprint no son propiedades corrientes — son los parámetros de la tarea, y MSBuild las vincula por nombre a atributos XML escritos en archivos de proyecto de consumidores que nunca verás. Es la misma situación que System.Text.Json vinculando por nombres de propiedad o Dapper mapeando columnas: los nombres de propiedades públicas son un contrato de cable, no un detalle de implementación. Renombra ManifestPath y el atributo ManifestPath="..." de la compilación se vincula silenciosamente a nada; tu comprobación [Required] lanza un confuso “required parameter not set” aunque el autor claramente lo haya establecido. Conserva cada propiedad pública asignable/legible que aparezca como parámetro de la tarea. Fíjate en la asimetría con el cuerpo de la clase: los nombres están fijados, pero los cuerpos de los métodos y cada miembro privado no.
La superficie de ITask
Execute es la implementación de la interfaz ITask.Execute (la obtienes a través de la clase base Task), así que el renombrado conserva automáticamente su ranura en la v-table — MSBuild lo llama a través de la interfaz, no por cadena. Las propiedades BuildEngine y HostObject son miembros de interfaz que el motor establece; se conservan por la misma razón. Las únicas reglas son las de siempre: no elimines la implementación de la interfaz, no cambies la firma y mantén público el constructor público sin parámetros (el motor llama a Activator.CreateInstance).
Un detalle fácil de pasar por alto: el código de diagnóstico "ACMEB001" es un contrato público. Los equipos lo buscan con grep, lo suprimen en CI y lo enrutan en analizadores de registros. El cifrado de cadenas está bien — el valor se reconstruye antes de que LogError lo emita — pero el valor de la cadena no debe alterarse.
Qué se renombra sin problemas
Todo lo que importa. ManifestInspector.Analyze, los tipos de modelo que devuelve, cada ayudante privado, el análisis sintáctico, el fingerprinting, el motor de reglas — nada de eso está nombrado en ningún archivo de compilación, así que todo se renombra, y es exactamente la lógica que merece la pena proteger. Una tarea suele ser una cáscara fina y amigable con la reflexión envolviendo un cuerpo de trabajo real; la cáscara está fijada y el trabajo es libre. Igual que con un generador, la gran mayoría del ensamblado se ofusca como cualquier otra biblioteca. Estás fijando una puerta, no una casa.
El matiz: tú posees los .targets, los consumidores poseen los atributos
Ayuda separar las dos fuentes de texto. La cadena del nombre de tipo en UsingTask suele vivir en tus build/*.targets empaquetados, así que en principio está bajo tu control. Los atributos con nombres de propiedad (ManifestPath="...") viven en el proyecto del consumidor y en tu documentación pública — totalmente fuera de tu control. Eso significa que aunque estuvieras dispuesto a renombrar de forma sincronizada la única cadena que posees, aún no puedes tocar los nombres de las propiedades, que de todos modos son la mayor parte de la superficie fijada. El modelo honesto es: trata toda la superficie de la tarea con nombre externo como API pública, fíjala en la configuración y deja el cuerpo al renombrador.
La configuración de Nebula
En términos de Nebula esto es un perfil de biblioteca que fija la superficie con nombre externo de la tarea y deja ir todo lo demás:
{
"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*" ] }
}
Conservar toda la superficie pública del tipo de la tarea — en lugar de enumerar cada propiedad — es deliberado: es robusto frente a que alguien añada un parámetro más adelante y olvide actualizar la lista keep, que es la causa clásica de un parámetro que deja de vincularse silenciosamente tras una refactorización. autoDetect ya protege la implementación de ITask; la entrada explícita preserve es por redundancia. Excluir Execute del aplanamiento de flujo de control es una menor elección de rendimiento (la tarea puede ejecutarse en cada compilación incremental) y no cuesta protección, porque Execute es un despachador fino — el trabajo real está en ManifestInspector, que permanece totalmente transformado.
Ejecútalo como parte de tu pipeline de empaquetado:
nebula protect --config nebula.json --in bin/Release/Acme.Build.dll --out dist/Acme.Build.dll
Verifica con una compilación real, no con una carga
El modo de fallo aquí es silencioso, así que verificar cargando el DLL no prueba nada. Tienes que ejecutar MSBuild contra el ensamblado ofuscado y comprobar el comportamiento:
# point a throwaway project's UsingTask at dist/Acme.Build.dll
dotnet build tests/TaskHarness/TaskHarness.csproj -t:CheckManifest -v:normal
Tres cosas deben cumplirse: la tarea se resuelve (sin “task was not found”), las entradas se vinculan (un manifiesto deliberadamente malo produce ACMEB001, demostrando que ManifestPath y MaxEntries llegaron) y el [Output] regresa ($(ManifestHash) no está vacío aguas abajo). Si un parámetro quedó sin vincular verás una ejecución con valores por defecto en lugar de un fallo — que es exactamente por lo que el harness comprueba los valores producidos, no solo el código de salida.
La conclusión
Una tarea personalizada de MSBuild es la imagen especular del generador: el compilador encuentra un generador por atributo y te deja renombrar todo, mientras que MSBuild encuentra una tarea por una cadena literal del nombre del tipo y vincula sus parámetros por nombre de propiedad pública, lo que convierte a ambos en un contrato externo rígido. Fija la superficie pública del tipo de la tarea — el nombre del tipo y cada propiedad que aparezca como parámetro de la tarea — conserva la ranura ITask/Execute y el constructor público, y deja intactos los valores de las cadenas de códigos de diagnóstico. Luego deja que Nebula renombre y transforme todo el cuerpo, que es donde vive tu verdadera lógica de herramientas. Verifica ejecutando un target real contra el DLL ofuscado y comprobando las entradas y salidas vinculadas, porque la única manera en que esto se rompe es en silencio.
Prueba Nebula.NET
Endurece tu código .NET en minutos — empieza con la edición gratuita.