msticpy.context.tiproviders.pulsedive module

Pulsedive TI Provider.

class msticpy.context.tiproviders.pulsedive.PDEntityType(value)

Bases: Enum

Enum class for Pulsedive entity types.

This class defines the different types of entities that can be queried through the Pulsedive API. The available options are:

INDICATOR: Queries information about a specific indicator of compromise (IOC) THREAT: Queries information about a specific threat EXPLORE: Executes a general search across the Pulsedive data set SCAN: Submits an indicator of compromise (IOC) for scanning

EXPLORE = 'explore'
INDICATOR = 'indicator'
SCAN = 'scan'
THREAT = 'threat'
class msticpy.context.tiproviders.pulsedive.PDQuery(query_type: str, data: str)

Bases: NamedTuple

Query object for Pulsedive queries.

Create new instance of PDQuery(query_type, data)

count(value, /)

Return number of occurrences of value.

data: str

Alias for field number 1

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

query_type: str

Alias for field number 0

class msticpy.context.tiproviders.pulsedive.PDlookup(pd_key: str | None = None)

Bases: object

PDlookup: A class to interact with the Pulsedive API.

This class allows you to look up indicators of compromise (IOCs) and explore different types of data available in the Pulsedive API.

Init function to get the API key if necessary.

Parameters:

pd_key (str) – An API key for the Pulsedive API.

explore(query: str) → DataFrame

Perform a search query on the Pulsedive API.

Parameters:

query (str) – The query to perform.

Returns:

A Pandas DataFrame with the API’s response.

Return type:

pd.DataFrame

lookup_ioc(observable: str, pd_type: str = 'indicator') → DataFrame

Lookup an indicator of compromise (IOC) in the Pulsedive API.

Parameters:

  • observable (str) – The IOC to lookup.

  • pd_type (str) – The lookup type to perform, default is “indicator”.

Returns:

A Pandas DataFrame with the API’s response.

Return type:

pd.DataFrame

Notes

In the case of pd_type=”explore”, the observable value should be a pulsedive query string. See https://pulsedive.com/explore/

See also

PDlookup.lookup_threat, PDlookup.explore, PDlookup.scan

lookup_threat(observable: str) → DataFrame

Lookup a Threat name in the Pulsedive API.

Parameters:

observable (str) – The IOC to lookup.

Returns:

A Pandas DataFrame with the API’s response.

Return type:

pd.DataFrame

scan(observable: str) → DataFrame

Scan an observable in the Pulsedive API.

Parameters:

observable (str) – The observable to scan.

Returns:

A Pandas DataFrame with the API’s response.

Return type:

pd.DataFrame

class msticpy.context.tiproviders.pulsedive.Pulsedive(*, timeout: int | None = None, ApiID: str | None = None, AuthKey: str | None = None, Instance: str | None = None)

Bases: HttpTIProvider

Pulsedive TI Lookup.

Set OTX specific settings.

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: str) → bool

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: str | IoCType) → bool

Return True if the passed type is supported.

Parameters:

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

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: str, ioc_type: str | None = None, query_type: str | None = None, *, provider_name: str | None = None, timeout: int = 120) → pd.DataFrame

Lookup from a value.

Parameters:

  • ioc (str) – ioc to lookup

  • ioc_type (str, optional) – The Type of the ioc 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 ioc will be returned.

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

  • timeout (str, optional) – Timeout for lookup queries

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 item to try avoid repeated network calls for the same item.

lookup_iocs(data: pd.DataFrame | dict[str, str] | Iterable[str], ioc_col: str | None = None, ioc_type_col: str | None = None, query_type: str | None = None) → pd.DataFrame

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.

Returns:

DataFrame of results.

Return type:

pd.DataFrame

async lookup_iocs_async(data: pd.DataFrame | dict[str, str] | Iterable[str], ioc_col: str | None = None, ioc_type_col: str | None = None, query_type: str | None = None) → pd.DataFrame

Call base async wrapper.

lookup_item(item: str, item_type: str | None = None, query_type: str | None = None) → pd.DataFrame

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.

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: pd.DataFrame | dict[str, str] | Iterable[str], item_col: str | None = None, item_type_col: str | None = None, query_type: str | None = None) → pd.DataFrame

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.

Returns:

DataFrame of results.

Return type:

pd.DataFrame

async lookup_items_async(data: pd.DataFrame | dict[str, str] | Iterable[str], item_col: str | None = None, item_type_col: str | None = None, query_type: str | None = None, *, prog_counter: ProgressCounter | None = None, item_type: str | None = None) → pd.DataFrame

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

Returns:

DataFrame of results.

Return type:

pd.DataFrame

property name: str

Return the name of the provider.

parse_results(response: dict) → LookupResult

Return the details of the response.

Parameters:

response (Dict) – The returned data response

Returns:

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

Return type:

Tuple[bool, ResultSeverity, Any]

static resolve_ioc_type(observable: str) → str

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: str) → str

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() → None

Print usage of provider.