Cuckoo Sandbox

Malware dynamic analysis sandboxing.

Forensics & Malware Analysis · Cuckoo Sandbox

Details

IDCuckoo Sandbox
ProviderOpen Source
CategoryForensics & Malware Analysis
From Version5.0.0
Supported ModulesAgentix XSIAM EDR Cortex Cloud Cloud Runtime Security

README

Overview

This integration was integrated and tested with Cuckoo Sandbox v2.0.7.

Cuckoo Sandbox Playbook

  • CuckooDetonateFile: Gets a file and detonates it on Cuckoo, returns report when available.
  • CuckooDetonateURL: Gets a URL and detonates it on Cuckoo, returns report when available.
  • CuckooGetScreenshots: Gets a taskID of Cuckoo's investigation and returns zipped screenshots

Use Cases

  • Analyze files and URLs in a safe environment (sandbox)
  • View Cuckoo's tasks and machines

Configure Cuckoo Sandbox on Cortex XSOAR

  1. Navigate to Settings > Integrations > Servers & Services.
  2. Search for Cuckoo Sandbox.
  3. Click Add instance to create and configure a new integration instance.
    • Name: a textual name for the integration instance.
    • Server URL (e.g. https://192.168.0.1)
    • Username (Only if your Cuckoo service requires HTTP auth)
    • In order to authenticate with an API token, insert '__token' in the "Username" textbox, and the token itself in the "Password" textbox.
    • Trust any certificate (not secure)
    • Use system proxy settings
  4. Click Test to validate the URLs, token, and connection.

Commands

You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

  1. Create a task from a file: cuckoo-create-task-from-file
  2. Get a task report: cuckoo-get-task-report
  3. Get a list of all tasks: cuckoo-list-tasks
  4. Submit a URL for analysis: cuckoo-create-task-from-url
  5. Get task information: cuckoo-view-task
  6. Delete a task: cuckoo-delete-task
  7. Get analysis screenshots: cuckoo-task-screenshot
  8. Get a list of analysis machines: cuckoo-machines-list
  9. Get analysis machine information: cuckoo-machine-view

1. Create a task from a file


Retrieves a file's entry ID and creates a task with it.

Base Command
cuckoo-create-task-from-file
Input
Argument Name Description Required
entryID File entry ID Optional
fileID File ID Optional
machine Label of the machine to use for analysis Optional
package Analysis package to be used for the analysis Optional
timeout Analysis timeout (in seconds) Optional
enforce_timeout Enable to enforce the execution for the full timeout value Optional
platform Name of the platform to select the analysis machine from (e.g., “windows”) Optional
tags Define machine to start by tags. Platform must be set to use that. Tags are comma-separated Optional
memory Enables the creation of a full memory dump of the analysis machine Optional
options Options to pass to the analysis package Optional
 
Context Output
Path Description
Cuckoo.Task.ID ID of the task
 
Command Example
!cuckoo-create-task-from-file entryID=814@a969c6ba-e443-4287-8dce-378aa183e2d5
Context Example

image

Human Readable Output

image

2. Get a task report


Retrieves a task report by a task ID.

Base Command
cuckoo-get-task-report
Input
Argument Name Description Required
id Task ID Required
 
Context Output
Path Description
Cuckoo.Task.Category Category of task
Cuckoo.Task.Machine Machine of task
Cuckoo.Task.Errors Errors of task
Cuckoo.Task.Target Target of task
Cuckoo.Task.Package Package of task
Cuckoo.Task.SampleID Sample ID of task
Cuckoo.Task.Guest Task guest
Cuckoo.Task.Custom Custom values of task
Cuckoo.Task.Owner Task owner
Cuckoo.Task.Priority Priority of task
Cuckoo.Task.Platform Platform of task
Cuckoo.Task.Options Task options
Cuckoo.Task.Status Task status
Cuckoo.Task.EnforceTimeout Is timeout of task enforced
Cuckoo.Task.Timeout Task timeout
Cuckoo.Task.Memory Task memory
Cuckoo.Task.Tags Task tags
Cuckoo.Task.ID ID of task
Cuckoo.Task.AddedOn Date the task was added
Cuckoo.Task.CompletedOn Date the task was completed
Cuckoo.Task.Score Reported score of the the task
Cuckoo.Task.Monitor Monitor of the reported task
Cuckoo.Task.FileInfo.sha1 The SHA1 hash of the file.
Cuckoo.Task.FileInfo.name The file name.
Cuckoo.Task.FileInfo.type The file type.
Cuckoo.Task.FileInfo.sha256 The SHA256 hash of the file.
Cuckoo.Task.FileInfo.urls Related URLs of the file.
Cuckoo.Task.FileInfo.crc32 The CRC32 of the file.
Cuckoo.Task.FileInfo.path The file path.
Cuckoo.Task.FileInfo.ssdeep The ssdeep of the file.
Cuckoo.Task.FileInfo.size The size of the file.
Cuckoo.Task.FileInfo.sha512 The SHA512 hash of the file.
Cuckoo.Task.FileInfo.md5 The MD5 hash of the file.
 
Command Example
!cuckoo-get-task-report id=86
Context Example

image

Human Readable Output

image

3. Get a list of all tasks


Returns a list of all tasks.

Base Command
cuckoo-list-tasks
Input

There is no input for this command.

Context Output
Path Description
Cuckoo.Task.Category Category of task
Cuckoo.Task.Machine Machine of task
Cuckoo.Task.Errors Errors of task
Cuckoo.Task.Target Target of task
Cuckoo.Task.Package Package of task
Cuckoo.Task.SampleID Sample ID of task
Cuckoo.Task.Guest Task guest
Cuckoo.Task.Custom Custom values of task
Cuckoo.Task.Owner Task owner
Cuckoo.Task.Priority Priority of task
Cuckoo.Task.Platform Platform of task
Cuckoo.Task.Options Task options
Cuckoo.Task.Status Task status
Cuckoo.Task.EnforceTimeout Is timeout of task enforced
Cuckoo.Task.Timeout Task timeout
Cuckoo.Task.Memory Task memory
Cuckoo.Task.Tags Task tags
Cuckoo.Task.ID ID of task
Cuckoo.Task.AddedOn Date the task was added
Cuckoo.Task.CompletedOn Date the task was completed
 
Command Example
!cuckoo-list-tasks
Context Example

image

Human Readable Output

image

4. Submit a URL for analysis


Submits a URL to Cuckoo Sandbox for analysis.

Notice: Submitting indicators using this command might make the indicator data publicly available. See the vendor’s documentation for more details.

Base Command
cuckoo-create-task-from-url
Input
Argument Name Description Required
url URL to analyze Required
 
Context Output
Path Description
Cuckoo.Task.ID Task ID
 
Command Example
!cuckoo-create-task-from-url url=google.com
Context Example

image

Human Readable Output

image

5. Get task information


Returns information for a specified task.

Base Command
cuckoo-view-task
Input
Argument Name Description Required
id A comma-separated list of task IDs for which to retrieve information. Required
 
Context Output
Path Description
Cuckoo.Task.Category Category of task
Cuckoo.Task.Machine Machine of task
Cuckoo.Task.Errors Errors of task
Cuckoo.Task.Target Target of task
Cuckoo.Task.Package Package of task
Cuckoo.Task.SampleID Sample ID of task
Cuckoo.Task.Guest Task guest
Cuckoo.Task.Custom Custom values of task
Cuckoo.Task.Owner Task owner
Cuckoo.Task.Priority Priority of task
Cuckoo.Task.Platform Platform of task
Cuckoo.Task.Options Task options
Cuckoo.Task.Status Task status
Cuckoo.Task.EnforceTimeout Is timeout of task enforced
Cuckoo.Task.Timeout Task timeout
Cuckoo.Task.Memory Task memory
Cuckoo.Task.Tags Task tags
Cuckoo.Task.ID ID of task
Cuckoo.Task.AddedOn Date the task was added
Cuckoo.Task.CompletedOn Date the task was completed
 
Command Example

!cuckoo-view-task id=88

Context Example

image

Human Readable Output

image

6. Delete a task


Deletes a task from Cuckoo Sandbox.

Base Command
cuckoo-delete-task
Input
Argument Name Description Required
id Task ID Required
 
Context Output

There is no context output for this command.

Command Example
!cuckoo-delete-task id=88

7. Get analysis screenshots


Retrieves screenshots taken during a task analysis. If the screenshot number argument is omitted, the command retrieves a ZIP file with all screenshots.

Base Command

cuckoo-task-screenshot

Input
Argument Name Description Required
id ID of the task that generated the screenshot Required
screenshot Numerical identifier of a single screenshot (e.g., 0001, 0002) Optional
 
Context Output
Path Description
File.Size Size of file
File.SHA1 File SHA-1
File.SHA256 File SHA-256
File.Name File name
File.SSDeep File SSDeep
File.EntryID File entry ID
File.Info File info
File.Type File type
File.MD5 File MD5
File.Extension File extension
 
Command Example
!cuckoo-task-screenshot id=90
Context Example

image

Human Readable Output

image

8 Get a list of analysis machines


Returns a list with details on the analysis machines available to Cuckoo.

Base Command
cuckoo-machines-list
Input

There is no input for this command.

Context Output
Path Description
Machine.Status Status of machine
Machine.Locked Is the machine locked
Machine.Name Name of machine
Machine.ResultserverIP IP address of machine's result server
Machine.IP IP address of machine
Machine.Label Label of the machine
Machine.LockedChangedOn Last update time of machine lock status
Machine.Platform Platform of the machine
Machine.Snapshot Snapshot
Machine.Interface Interface of machine
Machine.StatusChangedOn Last update time of machine status
Machine.ID ID of machine
Machine.ResultserverPort Port address of machine's result server
Machine.Tags Machine tags
 
Command Example
!cuckoo-machines-list
Context Example

image

Human Readable Output

image

9. Get analysis machine information


Returns details about the analysis machine associated with the specified machine name.

Base Command
cuckoo-machine-view
Input
Argument Name Description Required
name Name of machine to get information for Required
 
Context Output
Path Description
Machine.Status Status of machine
Machine.Locked Is the machine locked
Machine.Name Name of machine
Machine.ResultserverIP IP address of machine's result server
Machine.IP IP address of machine
Machine.Label Label of machine
Machine.LockedChangedOn last update time of machine lock status
Machine.Platform Platform of machine
Machine.Snapshot Snapshot
Machine.Interface Interface of machine
Machine.StatusChangedOn Last update time of machine status
Machine.ID ID of machine
Machine.ResultserverPort Port address of machine's result server
Machine.Tags Machine tags
 
Command Example
!cuckoo-machine-view name=windowsxp
Context Example

image

Human Readable Output

image

Configuration parameters

  • server — Server URL (e.g. https://192.168.0.1)
  • authentication — Username (Only if your cuckoo service requires HTTP auth)
  • insecure — Trust any certificate (not secure)
  • proxy — Use system proxy settings

Commands (18)

  • ck-del Deprecated

    commands.server.ckDelete.description

  • ck-file Deprecated

    commands.server.ckFile.description

  • ck-list Deprecated

    commands.server.ckList.description

  • ck-machine-view Deprecated

    Returns details on the analysis machine associated with the given name.

  • ck-machines-list Deprecated

    Returns a list with details on the analysis machines available to Cuckoo.

  • ck-report Deprecated

    commands.server.ckReport.description

  • ck-scrshot Deprecated

    Retrieve screenshots taken during analysis. If the screenshot number argument is omitted, retrieves a zip file with all screenshots.

  • ck-url Deprecated

    Submit a URL for analysis

  • ck-view Deprecated

    commands.server.ckView.description

  • cuckoo-create-task-from-file

    commands.server.ckFile.description

  • cuckoo-create-task-from-url

    Submit a URL for analysis

  • cuckoo-delete-task

    commands.server.ckDelete.description

  • cuckoo-get-task-report

    commands.server.ckReport.description

  • cuckoo-list-tasks

    commands.server.ckList.description

  • cuckoo-machine-view

    Returns details on the analysis machine associated with the given name.

  • cuckoo-machines-list

    Returns a list with details on the analysis machines available to Cuckoo.

  • cuckoo-task-screenshot

    Retrieve screenshots taken during analysis. If the screenshot number argument is omitted, retrieves a zip file with all screenshots.

  • cuckoo-view-task

    commands.server.ckView.description

var entityMap = {
    Machine:{
        status :            'Status',
        locked :            'Locked',
        name :              'Name',
        resultserver_ip :   'ResultserverIP',
        ip :                'IP',
        label :             'Label',
        locked_changed_on : 'LockedChangedOn',
        platform :          'Platform',
        snapshot :          'Snapshot',
        interface :         'Interface',
        status_changed_on : 'StatusChangedOn',
        id :                'ID',
        resultserver_port : 'ResultserverPort',
        tags :              'Tags'
    },
    Task: {
        category  :         'Category',
        machine :           'Machine',
        errors :            'Errors',
        target :            'Target',
        package :           'Package',
        sample_id :         'SampleID',
        guest :             'Guest',
        custom :            'Custom',
        owner :             'Owner',
        priority :          'Priority',
        platform :          'Platform',
        options :           'Options',
        status :            'Status',
        enforce_timeout :   'EnforceTimeout',
        timeout :           'Timeout',
        memory :            'Memory',
        tags :              'Tags',
        id :                'ID',
        added_on :          'AddedOn',
        completed_on :      'CompletedOn',
        score :             'Score',
        monitor :           'Monitor',
        FileInfo :          'FileInfo'

    },
    FileInfo: {
        yara :              'yara',
        sha1 :              'sha1',
        name :              'name',
        type :              'type',
        sha256 :            'sha256',
        urls :              'urls',
        crc32 :             'crc32',
        path :              'path',
        ssdeep :            'ssdeep',
        size :              'size',
        sha512 :            'sha512',
        md5 :               'md5'
    }

};

var undrscrToCamelCase = function(string){
    string = '_'+string;
    return string.replace(/_([a-z])/g, function (g) { return g[1].toUpperCase(); });
};

//returns single object withing entity (i.e. File[0])
var jsonToEntityObject = function(origObj, newKeys){
    var ret = {};
    var path;
    var newField;
    for(var key in newKeys){
        if(newKeys[key]){
            ret[newKeys[key]] = dq(origObj, '.'+key);
        }
    }
    return ret;
};

//returns entire entity array (i.e. File)
var jsonToEntity = function(origObj, newKeys){
    var j;
    var ret;
    if(!Array.isArray(origObj)){
        ret = [jsonToEntityObject(origObj, newKeys)];
        return ret;
    }
    else if(origObj.length > 0){ //makes sure no empty arrays are pushed
        ret = [];
        for(j=0; j<origObj.length; j++){
            ret.push(jsonToEntityObject(origObj[j], newKeys));
        }
        return ret;
    }
};

var fixUrl = function(base) {
    res = base;
    if (base && base[base.length - 1] != '/') {
        res = res + '/';
    }
    return res;
};

var parseResponse = function(resp) {
    if (resp.StatusCode === 200) {
        try {
            return JSON.parse(resp.Body);
        } catch (e) {
            return resp.Body;
        }
    } else {
        err = resp.Status;
        if (resp.Body) {
            err += '\n' + resp.Body;
        }
        throw err;
    }
};

var cuckooGet = function(qArgs, qParams, suffix) {
    url = fixUrl(qParams['server']) + suffix;
    username = qParams['authentication'] ? qParams['authentication']['identifier'] : '';
    password = qParams['authentication'] ? qParams['authentication']['password'] : '';
    headers = {};
    if (username == '__token'){
        headers = {'Authorization': ['Bearer ' + password]};
        username = '';
        password = '';
    }
    res = http(
          url,
          {
              Method: 'GET',
              Headers: headers,
              Username: username,
              Password: password
          },
          qParams['insecure'],
          qParams['proxy']
      );
    return result =  parseResponse(res);
};

var cuckooGetRaw = function(qArgs, qParams, suffix) {
    url = fixUrl(qParams['server']) + suffix;
    username = qParams['authentication'] ? qParams['authentication']['identifier'] : '';
    password = qParams['authentication'] ? qParams['authentication']['password'] : '';
    headers = {};
    if (username == '__token'){
        headers = {'Authorization': ['Bearer ' + password]};
        username = '';
        password = '';
    }
    res = http(
          url,
          {
              Method: 'GET',
              Headers: headers,
              Username: username,
              Password: password
          },
          qParams['insecure'],
          qParams['proxy']
      );
    return res;
};

var cuckooGetFile = function(qArgs, qParams, suffix, filename) {
    url = fixUrl(qParams['server']) + suffix;
    username = qParams['authentication'] ? qParams['authentication']['identifier'] : '';
    password = qParams['authentication'] ? qParams['authentication']['password'] : '';
    headers = {};
    if (username == '__token'){
        headers = {'Authorization': ['Bearer ' + password]};
        username = '';
        password = '';
    }
    res = http(
          url,
          {
            Method: 'GET',
            Headers: headers,
            Username: username,
            Password: password,
            SaveToFile: true
            },
            qParams['insecure'],
            qParams['proxy']
    );

    if (res.StatusCode !== 200) {
        err = res.Status;
        if (res.Body) {
            err += '\n' + res.Body;
        }
        throw err;
    }
    return {
        Type: 3,
        FileID: res.Path,
        File: filename,
        Contents: filename
    };
};

var cuckooPost = function(qArgs, qParams, suffix) {
    url = fixUrl(qParams.server) + suffix;
    username = qParams['authentication'] ? qParams['authentication']['identifier'] : '';
    password = qParams['authentication'] ? qParams['authentication']['password'] : '';
    headers = {};
    if (username == '__token'){
        headers = {'Authorization': ['Bearer ' + password]};
        username = '';
        password = '';
    }
    res = httpMultipart(
        url,
        '', // Optional - FilePath / EntryID
        {
            Method: 'POST',
            Headers: headers,
            Username: username,
            Password: password
        },
        { // Multipart Contents
            url: qArgs['url']
        },
        qParams['insecure'],
        qParams['proxy']
    );

    return parseResponse(res);
};

var fetchFiles = function(qArgs, qParams) {
    url = fixUrl(qParams['server']) + 'tasks/create/file';
    fileParam = qArgs['entryID'] ? qArgs['entryID'] : qArgs['fileID'];
    delete qArgs.entryID;
    username = qParams['authentication'] ? qParams['authentication']['identifier'] : '';
    password = qParams['authentication'] ? qParams['authentication']['password'] : '';
    headers = {};
    if (username == '__token'){
        headers = {'Authorization': ['Bearer ' + password]};
        username = '';
        password = '';
    }
    res = httpMultipart(
        url,
        fileParam,
        {
            Method: 'POST',
            Headers: headers,
            Username: username,
            Password: password
        },
        qArgs,
        qParams['insecure'],
        qParams['proxy']
      );

    return parseResponse(res);
};

var createTaskFromFile = function(args, params){
    var res =  fetchFiles(args, params);
    return {
        Type: entryTypes.note,
        Contents: res,
        ContentsFormat: formats.json,
        HumanReadable: 'Task was created successfully, task ID = ' + res.task_id,
        EntryContext: {'Cuckoo.Task' : {ID: res.task_id}}
    };
};

var createTaskFromURL = function(args, params){
    var res = cuckooPost(args, params, 'tasks/create/url');
    return {
        Type: entryTypes.note,
        Contents: res,
        ContentsFormat: formats.json,
        HumanReadable: 'Task was created successfully, task ID = ' + res.task_id,
        EntryContext: {'Cuckoo.Task' : {ID: res.task_id}}
    };
};

var tblToMdWithTransform = function(title, t, transform){
    return tblToMd(title, t, undefined, undefined, transform);
}

var getTaskReport = function(args, params){
    var result = cuckooGet(args, params, 'tasks/report/' + args['id']);
    var md;
    var context = {};


    context = jsonToEntity(result.info, entityMap.Task);
    if ('file' in result.target) {
        context[0]['FileInfo'] = jsonToEntity(result.target.file, entityMap.FileInfo)[0];
    }
    md = tblToMdWithTransform('Task Target', result.target, undrscrToCamelCase);
    md += tblToMdWithTransform('Task Info', result.info, undrscrToCamelCase);
    md += tblToMdWithTransform('Task Metadata', result.metadata, undrscrToCamelCase);
    md += tblToMdWithTransform('Task Network Data', result.network);
    if(result.signatures && result.signatures.length > 0){
        md += tblToMdWithTransform('Task Signatures', result.signatures, undrscrToCamelCase);
    }

    return {
        Type: entryTypes.note,
        Contents: result,
        ContentsFormat: formats.json,
        HumanReadable: md,
        EntryContext: {'Cuckoo.Task(val.ID && val.ID == obj.ID)': context}

    };
};
var viewTasks = function(args, params){
    ids = argToList(args['id']);
    var res = [];
    for(var i in ids){
        task_id = ids[i];
        entry = viewTask(args, params, task_id);
        res.push(entry);
    }
    return res;
};

var viewTask = function(args, params, id){
    result = cuckooGet(args, params, 'tasks/view/' + id);

    return {
        Type: entryTypes.note,
        Contents: result,
        ContentsFormat: formats.json,
        HumanReadable: tblToMdWithTransform('Task Table', result.task, undrscrToCamelCase),
        EntryContext: {'Cuckoo.Task(val.ID === obj.ID)' : jsonToEntity(result.task, entityMap.Task)}
    };
};

var deleteTask = function(args, params){
    var res = JSON.parse(cuckooGetRaw(args, params, 'tasks/delete/' + args['id']).Body);
    return (res.status? res.status : res.message);
};

var listTasks = function(args, params){
    var result = cuckooGet(args, params, 'tasks/list');

    return {
        Type: entryTypes.note,
        Contents: res,
        ContentsFormat: formats.json,
        HumanReadable: tblToMdWithTransform('Task Table', result.tasks, undrscrToCamelCase),
        EntryContext: {'Cuckoo.Task' : jsonToEntity(result.tasks, entityMap.Task)}
    };
};

var listMachines = function(args, params){
    var result = cuckooGet(args, params, 'machines/list');

    return {
        Type: entryTypes.note,
        Contents: res,
        ContentsFormat: formats.json,
        HumanReadable: tblToMdWithTransform('Machines Table', result.machines, undrscrToCamelCase),
        EntryContext: {'Cuckoo.Machine' : jsonToEntity(result.machines, entityMap.Machine)}
    };
};

var viewMachine = function(args, params){
    result = cuckooGet(args, params, 'machines/view/' + args['name']);

    return {
        Type: entryTypes.note,
        Contents: res,
        ContentsFormat: formats.json,
        HumanReadable: tblToMdWithTransform('Machines Table', result.machine, undrscrToCamelCase),
        EntryContext: {'Cuckoo.Machine' : jsonToEntity(result.machine, entityMap.Machine)}
    };
};

var taskScreenshot = function(args ,params){
    var uri = 'tasks/screenshots/' + args['id'];
    var filename = 'CuckooScreenshots.zip'
    if (args['screenshot']) {
        filename = args['screenshot'];
        uri += '/'+ args['screenshot'];
    }
    return cuckooGetFile(args, params, uri, filename);
};



// The command input arg holds the command sent from the user.
switch (command) {
    // This is the call made when pressing the integration test button.
    case 'test-module':
        var resp = cuckooGetRaw(args, params, 'tasks/list');
        if (resp.StatusCode === 200) {
            return 'ok';
        } else if (resp.Status) {
            return resp.Status;
        } else {
            return resp;
        }
        break;

    case 'ck-file'://deprecated
    case 'cuckoo-create-task-from-file':
        return createTaskFromFile(args, params);

    case 'ck-url'://deprecated
    case 'cuckoo-create-task-from-url':
        return createTaskFromURL(args, params);

    case 'ck-report'://deprecated
    case 'cuckoo-get-task-report':
        return getTaskReport(args, params);

    case 'ck-view'://deprecated
    case 'cuckoo-view-task':
        return viewTasks(args, params);

    case 'ck-del'://deprecated
    case 'cuckoo-delete-task':
        return deleteTask(args, params);

    case 'ck-list'://deprecated
    case 'cuckoo-list-tasks':
        return listTasks(args, params);

    case 'ck-machines-list': //deprecated
    case 'cuckoo-machines-list':
        return listMachines(args, params);

    case 'ck-machine-view'://deprecated
    case 'cuckoo-machine-view':
        return viewMachine(args, params);

    case 'ck-scrshot'://deprecated
    case 'cuckoo-task-screenshot':   //unchanged
        return taskScreenshot(args, params);
}