def list(self, user=None, group=None, fq=None, rows=10, offset=0):
"""\
List all submissions of a given group or user.
Required:
sid : Submission ID. (string)
Optional:
user : user to get the submissions from
group : groups to get the submissions from
offset : Offset at which we start giving submissions
rows : Number of submissions to return
fq : Query to filter to the submission list
"""
kw = {'rows': rows, 'offset': offset}
if fq:
kw['query'] = fq
if user:
return self._connection.get(
api_path_by_module(self, 'user', user, **kw))
if group:
return self._connection.get(
api_path_by_module(self, 'group', group, **kw))
return self._connection.get(
api_path_by_module(self, 'group', 'ALL', **kw))
def add_update(self, data, dedup_name=True):
"""\
Add or update a signature.
Required:
Data block:
{
"name": "sig_name", # Signature name
"type": "yara", # One of yara, suricata or tagcheck
"data": "rule sample {...}", # Data of the rule to be added
"source": "yara_signatures" # Source from where the signature has been gathered
}
Optional:
dedup_name : Should we check if the signature already exist before inserting it (default: True)
Returns:
{
"success": True,
"signature_id": <ID of the saved signature>
}
"""
return self._connection.post(api_path_by_module(
self, **get_funtion_kwargs('data', 'self')),
json=data)
def statistics(self,
fq=[],
q=None,
tc_start=None,
tc=None,
no_delay=False):
"""\
Find the different statistics for the alerts matching the query.
Optional:
fq : Post filter queries (you can have multiple of these)
q : Query to apply to the alert list
tc_start: Time offset at which we start the time constraint
tc : Time constraint applied to the API
no_delay: Do not delay alerts
"""
params_tuples = [('fq', x) for x in fq]
kw = {
'params_tuples': params_tuples,
'q': q,
'tc_start': tc_start,
'tc': tc
}
if no_delay:
kw['no_delay'] = True
return self._connection.get(api_path_by_module(self, **kw))
def update(self, name, image, tag, username=None, password=None):
"""\
Update a given service
Required:
name : Name of the service to update
image : Full path to the container image including tag
tag : Tag to update the service to
Optional:
username : Username to log into the docker registry
password : Password to log into the docker registry
"""
data = {
'name': name,
'update_data': {
'name': name,
'image': image,
'latest_tag': tag
}
}
if username and password:
data['update_data']['auth'] = {
'username': username,
'password': password
}
return self._connection.put(api_path_by_module(self), json=data)
def add_update_many(self, source, sig_type, data, dedup_name=True):
"""\
Add or update multiple signatures.
Required:
source : Source of the signature
sig_type : Type of signature
data : List of signatures
Data block example:
[ # List of signatures to update
{
"name": "sig_name", # Signature name
"type": "yara", # One of yara, suricata or tagcheck
"data": "rule sample {...}", # Data of the rule to be added
"source": "yara_signatures" # Source from where the signature has been gathered
},
...
]
Optional:
dedup_name : Should we check if the signatures already exist before inserting it (default: True)
Returns:
{
"success": 23, # Number of successful inserts
"errors": [], # List of signature that failed
"skipped": [], # List of skipped signatures, they already exist
}
"""
return self._connection.post(api_path_by_module(self, **get_function_kwargs('data', 'self')), json=data)
def list(self,
fq=[],
q=None,
tc_start=None,
tc=None,
no_delay=False,
offset=0,
rows=10):
"""\
List all alerts in the system (per page)
Optional:
fq : Post filter queries (you can have multiple of these)
q : Query to apply to the alert list
no_delay: Do not delay alerts
offset : Offset at which we start giving alerts
rows : Number of alerts to return
tc_start: Time offset at which we start the time constraint
tc : Time constraint applied to the API
"""
params_tuples = [('fq', x) for x in fq]
kw = {
'offset': offset,
'params_tuples': params_tuples,
'q': q,
'rows': rows,
'tc_start': tc_start,
'tc': tc
}
if no_delay:
kw['no_delay'] = True
return self._connection.get(api_path_by_module(self, **kw))
def update_available(self, since='', sig_type='*'):
"""\
Check if updated signatures are available.
Optional:
since : ISO 8601 date (%Y-%m-%dT%H:%M:%S). (string)
"""
return self._connection.get(api_path_by_module(self, last_update=since, type=sig_type))
def constants(self):
"""\
Return the current system configuration constants which include:
* Priorities
* File types
* Service tag types
* Service tag contexts
"""
return self._connection.get(api_path_by_module(self))
def configuration(self):
"""\
Return the current system configuration:
* Max file size
* Max number of embedded files
* Extraction's max depth
* and many others...
"""
return self._connection.get(api_path_by_module(self))
def setup_watch_queue(self, sid):
"""\
Set up a watch queue for the submission with the given sid.
Required:
sid : Submission ID. (string)
Throws a Client exception if the submission does not exist.
"""
return self._connection.get(api_path_by_module(self, sid))
def submission_params(self, username):
"""\
Return the submission parameters for the given username.
Required:
username: User key. (string).
Throws a Client exception if the submission does not exist.
"""
return self._connection.get(api_path_by_module(self, username))
def tree(self, sid):
"""\
Return the file hierarchy for the submission with the given sid.
Required:
sid : Submission ID. (string)
Throws a Client exception if the submission does not exist.
"""
return self._connection.get(api_path_by_module(self, sid))
def report(self, sid):
"""\
Create a report for a submission based on its ID.
Required:
sid : Submission ID. (string)
Throws a Client exception if the submission does not exist.
"""
return self._connection.get(api_path_by_module(self, sid))
def error(self, key):
"""\
Return the error with the given key.
Required:
key : Error key.
Throws a Client exception if the error does not exist.
"""
return self._connection.get(api_path_by_module(self, key))
def ownership(self, alert_id):
"""\
Set the ownership of the alert with the given alert_id to the current user.
Required:
alert_id: Alert key (string)
Throws a Client exception if the alert does not exist.
"""
return self._connection.get(api_path_by_module(self, alert_id))
def children(self, sha256):
"""\
Return the list of children for the file with the given sha256.
Required:
sha256 : File key (string)
Throws a Client exception if the file does not exist.
"""
return self._connection.get(api_path_by_module(self, sha256))
def strings(self, sha256):
"""\
Return all strings found in the file.
Required:
sha256 : File key (string)
Throws a Client exception if the file does not exist.
"""
return self._connection.get(api_path_by_module(self, sha256))
def full(self, sid):
"""\
Return the full result for the given submission.
Required:
sid : Submission ID. (string)
Throws a Client exception if the submission does not exist.
"""
return self._connection.get(api_path_by_module(self, sid))
def ascii(self, sha256):
"""\
Return an ascii representation of the file.
Required:
sha256 : File key (string)
Throws a Client exception if the file does not exist.
"""
return self._connection.get(api_path_by_module(self, sha256))
def versions(self, service_name):
"""\
List the different versions of a service stored in the system
Required:
service_name: Name of the service to get the versions for
Throws a Client exception if the service does not exist.
"""
return self._connection.get(api_path_by_module(self, service_name))
def score(self, sha256):
"""\
Return the latest score for the given sha256.
Required:
sha256 : File key (string)
Throws a Client exception if the file does not exist.
"""
return self._connection.get(api_path_by_module(self, sha256))
def get_message_list(self, wq):
"""\
Return all current messages from the given watch queue.
Required:
wq : Watch queue name. (string)
Throws a Client exception if the watch queue does not exist.
"""
return self._connection.get(api_path_by_module(self, wq))
def tos(self, username):
"""\
Specified user send agreement to Terms of Service
Required:
username : Username of the user that agrees with terms of service (string)
Throws a Client exception if the user does not exist.
"""
return self._connection.get(api_path_by_module(self, username))
def get_message_list(self, nq):
"""\
Return all messages from the given notification queue.
Required:
nq : Notification queue name. (string)
Throws a Client exception if the watch queue does not exist.
"""
return self._connection.get(api_path_by_module(self, nq))
def resubmit(self, sid):
"""\
Resubmit a file for analysis with the exact same parameters.
Required:
sid : Submission ID. (string)
Throws a Client exception if the submission does not exist.
"""
return self._connection.get(api_path_by_module(self, sid))
def change_status(self, signature_id, status):
"""\
Change the status of a signature
Required:
signature_id : ID of the signature to change the status
status : New status for the signature (DEPLOYED, NOISY, DISABLED, TESTING, STAGING)
Throws a Client exception if the signature does not exist or the status is invalid.
"""
return self._connection.get(api_path_by_module(self, signature_id, status))
def backup(self, output=None):
"""\
Create a backup of the current system configuration
Optional:
output : Path or file handle (string or file-like object)
"""
path = api_path_by_module(self)
if output:
return self._connection.download(path, stream_output(output))
return self._connection.download(path, raw_output)
def outstanding_services(self, sid):
"""\
List outstanding services and the number of files each
of them still have to process.
Required:
sid: Submission ID (string)
Throws a Client exception if the submission does not exist.
"""
return self._connection.get(api_path_by_module(self, sid))
def dynamic(self, sha256, copy_sid=None, name=None):
"""\
Resubmit a file for dynamic analysis
Required:
sid : Submission ID. (string)
Throws a Client exception if the submission does not exist.
"""
kw = get_function_kwargs('self', 'sha256')
return self._connection.get(api_path_by_module(self, sha256, **kw))
def list(self, query=None, offset=0, rows=10, sort=None):
"""\
List all errors in the system (per page)
Required:
offset: Offset at which we start giving errors
query : Query to apply to the error list
rows : Number of errors to return
sort : Sort order
"""
kw = {'offset': offset, 'q': query, 'rows': rows, 'sort': sort}
return self._connection.get(api_path_by_module(self, **kw))
