Library

This page describes the retdec-python library and its API.

Organization

The base package is retdec. Everything that the library provides is inside this package.

Authentication

The library needs to authenticate you to retdec.com. To specify your API key, either pass it as a parameter when creating a resource:

decompiler = retdec.decompiler.Decompiler(api_key='YOUR-API-KEY')

or set the RETDEC_API_KEY environment variable:

$ export RETDEC_API_KEY=YOUR-API-KEY

An advantage of the environment variable is that you do not need to specify the API key every time you use the library:

decompiler = retdec.decompiler.Decompiler()

Error Handling

The library uses exceptions to signalize errors. The base class is retdec.exceptions.RetdecError, which you can use to catch all custom exceptions raised by the library:

try:
    # ...
except retdec.exceptions.RetdecError as ex:
    # Handle the error.

You can also catch specific exceptions, e.g. retdec.exceptions.AuthenticationError, and react on them. See the retdec.exceptions module for a list of all custom exceptions.

Decompiler

The retdec.decompiler module provides access to the decompilation service. It allows you to decompile binary files into a high-level language representation, such as C.

Creating a Decompiler

The decompiler is represented by the retdec.decompiler.Decompiler class:

decompiler = retdec.decompiler.Decompiler(api_key='YOUR-API-KEY')

Starting a Decompilation

To start a decompilation of a file, call start_decompilation() on the created decompiler:

decompilation = decompiler.start_decompilation(input_file=FILE)

FILE is either a path to the file or a file-like object. For a complete list of parameters that you can use when starting a decompilation, see the description of start_decompilation().

The returned object is an instance of retdec.decompilation.Decompilation.

Waiting For the Decompilation To Finish

After the start_decompilation() call above returns, the decompilation has been automatically started. To wait until it finishes, call wait_until_finished():

decompilation.wait_until_finished()

If you want to track the decompilation progress (e.g. by showing a progress bar or displaying the log), you can pass a callback function to wait_until_finished():

def show_progress(decompilation):
    print(decompilation.get_completion())

decompilation.wait_until_finished(
    callback=show_progress
)

When the status of the decompilation changes (e.g. it moves to another phase), the callback is automatically called with the decompilation being passed as its parameter.

Downloading Outputs

To obtain the generated high-level language (HLL) code as a string, call get_hll_code():

print(decompilation.get_hll_code())

Alternatively, you can call save_hll_code(), which obtains and saves the generated HLL code into the given directory:

decompilation.save_hll_code('/home/user/downloads')

Apart from obtaining the HLL code, you can also get the disassembled code, control-flow graphs, call graph, archive with all the outputs or, in the c mode, the compiled version of the input C file. See the description of Decompilation for more details.

For a complete example, take a look the retdec/tools/decompiler.py file. It is an implementation of the Decompiler script.

Fileinfo

The retdec.fileinfo module provides access to the file-analyzing service. It allows you to obtain information about binary files.

Creating an Analyzer

The analyzer is represented by the retdec.fileinfo.Fileinfo class:

fileinfo = retdec.fileinfo.Fileinfo(api_key='YOUR-API-KEY')

Starting an Analysis

To start an analysis of a file, call start_analysis() on the created analyzer with a file to be analyzed:

analysis = fileinfo.start_analysis(input_file=FILE)

FILE is either a path to the file or a file-like object. Optionally, you can pass the following parameters:

  • verbose=True – makes the analysis obtain all available information about the file.
  • output_format=json – causes the output from the analysis to be in the JSON format instead of in the plain format.

The returned object is an instance of retdec.analysis.Analysis.

Waiting For the Analysis To Finish

After the start_analysis() call above returns, the analysis has been automatically started. To wait until it finishes, call wait_until_finished():

analysis.wait_until_finished()

Obtaining the Results of the Analysis

To obtain the output from the analysis, call get_output():

print(analysis.get_output())

For a complete example, take a look at the retdec/tools/fileinfo.py file. It is an implementation of the Fileinfo script.

Test

Access to the testing service is provided by the retdec.test module.

Authentication

To check whether you can authenticate successfully, use retdec.test.Test.auth():

test = retdec.test.Test(api_key='YOUR-API-KEY')
try:
    test.auth()
    print('authentication succeeded')
except retdec.exceptions.AuthenticationError as ex:
    print('authentication failed:', ex)

Parameter Passing

To check that parameters are passed correctly when performing requests to the retdec.com API, use retdec.test.Test.echo():

test = retdec.test.Test(api_key='YOUR-API-KEY')
result = test.echo(param='value')
print(result)  # Prints {'param': 'value'}.