msticpy.context.tiproviders.riskiq module

RiskIQ Threat Intelligence Provider.

Input can be a single IoC observable or a pandas DataFrame containing multiple observables. Processing may require a an API key and processing performance may be limited to a specific number of requests per minute for the account type that you have.

class msticpy.context.tiproviders.riskiq.RiskIQ(*, ApiID=None, AuthKey=None)

Bases: TIProvider, TIPivotProvider

RiskIQ Threat Intelligence Lookup.

Instantiate RiskIQ class.

Parameters:

  • ApiID (str | None)

  • AuthKey (str | None)

description
property ioc_query_defs: dict[str, Any]

Return current dictionary of IoC query/request definitions.

Returns:

IoC query/request definitions keyed by IoCType

Return type:

dict[str, Any]

classmethod is_known_type(item_type)

Return True if this a known IoC Type.

Parameters:

item_type (str) – IoCType string to test

Returns:

True if known type.

Return type:

bool

is_supported_type(item_type)

Return True if the passed type is supported.

Parameters:

  • item_type (Union[str, IoCType]) – type name or instance

  • self (Self)

Returns:

True if supported.

Return type:

bool

property item_query_defs: dict[str, Any]

Return current dictionary of IoC query/request definitions.

Returns:

IoC query/request definitions keyed by IoCType

Return type:

dict[str, Any]

lookup_ioc(ioc, ioc_type=None, query_type=None, *, provider_name=None)

Lookup a single IoC observable.

Parameters:

  • ioc (str) – IoC Observable value

  • ioc_type (str, optional) – IoC Type, by default None (type will be inferred)

  • query_type (str, optional) – Specify the data subtype to be queried, by default None. If not specified the default record type for the IoC type will be returned.

  • provider_name (str, optional) – Name of the provider to use for query

  • self (Self)

Returns:

The returned results.

Return type:

pd.DataFrame

lookup_iocs(data, ioc_col=None, ioc_type_col=None, query_type=None)

Lookup collection of IoC observables.

Parameters:

  • data (Union[pd.DataFrame, dict[str, str], Iterable[str]]) – Data input in one of three formats: 1. Pandas dataframe (you must supply the column name in ioc_col parameter) 2. Dict of observable, IoCType 3. Iterable of observables - IoCTypes will be inferred

  • ioc_col (str, optional) – DataFrame column to use for observables, by default None

  • ioc_type_col (str, optional) – DataFrame column to use for IoCTypes, by default None

  • query_type (str, optional) – Specify the data subtype to be queried, by default None. If not specified the default record type for the IoC type will be returned.

  • self (Self)

Returns:

DataFrame of results.

Return type:

pd.DataFrame

async lookup_iocs_async(data, ioc_col=None, ioc_type_col=None, query_type=None)

Call base async wrapper.

Parameters:

  • self (Self)

  • data (pd.DataFrame | dict[str, str] | Iterable[str])

  • ioc_col (str | None)

  • ioc_type_col (str | None)

  • query_type (str | None)

Return type:

pd.DataFrame

lookup_item(item, item_type=None, query_type=None)

Lookup a single item.

Parameters:

  • item (str) – Item value to lookup

  • item_type (str, optional) – The Type of the value to lookup, by default None (type will be inferred)

  • query_type (str, optional) – Specify the data subtype to be queried, by default None. If not specified the default record type for the item_value will be returned.

  • self (Self)

Returns:

The lookup result: result - Positive/Negative, details - Lookup Details (or status if failure), raw_result - Raw Response reference - URL of the item

Return type:

pd.DataFrame

Raises:

NotImplementedError – If attempting to use an HTTP method or authentication protocol that is not supported.

Notes

Note: this method uses memoization (lru_cache) to cache results for a particular observable to try avoid repeated network calls for the same item.

lookup_items(data, item_col=None, item_type_col=None, query_type=None)

Lookup collection of items.

Parameters:

  • data (Union[pd.DataFrame, dict[str, str], Iterable[str]]) – Data input in one of three formats: 1. Pandas dataframe (you must supply the column name in item_col parameter) 2. Dict of items 3. Iterable of items

  • item_col (str, optional) – DataFrame column to use for items, by default None

  • item_type_col (str, optional) – DataFrame column to use for types, by default None

  • query_type (str, optional) – Specify the data subtype to be queried, by default None. If not specified the default record type for the type will be returned.

  • self (Self)

Returns:

DataFrame of results.

Return type:

pd.DataFrame

async lookup_items_async(data, item_col=None, item_type_col=None, query_type=None, *, prog_counter=None, item_type=None)

Lookup collection of items.

Parameters:

  • data (Union[pd.DataFrame, dict[str, str], Iterable[str]]) – Data input in one of three formats: 1. Pandas dataframe (you must supply the column name in item_col parameter) 2. Dict of items, Type 3. Iterable of items - Types will be inferred

  • item_col (str, optional) – DataFrame column to use for items, by default None

  • item_type_col (str, optional) – DataFrame column to use for Types, by default None

  • query_type (str, optional) – Specify the data subtype to be queried, by default None. If not specified the default record type for the item will be returned.

  • prog_counter (ProgressCounter, Optional) – Progress Counter to display progess of IOC searches.

  • item_type (str, Optional) – Type of item

  • self (Self)

Returns:

DataFrame of results.

Return type:

pd.DataFrame

property name: str

Return the name of the provider.

parse_results(response)

Return the details of the response.

Parameters:

  • response (Dict) – The returned data response

  • self (Self)

Returns:

bool = positive or negative hit ResultSeverity = enumeration of severity Object with match details

Return type:

Tuple[bool, ResultSeverity, Any]

pivot_value(prop, host, *, start=None, end=None, exclude_links=True, explode_rules=False, drop_links=False, **kwargs)

Perform a pivot on a single value.

Parameters:

  • self (Self)

  • prop (str)

  • host (str)

  • start (datetime | None)

  • end (datetime | None)

  • exclude_links (bool)

  • explode_rules (bool)

  • drop_links (bool)

  • kwargs (str)

Return type:

pd.DataFrame

register_pivots(pivot_reg, pivot)

Register pivot functions for the TI Provider.

Parameters:

  • pivot_reg (PivotRegistration) – Pivot registration settings.

  • pivot (Pivot) – Pivot library instance

  • self (Self)

Return type:

None

static resolve_ioc_type(observable)

Return IoCType determined by IoCExtract.

Parameters:

observable (str) – IoC observable string

Returns:

IoC Type (or unknown if type could not be determined)

Return type:

str

static resolve_item_type(item)

Return IoCType determined by ItemExtract.

Parameters:

item (str) – Item string

Returns:

IoCType (or unknown if type could not be determined)

Return type:

str

property supported_types: list[str]

Return list of supported types for this provider.

Returns:

List of supported type names

Return type:

list[str]

classmethod usage()

Print usage of provider.

Return type:

None

exception msticpy.context.tiproviders.riskiq.RiskIQAPIUserError(api_exception)

Bases: RiskIQUserError

RiskIQ API provider exception.

Create RiskIQ API exception.

Parameters:

api_exception (ptanalyzer.AnalyzerAPIError) – Underlying API exception.

Return type:

None

DEF_HELP_URI: ClassVar[tuple[str, str]] = ('msticpy documentation', 'https://msticpy.readthedocs.org')
add_note()

Exception.add_note(note) – add a note to the exception

args
display_exception()

Output the exception HTML or text friendly exception.

Return type:

None

property help_uri: tuple[str, str] | str

Get the default help URI.

classmethod no_display_exceptions()

Context manager to block exception display to IPython/stdout.

Return type:

Generator[None, Any, None]

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception msticpy.context.tiproviders.riskiq.RiskIQUserError(message, help_uri=None)

Bases: MsticpyUserError

Generic RiskIQ provider exception.

Create RiskIQ provider exception.

Parameters:

  • message (str) – Error message

  • help_uri (Union[Tuple[str, str], str, None], optional) – Override the default help URI.

Return type:

None

DEF_HELP_URI: ClassVar[tuple[str, str]] = ('msticpy documentation', 'https://msticpy.readthedocs.org')
add_note()

Exception.add_note(note) – add a note to the exception

args
display_exception()

Output the exception HTML or text friendly exception.

Return type:

None

property help_uri: tuple[str, str] | str

Get the default help URI.

classmethod no_display_exceptions()

Context manager to block exception display to IPython/stdout.

Return type:

Generator[None, Any, None]

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.