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.
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.
Rule Element
The Rule element is used to define a Babel rule that can target one or more Babel Obfuscator features.
The Rule element accepts the following attributes:
| 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:
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:
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:
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.
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.
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
The option --rules can be entered multiple times on the command line to specify additional XML rules files.
MSBuild Babel Task
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
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.
Last updated
