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.
Rules Element
The Rules element defines a set of rules to be applied to the target assembly.
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.
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
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:
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
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.
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
TaskNameList
String
A comma-separated list of agent task names to which the rule applies.
cleanup attributes
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
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
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
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
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
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
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
