Scripting

Malcat features powerful python bindings which gives users access to most of the analysis result in a pythonic way. The bindings described below are available for the anomalies (cf. Anomaly scanner), for the summary templates (data/templates) and for user scripts (data/scripts) unless specified differently. Malcat python bindings also allow you to edit the file, add comments, define functions … basically everything you can do using the GUI.

How to script

Run a script from the user interface

Using Malcat’s built-in Script editor, you can edit and run python scripts against the currently analyzed file. If you open the Script editor using F8, it will display by default a toy script which will show you some basic usage of the bindings. The editor is based on Scintilla (like Notepad++).

../_images/script.png

The script editor window

Running a python script within the editor makes your life a bit easier, since your scripts will have directly access to a global varible named analysis. This variable contains the analysis result for the currently displayed file. So you won’t have to open a file and analyse it, it’s already done! Additionally, running a script from the editor offers two more advantages:

  • it has access to Additional GUI bindings which offer additional ways to interact with the GUI (like progress report, or opening new files in the GUI)

  • the script output window can display formated text with colors and clickable addresses (cf. malcat.UI.print())

Run Malcat from your python interpreter

With version 0.9.3 we have bundled Malcat’s binary analysis into a python module. The module is available in Full & Pro versions. Using the module you can use all Malcat’s analyses without having to run the GUI (aka headless scripting). That’s the way to go if you want to process large amount of files. Note that there are Legal restrictions when using the python module.

../_images/module.png

Using the python module

Setup

Malcat python module is located inside the <malcat install dir>/bin directory. In order to use the module from one of your python scripts, you have to make sure that it can be seen and imported by the python interpreter. There are three ways to achieve this:

  • Put your script inside <malcat install dir>/bin

  • Add <malcat install dir>/bin to sys.path before importing the Malcat module

  • Install the module into your (virtual) environment using the script <malcat install dir>/install_api.py [PREFERRED]

The later option is the preferred way, as it makes Malcat available to your scripts from everywhere. The script <malcat install dir>/install_api.py let you install the API in either your root python environment, your user environment or the current virtual environment.

$ python install_api.py --help
 Usage: install_api.py

 Install Malcat's module to your python (virtual) environment. This needs to be
 done only once (per environment). The script also allows you to
 activate/register Malcat on this computer if needed.

 Options:
   -h, --help            show this help message and exit
   -s, --silent          Non-interactive, use this option when running from
                         scripts
   -u, --uninstall       Uninstall Malcat
   -r, --install-on-root
                         Target is the system python environment
   -e, --install-on-pyenv
                         Target is the current python virtual environment
   -c LICENSE_KEY_OR_ACTIVATION_CODE, --code=LICENSE_KEY_OR_ACTIVATION_CODE
                         License key OR activation code to use for Malcat
                         activation (if needed). If not specified, will be
                         prompted from command line.
   -a, --activate-only   Don't install the API, only activate an already
                         installed Malcat
   -n, --no-activate     Don't check if malcat is activated or not, only
                         install

Note

The script will only add the directory <malcat install dir>/bin to the python’s environment, Malcat’s python module will not be copied over.

The script install_api.py also offers you to activate Malcat for you on this computer using either:

  • A license key (will perform an online activation)

  • An activation code (if the server is offline, see Activate the software)

The code can be given on the command line using the -c option. If not specified, the activation code / license will be asked interactively at run time.

Usage

Using malcat as a python module, you will have to start the analysis yourself using one of the following prototypes of the malcat.analyse() method (which are is available when you Run a script from the user interface):

malcat.analyse(path_to_file, options={}, use_file_mapping=False)

open a new file on disk and run all analyses. The set of analyses that will be computed can be modified using the options dictionnary. Return a malcat.Analysis instance on success, throws an exception on failure.

Parameters:
  • path_to_file (str) – path to the file to be analyzed

  • options (dict) – options to customize the analysis (see below)

  • use_file_mapping (bool) – if True, will mmap() the file instead of opening it (cf. Big file mode)

Return type:

malcat.Analysis

malcat.analyse(buffer, options={}, nice_name='<user buffer>')

open a new file from a memory buffer and run all analyses. The set of analyses that will be computed can be modified using the options dictionnary. Return a malcat.Analysis instance on success, throws an exception on failure.

Parameters:
  • buffer (bytes) – the file data

  • options (dict) – options to customize the analysis (see below)

  • nice_name (str) – the (arbitrary) malcat.File.name that will be given to the file

Return type:

malcat.Analysis

malcat.analyse(malcat_file, options={})

open a file and run all analyses. The set of analyses that will be computed can be modified using the options dictionnary. Return a malcat.Analysis instance on success, throws an exception on failure.

Parameters:
  • malcat_file (malcat.File) – the file

  • options (dict) – options to customize the analysis (see below)

Return type:

malcat.Analysis

The returned malcat.Analysis object is the same object you get when you Run a script from the user interface. Analyses can be customized using the options dictionnary. The options that you can change there are the same that you can find in the option dialog: Edit‣Preferences‣Analysis Setup (cf. Changing options). Most of them revolve around disabling part of the analysis, in order to save CPU time and/or memory space:

Analysis options

Name

Type

Description

num_threads

int

Maximum number of threads to use for the analysis. If not specified, the default is to use the number of cores of your CPU.

cons_disable

bool

Don’t run the Constant scanner (malcat.Analysis.constants will be empty)

flirt_disable

bool

Don’t apply FLIRT signatures

sign_disable

bool

Don’t scan for Yara signatures (malcat.Analysis.sigs will be empty)

anom_disable

bool

Don’t run the Anomaly scanner (malcat.Analysis.anomalies will be empty)

loop_disable

bool

Don’t run the Strongly Connected Components discovery (malcat.Analysis.loops will be empty)

cfg_disable

bool

Don’t perform any CFG reconstruction (malcat.Analysis.cfg will be empty)

cfg_disable_markov

bool

Don’t use markov models to refine the CFG reconstruction (cfg_disable must be set to False)

cfg_disable_linear_sweep

bool

Don’t try to scan for standard function prolog patterns during the CFG reconstruction (cfg_disable must be set to False)

cfg_disable_coderef_sweep

bool

Don’t follow code references during the CFG reconstruction (cfg_disable must be set to False)

cfg_disable_dataref_sweep

bool

Don’t follow data references during the CFG reconstruction (cfg_disable must be set to False)

func_disable

bool

Don’t perform any Functions recovery (malcat.Analysis.fns will be empty)

str_disable

bool

Don’t do any String analysis (malcat.Analysis.strings will be empty)

str_minsize

int

Minimal string size for the linear sweep string scanner

subf_disable

bool

Don’t perform any File carving (malcat.Analysis.carved will be empty)

dbg_disable

bool

Don’t extract debug metadata (it also includes python and .NET method detection)

xref_disable

bool

Don’t run the Cross References Scanner (malcat.Analysis.xref will be empty)

etpy_disable

bool

Don’t run the Entropy computation (malcat.Analysis.entropy will be empty). Disabling this will also disable md5/sha1/sha256 computation

etpy_resolution

int

Grain (i.e. window size) for the Entropy computation (defaults to 512)

Available objects

Base objects

Data analysis

Code analysis

Sub-files

Scanners

User annotations

Index