Obfuscation

The obfuscation translator is responsible for de-obfuscating the JZR recording.
De-obfuscation is applied on the stack traces contained in the JZR recording.

The translator relies on de-obfuscation plugins and property card mappers.

Configuration

These mappers and plugins have their own configuration file, referenced by the translator configuration file.
A default de-obfuscation translator configuration is provided in standard.
It is available in the analyzer/config/translators/obfuscation directory of your Jeyzer installation.

De-obfuscated files get stored in the directory and are by default deleted at the end of the analysis. Set the keep_files option to true to keep it.

<translator>
  <deobfuscation 
    enabled="true"
    directory="${JEYZER_RECORD_DIRECTORY}/deobfuscated"
    keep_files="false">

    <plugins>
      <plugin_set config_file="${JEYZER_ANALYZER_CONFIG_DIR}/translators/obfuscation/plugin_set.xml"/>
      ...
    </plugins>

    <property_card_mappers>
      <property_card_mapper_set config_file="${JEYZER_ANALYZER_CONFIG_DIR}/translators/obfuscation/property_card_mapper_set.xml"/>
       ...
    </property_card_mappers>

  </deobfuscation>
</translator>

.

De-obfuscation plugins

The de-obfuscation plugins are called sequentially : each one is responsible to de-obfuscate the processed stacks based on the mapping file (which was used originally to obfuscate the code).

Retrace-alt plugin
By default, Jeyzer is delivered with the Retrace alt plugin which permits to process stacks originally obfuscated with Proguard.
The Retrace implementation is under MIT license.

Plugin configuration

One XML plugin configuration file must be set per de-obfuscation.
For example, you would define one plugin configuration for an application and another one for a framework library.
The framework library plugin can therefore be referenced by other applications.

Plugins share a common set of parameters :

• id : the plugin identifier, used for logging.
• type : the plugin implementation. Use retrace-alt for Proguard.
• fail_if_config_not_found : controls the strictness of the underlying configuration file presence.
  Typically with property card mappers, invalid configuration files may be instantiated.
• abort_on_error : instructs if the analysis must abort or not in case the de-obfuscation failed for any reason.
  If set to true, the analysis will pursue anyway with obfuscated stack lines.
  This parameter is of interest if access to mapper configurations is not always available.

The plugin must reference one or more mapping files which will be loaded in the declaration order.
The mapping file path can contain variables resolved in this order:

• Jeyzer variables, which include the process card properties
• Process jar version variables (enclosed by the %% characters)
  From a process jar name, expand the process jar version taken out from the process jar paths file available in the JZR recording.
  Example : %%logback-core%%
• Process module version variables (enclosed by the ## characters)
  From a Java module name, expand its module version taken out from the process modules file available in the JZR recording.
  Example : ##ch.qos.logback.core##
• Property card mapper variables (enclosed by the @@ characters).
  See hereafter for details.

Note : variables that could not be resolved are kept as such in the path and a warning is emitted in the analysis log.

The first mapping file loaded successfully will be considered.
For example, the plugin could attempt to load a mapping file from a Nexus repository and then default on a local mapping file if not found.

Using a property card mapper property requires to reference its related mapper in the property_card_mappers list field.

<plugin
    id="${JEYZER_TARGET_PROFILE}" 
    type="retrace-alt" 
    fail_if_config_not_found="false"
    abort_on_error="true">
  <configurations>
    <config
      file="${JEYZER_REPOSITORY_MANAGER_URL}/@@module@@/@@module@@-@@version@@-@@build_number@@-proguard_map.txt" 
      property_card_mappers="mapper-name, mapper-version, mapper-build-number"/>
    <config
      file="${JEYZER_DEOBSFUCATION_CONFIG_DIR}/${jh.process.name}/library/proguard_map.txt"/>
  </configurations>
</plugin>

.

Property card mappers

Property card mappers are responsible for creating and providing de facto properties.

Those properties are used to build the plugin configuration access paths (see above).
These are referenced with the @@ prefix and suffix.

In practice, these properties will contain for example a product name, a version or a build number which will help to access the de-obfuscation mapping file.
Such information is available in the process card properties within a property value or property name.

The property card mapper will therefore work on the process card properties and extract the required piece(s) of data from it, to be exposed as new de facto properties.

Property card mapper configuration

One XML property card mapper configuration file should be set per target product or library.
The set of property card mappers of a library can therefore be referenced by other analysis profiles.

The property_card_mapper defines a mapper referenced by its name value.

The source_property is the process property card on which the mapper will work.

Each property must have :

• name : the property name.
  The name will be referenced within @@ in the plugin configuration.
• pattern : the capture pattern to apply on the source property.
  Use (.*) to copy the entire value.
• scope : the side of the source property to match against.
  Either property-name or property-value.

<property_card_mapper_set>

  <property_card_mapper name="mapper-version" source_property="jzr.process.version">
    <properties>
      <property name="version" pattern="(.*)" scope="property-value"/>
    </properties> 
  </property_card_mapper>

  <property_card_mapper 
    name="build_version_mapper"
    source_property="build.version-(.*)">
    <properties>
      <property 
         name="module"
         pattern="build.version-(.*)" 
         scope="property-name"/>
       <property 
         name="version" 
         pattern="(.*)"
         scope="property-value"/> 
    </properties>
  </property_card_mapper>
</property_card_mapper_set>