msticpy.data.drivers.mordor_driver module

Mordor/OTRF Security datasets driver.

class msticpy.data.drivers.mordor_driver.MitreAttack(attack: Dict[str, Any] | None = None, technique: str | None = None, sub_technique: str | None = None, tactics: List[str] | None = None)

Bases: object

MitreAttack container for techniques and tactics.

Create instance of MitreAttack.

Parameters:

• attack (Dict[str, Any], optional) – attack data as dictionary, by default None

• technique (str, optional) – technique ID, by default None

• sub_technique (str, optional) – sub-technique ID, by default None

• tactics (List[str], optional) – List of associated tactics, by default None

MTR_TAC_URI = 'https://attack.mitre.org/tactics/{tactic_id}/'

MTR_TECH_URI = 'https://attack.mitre.org/techniques/{technique_id}/'

property tactics_full: List[Tuple[str, str, str, str]]

Return full listing of Mitre tactics.

Returns:

List of tuples of: (ID, Name, Description, URI)

Return type:

List[Tuple[str, str, str, str]]

property technique_desc: str | None

Return Mitre technique description.

Returns:

Technique description

Return type:

Optional[str]

property technique_name: str | None

Return Mitre Technique full name.

Returns:

Name of the Mitre technique

Return type:

Optional[str]

property technique_uri: str

Return Mitre Technique URI.

Returns:

URI of the Mitre technique

Return type:

Optional[str]

class msticpy.data.drivers.mordor_driver.MordorDriver(**kwargs)

Bases: DriverBase

Mordor data driver.

Initialize the Mordor driver.

add_query_filter(name: str, query_filter: str | Iterable)

Add an expression to the query attach filter.

connect(connection_str: str | None = None, **kwargs)

Connect to data source.

Parameters:

connection_str (Optional[str]) – Connect to a data source

property connected: bool

Return true if at least one connection has been made.

Returns:

True if a successful connection has been made.

Return type:

bool

Notes

This does not guarantee that the last data source connection was successful. It is a best effort to track whether the provider has made at least one successful authentication.

property driver_queries: Iterable[Dict[str, Any]]

Return generator of Mordor query definitions.

Yields:

Iterable[Dict[str, Any]] – Iterable of Dictionaries containing query definitions.

get_driver_property(name: str) → Any

Return value or KeyError from driver properties.

static get_http_timeout(**kwargs)

Get http timeout from settings or kwargs.

property instance: str | None

Return instance name, if one is set.

Returns:

The name of driver instance or None if the driver does not support multiple instances

Return type:

Optional[str]

property loaded: bool

Return true if the provider is loaded.

Returns:

True if the provider is loaded.

Return type:

bool

Notes

This is not relevant for some providers.

query(query: str, query_source: QuerySource | None = None, **kwargs) → DataFrame | Any

Execute query string and return DataFrame of results.

Parameters:

• query (str) – The query to execute

• query_source (QuerySource) – The query definition object

• kwargs – Are passed to the underlying provider query method, if supported.

Returns:

A DataFrame (if successfull) or the underlying provider result if an error.

Return type:

Union[pd.DataFrame, Any]

property query_attach_spec: Dict[str, Set[str]]

Parameters that determine whether a query is relevant for the driver.

query_usable(query_source: QuerySource) → bool

Return True if query should be exposed for this driver.

query_with_results(query: str, **kwargs) → Tuple[DataFrame, Any]

Execute query string and return DataFrame plus native results.

Parameters:

query (str) – The query to execute

Returns:

A DataFrame and native results.

Return type:

Tuple[pd.DataFrame,Any]

property schema: Dict[str, Dict]

Return current data schema of connection.

Returns:

Data schema of current connection.

Return type:

Dict[str, Dict]

search_queries(search: str) → Iterable[str]

Search queries for matching attributes.

Parameters:

search (str) – Search string. Substrings separated by commas will be treated as OR terms - e.g. “a, b” == “a” or “b”. Substrings separated by “+” will be treated as AND terms - e.g. “a + b” == “a” and “b”

Returns:

Iterable of matching query names.

Return type:

Iterable[str]

property service_queries: Tuple[Dict[str, str], str]

Return queries retrieved from the service after connecting.

Returns:

Dictionary of query_name, query_text. Name of container to add queries to.

Return type:

Tuple[Dict[str, str], str]

set_driver_property(name: str, value: Any)

Set an item in driver properties.

class msticpy.data.drivers.mordor_driver.MordorEntry(title: str, id: str, type: str, creation_date, modification_date, contributors: List[str] = NOTHING, author: str | None = None, platform: str | None = None, description: str | None = None, tags: List[str] = NOTHING, files: List[Dict[str, Any]] = NOTHING, datasets: List[Dict[str, Any]] = NOTHING, attack_mappings: List[Dict[str, Any]] = NOTHING, notebooks: List[Dict[str, str]] = NOTHING, simulation: Dict[str, Any] = NOTHING, references: List[Any] = NOTHING, rel_file_paths: List[Dict[str, Any]] = NOTHING)

Bases: object

Mordor data set metadata.

Method generated by attrs for class MordorEntry.

attack_mappings: List[Dict[str, Any]]

author: str | None

contributors: List[str]

creation_date: datetime

datasets: List[Dict[str, Any]]

description: str | None

files: List[Dict[str, Any]]

get_attacks() → List[MitreAttack]

Return list of Mitre attack classifications.

Returns:

List of MitreAttack definitions.

Return type:

List[MitreAttack]

get_file_paths() → List[Dict[str, str]]

Return list of data file links.

Returns:

list of dictionaries describing files. Each entry has key/values for: - file_type - file_path - relative_path - qry_path

Return type:

List[Dict[str, str]]

get_notebooks() → List[Tuple[str, str, str]]

Return the list of notebooks for the dataset.

Returns:

Tuples of (name, project, link)

Return type:

List[Tuple[str, str, str]]

id: str

modification_date: datetime

notebooks: List[Dict[str, str]]

platform: str | None

references: List[Any]

simulation: Dict[str, Any]

tags: List[str]

title: str

type: str

msticpy.data.drivers.mordor_driver.download_mdr_file(file_uri: str, use_cached: bool = True, save_folder: str = '.', silent: bool = False) → DataFrame

Download data file from Mordor.

Parameters:

• file_uri (str) – The URI of the file to download.

• use_cached (bool, optional) – Try to use locally saved file first, by default True

• save_folder (str, optional) – Path to output folder, by default “.”

• silent (bool) – If True, suppress feedback. By default, False.

Returns:

DataFrame of Dataset

Return type:

pd.DataFrame

msticpy.data.drivers.mordor_driver.get_mdr_data_paths(item_type='metadata') → Generator[str, None, None]

Generate Mordor data sets from GitHub repo.

Parameters:

item_type (str, optional) – The type of item required, by default “metadata” Other values are “large”, “small.

Yields:

str – Iterable of paths

msticpy.data.drivers.mordor_driver.search_mdr_data(mdr_data: Dict[str, MordorEntry], terms: str | None = None, subset: Iterable[str] | None = None) → Set[str]

Return IDs for items matching terms.

Parameters:

• mdr_data (Dict[str, MordorEntry]) – Mordor dataset

• terms (str, optional) – Search terms, by default None (comma-separated values are treated as OR terms plus-separated values are treated as AND terms)

• subset (Iterable[str], optional) – A subset of IDs over which to search, by default None

Returns:

The set of matching IDs.

Return type:

Set[str]