retdec package¶

Subpackages¶

retdec.tools package

Submodules¶

retdec.analysis module¶

A representation of fileinfo analyses.

class retdec.analysis.Analysis(id, conn)[source]¶

Bases: retdec.resource.Resource

A representation of a fileinfo analysis.

wait_until_finished(on_failure=<class 'retdec.exceptions.AnalysisFailedError'>)[source]¶

Waits until the analysis is finished.

Parameters:	on_failure (callable) – What should be done when the analysis fails?

If on_failure is None, nothing is done when the analysis fails. Otherwise, it is called with the error message. If the returned value is an exception, it is raised.

get_output()[source]¶: Obtains and returns the output from the analysis (str).

retdec.conn module¶

API connection.

class retdec.conn.APIConnection(base_url, api_key)[source]¶

Bases: object

Connection to the API.

Parameters:	base_url (str) – Base URL from which all subsequent URLs are constructed. api_key (str) – API key to be used for authentication.

The methods of this class may raise the following exceptions:

ConnectionError: When there is a connection error.
AuthenticationError: When the authentication fails.
UnknownAPIError: When there is an API error other than failed authentication.

send_get_request(path='', params=None)[source]¶

Sends a GET request to the given path with the given parameters.

Parameters:	path (str) – Path to which the request should be sent. params (dict) – Request parameters.
Returns:	Response from the API (parsed JSON).

If path is the empty string, it sends the request to the base URL from which the connection was initialized.

send_post_request(path='', params=None, files=None)[source]¶

Sends a POST request to the given path with the given parameters.

Parameters:	path (str) – Path to which the request should be sent. params (dict) – Request parameters. files (dict) – Request files.
Returns:	Response from the API (parsed JSON).

If path is the empty string, it sends the request to the base URL from which the connection was initialized.

get_file(path='', params=None)[source]¶

GETs a file from the given path with the given parameters.

Parameters:	path (str) – Path to which the request should be sent. params (dict) – Request parameters.
Returns:	File from path (`File`).

If path is the empty string, it sends the request to the base URL from which the connection was initialized.

retdec.decompilation module¶

A representation of decompilations.

class retdec.decompilation.DecompilationPhase(name, part, description, completion, warnings)[source]¶

Bases: object

Phase of a decompilation.

Parameters:	name (str) – Name of the phase. part (str) – Part into which the phase belongs. description (str) – Description of the phase. completion (int) – What percentage of the decompilation has been completed? warnings (list) – A list of warnings that were produced by the decompiler in the phase. Each warning is a string.

part may be None if the phase does not belong to any part.

name¶: Name of the phase (str).

part¶

Part to which the phase belongs (str).

May be None if the phase does not belong to any part.

description¶: Description of the phase (str).

completion¶: Completion (in percentages, 0-100).

warnings¶

A list of warnings that were produced by the decompiler in the phase.

Each warning is a string.

class retdec.decompilation.Decompilation(id, conn)[source]¶

Bases: retdec.resource.Resource

A representation of a decompilation.

get_completion()[source]¶

How much of the decompilation has been completed (in percentage)?

It is an int between 0 and 100.

get_phases()[source]¶: Obtains and returns the list of phases (DecompilationPhase).

wait_until_finished(callback=None, on_failure=<class 'retdec.exceptions.DecompilationFailedError'>)[source]¶

Waits until the decompilation is finished.

Parameters:	callback (callable) – Function to be called when the status of the decompilation is changed or when it finishes. on_failure (callable) – What should be done when the decompilation fails?

If callback is not None, it is called with the decompilation as its argument when the status of the decompilation is changed or when it finishes.

If on_failure is None, nothing is done when the decompilation fails. Otherwise, it is called with the error message. If the returned value is an exception, it is raised.

get_hll_code()[source]¶: Obtains and returns the decompiled code in the high-level language (str).

save_hll_code(directory=None)[source]¶

Saves the decompiled code in the high-level language to the given directory.

Parameters:	directory (str) – Path to a directory in which the decompiled code will be stored.
Returns:	Path to the saved file (str).

If directory is None, the current working directory is used.

get_dsm_code()[source]¶: Obtains and returns the disassembled input file in assembly-like syntax (str).

save_dsm_code(directory=None)[source]¶

Saves the disassembled input file in assembly-like syntax to the given directory.

Parameters:	directory (str) – Path to a directory in which the file will be stored.
Returns:	Path to the saved file (str).

If directory is None, the current working directory is used.

cg_generation_has_finished()[source]¶

Checks if the call-graph generation has finished.

Raises:	OutputNotRequestedError – When the call graph was not requested to be generated.

cg_generation_has_succeeded()[source]¶

Checks if the call-graph generation has succeeded.

Raises:	OutputNotRequestedError – When the call graph was not requested to be generated.

cg_generation_has_failed()[source]¶

Checks if the call graph has failed to generate.

Raises:	OutputNotRequestedError – When the call graph was not requested to be generated.

get_cg_generation_error()[source]¶

Returns the reason why the call graph failed to generate.

Raises:	OutputNotRequestedError – When the call graph was not requested to be generated.

If the call-graph generation has not failed, it returns None.

wait_until_cg_is_generated(on_failure=<class 'retdec.exceptions.CGGenerationFailedError'>)[source]¶

Waits until the call graph is generated.

Parameters:	on_failure (callable) – What should be done when the generation fails?
Raises:	OutputNotRequestedError – When the call graph was not requested to be generated.

If on_failure is None, nothing is done when the generation fails. Otherwise, it is called with the error message. If the returned value is an exception, it is raised.

save_cg(directory=None)[source]¶

Saves the call graph to the given directory.

Parameters:	directory (str) – Path to a directory in which the file will be stored.
Returns:	Path to the saved file (str).

If directory is None, the current working directory is used.

funcs_with_cfg¶

A list of names of functions having a control-flow graph.

The returned list does not depend on the control-flow-graph-generation status. It always returns the same function names, disregarding whether their control-flow graph has or has not been generated.

The returned list is ordered by function names.

Raises:	OutputNotRequestedError – When control-flow graphs were not requested to be generated.

cfg_generation_has_finished(func)[source]¶

Checks if the generation of a control-flow graph for the given function has finished.

Parameters:	func (str) – Name of the function.
Raises:	OutputNotRequestedError – When control-flow graphs were not requested to be generated. NoSuchCFGError – When there is no control-flow graph for the given function.

cfg_generation_has_succeeded(func)[source]¶

Checks if the generation of a control-flow graph for the given function has succeeded.

Parameters:	func (str) – Name of the function.
Raises:	OutputNotRequestedError – When control-flow graphs were not requested to be generated. NoSuchCFGError – When there is no control-flow graph for the given function.

cfg_generation_has_failed(func)[source]¶

Checks if the generation of a control-flow graph for the given function has failed.

Parameters:	func (str) – Name of the function.
Raises:	OutputNotRequestedError – When control-flow graphs were not requested to be generated. NoSuchCFGError – When there is no control-flow graph for the given function.

get_cfg_generation_error(func)[source]¶

Returns the reason why the control-flow graph for the given function failed to generate.

Parameters:	func (str) – Name of the function.
Raises:	OutputNotRequestedError – When control-flow graphs were not requested to be generated. NoSuchCFGError – When there is no control-flow graph for the given function.

If the control-flow-graph generation has not failed, it returns None.

wait_until_cfg_is_generated(func, on_failure=<class 'retdec.exceptions.CFGGenerationFailedError'>)[source]¶

Waits until the control-flow graph for the given function is generated.

Parameters:	func (str) – Name of the function. on_failure (callable) – What should be done when the generation fails?
Raises:	OutputNotRequestedError – When control-flow graphs were not requested to be generated. NoSuchCFGError – When there is no control-flow graph for the given function.

If on_failure is None, nothing is done when the generation fails. Otherwise, it is called with the error message. If the returned value is an exception, it is raised.

save_cfg(func, directory=None)[source]¶

Saves the control-flow graph for the given function to the given directory.

Parameters:	func (str) – Name of the function. directory (str) – Path to a directory in which the file will be stored.
Returns:	Path to the saved file (str).

If directory is None, the current working directory is used.

archive_generation_has_finished()[source]¶

Checks if the archive generation has finished.

Raises:	OutputNotRequestedError – When the archive was not requested to be generated.

archive_generation_has_succeeded()[source]¶

Checks if the archive generation has succeeded.

Raises:	OutputNotRequestedError – When the archive was not requested to be generated.

archive_generation_has_failed()[source]¶

Checks if the archive has failed to generate.

Raises:	OutputNotRequestedError – When the archive was not requested to be generated.

get_archive_generation_error()[source]¶

Returns the reason why the archive failed to generate.

Raises:	OutputNotRequestedError – When the archive was not requested to be generated.

If the archive has not failed, it returns None.

wait_until_archive_is_generated(on_failure=<class 'retdec.exceptions.ArchiveGenerationFailedError'>)[source]¶

Waits until the archive containing all outputs from the decompilation is generated.

Parameters:	on_failure (callable) – What should be done when the generation fails?
Raises:	OutputNotRequestedError – When the archive was not requested to be generated.

If on_failure is None, nothing is done when the generation fails. Otherwise, it is called with the error message. If the returned value is an exception, it is raised.

save_archive(directory=None)[source]¶

Saves the archive containing all outputs from the decompilation to the given directory.

Parameters:	directory (str) – Path to a directory in which the file will be stored.
Returns:	Path to the saved file (str).

If directory is None, the current working directory is used.

save_binary(directory=None)[source]¶

Saves the compiled version of the input C file (provided that the input was a C file) to the given directory.

Parameters:	directory (str) – Path to a directory in which the file will be stored.
Returns:	Path to the saved file (str).

If directory is None, the current working directory is used.

retdec.decompiler module¶

Access to the decompiler (decompilation of files).

class retdec.decompiler.Decompiler(*, api_key=None, api_url=None)[source]¶

Bases: retdec.service.Service

Access to the decompilation service.

start_decompilation(**kwargs)[source]¶

Starts a decompilation with the given parameters.

Parameters:

input_file (str or file-like object) – File to be analyzed (required).
pdb_file (str or file-like object) – A PDB file associated with input_file containing debugging information.
mode (str) – Decompilation mode.
target_language (str) – Target high-level language.
graph_format (str) – Format of the generated call and control-flow graphs.
decomp_var_names (str) – Naming style for variables.
decomp_optimizations (str) – Level of optimizations performed by the decompiler.
decomp_unreach_funcs (bool) – Should all functions be decompiled, even if they are not reachable from the main function?
decomp_emit_addresses (bool) – Should addresses in comments be emitted in the generated code?
architecture (str) – Architecture. The precise meaning depends on the used mode.
file_format (str) – File format. File format to be used when compiling input C source files.
comp_compiler (str) – Compiler to be used when compiling input C source files.
comp_optimizations (str) – Compiler optimizations to be used when compiling input C source files.
comp_debug (bool) – Should the input C source file be compiled with debugging information?
comp_strip (bool) – Should the compiled input C source file be stripped?
sel_decomp_funcs (str/iterable) – Decompile only the selected functions. It can be either an iterable of function names (e.g. ['func1', 'func2']) or a string with comma-separated function names (e.g. 'func1, func2').
sel_decomp_ranges (str/iterable) – Decompile only the selected address ranges. It can be either an iterable of ranges (e.g. [(0x100, 0x200), (0x400, 0x500)]) or a string with comma-separated ranges (e.g. '0x100-0x200,0x400-0x500').
sel_decomp_decoding (str) – What instructions should be decoded when either sel_decomp_funcs or sel_decomp_ranges is given?
endian (str) – Endianness of the machine code ('little' or 'big'). Only for the raw mode.
raw_entry_point (str) – Virtual memory address where execution flow should start in the raw machine code. Only for the raw mode.
raw_section_vma (str) – Address where the section created from the raw machine code will be placed in virtual memory. Only for the raw mode.
ar_index (int/str) – Index of the object file in the input archive to be decompiled when decompiling an archive.
ar_name (str) – Name of the object file in the input archive to be decompiled when decompiling an archive.
generate_cg (bool) – Should a call graph be generated?
generate_cfgs (bool) – Should control-flow graphs for all functions be generated?
generate_archive (bool) – Should an archive containing all outputs from the decompilation be generated?

Returns:

Started decompilation (Decompilation).

If mode is not given, it is automatically determined based on the name of input_file. If the input file ends with .c or .C, the mode is set to c. Otherwise, the mode is set to bin.

See the official documentation for more information about the parameters.

retdec.exceptions module¶

Custom exceptions raised by the library.

exception retdec.exceptions.RetdecError[source]¶

Bases: Exception

Base class of all custom exceptions raised by the library.

exception retdec.exceptions.MissingAPIKeyError[source]¶

Bases: retdec.exceptions.RetdecError

Exception raised when an API key is missing.

exception retdec.exceptions.MissingParameterError(name)[source]¶

Bases: retdec.exceptions.RetdecError

Exception raised when a required parameter is not set.

Parameters:	name (str) – Name of the missing parameter.

exception retdec.exceptions.InvalidValueError(name, value)[source]¶

Bases: retdec.exceptions.RetdecError

Exception raised when a parameter has an invalid value.

Parameters:	name (str) – Name of the parameter whose value is invalid. value – The invalid value.

exception retdec.exceptions.AuthenticationError[source]¶

Bases: retdec.exceptions.RetdecError

Exception raised when authentication with the provided API key fails.

exception retdec.exceptions.ConnectionError[source]¶

Bases: retdec.exceptions.RetdecError

Exception raised when there is a connection error.

exception retdec.exceptions.AnalysisFailedError[source]¶

Bases: retdec.exceptions.RetdecError

Exception raised when a fileinfo analysis has failed.

exception retdec.exceptions.DecompilationFailedError[source]¶

Bases: retdec.exceptions.RetdecError

Exception raised when a decompilation has failed.

exception retdec.exceptions.OutputNotRequestedError[source]¶

Bases: retdec.exceptions.RetdecError

Exception raised when an output is queried which was not requested to be generated.

exception retdec.exceptions.CGGenerationFailedError[source]¶

Bases: retdec.exceptions.RetdecError

Exception raised when the generation of a call graph fails.

exception retdec.exceptions.CFGGenerationFailedError[source]¶

Bases: retdec.exceptions.RetdecError

Exception raised when the generation of a control-flow graph fails.

exception retdec.exceptions.NoSuchCFGError(func)[source]¶

Bases: retdec.exceptions.RetdecError

Exception raised when a control-flow graph for a non-existing function is requested.

Parameters:	func (str) – Name of the function whose control-flow graph was requested.

exception retdec.exceptions.ArchiveGenerationFailedError[source]¶

Bases: retdec.exceptions.RetdecError

Exception raised when the generation of an archive fails.

exception retdec.exceptions.UnknownAPIError(code, message, description)[source]¶

Bases: retdec.exceptions.RetdecError

Exception raised when there is an unknown API error.

Parameters:	code (int) – Error code. message (str) – Short message describing what went wrong. description (str) – Longer description of what went wrong.

code¶: Error code (int).

message¶: Short message describing what went wrong (str).

description¶: Longer description of what went wrong (str).

retdec.file module¶

Representation of a file.

class retdec.file.File(file, name=None)[source]¶

Bases: object

Representation of a file.

Parameters:	object file (str/file-like) – Either path to the file (str) or an opened file (a file-like object). name (str) – Name of the file to be used.

When name is not given or it is None, the name is taken from file. You can use name to set a custom file name that may be different from the real file’s name.

name¶

Name of the file (str).

May be None if the file has no name.

mode¶

Mode in which the file is opened.

If the file does not have a mode, it returns None.

retdec.fileinfo module¶

Access to the file-analyzing service (fileinfo).

class retdec.fileinfo.Fileinfo(*, api_key=None, api_url=None)[source]¶

Bases: retdec.service.Service

Access to the file-analyzing service.

start_analysis(**kwargs)[source]¶

Starts an analysis with the given parameters.

Parameters:	input_file (str or file-like object) – File to be analyzed (required). output_format (str) – Format of the output from the analysis. verbose (bool) – Should the analysis produce a detailed output?
Returns:	Started analysis (`Analysis`).

retdec.resource module¶

Base class of all resources.

class retdec.resource.Resource(id, conn)[source]¶

Bases: object

Base class of all resources.

Parameters:	id (str) – Unique identifier of the resource. conn (retdec.conn.APIConnection) – Connection to the API to be used for sending API requests.

id¶: Unique identifier of the resource.

is_pending()[source]¶

Is the resource in a pending state?

A resource is pending if it is scheduled to run but has not started yet.

is_running()[source]¶: Is the resource currently running?

has_finished()[source]¶: Has the resource finished?

has_succeeded()[source]¶: Has the resource succeeded?

has_failed()[source]¶

Has the resource failed?

For finished resources, this is always the negation of has_succeeded().

get_error()[source]¶

Returns the reason why the resource failed.

If the resource has not failed, it returns None.

retdec.service module¶

Base class of all services.

class retdec.service.Service(*, api_key=None, api_url=None)[source]¶

Bases: object

Base class of all services.

Parameters:	api_key (str) – API key to be used for authentication. api_url (str) – URL to the API.

api_key¶: API key that is being used for authentication (str).

api_url¶: URL to the API (str).

retdec.test module¶

Access to the testing service.

class retdec.test.Test(*, api_key=None, api_url=None)[source]¶

Bases: retdec.service.Service

Access to the testing service.

auth()[source]¶

Tries to authenticate.

Raises:	AuthenticationError – When the authentication fails.

Does nothing when the authentication succeeds.

echo(**kwargs)[source]¶

Echoes the given parameters.

Returns:	Echoed kwargs (dict).
Raises:	AuthenticationError – When the authentication fails.

Module contents¶

The main package of a Python library and tools providing easy access to the retdec.com decompilation service through their public REST API.

retdec.DEFAULT_API_URL = 'https://retdec.com/service/api'¶: Default API URL.