Details
| ID | Cuckoo Sandbox |
|---|---|
| Provider | Open Source |
| Category | Forensics & Malware Analysis |
| From Version | 5.0.0 |
| Supported Modules | Agentix 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
- Navigate to Settings > Integrations > Servers & Services.
- Search for Cuckoo Sandbox.
- 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
- 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.
- Create a task from a file: cuckoo-create-task-from-file
- Get a task report: cuckoo-get-task-report
- Get a list of all tasks: cuckoo-list-tasks
- Submit a URL for analysis: cuckoo-create-task-from-url
- Get task information: cuckoo-view-task
- Delete a task: cuckoo-delete-task
- Get analysis screenshots: cuckoo-task-screenshot
- Get a list of analysis machines: cuckoo-machines-list
- 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
Human Readable Output
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
Human Readable Output
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
Human Readable Output
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
Human Readable Output
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
Human Readable Output
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
Human Readable Output
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
Human Readable Output
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
Human Readable Output
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-delDeprecatedcommands.server.ckDelete.description
-
ck-fileDeprecatedcommands.server.ckFile.description
-
ck-listDeprecatedcommands.server.ckList.description
-
ck-machine-viewDeprecatedReturns details on the analysis machine associated with the given name.
-
ck-machines-listDeprecatedReturns a list with details on the analysis machines available to Cuckoo.
-
ck-reportDeprecatedcommands.server.ckReport.description
-
ck-scrshotDeprecatedRetrieve screenshots taken during analysis. If the screenshot number argument is omitted, retrieves a zip file with all screenshots.
-
ck-urlDeprecatedSubmit a URL for analysis
-
ck-viewDeprecatedcommands.server.ckView.description
-
cuckoo-create-task-from-filecommands.server.ckFile.description
-
cuckoo-create-task-from-urlSubmit a URL for analysis
-
cuckoo-delete-taskcommands.server.ckDelete.description
-
cuckoo-get-task-reportcommands.server.ckReport.description
-
cuckoo-list-taskscommands.server.ckList.description
-
cuckoo-machine-viewReturns details on the analysis machine associated with the given name.
-
cuckoo-machines-listReturns a list with details on the analysis machines available to Cuckoo.
-
cuckoo-task-screenshotRetrieve screenshots taken during analysis. If the screenshot number argument is omitted, retrieves a zip file with all screenshots.
-
cuckoo-view-taskcommands.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); }















