XML Rules

In addition to options specified on the command line or through the MSBuild Babel task, Babel Obfuscator can be driven by rules defined in an external XML file.

Rules Files

Babel rules files are XML files that contain the information used to customize the obfuscation process.

<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. Example:

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

In the XML rule file, rules are processed from top to bottom in the order they appear. This order of processing allows for overriding any existing rules with more specific rules that are listed subsequently.

Rules Element

The Rules element defines a set of rules to be applied to the target assembly.

Attribute
Description

targetAssembly

Specifies the fully qualified name of the assembly to which the rules are applied. If not defined, the rules will apply to all assemblies involved in the obfuscation process.

Rule Element

The Rule element is used to define a Babel rule that can target one or more Babel Obfuscator features.

Attribute
Description

name

Friendly rule name

feature

The obfuscator feature name, or a list of feature names, that targets this rule

exclude

Whether this rule will prevent the feature or features to be executed

applyToMembers

Whether to apply the rule to all members of a symbol that match the rule itself

locked

Whether this rule cannot be overridden by other rules

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

The obfuscator features are fixed strings. All the supported feature names are listed in the following table.

Feature Table

Feature
Description

all

Targets all the features

default

The default feature will refer to renaming

agent

Obfuscation agent

cleanup attributes

Cleanup unwanted attributes

control flow

Control flow obfuscation

dead code

Dead code removal

dynamic proxy

Dynamic proxy calls

embed

Assembly embedding

merge

Assembly merging

msil encryption

Code encryption (MSIL encryption)

renaming

Member names obfuscation

renaming blob

Rename literal strings that correspont to a renamed symbol

resource encryption

Ebedded resources encryption

string encryption

Targets encryption of inline strings

value encryption

Targets encryption of inline values and arrays

inline

Targets methods to be inlined

instrumentation

Rule code instrumentation

optimizations

Targets all metadata optimizations

xaml

Targets the renaming of XAML or BAML resources

The above features can target all the symbols defined inside an assembly (types, methods, properties, fields, events)

The following obfuscation features can be applied only to methods:

Feature
Description

msil encryption get stream

Declare code encryption get source stream method

string encryption encrypt method

Defines string encrypt method

string encryption decrypt method

Defines string decrypt method

instrumentation on entry method

Defines code instrumentation on entry method

instrumentation on exit method

Defines code instrumentation on exit method

instrumentation on exception method

Defines code instrumentation on exception method

module initializer

Defines a method that should call when the module initializes

Any Rule element can have other child elements like Access, Target, Pattern, HasAttribute, Properties and Description. The Pattern element is mandatory, whereas the others are optional. 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>

Follows the list of all possible Rule child elements

Element

Access

Targets

Pattern

HasAttribute

HasBase

Implements

Namespace

Properties

Description

Access Element

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

Access
Description

Public

Accessible from any type.

Protected

Accessible from within the same type as the member, and from derived types that inherit from it (Family).

Internal

Accessible only in the assembly in which the type is defined (Assembly)

Private

Accessible only from within the same type as the member, or within a nested type.

FamilyOrAssembly

Accessible only from types that qualify for either family or assembly access (Protected Internal).

FamilyAndAssembly

Accessible only from types that qualify for both family and assembly access.

Targets Element

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

Pattern Element

The Pattern element within Babel Obfuscator's XML Rule definition serves as a crucial component for identifying assembly symbols 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 symbol names.

Wildcard Expressions: For a simpler selection criterion, 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.

Regular Expressions: For more complex and precise filtering requirements, regular expressions can be employed in the Pattern element. In such instances, the attribute isRegEx must be set to "true", signifying the use of a regular expression. It is advisable to encapsulate the regular expression within a CDATA section to ensure accurate interpretation of the pattern. 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 is contingent upon the type of symbol being targeted. This nuanced approach ensures precise and effective obfuscation across various symbol types.

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

Nested Types: For nested types, the format adheres to NamespaceName.TypeName/NestedTypeName. This notation distinctly differentiates nested types from their parent types.

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

NamespaceName.TypeName<GenericArgumentList>

GenericArgumentList: This element is not an independent pattern but rather an integral part of the Generic Types pattern, defining the list of generic type arguments.

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

Methods: The typical format for methods is given by the following expression:

NamespaceName.TypeName::MethodName(ParameterList):ReturnType

It is worth mentioning that the inclusion of the ReturnType in the pattern is optional and may not always be present.

Properties: The prescribed format for properties is

NamespaceName.TypeName::PropertyName:PropertyType.

Generally, the property type does not form part of this pattern.

Events: The format for events is articulated as

NamespaceName.TypeName::EventName:EventHandlerType

which encompasses both the event name and its handler type.

Fields: Fields follow the format

NamespaceName.TypeName::FieldName:FieldType

Similar to properties, the field type is usually not included in this pattern.

ParameterList: This component is exclusively associated with the Methods pattern, detailing the types of parameters involved, separated by commas.

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

Remember, these patterns are used to specify which parts of the code Babel Obfuscator should target for obfuscation. The exact syntax can vary slightly depending on the context and the specific requirements of your obfuscation strategy.

HasAttribute Element

Specifies a list of fully-qualified type custom attributes. If the target symbol has at least one of these attributes, the rule will be applied to the target symbol. This element can have the onEnclosingType attribute. This attribute will specify if the custom attribute should be considered for the target symbol enclosing type:

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

It will catch symbols like methods, properties, fields and events of any serializable types.

HasBase Element

Specifies a list of fully qualified type names. The rule will catch the type symbol if the target type derives from one of these base types. This element can have the onEnclosingType attribute. This attribute will specify if Babel should search in the enclosing type hierarchy of the target symbols.

Namespace Element

Restrict the rule to a specified namespace name.

<Namespace>ACME.Data</Namespace>

The rule will be applied to all the symbols inside the ACME.Data namespace.

Properties

The Properties element defines a collection of XML elements to customize the selected rule feature behaviour.

<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 will set the msil encryption feature properties Cache and MinInstructionCount for the DataWriter class.

Follow the list of property elements supported by each feature.

agent

Property
Type
Description

TaskNameList

String

A comma-separated list of agent task names to which the rule applies.

cleanup attributes

Property
Type
Description

Attributes

String

A comma-separated list of qualified type attribute names or regular expressions that match the members to include in the search.

IncludeMembers

String

A comma-separated list of qualified symbol names or regular expressions that match the members to include in the search.

ExcludeMembers

String

A comma-separated list of qualified symbol names or regular expressions that match the members to exclude in the search.

control flow

Property
Type
Description

ILIterations

Integer

The number of iterations to use in the control flow obfuscation.

EmitIvalidOpcodes

Boolean

Whether to add invalid instruction opcodes within a method flow.

ChangeIfStatement

Boolean

Whether to obfuscate instructions of if statements.

AddSwitchStatement

Boolean

Whether to enrich control flow by adding switch statements instructions into method flow.

ScrambleControlFlow

Boolean

Whether to produce spaghetti code inserting irrelevant branches

MaxSwitchTargets

Integer

Set the maximum number of case targets in the switch control flow obfuscation.

HideCaseConstantExpressions

Boolean

Whether to hide the calculated constant values in switch control flow obfuscation.

RandomCall

Boolean

Whether to add random call instructions (available only when switch control flow is enabled)

AddMethodToken (*)

Boolean

Whether to enrich control flow by adding load token instructions into method flow.

StackUnderflow (*)

Boolean

If enabled, it inserts instructions to generate conditions where the stack underflows.

(*) Generates unverifiable IL code. If your assembly must run in a fully trusted environment, do not enable this option.

renaming

Property
Type
Description

DisableOverloading

Boolean

Whether to disable overloaded renaming

DisableUnicode

Boolean

Whether to disable unicode names

Internalize

Boolean

Whether all public types that match the rule change their visibility to internal.

NameLength

Integer

Set the renamed symbol name length

NamePrefix

String

Set a name prefix for renamed symbols

string encryption

Property
Type
Description

MinInstructionCount

Integer

Sets the threshold for the minimum number of method instructions for which the rule applies

MaxInstructionCount

Integer

Sets the threshold for the maximum number of method instructions for which the rule applies

merge

Property
Type
Description

CopyAttributes

String

A comma-separated list of fully qualified custom attribute type names and regular expressions to filter attributes to be copied to the target assembly

NoCopyAttributes

String

A comma-separated list of fully qualified custom attribute type names and regular expressions to filter attributes that will not be copied to the target assembly

Internalize

Boolean

Whether to change the visibility from public to internal of all merged types that match the rule

MergeAction

Default/Discard/Redirect

Specify the merge action to be taken for the selected type. If Redirect is specified, the selected type is not merged but redirected to another type inside the target assembly specified by the RedirecTo property.

RedirectTo

String

Contains the fully qualified target assembly type name, which replaces the type for which the Redirect merge action has been specified.

msil encryption

Property
Type
Description

Cache

Boolean

Whether to cache the encrypted method to memory so that the compilation occurs only the first time the method is accessed.

Internal

Boolean

Whether the MSIL-encrypted code is stored inside the target assembly or in an external file.

Password

String

Set encrypted code password.

Source

String

Define a source name fro encrypted code.

MinInstructionCount

Integer

Sets the threshold for the minimum number of method instructions for which the rule applies

MaxInstructionCount

Integer

Sets the threshold for the maximum number of method instructions for which the rule applies

optimizations

Property
Type
Description

ClassSealing

Boolean

Whether to enable class sealing optimization

ConstRemoval

Boolean

Whether to enable the removal of unwanted attributes

DisgregateRemoval

Boolean

Whether to enable removal of enum types

EnumRemoval

Boolean

Whether to enable removal of constant fields

UnwantedAttributes

Boolean

Whether to enable the removal of properties and events metadata.

Description Element

Any proper rule description. This will be displayed on the obfuscation log.

Configuring Rules

Rules files can be configured in Babel Obfuscator through the command line, the MSBuild Babel task, and the Babel User Interface.

Command Line

babel myapp.exe --rules babelRules.xml

The option --rules can be entered multiple times on the command line to specify additional XML rules files.

MSBuild Babel Task

<ItemGroup>
  <RuleFile Include="babelRules.xml" />
</ItemGroup>

<Babel RulesFiles="@(RuleFile)" />

The RulesFiles option in Babel Obfuscator can accept a list of XML rules files, which can be defined using the ItemGroup element in the MSBuild project file. This allows for multiple rule files to be specified and easily managed within the project. 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 the code.

In addition to using XML rules files, it is possible to add the XML rules definition directly inside the project file by using the XmlRules Babel task attribute, 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 obfuscate multiple target assemblies in a project, it is possible to specify which target assembly a set of rules should be applied to by using the targetAssembly attribute in the XML rules file. This attribute allows you to target a specific assembly by its name. If the targetAssembly is missing, the rules will be applied to all the target assemblies defined in the project.

Babel UI

Babel UI provides a graphical interface for adding, editing and managing rules, which can make it easier to set up obfuscation for your projects.

To add XML rules files to a Babel Obfuscator project using the Babel UI, you can 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 underneath grid.

  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 opened file dialog.

  6. Once you have selected the file, click on the "Open" button.

  7. If needed, you can edit the XML rule file in the system-configured text editor by pressing the pencil button.

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

Babel Obfuscator UI provides a user-friendly interface for directly editing obfuscation rules. To do so, 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 tree view of the symbols in your target assembly.

  3. Right-click on a symbol node in the tree view to bring up a pop-up menu.

  4. From the pop-up menu, select "Add Rule" to define a new obfuscation rule for that symbol.

  5. Choose the obfuscation feature you want to apply to the rule from the submenu that appears.

  6. Then from the secondary menu, select one of the predefined rules for that feature.

  7. If needed, you can further customize the rule by changing its settings in the "Rule Properties" panel on the bottom right.

Following these steps, you can quickly and easily define custom obfuscation rules for specific symbols in your target assembly. This allows you to fine-tune the obfuscation process to meet the specific needs of your application.

In Babel Obfuscator UI, all the rules defined in the "Rules" panel for a given target assembly are stored inside the project file using the XmlRules Babel task attribute. By storing the rules directly in the project file, Babel Obfuscator UI ensures that all obfuscation rules are kept together and easily accessible. This makes it easy to manage and update the rules as needed and ensures that the rules are always saved with the project.

Last updated