import init
from vocabulary import Common as c
from vocabulary import Status as s
from vocabulary import ThreatExchange as t
from vocabulary import ThreatIndicator as ti
from vocabulary import PrivacyType as pt
from errors import (
pytxAttributeError,
pytxValueError,
pytxInitError
)
[docs]class class_or_instance_method(object):
"""
Custom decorator. This binds to the class if no instance is avaialble,
otherwise it will bind to the instance.
This allows us to use a single method which can take both "self" and "cls"
as the first argument.
"""
def __init__(self, func):
self.func = func
def __get__(self, instance, cls=None):
if instance is None:
return classmethod(self.func).__get__(None, cls)
return self.func.__get__(instance, cls)
[docs]class Common(object):
_internal = [
'_DETAILS',
'_RELATED',
'_changed',
'_new',
'_access_token',
c.ID
]
_changed = []
_new = True
_access_token = None
def __init__(self, **kwargs):
"""
Initialize the object. Set the _access_token and any attributes that
were provided.
"""
self._access_token = init.__ACCESS_TOKEN__
if self._access_token == None:
raise pytxInitError("Must init() before instantiating")
for name, value in kwargs.items():
self.__setattr__(name, value)
def __setattr__(self, name, value):
"""
Override __setattr__. If it is the ID being set then we will set the
URLs to leverage the ID (used when instantiating classes with data
returned from a GET request).
If the attribute was changed from a previous value, we will add it to
_changed in the event this is an edit.
"""
object.__setattr__(self, name, value)
if name == c.ID and value not in self._DETAILS:
self._DETAILS = self._DETAILS + value + '/'
self._RELATED = self._DETAILS + t.RELATED
if name not in self._changed and name in self._fields:
self._changed.append(name)
def __getattr__(self, attr):
"""
Get an attribute. If the attribute does not exist, return None
"""
if attr not in self._fields + self._internal + self._unique:
raise pytxAttributeError("%s is not a valid attribute" % attr)
try:
return object.__getattribute__(self, attr)
except:
return None
[docs] def set(self, name, value):
"""
Wrapper around __setattr__ making it easier to use the vocabulary to set
class attributes.
:param name: The name of the attribute to set.
:type name: str
:param value: The value to set the attribute to.
:type value: None, int, str, bool
"""
return self.__setattr__(name, value)
[docs] def get(self, attr):
"""
Wrapper around __getattr__ making it easier to use the vocabulary to get
class attributes.
:param attr: The name of the attribute to get.
:type attr: str
"""
return self.__getattr__(attr)
[docs] def populate(self, attrs):
"""
Given a dictionary, populate self with the keys as attributes.
:param attrs: A dictionary used as attributes and values.
:type attrs: dict
"""
for k,v in attrs.iteritems():
self.set(k, v)
@property
[docs] def access_token(self):
"""
Returns the combined APP-ID and APP-SECRET stored during init().
:returns: str
"""
return self._access_token
[docs] def to_dict(self):
"""
Convert this object into a dictionary.
:returns: dict
"""
d = dict(
(n, getattr(self, n, None)) for n in self._fields
)
return d
@classmethod
[docs] def objects(cls, text=None, strict_text=False, type_=None, threat_type=None,
fields=None, limit=None, since=None, until=None, __raw__=None,
full_response=False, dict_generator=False):
"""
Get objects from ThreatExchange.
:param text: The text used for limiting the search.
:type text: str
:param strict_text: Whether we should use strict searching.
:type strict_text: bool, str, int
:param type_: The Indicator type to limit to.
:type type_: str
:param threat_type: The Threat type to limit to.
:type threat_type: str
:param fields: Select specific fields to pull
:type fields: str, list
:param limit: The maximum number of objects to return.
:type limit: int, str
:param since: The timestamp to limit the beginning of the search.
:type since: str
:param until: The timestamp to limit the end of the search.
:type until: str
:param __raw__: Provide a dictionary to force as GET parameters.
Overrides all other arguments.
:type __raw__: dict
:param full_response: Return the full response instead of the generator.
Takes precedence over dict_generator.
:type full_response: bool
:param dict_generator: Return a dictionary instead of an instantiated
object.
:returns: Generator, dict (using json.loads())
"""
if __raw__:
if isinstance(__raw__, dict):
params = __raw__
else:
raise pytxValueError("__raw__ must be of type dict")
else:
params = init.Broker.build_get_parameters(
text=text,
strict_text=strict_text,
type_=type_,
threat_type=threat_type,
fields=fields,
limit=limit,
since=since,
until=until,
)
if full_response:
return init.Broker.get(cls._URL, params=params)
else:
return init.Broker.get_generator(cls,
cls._URL,
limit,
to_dict=dict_generator,
params=params)
@class_or_instance_method
[docs] def details(cls_or_self, id=None, fields=None, connection=None,
full_response=False, dict_generator=False, metadata=False):
"""
Get object details. Allows you to limit the fields returned in the
object's details. Also allows you to provide a connection. If a
connection is provided, the related objects will be returned instead
of the object itself.
NOTE: This method can be used on both instantiated and uninstantiated
classes like so:
foo = ThreatIndicator(id='1234')
foo.details()
foo = ThreatIndicator.details(id='1234')
BE AWARE: Due to the nature of ThreatExchange allowing you to query for
an object by ID but not actually telling you the type of object returned
to you, using an ID for an object of a different type (ex: ID for a
Malware object using ThreatIndicator class) will result in the wrong
object populated with only data that is common between the two objects.
:param id: The ID of the object to get details for if the class is not
instantiated.
:type id: str
:param fields: The fields to limit the details to.
:type fields: None, str, list
:param connection: The connection to find other related objects with.
:type connection: None, str
:param full_response: Return the full response instead of the generator.
Takes precedence over dict_generator.
:type full_response: bool
:param dict_generator: Return a dictionary instead of an instantiated
object.
:type dict_generator: bool
:param metadata: Get extra metadata in the response.
:type metadata: bool
:returns: Generator, dict, class
"""
if isinstance(cls_or_self, type):
url = t.URL + t.VERSION + id + '/'
else:
url = cls_or_self._DETAILS
if connection:
url = url + connection + '/'
params = init.Broker.build_get_parameters()
if isinstance(fields, basestring):
fields = fields.split(',')
if fields is not None and not isinstance(fields, list):
raise pytxValueError("fields must be a list")
if fields is not None:
params[t.FIELDS] = ','.join(f.strip() for f in fields)
if metadata:
params[t.METADATA] = 1
if full_response:
return init.Broker.get(url, params=params)
else:
if connection:
return init.Broker.get_generator(cls_or_self,
url,
t.NO_TOTAL,
to_dict=dict_generator,
params=params)
else:
if isinstance(cls_or_self, type):
return init.Broker.get_new(cls_or_self,
init.Broker.get(url,
params=params))
else:
cls_or_self.populate(init.Broker.get(url, params=params))
[docs] def save(self):
"""
Save this object. If it is a new object, use self._fields to build the
POST and submit to the appropriate URL. If it is an update to an
existing object, use self._changed to only submit the modified
attributes in the POST.
:returns: dict (using json.loads())
"""
if self._new:
params = dict(
(n, getattr(self, n)) for n in self._fields if n != c.ID
)
if ti.PRIVACY_TYPE not in params:
raise pytxValueError("Must provide a %s" % ti.PRIVACY_TYPE)
pass
else:
if (params[ti.PRIVACY_TYPE] != pt.VISIBLE and
len(params[ti.PRIVACY_MEMBERS].split(',')) < 1):
raise pytxValueError("Must provide %s" % ti.PRIVACY_MEMBERS)
return init.Broker.post(self._URL, params=params)
else:
params = dict(
(n, getattr(self, n)) for n in self._changed if n != c.ID
)
if (ti.PRIVACY_TYPE in params and
params[ti.PRIVACY_TYPE] != pt.VISIBLE and
len(params[ti.PRIVACY_MEMBERS].split(',')) < 1):
raise pytxValueError("Must provide %s" % ti.PRIVACY_MEMBERS)
return init.Broker.post(self._DETAILS, params=params)
[docs] def expire(self, timestamp):
"""
Expire by setting the 'expired_on' timestamp.
:param timestamp: The timestamp to set for an expiration date.
:type timestamp: str
"""
init.Broker.is_timestamp(timestamp)
self.set(ti.EXPIRED_ON, timestamp)
self.save()
[docs] def false_positive(self, object_id):
"""
Mark an object as a false positive by setting the status to
UNKNOWN.
:param object_id: The object-id of the object to mark.
:type object_id: str
"""
self.set(c.STATUS, s.UNKNOWN)
self.save()
[docs] def add_connection(self, object_id):
"""
Use HTTP POST and add a connection between two objects.
:param object_id: The other object-id in the connection.
:type object_id: str
:returns: dict (using json.loads())
"""
params = {
t.RELATED_ID: object_id
}
return init.Broker.post(self._RELATED, params=params)
# DELETE REQUESTS
[docs] def delete_connection(self, object_id):
"""
Use HTTP DELETE and remove the connection to another object.
:param object_id: The other object-id in the connection.
:type object_id: str
:returns: dict (using json.loads())
"""
params = {
t.RELATED_ID: object_id
}
return init.Broker.delete(self._RELATED, params=params)