def save(cls_or_self, params): """ Submit params to the graph to add/update an object. If this is an uninstantiated class then we will submit to the object URL (used for creating new objects in the graph). If this is an instantiated class object then we will determine the Details URL and submit there (used for updating an existing object). :param params: The parameters to submit. :type params: dict :returns: dict (using json.loads()) """ if isinstance(cls_or_self, type): url = t.URL + t.VERSION + id + '/' else: url = cls_or_self._DETAILS 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 Broker.post(url, params=params)
def new(cls, params, retries=None, proxies=None, verify=None): """ Submit params to the graph to add an object. We will submit to the object URL used for creating new objects in the graph. When submitting new objects you must provide privacy type and privacy members if the privacy type is something other than visible. :param params: The parameters to submit. :type params: dict :param retries: Number of retries to submit before stopping. :type retries: int :param proxies: proxy info for requests. :type proxies: dict :param verify: verify info for requests. :type verify: bool, str :returns: dict (using json.loads()) """ if cls.__name__ != 'ThreatPrivacyGroup': if td.PRIVACY_TYPE not in params: raise pytxValueError('Must provide a %s' % td.PRIVACY_TYPE) pass else: if (params[td.PRIVACY_TYPE] != pt.VISIBLE and len(params[td.PRIVACY_MEMBERS].split(',')) < 1): raise pytxValueError('Must provide %s' % td.PRIVACY_MEMBERS) return Broker.post(cls._URL, params=params, retries=retries, proxies=proxies, verify=verify)
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)
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) result = Broker.post(self._URL, params=params) if r.ID in result: self.set(ti.ID, result[r.ID]) return result 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 Broker.post(self._DETAILS, params=params)
def mine(cls, role=None, full_response=False, dict_generator=False, retries=None, headers=None, proxies=None, verify=None): """ Find all of the Threat Privacy Groups that I am either the owner or a member. :param role: Whether you are an 'owner' or a 'member' :type role: 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 retries: Number of retries to fetch a page before stopping. :type retries: int :param headers: header info for requests. :type headers: dict :param proxies: proxy info for requests. :type proxies: dict :param verify: verify info for requests. :type verify: bool, str :returns: Generator, dict (using json.loads()) """ if role is None: raise pytxValueError('Must provide a role') app_id = get_app_id() + '/' if role == 'owner': role = t.THREAT_PRIVACY_GROUPS_OWNER elif role == 'member': role = t.THREAT_PRIVACY_GROUPS_MEMBER else: raise pytxValueError('Role must be "owner" or "member"') params = {'fields': ','.join(cls._fields)} url = t.URL + t.VERSION + app_id + role if full_response: return Broker.get(url, params=params, retries=retries, headers=headers, proxies=proxies, verify=verify) else: return Broker.get_generator(cls, url, params=params, to_dict=dict_generator, retries=retries, headers=headers, proxies=proxies, verify=verify)
def set_members(self, members=None, retries=None, headers=None, proxies=None, verify=None): """ Set the members of a Threat Privacy Group :param members: str or list of member IDs to add as members. :type members: str or list :param retries: Number of retries to fetch a page before stopping. :type retries: int :param headers: header info for requests. :type headers: dict :param proxies: proxy info for requests. :type proxies: dict :param verify: verify info for requests. :type verify: bool, str :returns: list """ if members is None: raise pytxValueError('Must provide members as a str or list') elif isinstance(members, list): members = ','.join(members) return Broker.post(self._DETAILS, params={'members': members}, retries=retries, headers=headers, proxies=proxies, verify=verify)
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, retries=None): """ 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. :type dict_generator: bool :param retries: Number of retries to fetch a page before stopping. :type retries: int :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 = 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 Broker.get(cls._URL, params=params, retries=retries) else: return Broker.get_generator(cls, cls._URL, to_dict=dict_generator, params=params, retries=retries)
def objects(cls, text=None, strict_text=False, type_=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 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_, 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)
def get_generator(cls, klass, url, to_dict=False, params=None, retries=None): """ Generator for managing GET requests. For each GET request it will yield the next object in the results until there are no more objects. If the GET response contains a 'next' value in the 'paging' section, the generator will automatically fetch the next set of results and continue the process until the total limit has been reached or there is no longer a 'next' value. :param klass: The class to use for the generator. :type klass: class :param url: The URL to send the GET request to. :type url: str :param to_dict: Return a dictionary instead of an instantiated class. :type to_dict: bool :param params: The GET parameters to send in the request. :type params: dict :param retries: Number of retries before stopping. :type retries: int :returns: Generator """ if not klass: raise pytxValueError('Must provide a valid object to query.') if not params: params = dict() next_ = True while next_: results = cls.get(url, params, retries) if do_log(): try: before = results[t.PAGING][p.CURSORS].get(pc.BEFORE, 'None') after = results[t.PAGING][p.CURSORS].get(pc.AFTER, 'None') count = len(results[t.DATA]) log_message( 'Cursor: BEFORE: %s, AFTER: %s, LEN: %d' % (before, after, count ) ) except Exception, e: log_message('Missing key in response: %s' % e) for data in results[t.DATA]: if to_dict: yield data else: yield cls.get_new(klass, data) try: next_ = results[t.PAGING][t.NEXT] except: log_message('No next in Pager to follow.') next_ = False if next_: url = next_ params = {}
def new(cls, params): """ Submit params to the graph to add an object. We will submit to the object URL used for creating new objects in the graph. When submitting new objects you must provide privacy type and privacy members if the privacy type is something other than visible. :param params: The parameters to submit. :type params: dict :returns: dict (using json.loads()) """ if td.PRIVACY_TYPE not in params: raise pytxValueError('Must provide a %s' % td.PRIVACY_TYPE) pass else: if (params[td.PRIVACY_TYPE] != pt.VISIBLE and len(params[td.PRIVACY_MEMBERS].split(',')) < 1): raise pytxValueError('Must provide %s' % td.PRIVACY_MEMBERS) return Broker.post(cls._URL, params=params)
def validate_limit(limit): """ Verifies the limit provided is valid and within the max limit Facebook will allow you to use. :param limit: Value to verify is a valid limit. :type limit: int, str :returns: :class:`pytxValueError` if invalid. """ try: int(limit) except ValueError, e: raise pytxValueError(e)
def get_generator(cls, klass, url, total, to_dict=False, params=None): """ Generator for managing GET requests. For each GET request it will yield the next object in the results until there are no more objects. If the GET response contains a 'next' value in the 'paging' section, the generator will automatically fetch the next set of results and continue the process until the total limit has been reached or there is no longer a 'next' value. :param klass: The class to use for the generator. :type klass: class :param url: The URL to send the GET request to. :type url: str :param total: The total number of objects to return (-1 to disable). :type total: None, int :param to_dict: Return a dictionary instead of an instantiated class. :type to_dict: bool :param params: The GET parameters to send in the request. :type params: dict :returns: Generator """ if not klass: raise pytxValueError('Must provide a valid object to query.') if not params: params = dict() if total is None: total = t.NO_TOTAL if total == t.MIN_TOTAL: yield None next_ = True while next_: results = cls.get(url, params) for data in results[t.DATA]: if total == t.MIN_TOTAL: raise StopIteration if to_dict: yield data else: yield cls.get_new(klass, data) total -= t.DEC_TOTAL try: next_ = results[t.PAGING][t.NEXT] except: next_ = False if next_: url = next_ params = {}
def details(cls_or_self, id=None, fields=None, connection=None, full_response=False, dict_generator=False, retries=None, 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 retries: Number of retries to fetch a page before stopping. :type retries: int :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 = 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 Broker.get(url, params=params, retries=retries) else: if connection: # Avoid circular imports from malware import Malware from malware_family import MalwareFamily from threat_indicator import ThreatIndicator from threat_descriptor import ThreatDescriptor conns = { conn.DESCRIPTORS: ThreatDescriptor, conn.DROPPED: Malware, conn.DROPPED_BY: Malware, conn.FAMILIES: MalwareFamily, conn.MALWARE_ANALYSES: Malware, conn.RELATED: ThreatIndicator, conn.THREAT_INDICATORS: ThreatIndicator, conn.VARIANTS: Malware, } klass = conns.get(connection, None) return Broker.get_generator(klass, url, to_dict=dict_generator, params=params, retries=retries) else: if isinstance(cls_or_self, type): return Broker.get_new( cls_or_self, Broker.get(url, params=params, retries=retries)) else: cls_or_self.populate( Broker.get(url, params=params, retries=retries)) cls_or_self._changed = []
def connections(cls_or_self, id=None, connection=None, fields=None, limit=None, full_response=False, dict_generator=False, request_dict=False, retries=None, headers=None, proxies=None, verify=None, metadata=False): """ Get object connections. Allows you to limit the fields returned for the objects. NOTE: This method can be used on both instantiated and uninstantiated classes like so: foo = ThreatIndicator(id='1234') foo.connections(connections='foo') foo = ThreatIndicator.connetions(id='1234' connections='foo') :param id: The ID of the object to get connections 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 limit: Limit the results. :type limit: None, int :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 request_dict: Return a request dictionary only. :type request_dict: bool :param retries: Number of retries to fetch a page before stopping. :type retries: int :param headers: header info for requests. :type headers: dict :param proxies: proxy info for requests. :type proxies: dict :param verify: verify info for requests. :type verify: bool, str :param metadata: Get extra metadata in the response. :type metadata: bool :returns: Generator, dict, class, str """ if isinstance(cls_or_self, type): url = t.URL + t.VERSION + id + '/' else: url = cls_or_self._DETAILS if connection: url = url + connection + '/' params = Broker.build_get_parameters(limit=limit) 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 request_dict: return Broker.request_dict('GET', url, params=params) if full_response: return Broker.get(url, params=params, retries=retries, headers=headers, proxies=proxies, verify=verify) else: # Avoid circular imports from malware import Malware from malware_family import MalwareFamily from threat_indicator import ThreatIndicator from threat_descriptor import ThreatDescriptor conns = { conn.DESCRIPTORS: ThreatDescriptor, conn.DROPPED: Malware, conn.DROPPED_BY: Malware, conn.FAMILIES: MalwareFamily, conn.MALWARE_ANALYSES: Malware, conn.RELATED: ThreatIndicator, conn.THREAT_INDICATORS: ThreatIndicator, conn.VARIANTS: Malware, } klass = conns.get(connection, None) return Broker.get_generator(klass, url, to_dict=dict_generator, params=params, retries=retries, headers=headers, proxies=proxies, verify=verify)
def objects(cls, text=None, strict_text=False, type_=None, threat_type=None, fields=None, limit=None, since=None, until=None, include_expired=False, max_confidence=None, min_confidence=None, owner=None, status=None, __raw__=None, full_response=False, dict_generator=False, retries=None, headers=None, proxies=None, verify=None): """ 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 include_expired: Include expired content in your results. :type include_expired: bool :param max_confidence: The max confidence level to search for. :type max_confidence: int :param min_confidence: The min confidence level to search for. :type min_confidence: int :param owner: The owner to limit to. This can be comma-delimited to include multiple owners. :type owner: str :param status: The status to limit to. :type status: 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. :type dict_generator: bool :param retries: Number of retries to fetch a page before stopping. :type retries: int :param headers: header info for requests. :type headers: dict :param proxies: proxy info for requests. :type proxies: dict :param verify: verify info for requests. :type verify: bool, str :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 = Broker.build_get_parameters( text=text, strict_text=strict_text, type_=type_, threat_type=threat_type, fields=fields, limit=limit, since=since, until=until, include_expired=include_expired, max_confidence=max_confidence, min_confidence=min_confidence, owner=owner, status=status ) if full_response: return Broker.get(cls._URL, params=params, retries=retries, headers=headers, proxies=proxies, verify=verify) else: return Broker.get_generator(cls, cls._URL, to_dict=dict_generator, params=params, retries=retries, headers=headers, proxies=proxies, verify=verify)
def details(cls_or_self, id=None, fields=None, connection=None, full_response=False, dict_generator=False, retries=None, headers=None, proxies=None, verify=None, 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 retries: Number of retries to fetch a page before stopping. :type retries: int :param headers: header info for requests. :type headers: dict :param proxies: proxy info for requests. :type proxies: dict :param verify: verify info for requests. :type verify: bool, str :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 = 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 Broker.get(url, params=params, retries=retries, headers=headers, proxies=proxies, verify=verify) else: if connection: # Avoid circular imports from malware import Malware from malware_family import MalwareFamily from threat_indicator import ThreatIndicator from threat_descriptor import ThreatDescriptor conns = { conn.DESCRIPTORS: ThreatDescriptor, conn.DROPPED: Malware, conn.DROPPED_BY: Malware, conn.FAMILIES: MalwareFamily, conn.MALWARE_ANALYSES: Malware, conn.RELATED: ThreatIndicator, conn.THREAT_INDICATORS: ThreatIndicator, conn.VARIANTS: Malware, } klass = conns.get(connection, None) return Broker.get_generator(klass, url, to_dict=dict_generator, params=params, retries=retries, headers=headers, proxies=proxies, verify=verify) else: if isinstance(cls_or_self, type): return Broker.get_new(cls_or_self, Broker.get(url, params=params, retries=retries, headers=headers, proxies=proxies, verify=verify)) else: cls_or_self.populate(Broker.get(url, params=params, retries=retries, headers=headers, proxies=proxies, verify=verify)) cls_or_self._changed = []
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))
def objects(cls, text=None, strict_text=False, type_=None, threat_type=None, fields=None, limit=None, since=None, until=None, include_expired=False, max_confidence=None, min_confidence=None, owner=None, status=None, __raw__=None, full_response=False, dict_generator=False, retries=None, proxies=None, verify=None): """ 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 include_expired: Include expired content in your results. :type include_expired: bool :param max_confidence: The max confidence level to search for. :type max_confidence: int :param min_confidence: The min confidence level to search for. :type min_confidence: int :param owner: The owner to limit to. This can be comma-delimited to include multiple owners. :type owner: str :param status: The status to limit to. :type status: 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. :type dict_generator: bool :param retries: Number of retries to fetch a page before stopping. :type retries: int :param proxies: proxy info for requests. :type proxies: dict :param verify: verify info for requests. :type verify: bool, str :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 = Broker.build_get_parameters( text=text, strict_text=strict_text, type_=type_, threat_type=threat_type, fields=fields, limit=limit, since=since, until=until, include_expired=include_expired, max_confidence=max_confidence, min_confidence=min_confidence, owner=owner, status=status) if full_response: return Broker.get(cls._URL, params=params, retries=retries, proxies=proxies, verify=verify) else: return Broker.get_generator(cls, cls._URL, to_dict=dict_generator, params=params, retries=retries, proxies=proxies, verify=verify)
class Broker(object): """ The Broker handles validation and submission of requests as well as consumption and returning of the result. It is leveraged by the other classes. Since the Broker takes care of the entire request/response cycle, it can be used on its own to interact with the ThreatExchange API without the need for the other classes if a developer wishes to use it. """ def __init__(self): """ Initialize the object. """ if init.__ACCESS_TOKEN__ == None: raise pytxInitError("Must init() before instantiating") @staticmethod def get_new(klass, attrs): """ Return a new instance of klass. :param klass: The class to create a new instance of. :type klass: :class: :param attrs: The attributes to set for this new instance. :type attrs: dict :returns: new instance of klass """ n = klass(**attrs) n._new = False return n @staticmethod def is_timestamp(timestamp): """ Verifies the timestamp provided is a valid timestamp. Valid timestamps are based on PHP's "strtotime" function. As of right now even with python's "dateutil" library there are some strtotime valid strings that do not validate properly. Until such a time as this can become accurate and robust enough to have feature parity with strtotime, this will always return True and leave proper timestamps to the API user. :param timestamp: Value to verify is a timestamp. :type timestamp: str :returns: True """ return True @staticmethod def validate_limit(limit): """ Verifies the limit provided is valid and within the max limit Facebook will allow you to use. :param limit: Value to verify is a valid limit. :type limit: int, str :returns: :class:`pytxValueError` if invalid. """ try: int(limit) except ValueError, e: raise pytxValueError(e) if limit > t.MAX_LIMIT: raise pytxValueError("limit cannot exceed %s (default: %s)" % (t.MAX_LIMIT, t.DEFAULT_LIMIT)) return
def details(cls_or_self, id=None, fields=None, full_response=False, dict_generator=False, retries=None, headers=None, proxies=None, verify=None, metadata=False): """ Get object details. Allows you to limit the fields returned in the object's details. 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 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 retries: Number of retries to fetch a page before stopping. :type retries: int :param headers: header info for requests. :type headers: dict :param proxies: proxy info for requests. :type proxies: dict :param verify: verify info for requests. :type verify: bool, str :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 params = 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 Broker.get(url, params=params, retries=retries, headers=headers, proxies=proxies, verify=verify) else: if isinstance(cls_or_self, type): return Broker.get_new(cls_or_self, Broker.get(url, params=params, retries=retries, headers=headers, proxies=proxies, verify=verify)) else: cls_or_self.populate(Broker.get(url, params=params, retries=retries, headers=headers, proxies=proxies, verify=verify)) cls_or_self._changed = []
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))