Auxiliary Modules

Auxiliary modules define some procedures that need to be executed in parallel to every single analysis process. All auxiliary modules should be placed under the modules/auxiliary/ directory.

The skeleton of a module would look something like this:

1from lib.cuckoo.common.abstracts import Auxiliary
2
3class MyAuxiliary(Auxiliary):
4
5    def start(self):
6        # Do something.
7
8    def stop(self):
9        # Stop the execution.

The function start() will be executed before starting the analysis machine and effectively executing the submitted malicious file, while the stop() function will be launched at the very end of the analysis process, before launching the processing and reporting procedures.

For example, an auxiliary module provided by default in CAPE is called sniffer.py and takes care of executing tcpdump in order to dump the generated network traffic.

Auxiliary Module Configuration

Auxiliary modules can be “configured” before being started. This allows data to be added at runtime, whilst also allowing for the configuration to be stored separately from the CAPE python code.

Private Auxiliary Module Configuration

Private auxiliary module configuration is stored outside the auxiliary class, in a module under the same name as the auxiliary module. This is useful when managing configuration of auxiliary modules separately if desired, for privacy reasons or otherwise.

Here is a configuration module example that installs some software prior to the auxiliary module starting:

 1# data/auxiliary/example.py
 2import subprocess
 3import logging
 4from pathlib import Path
 5
 6log = logging.getLogger(__name__)
 7BIN_PATH = Path.cwd() / "bin"
 8
 9
10def configure(aux_instance):
11    # here "example" refers to modules.auxiliary.example.Example
12    if not aux_instance.enabled:
13        return
14    msi = aux_instance.options.get("example_msi")
15    if not msi:
16        return
17    msi_path = BIN_PATH / msi
18    if not msi_path.exists():
19        log.warning("missing MSI %s", msi_path)
20        return
21    cmd = ["msiexec", "/i", msi_path, "/quiet"]
22    try:
23        log.info("Executing msi package...")
24        subprocess.check_output(cmd)
25        log.info("Installation succesful")
26    except subprocess.CalledProcessError as exc:
27        log.error("Installation failed: %s", exc)
28        return