DRAKVUF Sandbox is an automated black-box malware analysis system with DRAKVUF engine under the hood, which does not require an agent on guest OS.

This project provides you with a friendly web interface that allows you to upload suspicious files to be analyzed. Once the sandboxing job is finished, you can explore the analysis result through the mentioned interface and get an insight on whether the file is truly malicious or not.

Because it is usually pretty hard to set up a malware sandbox, this project also provides you with an installer app that would guide you through the necessary steps and configure your system using settings that are recommended for beginners. At the same time, experienced users can tweak some settings or even replace some infrastructure parts to better suit their needs.

Supported hardware & software

In order to run DRAKVUF Sandbox, your setup must fullfill all of the listed requirements:

  • Processor: Intel processor with VT-x and EPT features (how to check).
  • Host system: Debian 10 Buster/Ubuntu 18.04 Bionic/Ubuntu 20.04 Focal with at least 2 core CPU and 5 GB RAM, running GRUB as bootloader.
  • Guest system: Windows 7 (x64), Windows 10 (x64; experimental support)

Nested virtualization:

  • KVM does work, however it is considered experimental. If you experience any bugs, please report them to us for further investigation.
  • Due to lack of exposed CPU features, hosting DRAKVUF Sandbox in the cloud is not supported (although it might change in the future).
  • Hyper-V does not work.
  • Xen does work out of the box.
  • VMware Workstation Player does work, but you need to check Virtualize EPT option for a VM; Intel processor with EPT still required.

Basic installation

This instruction assumes that you want to create a single-node installation with the default components, which is recommended for beginners.

  • Download latest release packages.
  • Install DRAKVUF:

# apt update
# apt install ./drakvuf-bundle*.deb
# reboot

  • Install DRAKVUF Sandbox stack:

apt install redis-server
apt install ./drakcore.deb apt install ./drakrun.deb

  • Check if your Xen installation is compliant. This command should print “All tests passed”:

draksetup test

Execute:

draksetup install /opt/path_to_windows.iso

Read the command’s output carefully. This command will run a virtual machine with Windows system installation process.

Customize vCPUs/memory: You can pass additional options in order to customize number of vCPUs (--vcpus <number>) and amount of memory (--memory <num_mbytes>) per single VM. For instance: --vcpus 1 --memory 2048.

Recommended minimal values that are known to work properly with DRAKVUF Sandbox:

System versionMinimal vCPUsMinimal RAM
Windows 711536
Windows 1023072

Unattended installation: If you have autounattend.xml matching your Windows ISO, you can request unattended installation by adding --unattended-xml /path/to/autounattend.xml. Unattended install configuration can be generated with Windows Answer File Generator.

Use VNC to connect to the installation process:

vncviewer localhost:5900

  • Perform Windows installation until you are booted to the desktop.
  • Optional: At this point you might optionally install additional software. You can execute:
draksetup mount /path/to/some-cd.iso
  • which would mount a virtual CD disk containing additional software into your VM.
  • Optional: Generate .NET Framework native image cache by executing the following commands in the administrative prompt of your VM.
cd C:\Windows\Microsoft.NET\Framework\v4.0.30319
ngen.exe executeQueuedItems
cd C:\Windows\Microsoft.NET\Framework64\v4.0.30319
ngen.exe executeQueuedItems

In order to finalize the VM setup process, execute:

draksetup postinstall

Test your installation by navigating to the web interface ( http://localhost:6300/ ) and uploading some samples. The default analysis time is 10 minutes.

Optional Features

This sections contains various information about optional features that may be enabled when setting up DRAKVUF Sandbox.

ZFS storage backend

If you want to install DRAKVUF Sandbox with a ZFS storage backend, you should perform the following extra steps before executing draksetup install command:

  • Install ZFS on your machine (guide for: Debian Buster, Ubuntu 18.04)
  • Create a ZFS pool on a free partition
zpool create tank <partition_name>
  • where <partiton_name> is e.g. /dev/sda3. Be aware that all data stored on the selected partition may be erased.
  • Create a dataset for DRAKVUF Sandbox

Execute draksetup install as in “Basic installation” section, but remembering to provide additional command line switches:

–storage-backend zfs –zfs-tank-name tank/vms

Networking

Always:

  • Each instance of drakrun@<vm_id> will create a bridge drak<vm_id>, assign 10.13.<vm_id>.1/24 IP address/subnet to it and bring the interface up.
  • drakrun will drop any INPUT traffic originating from drak<vm_id> bridge, except DHCP traffic (UDP ports: 67, 68).

Only with net_enable=1:

  • drakrun will enable IPv4 forwarding.
  • drakrun will configure MASQUERADE through out_interface for packets originating from 10.13.<vm_id>.0/24.
  • drakrun will DROP traffic between drak<X> and drak<Y> bridges for X != Y.

In order to find out the exact details of the network configuration, search for _add_iptable_rule function usages in drakrun/drakrun/main.py file.

Basic networking

If you want your guest VMs to access Internet, you can enable networking by editing [drakrun] section in /etc/drakrun/config.ini:

  • Set net_enable=1 in order to enable guest Internet access.
  • Check if out_interface was detected properly (e.g. ens33) and if not, correct this setting.

After making changes to /etc/drakrun, you need to restart all drakrun services that are running in your system

Be aware that if your sandbox instance is already running some analyses, the above command will gracefully wait up to a few minutes until these are completed.

Using dnschef

You may optionally configure your guests to use dnschef.

  • Setup dnschef tool.
  • Start dnschef in such way to make it listen on all drak* interfaces that belong to DRAKVUF Sandbox.
  • Set dns_server=use-gateway-address in /etc/drakrun/config.ini.
  • Restart your drakrun instances: systemctl restart 'drakrun@*.

MS Office file support

There is an experimental support for analyzing word and excel samples. However this requires that you have Microsoft Office installed.

The steps below should be completed on guest vm before creating the snapshot (e.g. before you run draksetup postinstall). If you want to modify the existing snapshot, please refer to snapshot modification.

  • Install Microsoft Office. You can use draksetup mount /path/to/office.iso command to insert Office installation media during VM setup. After installation, you should be able to start word/excel by running start winword.exestart excel.exe from command line.
  • Adjust the registry keys by executing this .reg file:

ProcDOT integration

DRAKVUF Sandbox may optionally draw a behavioral graph using ProcDOT, if drakcore will find it’s binary installed at /opt/procdot/procmon2dot.

  • Download ProcDOT (Linux version).
  • With your downloaded procdot*_linux.zip archive, execute the following commands:
  • Your new analysis reports will also contain behavioral graphs.

Managing snapshots

Snapshot modification

Before trying to modify the installation, make sure that all drakrun@ services are stopped.

Execute drakplayground 0 as root. Output of the command should look similarly to this

dnsmasq: started, version 2.83 DNS disabled
dnsmasq: compile time options: IPv6 GNU-getopt DBus no-UBus i18n IDN2 DHCP DHCPv6 no-Lua TFTP conntrack ipset auth nettlehash DNSSEC loop-detect inotify dumpfile
dnsmasq-dhcp: DHCP, IP range 10.13.0.100 — 10.13.0.200, lease time 12h
dnsmasq-dhcp: DHCP, sockets bound exclusively to interface drak0
Loading new save file /var/lib/drakrun/volumes/snapshot.sav (new xl fmt info 0x3/0x0/2015)
Savefile contains xl domain config in JSON format
Parsing config from /etc/drakrun/configs/vm-0.cfg
xc: info: Found x86 HVM domain from Xen 4.15
xc: info: Restoring domain
xc: info: Restore successful
xc: info: XenStore: mfn 0xfeffc, dom 0, evt 1
xc: info: Console: mfn 0xfefff, dom 0, evt 2
*** Welcome to drakrun playground ***
Your VM is now ready and running with internet connection.
You can connect to it using VNC (password can be found in /etc/drakrun/scripts/cfg.template)
Run help() to list available commands
.

You will be dropped into a IPython shell, with vm-0 running and internet connection configured. At this point you can connect to VNC and perform the modifications. Don’t exit the shell or close the terminal.

If you have some scripts, executables or other files on the host, you can copy them into the VM with a helper function

Copied files should appear on the desktop.

When you’re done, open another terminal window and execute draksetup postinstall. The command will recreate the snapshot and profiles for other virtual machines.

It is now safe to close the shell. To do this execute

exit()

Importing and exporting snapshots

Current sandbox implemention allows for a single VM snapshot installed on a machine. However, it is possible to export and import snapshots from a remote server.

This is especially useful when running drakrun on multiple machines that should share same snapshot.

There are two types of snapshots: minimal and full. Before doing anything you should know which is appropriate for your usecase.

Minimal snapshot

Minimal snapshot contains only the most essential parts of the virtual machine which include HDD image and VM configuration.

This has both some advantages and drawbacks:

  • before using the snapshot on a new machine, VM must be cold booted to the desktop and draksetup postinstall must be executed to extract runtime information,
  • this snapshot type is more portable and stable as the operating system is being booted on the hardware that will be used for performing analyses.

Full snapshot

Full snapshots contain all of the data required by drakrun to work correctly. Apart from configuration and disk images they also contain compressed dumps of the VM’s physical memory and runtime information.

After importing a full snapshot no additional steps are required.

Scaling

Introduction

After performing installation, by default, your sandbox instance will be capable of processing one sample at a time. The service that performs the actual analysis is called drakrun@<instance_number>. You can check the state of a particular instance by executing:

systemctl status drakrun@1

You can change the number of parallel workers by executing:

Scaling up

Assuming you have a single instance but you want to be able to process 10 samples in parallel, you should execute:

draksetup scale 10

The setup script will configure and start additional instances named from drakrun@2 to drakrun@10.

Scaling down

Analogously, you can scale down by repeating the same command with the smaller number of instances, e.g.:

draksetup scale 7

Assuming you had 10 instances previously, it will cause drakrun@8 to drakrun@10 to be disabled and shut down. If the analysis is pending on these instances, the command will gracefully wait until it’s finished.

Postprocess

Analysis postprocessing doesn’t need hypervisor access, so it can be done in separate servers, assuming they have same configuration and connect to same minio & redis instances. This is highly recommended if you can afford such setup, as this frees resources on servers running hypervisor.

By default only 1 instance of postprocess worker is started and when running multiple instances of drakrun – needs to be scaled up. As a rule of thumb you can assume safe ratio of postprocess to drakrun workers to be 1:3 (however, this ratio can vary depending on performance of the platform and analysis duration). To startup more postprocessing instances just start more instances of drak-postprocess@ service. By default only 1 is present, so be sure to scale it accordingly to your needs.

Upgrading

We strive to make the installation and upgrade process as simple as possible, so in order to use a new version you have to perform just a few steps.

Before upgrading the sandbox, stop the sandbox workers:

systemctl stop drakrun@*

Install new packages and reboot:

apt install ./drakvuf-bundle.deb apt install ./drakrun.deb
apt install ./drakcore*.deb
systemctl reboot

Karton Integration

Connecting to existing karton system

In a simple installation, DRAKVUF Sandbox relies on services provided by the deb package and a local Redis instance. It is however possible to integrate it with a larger, karton-based pipeline. Doing this requires only a few steps:

  • Stop all drak-* services, if they’re running.
  • Open /etc/drakcore/config.ini and set system_disable=1 in section [drakmon]. This will disable local karton-system instance.
  • Copy Karton configuration to appropriate sections in /etc/drakcore/config.ini and /etc/drakrun/config.ini.
  • Restart all stopped services.

Building integrations

To create an integration, some familiarity with karton library is required. Here you can learn more about basic concepts such as tasks, headers or payloads.

Submitting samples from karton

In default configuration, drakrun services listen for tasks that contain headers:

  • type: sample
  • stage: recognized
  • platform: win32/win64

You can find an example here.

Analysis task structure

In default configuration, analysis tasks are guaranteed to have the following structure:Headers:

  • type: analysis
  • kind: drakrun

Payload:

  • sample – analyzed sample (Resource)
  • [plugin_name].log – DRAKVUF log emitted by given plugin (Resource)
    • present when the plugin was enabled and generated some output
  • dumps.zip – ZIP file containing extracted memory dumps (Resource)
  • dumps_metadata – List of dicts with keys: (list)
    • base_address – virtual base address of dump (in hexadecimal) (str)
    • filename – path to file inside the dump ZIP file, relative to root
  • dumps.pcap – Recorded network traffic (Resource)
  • wireshark_key_file.txt – (Resource)
    • present only when tlsmon was enabled and keys were successfully extracted
  • metadata – basic facts about analysis (dict);
    • sample_sha256 – hexencoded SHA256 sum of analyzed sample (str)
    • magic_output – libmagic output for the sample (str)
    • time_started – UNIX timestamp of analysis start (int)
    • time_finished – UNIX timestamp of analysis end (int)
    • snapshot_version – UNIX timestamp of VM snapshot (int)

Understanding the sandbox

Tech stack

DRAKVUF Sandbox is built on top of a few layers of software and hardware technologies:

  • Intel VT-x and EPT – extensions to x64 architecture that allow to run virtual machines natively on a CPU
  • Xen – hypervisor, spawns virtual machines and exposes interfaces for interaction and introspection
  • LibVMI – abstracts away introspection interfaces, provides utilities for reading/writing VM memory, parsing VMs’ kernel and handling notifications about certain events happening in a VM
  • DRAKVUF – stealthily hooks various parts of a guest VM and logs interesting events
  • DRAKVUF Sandbox – provides user friendly interface and high level analyses

Project structure

DRAKVUF Sandbox is divided into two packages:

  • drakcore – system core, provides a web interface, an internal task queue and object storage
  • drakrun – sandbox worker, wrapper for DRAKVUF, responsible for managing VMs, running analyses and sending results for further postprocessing.

DRAKVUF Sandbox is built around karton – microservice framework created at CERT Poland as a specialized tool for building flexible malware analysis pipelines. Its main goal is routing tasks between multiple services.

Daemons

  • drakcore package
    • drak-web – web interface that allows user to interact with the sandbox with either REST API or GUI
    • drak-system – internal task management system, using for dispatching jobs between workers
    • drak-minio – builtin object storage in which analysis results are stored
    • drak-postprocess – responsible for processing raw analysis logs into more usable form
  • drakrun package
    • drakrun 1..n – fetches incoming samples for analysis, runs VMs, and sends back results of analysis; each daemon handles one concurrent VM

Lifecycle of a analysis

  • User submits new analysis with a browser or programatically using karton API.
  • drak-system dispatches the job to one of the drakrun instances.
  • drakrun runs the analysis:
    • preconfigured virtual machine image is restored
    • sample is uploaded to the VM using DRAKVUF’s injector
    • sample is executed
    • after a chosen timeout, virtual machine is destroyed
  • Raw results (dumps, logs, pcaps) are sent back to drak-system as a karton task.
  • drak-system dispatches a task to drak-postprocess which extracts interesting data for the user

Sandbox development

DRAKVUF Sandbox is not a typical monolithic application. It is designed to be deployed over multiple servers either standalone or as a part of a larger karton system. Multiple components and daemons may be confusing at the beginning.

This is a quick tutorial that should help you when starting to develop the sandbox.

DRAKVUF Sandbox is based on karton framework. It is recommended to become familiar with its concepts before approaching the sandbox code.

High-level view of component interactions

Web UI (drakcore)

Serves as an GUI for the user for sample submission and browsing the results. Built with React and Hyper bootstrap theme.

Code location: drakcore/drakcore/frontend

Development

The prerequisite is to setup a working DRAKVUF Sandbox instance (MinIO, Redis, drakrun and API). Workflow is going to be similar to developing other React-based apps with a backend API. Don’t forget to run Prettier over the changes. Otherwise CI will reject your code.

cd drakcore/drakcore/frontend
$ # install dependencies (execute only the first time)
$ npm install
$ # point the application at a running instance of API server
$ export REACT_APP_API_SERVER=http://[API location]:6300/
$ # start serving the frontend with live reloading
$ npm start

REST API (drakcore)

Main entrypoint into the sandbox. The intended users are web UI and programmatic integrations with the sandbox.

Code location: drakcore/drakcore/app.py

Development

REST API is a simple Flask-based Python application. To work correctly it requires a configuration file (stored in /etc/drakcore/config.ini on a configured sandbox instance) to reach to Karton and drakrun workers. If you want to run the API server on a different machine than it is originally configured you may have to tweak it a little.

# Create python virtualenv
$ python -m venv venv
$ source env/bin/activate
$ cd drakcore
$ # Copy the configuration file to the same directory as config.dist.ini
$ cp /some/config.ini drakcore/config.ini
$ # Install drakcore dependencies
$ pip install -r requirements.txt
$ # Install drakcore in editable mode
$ pip install -e .
$ export FLASK_APP=drakcore/app.py
$ export FLASK_ENV=development
$ flask run

drakrun (drakrun)

This is the main component that manages the analysis process and the only one that has the requirement of being deployed on a machine (either virtual or physical) running Xen.

Code location: drakrun/drakrun

Development

This is the hardest part to develop as it has to be on a running on a separate machine. First, setup the basic environment in the repository

# Make sure that installed drakrun instance is not running
$ systemctl stop drakrun@1
$ # Create Python virtualenv
$ python -m venv venv
$ source env/bin/activate
$ cd drakrun
$ # Install drakrun dependencies
$ pip install -r requirements.txt
$ # Install drakrun in editable mode
$ pip install -e .
$ # Start drakrun
$ python drakrun/main.py 1

drakrun should start listening for new task from the rest of the system. After making some changes you have to restart the process.

To develop drakrun from your main development machine you can either:

  • mount the repository directory over SSHFS
  • use an IDE integration to edit remote files
  • (advanced) add the drakrun repository on a worker machine as another Git remote and push the changes

postprocessing (drakcore)

Hypervisor time is precious. This is why it’s important to perform as little work as possible in drakrun process. Analysis postprocessing extracts interesting data from DRAKVUF output and converts it into a form that is easier to consume by the frontend.

Development

On a drakrun machine:

# Make sure that the installed drak-postprocess instance is not running
$ systemctl stop drak-postprocess@1

Regression Testing

Introduction

Memory dumping is one of the core functionalities used for automated malware analysis. Unpacked or decrypted memory is saved for futher analysis with YARA rules or configuration extraction. Thus, it’s important to ensure that DRAKVUF development does cause any regressions that would break existing sample analysis.

Preparing a test set

Regression test set is a list of JSON objects that represent a number of sample submissions and the expected malware family name that should be detected.

Dump analysis is performed by providing a directory with malduck extractor modules. Here, you can learn more about them.

  • sha256 – SHA256 hash of the sample file
  • extension – file extension, supported by the sanbox, e.g. “exe” or “dll”
  • ripped – malware family name
  • path – (optional) path to the malware sample
[
    {
        "sha256": "35e756ef1b3d542deaf59f093bc4abe5282a1294f7144b32b61f4f60c147cabb",
        "extension": "dll",
        "ripped": "emotet"
    },
    {
        "sha256": "4239335443cbf3d45db485d33c13346c67d5ac717a57856315a166c190dde075",
        "extension": "exe",
        "ripped": "raccoon",
        "path": "samples/4239335443cbf3d45db485d33c13346c67d5ac717a57856315a166c190dde075"
    }

Test submitter supports two methods for obtaining the malware sample.

  • Manual – if the test case has a path key deinfed, malware sample will be read from this location (relative and absolute paths are allowed).
  • Automated – otherwise, sample will be downloaded from the mwdb.cert.pl service. Make sure to run the submitter with MWDB_API_KEY environment variable if you intend to use this method

Running the receiver daemon

First, configure the extractor module path in /etc/drakrun/config.ini

Building Installation Packages

In order to build installation packages on your own, you must first install Docker on your machine.

DRAKVUF Sandbox (drakcore, drakrun)

You may build your packages from source using following commands:

git clone https://github.com/CERT-Polska/drakvuf-sandbox.git
$ cd drakvuf-sandbox
$ sudo ./drakcore/package/build.sh
$ sudo ./drakrun/package/build.sh

Afterwards, you should find your installation packages produced in out/ directory.

DRAKVUF (drakvuf-bundle)

The build scripts for drakvuf-bundle are part of tklengyel/drakvuf repository. You may build your package using the following commands:

git clone --recursive https://github.com/tklengyel/drakvuf
$ cd drakvuf
$ sudo ./package/build.sh

The resulting package will be produced to package/out/ directory.

Using Drakpdb Tool

The drakpdb tool allows you to:

  • determine PDB name and GUID age given an executable file (e.g. DLL)
  • fetch PDB with given name and GUID age
  • parse PDB into a profile that could be plugged into DRAKVUF