XML Rules

Rules Files

Babel rules files are XML documents that contain configuration information used to customize and control the obfuscation process. These files allow you to define precisely which obfuscation features should be applied to specific parts of your code, giving you granular control over the protection of your assemblies.

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

The Rules element can define a targetAssembly attribute that limits the scope of the rules it contains to a specific assembly. If the targetAssembly attribute is not specified, the rules will apply to all assemblies being processed. Example:

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

Rules Element

The Rules element serves as the root container that defines a set of rules to be applied to the target assembly. This element can contain multiple Rule child elements, each specifying different obfuscation behaviors.

Rule Element

The Rule element is used to define a Babel obfuscation rule that can target one or more Babel Obfuscator features. Each rule specifies which code elements should be affected and how the obfuscation features should be applied to them.

The feature attribute defines the obfuscator feature on which the rule acts. The name and exclude attributes are mandatory, while the feature attribute is optional. If not specified, the feature defaults to “default”, which refers to the renaming feature.

The obfuscator features are predefined strings that correspond to specific obfuscation capabilities. All supported feature names are listed in the tables below.

Feature Table

The following features can target all symbol types defined inside an assembly, including types, methods, properties, fields, and events:

The following obfuscation features are method-specific and can only be applied to method symbols:

Any Rule element can contain child elements such as Access, Target, Pattern, HasAttribute, Properties and Description. The Pattern element is mandatory, while all others are optional. These child elements provide additional filtering and configuration capabilities for the rule. Example:

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

Below is the complete list of all possible Rule child elements:

Access Element

Restricts the rule’s scope to symbols with the specified visibility modifiers. Possible values are All or any combination of Public, Protected, Internal, Private, FamilyAndAssembly, and FamilyOrAssembly. If this element is not present, the default value All is used, meaning the rule applies to symbols of any visibility.

Targets Element

Restricts the scope of the rule to specific types of code symbols. Accepted values are All or any combination of Classes, Delegates, Structures, Interfaces, Enums, Events, Methods, Properties, Fields, StaticFields, and Resources. If this element is not present, the default value All is assumed, applying the rule to all symbol types.

Pattern Element

The Pattern element within Babel Obfuscator’s XML Rule definition serves as a crucial component for identifying and matching assembly symbols that are subject to obfuscation. This element accepts either a fully qualified symbol name, a wildcard expression, or a regular expression, thereby establishing a versatile and adaptable filtering mechanism for targeting specific code elements.

Wildcard Expressions: For simpler selection criteria, the Pattern element can incorporate wildcard characters. The ’?’ character represents any single character, while ’*’ denotes zero or more characters. This feature enables broad yet controlled selection criteria for symbol matching, making it easy to target groups of related symbols without writing complex patterns.

Regular Expressions: For more complex and precise filtering requirements, regular expressions can be employed within the Pattern element. When using regular expressions, the attribute isRegEx must be set to “true” to indicate that the pattern should be interpreted as a regular expression rather than a literal string or wildcard pattern. It is advisable to encapsulate the regular expression within a CDATA section to ensure proper XML parsing and accurate interpretation of special characters. For example:

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

Fully Qualified Name Format

The format of a fully qualified symbol name in Babel Obfuscator’s XML Rule pattern definition varies depending on the type of symbol being targeted. This nuanced approach ensures precise and effective obfuscation across various symbol types while maintaining clarity and consistency.

Types (Classes, Structures, Enums, Interfaces): The conventional format is represented as NamespaceName.TypeName, providing a straightforward notation for basic type declarations.

Nested Types: For nested types (types defined within other types), the format uses a forward slash separator: NamespaceName.TypeName/NestedTypeName. This notation clearly differentiates nested types from their parent types and maintains the hierarchical relationship.

Generic Types: The representation for generic types begins with NamespaceName.TypeName, followed by the generic type arguments enclosed within angle brackets:

NamespaceName.TypeName<GenericArgumentList>

GenericArgumentList: This element is not an independent pattern but rather an integral part of the Generic Types pattern. It defines the comma-separated list of generic type arguments, each specified with their full namespace and type name:

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

Methods: The typical format for methods includes the namespace, type name, method name, parameter list, and optionally the return type:

NamespaceName.TypeName::MethodName(ParameterList):ReturnType

It is worth noting that the inclusion of the ReturnType in the pattern is optional and may be omitted in most cases.

Properties: The prescribed format for properties follows this structure:

NamespaceName.TypeName::PropertyName:PropertyType

Generally, the property type does not need to be included in the pattern and can be omitted.

Events: The format for events is expressed as:

NamespaceName.TypeName::EventName:EventHandlerType

This format encompasses both the event name and its associated handler type.

Fields: Fields follow the format:

NamespaceName.TypeName::FieldName:FieldType

Similar to properties, the field type is typically optional and not required in most pattern definitions.

ParameterList: This component is exclusively associated with the Methods pattern. It details the fully qualified type names of parameters, separated by commas:

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

Remember, these patterns are used to specify precisely which parts of the code Babel Obfuscator should target for obfuscation. The exact syntax may vary slightly depending on the context and the specific requirements of your obfuscation strategy. Using accurate patterns ensures that only the intended symbols are affected by the obfuscation rules.

HasAttribute Element

Specifies a comma-separated list of fully qualified custom attribute type names. If the target symbol is decorated with at least one of these attributes, the rule will be applied to that symbol. This element provides attribute-based filtering for precise rule targeting.

This element supports the optional onEnclosingType attribute. When set to “true”, this attribute specifies that the custom attribute should be checked on the target symbol’s enclosing type rather than on the symbol itself:

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

This configuration will match symbols such as methods, properties, fields, and events that belong to any type decorated with the SerializableAttribute.

HasBase Element

Specifies a comma-separated list of fully qualified base type names. The rule will match a type symbol if the target type derives from one of these specified base types. This element enables inheritance-based filtering for rule application.

This element supports the optional onEnclosingType attribute. When set to “true”, this attribute specifies that Babel should search within the enclosing type hierarchy of the target symbols, allowing you to apply rules based on the inheritance structure of containing types.

Namespace Element

Restricts the rule to symbols within a specified namespace. This provides namespace-level filtering for rule application.

<Namespace>ACME.Data</Namespace>

The rule will be applied to all symbols defined within the ACME.Data namespace and its sub-namespaces.

Properties Element

The Properties element defines a collection of XML child elements used to customize the behavior of the selected rule feature. Each obfuscation feature supports specific properties that control its operation and fine-tune how it processes the matched symbols.

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

This rule configures the msil encryption feature by setting the Cache and MinInstructionCount properties for all methods in the DataWriter class.

Below is the comprehensive list of property elements supported by each obfuscation feature:

agent

cleanup attributes

control flow

(*) These options generate unverifiable IL code. If your assembly must run in a partially trusted environment or must pass PEVerify validation, do not enable these options.

renaming

string encryption

merge

msil encryption

optimizations

Description Element

Provides a descriptive text explanation of the rule’s purpose and behavior. This description will be displayed in the obfuscation log, making it easier to understand what each rule does when reviewing the obfuscation process.

Configuring Rules

Rules files can be configured and integrated into Babel Obfuscator through multiple methods: the command line interface, the MSBuild Babel task, and the Babel User Interface. Each method provides different advantages depending on your workflow and project structure.

Command Line

babel myapp.exe --rules babelRules.xml

The --rules option can be specified multiple times on the command line to include additional XML rules files. This allows you to organize rules into separate files and combine them as needed.

MSBuild Babel Task

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

The RulesFiles option in Babel Obfuscator accepts a list of XML rules files, which can be defined using the ItemGroup element in your MSBuild project file. This approach allows multiple rule files to be specified and easily managed within the project structure. Each rule file listed in the item group is treated as a separate input for Babel Obfuscator and can be used to specify different obfuscation rules and settings for different parts of your codebase.

In addition to using external XML rules files, you can embed the XML rules definition directly inside the project file by using the XmlRules attribute of the Babel task, as shown below:

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

When using Babel Obfuscator to process multiple target assemblies in a project, you can specify which target assembly a set of rules should be applied to by using the targetAssembly attribute in the XML rules. This attribute allows you to target a specific assembly by its fully qualified name, including version, culture, and public key token. If the targetAssembly attribute is omitted, the rules will be applied to all target assemblies defined in the project.

Babel UI

Babel UI provides a graphical user interface for adding, editing, and managing obfuscation rules, making it easier to configure and visualize obfuscation settings for your projects without manually editing XML files.

To add XML rules files to a Babel Obfuscator project using the Babel UI, follow these steps:

1. Open your Babel Obfuscator project in the Babel UI.
2. In the Input Grid, expand the row corresponding to the target assembly where you want to add the rule file.
3. Select the “Rules” tab and choose the first empty row in the grid displayed below.
4. Click on the ”…” button in the right-hand corner of the selected row.
5. Select the XML rules file you want to add from the file dialog that opens.
6. Once you have selected the file, click the “Open” button.
7. If needed, you can edit the XML rule file in your system’s default text editor by clicking the pencil button.

After following these steps, the XML rules file will be added to your project and its rules will be applied during the obfuscation process according to the definitions contained in the file.

Babel Obfuscator UI provides a user-friendly interface for directly editing and creating obfuscation rules without manually writing XML. To use this feature, follow these steps:

1. Select the “Rules” item in the left navigation panel of the Babel UI.
2. In the “Rules” panel that appears, you will see a hierarchical tree view of the symbols in your target assembly.
3. Right-click on a symbol node in the tree view to display a context menu.
4. From the context menu, select “Add Rule” to define a new obfuscation rule for that symbol.
5. Choose the obfuscation feature you want to apply from the submenu that appears.
6. From the secondary menu, select one of the predefined rule templates for that feature.
7. If needed, you can further customize the rule’s settings and properties using the “Rule Properties” panel located in the bottom-right section.

By following these steps, you can quickly and easily define custom obfuscation rules for specific symbols in your target assembly through a visual interface. This allows you to fine-tune the obfuscation process to meet the specific security and performance requirements of your application without needing to manually edit XML files.

In Babel Obfuscator UI, all rules defined in the “Rules” panel for a given target assembly are automatically stored within the project file using the XmlRules attribute of the Babel task. By storing the rules directly in the project file, Babel Obfuscator UI ensures that all obfuscation rules are maintained together with the project configuration and remain easily accessible. This integrated approach makes it convenient to manage and update rules as needed, while ensuring that the rules are always version-controlled and saved alongside the project.