Package lib :: Package cuckoo :: Package core :: Module database :: Class Database
[hide private]
[frames] | no frames]

Class Database

source code

object --+
         |
        Database

Analysis queue database.

This class handles the creation of the database user for internal queue management. It also provides some functions for interacting with it.

Instance Methods [hide private]
 
__init__(self, dsn=None, schema_check=True, echo=False)
x.__init__(...) initializes x; see help(type(x)) for signature
source code
 
__del__(self)
Disconnects pool.
source code
 
_connect_database(self, connection_string)
Connect to a Database.
source code
 
_get_or_create(self, session, model, **kwargs)
Get an ORM instance or create it if not exist.
source code
 
drop(self)
Drop all tables.
source code
 
clean_machines(self)
Clean old stored machines and related tables.
source code
 
add_machine(self, name, label, ip, platform, options, tags, interface, snapshot, resultserver_ip, resultserver_port)
Add a guest machine.
source code
 
set_status(self, task_id, status)
Set task status.
source code
 
set_route(self, task_id, route)
Set the taken route of this task.
source code
 
fetch(self, machine=None, service=True)
Fetches a task waiting to be processed and locks it for running.
source code
 
guest_start(self, task_id, name, label, manager)
Logs guest start.
source code
 
guest_get_status(self, task_id)
Logs guest start.
source code
 
guest_set_status(self, task_id, status)
Logs guest start.
source code
 
guest_remove(self, guest_id)
Removes a guest start entry.
source code
 
guest_stop(self, guest_id)
Logs guest stop.
source code
 
list_machines(self, locked=False)
Lists virtual machines.
source code
 
lock_machine(self, label=None, platform=None, tags=None)
Places a lock on a free virtual machine.
source code
 
unlock_machine(self, label)
Remove lock form a virtual machine.
source code
 
count_machines_available(self)
How many virtual machines are ready for analysis.
source code
 
get_available_machines(self)
Which machines are available
source code
 
set_machine_status(self, label, status)
Set status for a virtual machine.
source code
 
add_error(self, message, task_id)
Add an error related to a task.
source code
 
add(self, obj, timeout=0, package="", options="", priority=1, custom="", owner="", machine="", platform="", tags=None, memory=False, enforce_timeout=False, clock=None, category=None)
Add a task to database.
source code
 
add_path(self, file_path, timeout=0, package="", options="", priority=1, custom="", owner="", machine="", platform="", tags=None, memory=False, enforce_timeout=False, clock=None)
Add a task to database from file path.
source code
 
add_url(self, url, timeout=0, package="", options="", priority=1, custom="", owner="", machine="", platform="", tags=None, memory=False, enforce_timeout=False, clock=None)
Add a task to database from url.
source code
 
add_baseline(self, timeout=0, owner="", machine="", memory=False)
Add a baseline task to database.
source code
 
add_service(self, timeout, owner, tags)
Add a service task to database.
source code
 
add_reboot(self, task_id, timeout=0, options="", priority=1, owner="", machine="", platform="", tags=None, memory=False, enforce_timeout=False, clock=None)
Add a reboot task to database from an existing analysis.
source code
 
reschedule(self, task_id, priority=None)
Reschedule a task.
source code
 
list_tasks(self, limit=None, details=True, category=None, owner=None, offset=None, status=None, sample_id=None, not_status=None, completed_after=None, order_by=None)
Retrieve list of task.
source code
 
minmax_tasks(self)
Find tasks minimum and maximum
source code
 
count_tasks(self, status=None)
Count tasks in the database
source code
 
view_task(self, task_id, details=True)
Retrieve information on a task.
source code
 
delete_task(self, task_id)
Delete information on a task.
source code
 
view_sample(self, sample_id)
Retrieve information on a sample given a sample id.
source code
 
find_sample(self, md5=None, sha256=None)
Search samples by MD5.
source code
 
count_samples(self)
Counts the amount of samples in the database.
source code
 
view_machine(self, name)
Show virtual machine.
source code
 
view_machine_by_label(self, label)
Show virtual machine.
source code
 
view_errors(self, task_id)
Get all errors related to a task.
source code
 
processing_get_task(self, instance)
Get an available task for processing.
source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Class Variables [hide private]
  __metaclass__ = Singleton
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, dsn=None, schema_check=True, echo=False)
(Constructor)

source code 

x.__init__(...) initializes x; see help(type(x)) for signature

Parameters:
  • dsn - database connection string.
  • schema_check - disable or enable the db schema version check.
  • echo - echo sql queries.
Overrides: object.__init__

_connect_database(self, connection_string)

source code 

Connect to a Database.

Parameters:
  • connection_string - Connection string specifying the database

_get_or_create(self, session, model, **kwargs)

source code 

Get an ORM instance or create it if not exist.

Parameters:
  • session - SQLAlchemy session object
  • model - model to query
Returns:
row instance

drop(self)

source code 

Drop all tables.

Decorators:
  • @classlock

clean_machines(self)

source code 

Clean old stored machines and related tables.

Decorators:
  • @classlock

add_machine(self, name, label, ip, platform, options, tags, interface, snapshot, resultserver_ip, resultserver_port)

source code 

Add a guest machine.

Parameters:
  • name - machine id
  • label - machine label
  • ip - machine IP address
  • platform - machine supported platform
  • tags - list of comma separated tags
  • interface - sniffing interface for this machine
  • snapshot - snapshot name to use instead of the current one, if configured
  • resultserver_ip - IP address of the Result Server
  • resultserver_port - port of the Result Server
Decorators:
  • @classlock

set_status(self, task_id, status)

source code 

Set task status.

Parameters:
  • task_id - task identifier
  • status - status string
Returns:
operation status
Decorators:
  • @classlock

set_route(self, task_id, route)

source code 

Set the taken route of this task.

Parameters:
  • task_id - task identifier
  • route - route string
Returns:
operation status
Decorators:
  • @classlock

fetch(self, machine=None, service=True)

source code 

Fetches a task waiting to be processed and locks it for running.

Returns:
None or task
Decorators:
  • @classlock

guest_start(self, task_id, name, label, manager)

source code 

Logs guest start.

Parameters:
  • task_id - task identifier
  • name - vm name
  • label - vm label
  • manager - vm manager
Returns:
guest row id
Decorators:
  • @classlock

guest_get_status(self, task_id)

source code 

Logs guest start.

Parameters:
  • task_id - task id
Returns:
guest status
Decorators:
  • @classlock

guest_set_status(self, task_id, status)

source code 

Logs guest start.

Parameters:
  • task_id - task identifier
  • status - status
Decorators:
  • @classlock

guest_remove(self, guest_id)

source code 

Removes a guest start entry.

Decorators:
  • @classlock

guest_stop(self, guest_id)

source code 

Logs guest stop.

Parameters:
  • guest_id - guest log entry id
Decorators:
  • @classlock

list_machines(self, locked=False)

source code 

Lists virtual machines.

Returns:
list of virtual machines
Decorators:
  • @classlock

lock_machine(self, label=None, platform=None, tags=None)

source code 

Places a lock on a free virtual machine.

Parameters:
  • label - optional virtual machine label
  • platform - optional virtual machine platform
  • tags - optional tags required (list)
Returns:
locked machine
Decorators:
  • @classlock

unlock_machine(self, label)

source code 

Remove lock form a virtual machine.

Parameters:
  • label - virtual machine label
Returns:
unlocked machine
Decorators:
  • @classlock

count_machines_available(self)

source code 

How many virtual machines are ready for analysis.

Returns:
free virtual machines count
Decorators:
  • @classlock

get_available_machines(self)

source code 

Which machines are available

Returns:
free virtual machines
Decorators:
  • @classlock

set_machine_status(self, label, status)

source code 

Set status for a virtual machine.

Parameters:
  • label - virtual machine label
  • status - new virtual machine status
Decorators:
  • @classlock

add_error(self, message, task_id)

source code 

Add an error related to a task.

Parameters:
  • message - error message
  • task_id - ID of the related task
Decorators:
  • @classlock

add(self, obj, timeout=0, package="", options="", priority=1, custom="", owner="", machine="", platform="", tags=None, memory=False, enforce_timeout=False, clock=None, category=None)

source code 

Add a task to database.

Parameters:
  • obj - object to add (File or URL).
  • timeout - selected timeout.
  • options - analysis options.
  • priority - analysis priority.
  • custom - custom options.
  • owner - task owner.
  • machine - selected machine.
  • platform - platform.
  • tags - optional tags that must be set for machine selection
  • memory - toggle full memory dump.
  • enforce_timeout - toggle full timeout execution.
  • clock - virtual machine clock time
Returns:
cursor or None.
Decorators:
  • @classlock

add_path(self, file_path, timeout=0, package="", options="", priority=1, custom="", owner="", machine="", platform="", tags=None, memory=False, enforce_timeout=False, clock=None)

source code 

Add a task to database from file path.

Parameters:
  • file_path - sample path.
  • timeout - selected timeout.
  • options - analysis options.
  • priority - analysis priority.
  • custom - custom options.
  • owner - task owner.
  • machine - selected machine.
  • platform - platform.
  • tags - Tags required in machine selection
  • memory - toggle full memory dump.
  • enforce_timeout - toggle full timeout execution.
  • clock - virtual machine clock time
Returns:
cursor or None.

add_url(self, url, timeout=0, package="", options="", priority=1, custom="", owner="", machine="", platform="", tags=None, memory=False, enforce_timeout=False, clock=None)

source code 

Add a task to database from url.

Parameters:
  • url - url.
  • timeout - selected timeout.
  • options - analysis options.
  • priority - analysis priority.
  • custom - custom options.
  • owner - task owner.
  • machine - selected machine.
  • platform - platform.
  • tags - tags for machine selection
  • memory - toggle full memory dump.
  • enforce_timeout - toggle full timeout execution.
  • clock - virtual machine clock time
Returns:
cursor or None.

add_baseline(self, timeout=0, owner="", machine="", memory=False)

source code 

Add a baseline task to database.

Parameters:
  • timeout - selected timeout.
  • owner - task owner.
  • machine - selected machine.
  • memory - toggle full memory dump.
Returns:
cursor or None.

add_service(self, timeout, owner, tags)

source code 

Add a service task to database.

Parameters:
  • timeout - selected timeout.
  • owner - task owner.
  • tags - task tags.
Returns:
cursor or None.

add_reboot(self, task_id, timeout=0, options="", priority=1, owner="", machine="", platform="", tags=None, memory=False, enforce_timeout=False, clock=None)

source code 

Add a reboot task to database from an existing analysis.

Parameters:
  • task_id - task id of existing analysis.
  • timeout - selected timeout.
  • options - analysis options.
  • priority - analysis priority.
  • owner - task owner.
  • machine - selected machine.
  • platform - platform.
  • tags - tags for machine selection
  • memory - toggle full memory dump.
  • enforce_timeout - toggle full timeout execution.
  • clock - virtual machine clock time
Returns:
cursor or None.

reschedule(self, task_id, priority=None)

source code 

Reschedule a task.

Parameters:
  • task_id - ID of the task to reschedule.
Returns:
ID of the newly created task.
Decorators:
  • @classlock

list_tasks(self, limit=None, details=True, category=None, owner=None, offset=None, status=None, sample_id=None, not_status=None, completed_after=None, order_by=None)

source code 

Retrieve list of task.

Parameters:
  • limit - specify a limit of entries.
  • details - if details about must be included
  • category - filter by category
  • owner - task owner
  • offset - list offset
  • status - filter by task status
  • sample_id - filter tasks for a sample
  • not_status - exclude this task status from filter
  • completed_after - only list tasks completed after this timestamp
  • order_by - definition which field to sort by
Returns:
list of tasks.

minmax_tasks(self)

source code 

Find tasks minimum and maximum

Returns:
unix timestamps of minimum and maximum

count_tasks(self, status=None)

source code 

Count tasks in the database

Parameters:
  • status - apply a filter according to the task status
Returns:
number of tasks found
Decorators:
  • @classlock

view_task(self, task_id, details=True)

source code 

Retrieve information on a task.

Parameters:
  • task_id - ID of the task to query.
Returns:
details on the task.
Decorators:
  • @classlock

delete_task(self, task_id)

source code 

Delete information on a task.

Parameters:
  • task_id - ID of the task to query.
Returns:
operation status.
Decorators:
  • @classlock

view_sample(self, sample_id)

source code 

Retrieve information on a sample given a sample id.

Parameters:
  • sample_id - ID of the sample to query.
Returns:
details on the sample used in sample: sample_id.
Decorators:
  • @classlock

find_sample(self, md5=None, sha256=None)

source code 

Search samples by MD5.

Parameters:
  • md5 - md5 string
Returns:
matches list
Decorators:
  • @classlock

count_samples(self)

source code 

Counts the amount of samples in the database.

Decorators:
  • @classlock

view_machine(self, name)

source code 

Show virtual machine.

Returns:
virtual machine's details
Decorators:
  • @classlock

view_machine_by_label(self, label)

source code 

Show virtual machine.

Returns:
virtual machine's details
Decorators:
  • @classlock

view_errors(self, task_id)

source code 

Get all errors related to a task.

Parameters:
  • task_id - ID of task associated to the errors
Returns:
list of errors.
Decorators:
  • @classlock