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'}.