msticpy.context.tilookup module
Module for TILookup classes.
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.tilookup.ProgressCounter(total: int)
Bases:
object
Progress counter for async tasks.
Initialize the class.
- async decrement(increment: int = 1)
Decrement the counter.
- async get_remaining() int
Get the current remaining count.
- class msticpy.context.tilookup.TILookup(providers: Optional[List[str]] = None, **kwargs)
Bases:
object
Threat Intel observable lookup from providers.
Initialize TILookup instance.
- Parameters
primary_providers (Optional[List[TIProvider]], optional) – Primary TI Providers, by default None
secondary_providers (Optional[List[TIProvider]], optional) – Secondary TI Providers, by default None
providers (Optional[List[str]], optional) – List of provider names to load, by default all available providers are loaded. To see the list of available providers call TILookup.list_available_providers(). Note: if primary_provides or secondary_providers is specified This will override the providers list.
- add_provider(provider: TIProvider, name: Optional[str] = None, primary: bool = True)
Add a TI provider to the current collection.
- Parameters
provider (TIProvider) – Provider instance
name (str, optional) – The name to use for the provider (overrides the class name of provider)
primary (bool, optional) – “primary” or “secondary” if False, by default “primary”
- property available_providers: List[str]
Return a list of builtin providers.
- Returns
List of TI Provider classes.
- Return type
List[str]
- classmethod browse(data: DataFrame, severities: Optional[List[str]] = None, **kwargs)
Return TI Results list browser.
- Parameters
data (pd.DataFrame) – TI Results data from TIProviders
severities (Optional[List[str]], optional) – A list of the severity classes to show. By default these are [‘warning’, ‘high’]. Pass [‘information’, ‘warning’, ‘high’] to see all results.
kwargs – passed to SelectItem constructor.
- Returns
SelectItem browser for TI Data.
- Return type
- classmethod browse_results(data: DataFrame, severities: Optional[List[str]] = None, **kwargs)
Return TI Results list browser.
- Parameters
data (pd.DataFrame) – TI Results data from TIProviders
severities (Optional[List[str]], optional) – A list of the severity classes to show. By default these are [‘warning’, ‘high’]. Pass [‘information’, ‘warning’, ‘high’] to see all results.
kwargs – passed to SelectItem constructor.
- Returns
SelectItem browser for TI Data.
- Return type
- property configured_providers: List[str]
Return a list of avaliable providers that have configuration details present.
- Returns
List of TI Provider classes.
- Return type
List[str]
- disable_provider(providers: Union[str, Iterable[str]])
Set the provider as secondary (not used by default).
- Parameters
providers (Union[str, Iterable[str]) – Provider name or list of names. Use list_available_providers() to see the list of loaded providers.
- Raises
ValueError – If the provider name is not recognized.
- enable_provider(providers: Union[str, Iterable[str]])
Set the provider(s) as primary (used by default).
- Parameters
providers (Union[str, Iterable[str]) – Provider name or list of names. Use list_available_providers() to see the list of loaded providers.
- Raises
ValueError – If the provider name is not recognized.
- classmethod list_available_providers(show_query_types=False, as_list: bool = False) Optional[List[str]]
Print a list of builtin providers with optional usage.
- Parameters
show_query_types (bool, optional) – Show query types supported by providers, by default False
as_list (bool, optional) – Return list of providers instead of printing to stdout. Note: if you specify show_query_types this will be printed irrespective of this parameter setting.
- Returns
A list of provider names (if return_list=True)
- Return type
Optional[List[str]]
- property loaded_providers: Dict[str, TIProvider]
Return dictionary of loaded providers.
- Returns
[description]
- Return type
Dict[str, TIProvider]
- lookup_ioc(observable: Optional[str] = None, ioc_type: Optional[str] = None, ioc_query_type: Optional[str] = None, providers: Optional[List[str]] = None, default_providers: Optional[List[str]] = None, prov_scope: str = 'primary', **kwargs) Tuple[bool, List[Tuple[str, LookupResult]]]
Lookup single IoC in active providers.
- Parameters
observable (str) – IoC observable (ioc is also an alias for observable)
ioc_type (str, optional) – One of IoCExtract.IoCType, by default None If none, the IoC type will be inferred
ioc_query_type (str, optional) – The ioc query type (e.g. rep, info, malware)
providers (List[str]) – Explicit list of providers to use
default_providers (Optional[List[str]], optional) – Used by pivot functions as a fallback to providers. If providers is specified, it will override this parameter.
prov_scope (str, optional) – Use “primary”, “secondary” or “all” providers, by default “primary”
kwargs – Additional arguments passed to the underlying provider(s)
- Returns
The result returned as a tuple(bool, list): bool indicates whether a TI record was found in any provider list has an entry for each provider result
- Return type
Tuple[bool, List[Tuple[str, LookupResult]]]
- lookup_iocs(data: Union[DataFrame, Mapping[str, str], Iterable[str]], obs_col: Optional[str] = None, ioc_type_col: Optional[str] = None, ioc_query_type: Optional[str] = None, providers: Optional[List[str]] = None, default_providers: Optional[List[str]] = None, prov_scope: str = 'primary', **kwargs) DataFrame
Lookup a collection of IoCs.
- Parameters
data (Union[pd.DataFrame, Mapping[str, str], Iterable[str]]) – Data input in one of three formats: 1. Pandas dataframe (you must supply the column name in obs_col parameter) 2. Mapping (e.g. a dict) of [observable, IoCType] 3. Iterable of observables - IoCTypes will be inferred
obs_col (str, optional) – DataFrame column to use for observables, by default None (“col” and “column” are also aliases for this parameter)
ioc_type_col (str, optional) – DataFrame column to use for IoCTypes, by default None
ioc_query_type (str, optional) – The ioc query type (e.g. rep, info, malware)
providers (List[str]) – Explicit list of providers to use
default_providers (Optional[List[str]], optional) – Used by pivot functions as a fallback to providers. If providers is specified, it will override this parameter.
prov_scope (str, optional) – Use “primary”, “secondary” or “all” providers, by default “primary”
kwargs – Additional arguments passed to the underlying provider(s)
- Returns
DataFrame of results
- Return type
pd.DataFrame
- lookup_iocs_sync(data: Union[DataFrame, Mapping[str, str], Iterable[str]], obs_col: Optional[str] = None, ioc_type_col: Optional[str] = None, ioc_query_type: Optional[str] = None, providers: Optional[List[str]] = None, default_providers: Optional[List[str]] = None, prov_scope: str = 'primary', **kwargs) DataFrame
Lookup a collection of IoCs.
- Parameters
data (Union[pd.DataFrame, Mapping[str, str], Iterable[str]]) – Data input in one of three formats: 1. Pandas dataframe (you must supply the column name in obs_col parameter) 2. Mapping (e.g. a dict) of [observable, IoCType] 3. Iterable of observables - IoCTypes will be inferred
obs_col (str, optional) – DataFrame column to use for observables, by default None (“col” and “column” are also aliases for this parameter)
ioc_type_col (str, optional) – DataFrame column to use for IoCTypes, by default None
ioc_query_type (str, optional) – The ioc query type (e.g. rep, info, malware)
providers (List[str]) – Explicit list of providers to use
default_providers (Optional[List[str]], optional) – Used by pivot functions as a fallback to providers. If providers is specified, it will override this parameter.
prov_scope (str, optional) – Use “primary”, “secondary” or “all” providers, by default “primary”
kwargs – Additional arguments passed to the underlying provider(s)
- Returns
DataFrame of results
- Return type
pd.DataFrame
- property provider_status: Iterable[str]
Return loaded provider status.
- Returns
List of providers and descriptions.
- Return type
Iterable[str]
- provider_usage()
Print usage of loaded providers.
- classmethod reload_provider_settings()
Reload provider settings from config.
- reload_providers()
Reload settings and provider classes.
- static result_to_df(ioc_lookup: Tuple[bool, List[Tuple[str, LookupResult]]]) DataFrame
Return DataFrame representation of IoC Lookup response.
- Parameters
ioc_lookup (Tuple[bool, List[Tuple[str, LookupResult]]]) – Output from lookup_ioc
- Returns
The response as a DataFrame with a row for each provider response.
- Return type
pd.DataFrame
- set_provider_state(prov_dict: Dict[str, bool])
Set a dict of providers to primary/secondary.
- Parameters
prov_dict (Dict[str, bool]) – Dictionary of provider name and bool - True if enabled/primary, False if disabled/secondary.