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.
Last updated
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.
Last updated
Babel rules files are XML files that contain the information used to customize the obfuscation process.
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:
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.
The Rules element defines a set of rules to be applied to the target assembly.
| Attribute | Description |
|---|---|
The Rule element is used to define a Babel rule that can target one or more Babel Obfuscator features.
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.
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:
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:
Follows the list of all possible Rule child elements
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.
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.
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:
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.
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:
It will catch symbols like methods, properties, fields and events of any serializable types.
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.
Restrict the rule to a specified namespace name.
The rule will be applied to all the symbols inside the ACME.Data namespace.
The Properties element defines a collection of XML elements to customize the selected rule feature behaviour.
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.
(*) Generates unverifiable IL code. If your assembly must run in a fully trusted environment, do not enable this option.
Any proper rule description. This will be displayed on the obfuscation log.
Rules files can be configured in Babel Obfuscator through the command line, the MSBuild Babel task, and the Babel User Interface.
The option --rules can be entered multiple times on the command line to specify additional XML rules files.
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:
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 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:
Open your Babel Obfuscator project in the Babel UI.
In the Input Grid, expand the row corresponding to the target assembly where you want to add the rule file.
Select the "Rules" tab and choose the first empty row in the underneath grid.
Click on the "..." button in the right-hand corner of the selected row.
Select the XML rules file you want to add from the opened file dialog.
Once you have selected the file, click on the "Open" button.
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:
Select the "Rules" item in the left navigation panel of the Babel UI.
In the "Rules" panel that appears, you will see a tree view of the symbols in your target assembly.
Right-click on a symbol node in the tree view to bring up a pop-up menu.
From the pop-up menu, select "Add Rule" to define a new obfuscation rule for that symbol.
Choose the obfuscation feature you want to apply to the rule from the submenu that appears.
Then from the secondary menu, select one of the predefined rules for that feature.
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.
| Attribute | Description |
|---|---|
| Feature | Description |
|---|---|
| Feature | Description |
|---|---|
| Element |
|---|
| Access | Description |
|---|---|
| Property | Type | Description |
|---|---|---|
| Property | Type | Description |
|---|---|---|
| Property | Type | Description |
|---|---|---|
| Property | Type | Description |
|---|---|---|
| Property | Type | Description |
|---|---|---|
| Property | Type | Description |
|---|---|---|
| Property | Type | Description |
|---|---|---|
| Property | Type | Description |
|---|---|---|