Skip to Content
Nueva versión 12 disponible 🎉

Reglas XML

Además de las opciones que se indican en la línea de comandos o en la tarea Babel de MSBuild, Babel Obfuscator se puede controlar y configurar mediante reglas definidas en archivos XML externos. Estas reglas XML ofrecen un control detallado del proceso de ofuscación y permiten dirigirse a ensamblados, tipos, métodos y otros elementos de código concretos.

Archivos de reglas

Los archivos de reglas de Babel son documentos XML que contienen la información de configuración con la que se personaliza y se controla el proceso de ofuscación. Con estos archivos puede definir con precisión qué funciones de ofuscación se aplican a cada parte del código, lo que le da un control detallado sobre la protección de sus ensamblados.

XML
<Rules xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Rule name="rule 1" feature="default" exclude="false"> </Rule> <Rule name="rule 2" feature="control flow" exclude="true"> </Rule> </Rules>

El elemento Rules puede definir un atributo targetAssembly que limita el ámbito de las reglas que contiene a un ensamblado concreto. Si no se especifica el atributo targetAssembly, las reglas se aplican a todos los ensamblados que se procesan. Ejemplo:

XML
<Rules xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" targetAssembly="ACME.Data">

En el archivo de reglas XML, las reglas se procesan de forma secuencial, de arriba abajo, en el orden en que aparecen. Este procesamiento secuencial permite anular una regla existente con reglas más específicas situadas después, lo que da una estructura de reglas flexible y jerárquica.

Elemento Rules

El elemento Rules es el contenedor raíz que define el conjunto de reglas que se aplican al ensamblado de destino. Este elemento puede contener varios elementos hijos Rule, cada uno de los cuales especifica un comportamiento de ofuscación distinto.

AtributoDescripción
targetAssemblyEspecifica el nombre completo del ensamblado al que se aplican las reglas. Si no se define, las reglas se aplican a todos los ensamblados que intervienen en el proceso de ofuscación.

Elemento Rule

El elemento Rule define una regla de ofuscación de Babel que puede dirigirse a una o varias funciones de Babel Obfuscator. Cada regla especifica a qué elementos de código afecta y cómo se les aplican las funciones de ofuscación.

AtributoDescripción
nameNombre descriptivo de la regla, que ayuda a identificar su finalidad
featureNombre de la función del ofuscador, o lista de nombres de funciones separados por comas, a la que se dirige la regla. Se pueden indicar varias funciones para aplicar la misma regla a distintos aspectos de la ofuscación
excludeValor booleano que indica si la regla impide que se ejecuten las funciones especificadas. Establezca «true» para excluir símbolos de la ofuscación o «false» para incluirlos de forma explícita
applyToMembersValor booleano que indica si la regla se aplica a todos los miembros de un símbolo que cumple los criterios de la regla. Cuando está activado, la regla se propaga a los miembros anidados
lockedValor booleano que indica si la regla es inmutable y no pueden anularla las reglas posteriores en el orden de procesamiento

El atributo feature define la función del ofuscador sobre la que actúa la regla. Los atributos name y exclude son obligatorios, mientras que el atributo feature es opcional. Si no se especifica, la función toma el valor «default», que se refiere a la función de renombrado.

Las funciones del ofuscador son cadenas predefinidas que corresponden a capacidades de ofuscación concretas. Todos los nombres de funciones admitidos figuran en las tablas siguientes.

Tabla de funciones

Las funciones siguientes pueden dirigirse a todos los tipos de símbolos definidos en un ensamblado, incluidos tipos, métodos, propiedades, campos y eventos:

FunciónDescripción
allSe dirige a todas las funciones de ofuscación disponibles
defaultLa función predeterminada se refiere a la ofuscación por renombrado de símbolos
agentSe dirige a la funcionalidad del agente de ofuscación
cleanup attributesElimina los atributos no deseados de los metadatos del ensamblado
control flowAplica la ofuscación del flujo de control para que la lógica del código sea más difícil de entender
dead codeActiva la optimización de eliminación de código muerto
dynamic proxySustituye las llamadas directas a métodos por llamadas mediante proxy dinámico
embedIncrusta los ensamblados dependientes en el ensamblado de destino
mergeCombina varios ensamblados en un único ensamblado
msil encryptionCifra los cuerpos de los métodos mediante el cifrado de código MSIL (Microsoft Intermediate Language)
renamingOfusca los nombres de los miembros (tipos, métodos, propiedades, campos, eventos)
renaming blobRenombra los literales de cadena que corresponden a símbolos renombrados, de modo que el código siga funcionando
resource encryptionCifra los recursos incrustados en el ensamblado
string encryptionCifra los literales de cadena en línea del código
value encryptionCifra los valores constantes en línea y las inicializaciones de matrices
inlineIntegra en línea las llamadas a métodos para que la estructura del código sea menos visible
instrumentationActiva la instrumentación del código para la supervisión y el análisis
optimizationsAplica varias optimizaciones de metadatos y de código
xamlGestiona el renombrado de los símbolos a los que hacen referencia los recursos XAML o BAML

Las funciones de ofuscación siguientes son específicas de los métodos y solo se pueden aplicar a símbolos de método:

FunciónDescripción
msil encryption get streamDeclara el método con el que se obtiene la secuencia de origen del código cifrado para el descifrado MSIL
string encryption encrypt methodDefine el método personalizado con el que se cifran los literales de cadena
string encryption decrypt methodDefine el método personalizado con el que se descifran los literales de cadena en tiempo de ejecución
instrumentation on entry methodDefine el método al que se llama al entrar en un método instrumentado
instrumentation on exit methodDefine el método al que se llama al salir de un método instrumentado
instrumentation on exception methodDefine el método al que se llama cuando se produce una excepción en un método instrumentado
module initializerDesigna un método que se ejecuta automáticamente cuando el entorno de ejecución inicializa el módulo

Cualquier elemento Rule puede contener elementos hijos como Access, Target, Pattern, HasAttribute, Properties y Description. El elemento Pattern es obligatorio y todos los demás son opcionales. Estos elementos hijos aportan a la regla más posibilidades de filtrado y configuración. Ejemplo:

<Rule name="DataWriter" feature="msil encryption" exclude="false"> <Target>Methods</Target> <Pattern>SQLUtils.DataWriter::*</Pattern> <Properties> <Cache>true</Cache> <MinInstructionCount>6</MinInstructionCount> </Properties> <Description>Encrypt all methods of the DataWriter class.</Description> </Rule>

A continuación figura la lista completa de los elementos hijos posibles de Rule:

Elemento
Access
Targets
Pattern
HasAttribute
HasBase
Implements
Namespace
Properties
Description

Elemento Access

Restringe el ámbito de la regla a los símbolos que tienen los modificadores de visibilidad especificados. Los valores posibles son All o cualquier combinación de Public, Protected, Internal, Private, FamilyAndAssembly y FamilyOrAssembly. Si este elemento no está presente, se usa el valor predeterminado All, es decir, la regla se aplica a los símbolos de cualquier visibilidad.

AccesoDescripción
PublicAccesible desde cualquier tipo de cualquier ensamblado.
ProtectedAccesible desde el mismo tipo al que pertenece el miembro y desde cualquier tipo derivado que herede de él (también llamado acceso Family).
InternalAccesible solo dentro del ensamblado en el que se define el tipo (también llamado acceso Assembly).
PrivateAccesible solo desde el mismo tipo al que pertenece el miembro o desde un tipo anidado en ese tipo.
FamilyOrAssemblyAccesible desde los tipos que cumplen los requisitos del acceso Family o del acceso Assembly (en C#, protected internal).
FamilyAndAssemblyAccesible solo desde los tipos que cumplen a la vez los requisitos del acceso Family y del acceso Assembly (en C#, private protected).

Elemento Targets

Restringe el ámbito de la regla a tipos concretos de símbolos de código. Los valores aceptados son All o cualquier combinación de Classes, Delegates, Structures, Interfaces, Enums, Events, Methods, Properties, Fields, StaticFields y Resources. Si este elemento no está presente, se toma el valor predeterminado All y la regla se aplica a todos los tipos de símbolos.

Elemento Pattern

En la definición de una regla XML de Babel Obfuscator, el elemento Pattern es un componente esencial para identificar y seleccionar los símbolos del ensamblado sujetos a ofuscación. Este elemento acepta un nombre completo de símbolo, una expresión con comodines o una expresión regular, lo que proporciona un mecanismo de filtrado versátil y adaptable para dirigirse a elementos de código concretos.

Expresiones con comodines: para criterios de selección más sencillos, el elemento Pattern puede incluir caracteres comodín. El carácter «?» representa un único carácter cualquiera, mientras que «*» representa cero o más caracteres. Así se pueden definir criterios de selección amplios pero controlados para la coincidencia de símbolos, y resulta fácil dirigirse a grupos de símbolos relacionados sin escribir patrones complejos.

Expresiones regulares: para requisitos de filtrado más complejos y precisos, en el elemento Pattern se pueden emplear expresiones regulares. En ese caso, el atributo isRegEx debe establecerse en «true» para indicar que el patrón se interpreta como una expresión regular y no como una cadena literal o un patrón con comodines. Es aconsejable incluir la expresión regular en una sección CDATA para que el XML se analice correctamente y los caracteres especiales se interpreten bien. Por ejemplo:

<Pattern isRegEx="true"><![CDATA[^Properties.*]]></Pattern>

Formato del nombre completo

El formato del nombre completo de un símbolo en la definición del patrón de una regla XML de Babel Obfuscator varía según el tipo de símbolo al que se dirige. Esta distinción permite una ofuscación precisa y eficaz de los distintos tipos de símbolos sin perder claridad ni coherencia.

Tipos (clases, estructuras, enumeraciones, interfaces): el formato convencional es NamespaceName.TypeName, una notación sencilla para las declaraciones de tipos básicas.

Tipos anidados: para los tipos anidados (tipos definidos dentro de otros tipos), el formato usa una barra diagonal como separador: NamespaceName.TypeName/NestedTypeName. Esta notación distingue con claridad los tipos anidados de sus tipos contenedores y conserva la relación jerárquica.

Tipos genéricos: la representación de los tipos genéricos empieza por NamespaceName.TypeName, seguido de los argumentos de tipo genérico entre corchetes angulares:

NamespaceName.TypeName<GenericArgumentList>

GenericArgumentList: este elemento no es un patrón independiente, sino una parte del patrón de los tipos genéricos. Define la lista de argumentos de tipo genérico separados por comas, cada uno con su espacio de nombres y su nombre de tipo completos:

NamespaceName.TypeName1,NamespaceName.TypeName2,...,NamespaceName.TypeNameN

Métodos: el formato habitual de los métodos incluye el espacio de nombres, el nombre del tipo, el nombre del método, la lista de parámetros y, de forma opcional, el tipo de valor devuelto:

NamespaceName.TypeName::MethodName(ParameterList):ReturnType

Cabe señalar que incluir ReturnType en el patrón es opcional y que en la mayoría de los casos se puede omitir.

Propiedades: el formato de las propiedades sigue esta estructura:

NamespaceName.TypeName::PropertyName:PropertyType

Por lo general, no hace falta incluir el tipo de la propiedad en el patrón y se puede omitir.

Eventos: el formato de los eventos es:

NamespaceName.TypeName::EventName:EventHandlerType

Este formato incluye tanto el nombre del evento como el tipo de su controlador asociado.

Campos: los campos siguen el formato:

NamespaceName.TypeName::FieldName:FieldType

Como en las propiedades, el tipo del campo suele ser opcional y no hace falta en la mayoría de las definiciones de patrones.

ParameterList: este componente pertenece exclusivamente al patrón de los métodos. Indica los nombres de tipo completos de los parámetros, separados por comas:

NamespaceName.TypeName1,NamespaceName.TypeName2,...,NamespaceName.TypeNameN

Recuerde que estos patrones sirven para especificar con precisión qué partes del código debe ofuscar Babel Obfuscator. La sintaxis exacta puede variar ligeramente según el contexto y los requisitos concretos de su estrategia de ofuscación. Con patrones precisos, las reglas de ofuscación afectan únicamente a los símbolos previstos.

Elemento HasAttribute

Especifica una lista, separada por comas, de nombres completos de tipos de atributos personalizados. Si el símbolo de destino está decorado con al menos uno de estos atributos, la regla se le aplica. Este elemento permite filtrar por atributos para dirigir la regla con precisión.

Este elemento admite el atributo opcional onEnclosingType. Cuando se establece en «true», indica que el atributo personalizado debe buscarse en el tipo que contiene el símbolo de destino y no en el propio símbolo:

<HasAttribute onEnclosingType="true">System.SerializableAttribute</HasAttribute>

Esta configuración coincide con símbolos como métodos, propiedades, campos y eventos que pertenecen a cualquier tipo decorado con SerializableAttribute.

Elemento HasBase

Especifica una lista, separada por comas, de nombres completos de tipos base. La regla coincide con un símbolo de tipo si el tipo de destino deriva de uno de los tipos base especificados. Este elemento permite filtrar por herencia la aplicación de la regla.

Este elemento admite el atributo opcional onEnclosingType. Cuando se establece en «true», indica que Babel debe buscar en la jerarquía del tipo que contiene los símbolos de destino, lo que permite aplicar reglas en función de la estructura de herencia de los tipos contenedores.

Elemento Namespace

Restringe la regla a los símbolos de un espacio de nombres determinado. Así, la aplicación de la regla se filtra por espacio de nombres.

<Namespace>ACME.Data</Namespace>

La regla se aplica a todos los símbolos definidos en el espacio de nombres ACME.Data y en sus espacios de nombres anidados.

Elemento Properties

El elemento Properties define una colección de elementos XML hijos con los que se personaliza el comportamiento de la función seleccionada en la regla. Cada función de ofuscación admite propiedades específicas que controlan su funcionamiento y ajustan con precisión cómo procesa los símbolos coincidentes.

<Rule name="DataWriter" feature="msil encryption" exclude="false"> <Target>Methods</Target> <Pattern>ACME.Data.DataWriter::*</Pattern> <Properties> <Cache>true</Cache> <MinInstructionCount>6</MinInstructionCount> </Properties> <Description>Encrypts code in the DataWriter class.</Description> </Rule>

Esta regla configura la función msil encryption estableciendo las propiedades Cache y MinInstructionCount para todos los métodos de la clase DataWriter.

A continuación figura la lista completa de los elementos de propiedad que admite cada función de ofuscación:

agent

PropiedadTipoDescripción
TaskNameListCadenaLista, separada por comas, de los nombres de las tareas del agente a las que se aplica la regla.

cleanup attributes

PropiedadTipoDescripción
AttributesCadenaLista, separada por comas, de nombres calificados de tipos de atributos o de expresiones regulares que coinciden con los miembros que se incluyen en la búsqueda.
IncludeMembersCadenaLista, separada por comas, de nombres calificados de símbolos o de expresiones regulares que coinciden con los miembros que se incluyen en la búsqueda.
ExcludeMembersCadenaLista, separada por comas, de nombres calificados de símbolos o de expresiones regulares que coinciden con los miembros que se excluyen de la búsqueda.

control flow

PropiedadTipoDescripción
ILIterationsEnteroEspecifica el número de iteraciones que se aplican durante la ofuscación del flujo de control; los valores más altos producen estructuras de código más complejas.
EmitInvalidOpcodesBooleanoCuando está activada, añade códigos de operación no válidos en el flujo del método para confundir a los desensambladores y descompiladores.
ChangeIfStatementBooleanoCuando está activada, transforma y ofusca las instrucciones condicionales if para que la lógica sea más difícil de seguir.
AddSwitchStatementBooleanoCuando está activada, enriquece el flujo de control insertando instrucciones switch en el flujo del método, lo que crea rutas de ejecución más complejas.
ScrambleControlFlowBooleanoCuando está activada, produce «código espagueti» insertando bifurcaciones irrelevantes e instrucciones de salto que ocultan en gran medida el flujo de control original.
MaxSwitchTargetsEnteroEstablece el número máximo de destinos case permitidos en la ofuscación del flujo de control con switch, lo que controla la complejidad de las instrucciones switch generadas.
HideCaseConstantExpressionsBooleanoCuando está activada, oculta los valores constantes calculados en la ofuscación del flujo de control con switch, usando expresiones calculadas en lugar de valores literales.
RandomCallBooleanoCuando está activada, añade instrucciones de llamada a métodos aleatorios para dificultar aún más el análisis (solo disponible cuando el flujo de control con switch está activado).
AddMethodToken (*)BooleanoCuando está activada, enriquece el flujo de control añadiendo instrucciones de carga de token en el flujo del método, lo que aporta más complejidad.
StackUnderflow (*)BooleanoCuando está activada, inserta instrucciones que crean condiciones de desbordamiento negativo de la pila de evaluación, lo que dificulta el análisis estático.

(*) Estas opciones generan código IL no verificable. Si su ensamblado debe ejecutarse en un entorno de confianza parcial o debe superar la validación de PEVerify, no active estas opciones.

renaming

PropiedadTipoDescripción
DisableOverloadingBooleanoCuando está activada, desactiva el renombrado con sobrecarga, es decir, los métodos con firmas distintas reciben nombres ofuscados distintos en lugar de compartir el mismo nombre.
DisableUnicodeBooleanoCuando está activada, impide el uso de caracteres Unicode en los nombres ofuscados y limita los nombres a caracteres ASCII.
InternalizeBooleanoCuando está activada, cambia de public a internal la visibilidad de todos los tipos públicos que coinciden con la regla, lo que reduce la superficie de API del ensamblado.
NameLengthEnteroEspecifica la longitud deseada de los nombres de los símbolos renombrados, lo que permite controlar si los identificadores ofuscados son más largos o más cortos.
NamePrefixCadenaDefine una cadena de prefijo que se antepone a todos los símbolos renombrados, lo que ayuda a identificar o clasificar los nombres ofuscados.

string encryption

PropiedadTipoDescripción
MinInstructionCountEnteroEstablece el número mínimo de instrucciones que debe tener un método para que se le aplique la regla. Los métodos con menos instrucciones quedan excluidos.
MaxInstructionCountEnteroEstablece el número máximo de instrucciones que puede tener un método para que se le aplique la regla. Los métodos con más instrucciones quedan excluidos.

merge

PropiedadTipoDescripción
CopyAttributesCadenaLista, separada por comas, de nombres completos de tipos de atributos personalizados o de expresiones regulares con la que se filtran los atributos que se copian del ensamblado de origen al ensamblado de destino durante la combinación.
NoCopyAttributesCadenaLista, separada por comas, de nombres completos de tipos de atributos personalizados o de expresiones regulares con la que se filtran los atributos que NO se copian al ensamblado de destino durante la combinación.
InternalizeBooleanoCuando está activada, cambia de public a internal la visibilidad de todos los tipos combinados que coinciden con la regla, lo que los oculta a los ensamblados externos.
MergeActionDefault/Discard/RedirectEspecifica la acción de combinación que se realiza con el tipo seleccionado. Default realiza la combinación normal, Discard excluye el tipo de la combinación y Redirect redirige las referencias a otro tipo del ensamblado de destino (indicado en la propiedad RedirectTo).
RedirectToCadenaContiene el nombre completo del tipo del ensamblado de destino que sustituye al tipo de origen cuando se ha especificado la acción de combinación Redirect.

msil encryption

PropiedadTipoDescripción
CacheBooleanoCuando está activada, guarda en caché en memoria el método descifrado para que la compilación JIT se produzca solo en el primer acceso, lo que mejora el rendimiento posterior.
InternalBooleanoCuando está activada, almacena el código MSIL cifrado dentro del propio ensamblado de destino; cuando está desactivada, lo almacena en un archivo externo.
PasswordCadenaEspecifica la contraseña con la que se cifra el código del método, lo que añade una capa más de protección.
SourceCadenaDefine un nombre identificador de origen para el código cifrado, útil para organizar varios orígenes de cifrado.
MinInstructionCountEnteroEstablece el número mínimo de instrucciones que debe tener un método para que se le aplique la regla.
MaxInstructionCountEnteroEstablece el número máximo de instrucciones que puede tener un método para que se le aplique la regla.

optimizations

PropiedadTipoDescripción
ClassSealingBooleanoCuando está activada, aplica la optimización de sellado de clases, que marca como selladas (final) las clases que no tienen tipos derivados, lo que mejora el rendimiento.
ConstRemovalBooleanoCuando está activada, elimina los metadatos de los campos constantes y sustituye las referencias por valores literales directamente en el código.
DisgregateRemovalBooleanoCuando está activada, elimina los metadatos de propiedades y eventos, lo que reduce el volumen de metadatos del ensamblado.
EnumRemovalBooleanoCuando está activada, elimina las definiciones de tipos de enumeración y las sustituye por sus tipos enteros subyacentes.
UnwantedAttributesBooleanoCuando está activada, elimina los atributos personalizados no deseados que pueden revelar detalles de implementación o información de depuración.

Elemento Description

Proporciona un texto que explica la finalidad y el comportamiento de la regla. Esta descripción se muestra en el registro de la ofuscación, lo que ayuda a entender qué hace cada regla al revisar el proceso de ofuscación.

Configuración de las reglas

Puede pasar archivos de reglas a Babel Obfuscator desde la línea de comandos, la tarea Babel de MSBuild o Babel Desktop. Elija la opción que mejor se ajuste a su compilación.

Línea de comandos

babel myapp.exe --rules babelRules.xml

La opción --rules se puede indicar varias veces en la línea de comandos para incluir más archivos de reglas XML. Así puede organizar las reglas en archivos separados y combinarlos según sea necesario.

Tarea Babel de MSBuild

<ItemGroup> <RuleFile Include="babelRules.xml" /> </ItemGroup> <Babel RulesFiles="@(RuleFile)" />

La opción RulesFiles de Babel Obfuscator acepta una lista de archivos de reglas XML, que se puede definir con el elemento ItemGroup en el archivo de proyecto de MSBuild. De este modo se pueden indicar varios archivos de reglas y gestionarlos con facilidad dentro de la estructura del proyecto. Cada archivo de reglas del grupo de elementos se trata como una entrada independiente de Babel Obfuscator y puede servir para especificar reglas y ajustes de ofuscación distintos para distintas partes del código.

Además de usar archivos de reglas XML externos, puede incrustar la definición de las reglas XML directamente en el archivo de proyecto mediante el atributo XmlRules de la tarea Babel, como se muestra a continuación:

<PropertyGroup> <XmlRules> <Rules targetAssembly="Acme, Version=1.0.0.0, Culture=neutral, PublicKeyToken=f66185f16ea61c16"> <Rule name="rule1" feature="msil encryption" exclude="false"> <Target>Methods</Target> <Pattern>Acme.Engine*</Pattern> <Description>Enable MSIL Code Encryption in Acme Engine</Description> </Rule> </Rules> <Rules targetAssembly="Acme.Entities, Version=1.0.0.0, Culture=neutral, PublicKeyToken=f66185f16ea61c16"> <Rule name="rule2" feature="control flow" exclude="true"> <Target>Methods</Target> <Pattern>Acme.Entities.*</Pattern> <Description>Disable Control Flow Obfuscation for EF classes</Description> </Rule> </Rules> </XmlRules> </PropertyGroup> <Babel XmlRules="$(XmlRules)" />

Cuando Babel Obfuscator procesa varios ensamblados de destino en un proyecto, puede indicar a qué ensamblado de destino se aplica un conjunto de reglas mediante el atributo targetAssembly de las reglas XML. Este atributo permite dirigirse a un ensamblado concreto por su nombre completo, incluidos la versión, la configuración regional y el token de clave pública. Si se omite el atributo targetAssembly, las reglas se aplican a todos los ensamblados de destino definidos en el proyecto.

Babel Desktop

Para usar archivos de reglas XML externos, seleccione el ensamblado de destino en el diagrama del proyecto y añada los archivos a RulesFiles, en el grupo Archivos y dependencias del panel de propiedades.

Para escribir reglas en línea, abra la vista de reglas XML del ensamblado seleccionado (la pestaña Reglas XML del panel de propiedades, o Configuración > Ensamblado seleccionado > Reglas XML). El editor valida las reglas con el esquema XML de Babel e indica la línea y la columna de cada error, y puede abrir y guardar documentos de reglas como archivos XML.

Las reglas en línea se almacenan en el archivo de proyecto, en la propiedad XmlRules de la tarea Babel, como en el ejemplo de MSBuild de más arriba, por lo que se guardan y se versionan junto con la configuración del proyecto. Consulte Proyectos de ofuscación para saber cómo trabajar con proyectos en Babel Desktop.

Last updated on