CuckooAPI package

Module contents

class CuckooAPI.CuckooAPI(host='127.0.0.1', port=8000, proto='http', APIPY=False)

Bases: object

Class to hold Cuckoo API data.

droppeddownload(taskid=None, filepath=None)

Download files dropped by sample identified by task ID.

Parameters:

• taskid – The task ID of the sample.
• filepath – The file path of the file to create/download.

Returns:

Nothing

fileview(hashid=None, hashtype=None)

View the details for the file given the hash.

Parameters:

• hashid – The hash or task ID to search.
• hashtype – The following types of hash: ‘taskid’, ‘md5’, ‘sha256’. Any other values will cause an error!

Returns:

Returns the results of the file in a dict.

fullmemdownload(taskid=None, filepath=None)

Download SuriFiles for the sample identified by task ID.

Parameters:

• taskid – The task ID of the sample.
• filepath – The file path of the file to create/download.

Returns:

Nothing

getcuckoostatus()

Function to get the status of the Cuckoo instance.

Returns:Returns the status as a dictionary.

listmachines()

Lists the machines available for analysis.

Returns:Returns the list of machines as a list.

pcapdownload(taskid=None, filepath=None)

Download a pcap by task ID.

Parameters:taskid – The task ID to download the pcap. Returns:Nothing

procmemdownload(taskid=None, filepath=None, pid=None)

Download SuriFiles for the sample identified by task ID.

Parameters:

• taskid – The task ID of the sample.
• filepath – The file path of the file to create/download.
• pid – Process ID to download

Returns:

Nothing

sampledownload(hashid=None, hashtype=None, filepath=None)

Download a file by hash.

Parameters:

• hashid – The hash used to download the sample.
• hashtype – The hash type, can be “task”, “md5”, sha1”, or “sha256”. “task” means the task ID.

Returns:

Nothing

submitfile(filepath, data=None)

Function to submit a local file to Cuckoo for analysis.

Parameters:

• filepath – Path to a file to submit.
• data – This is data containing any other options for the submission form. This is a dict of values accepted by the create file options in the cuckoo-modified API. More form information can be found in the following link: https://github.com/spender-sandbox/cuckoo-modified/blob/master/docs/book/src/usage/api.rst

Returns:

Returns the json results of the submission

submiturl(url, data=None)

Function to submit a URL to Cuckoo for analysis.

Parameters:

• url – URL to submit.
• data – This is data containing any other options for the submission form. This is a dict of values accepted by the create file options in the cuckoo-modified API. More form information can be found in the following link: https://github.com/spender-sandbox/cuckoo-modified/blob/master/docs/book/src/usage/api.rst

Returns:

Returns the json results of the submission

surifilesdownload(taskid=None, filepath=None)

Download SuriFiles for the sample identified by task ID.

Parameters:

• taskid – The task ID of the sample.
• filepath – The file path of the file to create/download.

Returns:

Nothing

taskdelete(taskid=None)

Delete a task.

Parameters:taskid – The task ID to delete. Returns:Status

taskiocs(taskid=None, detailed=False)

View the task IOCs for the task ID.

Parameters:

• taskid – The ID of the task to view.
• detailed – Set to true for detailed IOCs.

Returns:

Returns a dict of task details.

taskreport(taskid=None, reportformat='json')

View the report for the task ID.

Parameters:

• taskid – The ID of the task to report.
• reportformat – Right now only json is supported.

Returns:

Returns a dict report for the task.

taskscreenshots(taskid=None, filepath=None, screenshot=None)

Download screenshot(s).

Parameters:

• taskid – The task ID for the screenshot(s).
• filepath – Where to save the screenshot(s). If you are using the Django web api the screenshots are saved as .tar.bz! If you are using the api.py script the screenshots are in .zip format. This function adds the apppropriate file extensions to the filepath variable.
• screenshot – The screenshot number to download.

Returns:

Nothing

tasksearch(hashid=None, hashtype=None)

View information about a specific task by hash.

Parameters:

• hashid – MD5, SHA1, or SHA256 hash to search.
• hashtype – ‘md5’, ‘sha1’, or ‘sha256’

Returns:

Returns a dict with results.

taskslist(limit=None, offset=None)

Lists the tasks in the Cuckoo DB.

Parameters:

• limit – Limit to this many results (Optional)
• offset – Offset the output to offset in the total task list and requires limit above. (Optional)

Returns:

Returns a list of task details.

taskstatus(taskid=None)

View the task status for the task ID.

Parameters:taskid – The ID of the task to view. Returns:Returns a dict of task details.

taskview(taskid=None)

View the task for the task ID.

Parameters:taskid – The ID of the task to view. Returns:Returns a dict of task details.

viewmachine(vmname=None)

Lists the details about an analysis machine.

Parameters:vmname – The vm name for the machine to be listed Returns:Returns the dictionary of the machine specifics

exception CuckooAPI.CuckooAPIBadRequest(apiurl)

Bases: Exception

Exception for when a Cuckoo machine is not found.

exception CuckooAPI.CuckooAPIFileExists(filepath)

Bases: Exception

Exception for when a file is about to be saved over an existing file or the file name is invalid.

exception CuckooAPI.CuckooAPIInvalidFileException(filepath)

Bases: Exception

Exception for when a file is not found.

exception CuckooAPI.CuckooAPINoHash(hashid, hashtype)

Bases: Exception

Exception for when an invalid file hash is used.

exception CuckooAPI.CuckooAPINoTaskID(taskid)

Bases: Exception

Exception for when an invalid task ID is used.

exception CuckooAPI.CuckooAPINoVM(vmname)

Bases: Exception

Exception for when a vm is not found.

exception CuckooAPI.CuckooAPINotAvailable(apicall)

Bases: Exception

Exception for when a call is not available on the remote server. This signifies you may have used an API call meant for the Django interface and sent it to the api.py interface, or vice versa.

exception CuckooAPI.CuckooAPINotImplemented(apicall)

Bases: Exception

Exception for when a call is not implemented, but is available.

exception CuckooAPI.CuckooAPITaskNoDelete(taskid)

Bases: Exception

Exception for when a task cannot be deleted.

CuckooAPI.buildapiurl(proto='http', host='127.0.0.1', port=8000, action=None, APIPY=False)

Create a URL for the Cuckoo API

Parameters:

• proto – http or https
• host – Hostname or IP address
• port – The port of the Cuckoo API server
• action – The action to perform with the API

Returns:

The URL

CuckooAPI.main()

Main function for this library