Configuration

CAPE relies on six main configuration files:

  • cuckoo.conf: for configuring general behavior and analysis options.

  • auxiliary.conf: for enabling and configuring auxiliary modules.

  • <machinery>.conf: for defining the options for your virtualization software

    (the file has the same name as the machinery module you choose in cuckoo.conf).

  • memory.conf: Volatility configuration.

  • processing.conf: for enabling and configuring processing modules.

  • reporting.conf: for enabling or disabling report formats.

  • routing.conf: for defining the routing of internet connection for the VMs.

To get CAPE working you have to edit auxiliary.conf, cuckoo.conf, and <machinery>.conf at least. We suggest you check all configs before starting, to be familiar with the possibilities that you have and what you want to be done.

Note

We recommend to you: create a custom/conf/ directory and put files in there whose names are the same as those in the top-level conf/ directory. These files only need to include settings that will override the defaults. In that way you won’t have problems with any upcoming changes to default configs.

To allow for further flexibility, you can also create a custom/conf/<type>.conf.d/ (e.g. custom/conf/reporting.conf.d/) directory and place files in there. Any file in that directory whose name ends in .conf will be read (in lexicographic order). The last value read for a value will be the one that is used.

Warning

Any section inside the configs that is marked #community at the top refers to a plugin that was developed by our community, but that doesn’t mean that we maintain it. Those plugins might be outdated or broken due to software/dependency changes. If you find anything like this broken, you are more than welcome to fix it and submit a pull request. The alternative is to switch off the offending plugin. Opening an issue for any of these is pointless as we don’t maintain them and cannot support them.

cuckoo.conf

The first file to edit is conf/cuckoo.conf, it contains the generic configuration options that you might want to verify before launching CAPE.

The file is largely commented and self-explaining, but some of the options you might want to pay more attention to are:

  • machinery in [cuckoo]: this defines which Machinery module you want CAPE to use to interact with your analysis machines. The value must be the name of the module without extension.

  • ip and port in [resultserver]: defines the local IP address and port that CAPE is going to use to bind the result server to. Make sure this matches the network configuration of your analysis machines, or they won’t be able to return the collected results.

  • connection in [database]: defines how to connect to the internal database. You can use any DBMS supported by SQLAlchemy using a valid Database Urls syntax.

Warning

Check your interface for resultserver IP! Some virtualization software (for example Virtualbox) doesn’t bring up the virtual networking interfaces until a virtual machine is started. CAPE needs to have the interface where you bind the resultserver up before the start, so please check your network setup. If you are not sure about how to get the interface up, a good trick is to manually start and stop an analysis virtual machine, this will bring virtual networking up. If you are using NAT/PAT in your network, you can set up the resultserver IP to 0.0.0.0 to listen on all interfaces, then use the specific options resultserver_ip and resultserver_port in <machinery>.conf to specify the address and port as every machine sees them. Note that if you set resultserver IP to 0.0.0.0 in cuckoo.conf you have to set resultserver_ip for all your virtual machines.

Note

Default freespace value is 50GB It is worth mentioning that the default freespace value in cuckoo.conf is 50000 MB aka 50 GB.

Please check the latest version of cuckoo.conf here: cuckoo.conf.

auxiliary.conf

Auxiliary modules are scripts that run concurrently with malware analysis, this file defines their options. Please see the latest version here: auxiliary.conf.

<machinery>.conf

Machinery modules are scripts that define how Cuckoo should interact with your virtualization software of choice.

Every module should have a dedicated configuration file that defines the details of the available machines. For example, if you created a kvm.py machinery module, you should specify kvm in conf/cuckoo.conf and have a conf/kvm.conf file.

CAPE provides some modules by default and for the sake of this guide, we’ll assume you’re going to use KVM. Please see the latest version here: kvm.conf.

If you are using KVM (kvm.conf), for each VM you want to use for analysis there must be a dedicated section. First you have to create and configure the VM (following the instructions in the dedicated chapter, see Preparing the Guest). The name of the section must be the same as the label of the VM as printed by $ virsh list --all. If no VMs are shown, you can execute the following command sequence: $ virsh, $ connect qemu:///system, $ list --all; or you can check this link to learn how to change the connection in Virtual Manager.

You can also find examples of other hypervisors like:

The comments for the options are self-explanatory.

You can use this same configuration structure for any other machinery module, although existing ones might have some variations or additional configuration options.

memory.conf

The Volatility tool offers a large set of plugins for memory dump analysis. Some of them are quite slow. In volatility.conf lets you enable or disable the plugins of your choice. To use Volatility you have to follow two steps:

  • Enable it in processing.conf

  • Enable memory_dump in cuckoo.conf

In the memory.conf’s basic section you can configure the Volatility profile and the deletion of memory dumps after processing:

# Basic settings
[basic]
# Profile to avoid wasting time identifying it
guest_profile = WinXPSP2x86
# Delete memory dump after volatility processing.
delete_memdump = no

After that every plugin has an own section for configuration:

# Scans for hidden/injected code and dlls
# http://code.google.com/p/volatility/wiki/CommandReference#malfind
[malfind]
enabled = on
filter = on

# Lists hooked api in user mode and kernel space
# Expect it to be very slow when enabled
# http://code.google.com/p/volatility/wiki/CommandReference#apihooks
[apihooks]
enabled = off
filter = on

The filter configuration helps you to remove known clean data from the resulting report. It can be configured separately for every plugin.

The filter itself is configured in the [mask] section. You can enter a list of pids in pid_generic to filter out processes:

# Masks. Data that should not be logged
# Just get this information from your plain VM Snapshot (without running malware)
# This will filter out unwanted information in the logs
[mask]
# pid_generic: a list of process ids that already existed on the machine before the malware was started.
pid_generic = 4, 680, 752, 776, 828, 840, 1000, 1052, 1168, 1364, 1428, 1476, 1808, 452, 580, 652, 248, 1992, 1696, 1260, 1656, 1156

Please see the latest version here: memory.conf.

processing.conf

This file allows you to enable, disable and configure all processing modules. These modules are located under modules/processing/ and define how to digest the raw data collected during the analysis.

You will find a section for each processing module here: processing.conf.

You might want to configure the VirusTotal key if you have an account of your own.

reporting.conf

The conf/reporting.conf file contains information on the automated reports generation. Please see the latest version here: reporting.conf.

By setting these options to on or off you enable or disable the generation of such reports.

routing.conf

The conf/routing.conf file contains information about how the guest VM is connected (or not) to the Internet via the Host, or whether it is isolated. This file is used in conjunction with the rooter.py utility.

Please see the latest version of routing.conf here: routing.conf.

You can read more about the routing.conf file and its options in the Per-Analysis Network Routing chapter and more about the rooter.py utility in the CAPE Rooter chapter.

Using environment variables in config files

Any of the above config files may reference environment variables in their values by using %(ENV:VARIABLE_NAME)s. For example, instead of putting a VirusTotal Intelligence API key in auxiliary.conf, you could use the following:

[virustotaldl]
enabled = yes
dlintelkey = %(ENV:DLINTELKEY)s

assuming the DLINTELKEY environment variable contains the API key.