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:

  1. Stop all drak-* services, if they’re running.

  2. Open /etc/drakcore/config.ini and set system_disable=1 in section [drakmon]. This will disable local karton-system instance.

  3. Copy Karton configuration to appropriate sections in /etc/drakcore/config.ini and /etc/drakrun/config.ini.

  4. Restart all stopped services.

Note

Karton GC removes resources when they’re not referenced by any task. This is why analysis artifacts are stored in drakrun bucket instead of the one used by karton. Karton services that depend on the sandbox will also have to be granted access to this bucket.

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)

Here you can find an example analysis consumer.