msticpy.data package

msticpy.nbtools.entityschema module

entityschema module.

Module for V3 Entities class

class msticpy.nbtools.entityschema.Account(src_entity: Mapping[str, Any] = None, src_event: Mapping[str, Any] = None, role: str = 'subject', **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

Account Entity class.

Name

Account Name

Type:str
NTDomain

Account NTDomain

Type:str
UPNSuffix

Account UPNSuffix

Type:str
Host

Account Host

Type:Host
LogonId

Account LogonId (deprecated)

Type:str
Sid

Account Sid

Type:str
AadTenantId

Account AadTenantId

Type:str
AadUserId

Account AadUserId

Type:str
PUID

Account PUID

Type:str
IsDomainJoined

Account IsDomainJoined

Type:bool
DisplayName

Account DisplayName

Type:str

Create a new instance of the entity type.

Parameters:
  • src_entity (Mapping[str, Any], optional) – Create entity from existing Account entity or other mapping object that implements entity properties. (the default is None)
  • src_event (Mapping[str, Any], optional) – Create entity from event properties (the default is None)
  • role (str, optional) – ‘subject’ or ‘target’ - only relevant if the entity is being constructed from an event. (the default is ‘subject’)
Other Parameters:
 

kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.

description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
qualified_name

Windows qualified account name.

to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.Alert(src_entity: Mapping[str, Any] = None, **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

Alert Entity class.

DisplayName

Alert DisplayName

Type:str
CompromisedEntity

Alert CompromisedEntity

Type:str
Count

Alert Count

Type:int
StartTimeUtc

Alert StartTimeUtc

Type:datetime
EndTimeUtc

Alert EndTimeUtc

Type:datetime
Severity

Alert Severity

Type:str
SystemAlertIds

Alert SystemAlertIds

Type:List[str]
AlertType

Alert AlertType

Type:str
VendorName

Alert VendorName

Type:str
ProviderName

Alert ProviderName

Type:str

Create a new instance of the entity type.

Parameters:src_entity (Mapping[str, Any], optional) – Create entity from existing entity or other mapping object that implements entity properties. (the default is None)
Other Parameters:
 kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.
description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.Algorithm

Bases: enum.Enum

FileHash Algorithm Enumeration.

MD5 = 1
SHA1 = 2
SHA256 = 3
SHA256AC = 4
Unknown = 0
class msticpy.nbtools.entityschema.AzureResource(src_entity: Mapping[str, Any] = None, **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

AzureResource Entity class.

ResourceId

AzureResource ResourceId

Type:str
SubscriptionId

AzureResource SubscriptionId

Type:str
ResourceIdParts

AzureResource ResourceIdParts

Type:Dict[str, str]

Create a new instance of the entity type.

Parameters:src_entity (Mapping[str, Any], optional) – Create entity from existing entity or other mapping object that implements entity properties. (the default is None)
Other Parameters:
 kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.
description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.CloudApplication(src_entity: Mapping[str, Any] = None, **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

CloudApplication Entity class.

Name

CloudApplication Name

Type:str

Create a new instance of the entity type.

Parameters:src_entity (Mapping[str, Any], optional) – Create entity from existing entity or other mapping object that implements entity properties. (the default is None)
Other Parameters:
 kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.
description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.DnsResolve(src_entity: Mapping[str, Any] = None, **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

DNS Resolve Entity class.

DomainName

DnsResolve DomainName

Type:str
IpAdresses

DnsResolve IpAdresses

Type:List[str]
DnsServerIp

DnsResolve DnsServerIp

Type:IPAddress
HostIpAddress

DnsResolve HostIpAddress

Type:IPAddress

Create a new instance of the entity type.

Parameters:src_entity (Mapping[str, Any], optional) – Create entity from existing entity or other mapping object that implements entity properties. (the default is None)
Other Parameters:
 kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.
description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.ElevationToken

Bases: enum.Enum

ElevationToken enumeration.

Default = 0
Full = 1
Limited = 2
class msticpy.nbtools.entityschema.Entity(src_entity: Mapping[str, Any] = None, **kwargs)

Bases: abc.ABC

Entity abstract base class.

Implements common methods for Entity classes

Create a new instance of an entity.

Parameters:src_entity (Mapping[str, Any], optional) – If src_entity is supplied it attempts to extract common properties from the source entity and assign them to the new instance. (the default is None)
Other Parameters:
 kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.
description_str

Return Entity Description.

Returns:Entity description (optional). If not overridden by the Entity instance type, it will return the Type string.
Return type:str
classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.File(src_entity: Mapping[str, Any] = None, src_event: Mapping[str, Any] = None, role: str = 'new', **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

File Entity class.

FullPath

File FullPath

Type:str
Directory

File Directory

Type:str
Name

File Name

Type:str
Md5

File Md5

Type:str
Host

File Host

Type:str
Sha1

File Sha1

Type:str
Sha256

File Sha256

Type:str
Sha256Ac

File Sha256Ac

Type:str
FileHashes

File FileHashes

Type:List[FileHash]

Create a new instance of the entity type.

Parameters:
  • src_entity (Mapping[str, Any], optional) – Create entity from existing entity or other mapping object that implements entity properties. (the default is None)
  • src_event (Mapping[str, Any], optional) – Create entity from event properties (the default is None)
  • role (str, optional) – ‘new’ or ‘parent’ - only relevant if the entity is being constructed from an event. (the default is ‘new’)
Other Parameters:
 

kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.

description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
path_separator

Return the path separator used by the file.

properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.FileHash(src_entity: Mapping[str, Any] = None, **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

File Hash class.

Algorithm

FileHash Algorithm

Type:Algorithm
Value

FileHash Value

Type:str

Create a new instance of the entity type.

Parameters:src_entity (Mapping[str, Any], optional) – Create entity from existing entity or other mapping object that implements entity properties. (the default is None)
Other Parameters:
 kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.
description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.GeoLocation(src_entity: Mapping[str, Any] = None, **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

GeoLocation class.

CountryCode

GeoLocation CountryCode

Type:str
CountryName

GeoLocation CountryName

Type:str
State

GeoLocation State

Type:str
City

GeoLocation City

Type:str
Longitude

GeoLocation Longitude

Type:float
Latitude

GeoLocation Latitude

Type:float
Asn

GeoLocation Asn

Type:str

Create a new instance of the entity type.

Parameters:src_entity (Mapping[str, Any], optional) – Create entity from existing entity or other mapping object that implements entity properties. (the default is None)
Other Parameters:
 kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.
description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.Host(src_entity: Mapping[str, Any] = None, src_event: Mapping[str, Any] = None, **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

Host Entity class.

DnsDomain

Host DnsDomain

Type:str
NTDomain

Host NTDomain

Type:str
HostName

Host HostName

Type:str
NetBiosName

Host NetBiosName

Type:str
AzureID

Host AzureID

Type:str
OMSAgentID

Host OMSAgentID

Type:str
OSFamily

Host OSFamily

Type:str
IsDomainJoined

Host IsDomainJoined

Type:bool

Create a new instance of the entity type.

Parameters:
  • src_entity (Mapping[str, Any], optional) – Create entity from existing entity or other mapping object that implements entity properties. (the default is None)
  • src_event (Mapping[str, Any], optional) – Create entity from event properties (the default is None)
Other Parameters:
 

kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.

computer

Return computer from source event.

description_str

Return Entity Description.

fqdn

Construct FQDN from host + dns.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.HostLogonSession(src_entity: Mapping[str, Any] = None, src_event: Mapping[str, Any] = None, **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

HostLogonSession Entity class.

Account

HostLogonSession Account

Type:Account
StartTimeUtc

HostLogonSession StartTimeUtc

Type:datetime
EndTimeUtc

HostLogonSession EndTimeUtc

Type:datetime
Host

HostLogonSession Host

Type:Host
SessionId

HostLogonSession SessionId

Type:str

Create a new instance of the entity type.

Parameters:
  • src_entity (Mapping[str, Any], optional) – Create entity from existing entity or other mapping object that implements entity properties. (the default is None)
  • src_event (Mapping[str, Any], optional) – Create entity from event properties (the default is None)
Other Parameters:
 

kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.

description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.IpAddress(src_entity: Mapping[str, Any] = None, src_event: Mapping[str, Any] = None, **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

IPAddress Entity class.

Address

IpAddress Address

Type:str
Location

IpAddress Location

Type:GeoLocation
ThreatIntelligence

IpAddress ThreatIntelligence

Type:List[ThreatIntelligence]

Create a new instance of the entity type.

Parameters:
  • src_entity (Mapping[str, Any], optional) – Create entity from existing entity or other mapping object that implements entity properties. (the default is None)
  • src_event (Mapping[str, Any], optional) – Create entity from event properties (the default is None)
Other Parameters:
 

kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.

description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
ip_address

Return a python ipaddress object from the entity property.

properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.Malware(src_entity: Mapping[str, Any] = None, **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

Malware Entity class.

Name

Malware Name

Type:str
Category

Malware Category

Type:str
File

Malware File

Type:File
Files

Malware Files

Type:List[File]
Processes

Malware Processes

Type:List[Process]

Create a new instance of the entity type.

Parameters:src_entity (Mapping[str, Any], optional) – Create entity from existing entity or other mapping object that implements entity properties. (the default is None)
Other Parameters:
 kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.
description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.NetworkConnection(src_entity: Mapping[str, Any] = None, **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

NetworkConnection Entity class.

SourceAddress

NetworkConnection SourceAddress

Type:IPAddress
SourcePort

NetworkConnection SourcePort

Type:int
DestinationAddress

NetworkConnection DestinationAddress

Type:IPAddress
DestinationPort

NetworkConnection DestinationPort

Type:int
Protocol

NetworkConnection Protocol

Type:str

Create a new instance of the entity type.

Parameters:src_entity (Mapping[str, Any], optional) – Create entity from existing entity or other mapping object that implements entity properties. (the default is None)
Other Parameters:
 kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.
description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.OSFamily

Bases: enum.Enum

OSFamily enumeration.

Linux = 0
Windows = 1
class msticpy.nbtools.entityschema.Process(src_entity: Mapping[str, Any] = None, src_event: Mapping[str, Any] = None, role='new', **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

Process Entity class.

ProcessId

Process ProcessId

Type:str
CommandLine

Process CommandLine

Type:str
ElevationToken

Process ElevationToken

Type:str
CreationTimeUtc

Process CreationTimeUtc

Type:datetime
ImageFile

Process ImageFile

Type:File
Account

Process Account

Type:Account
ParentProcess

Process ParentProcess

Type:Process
Host

Process Host

Type:Host
LogonSession

Process LogonSession

Type:HostLogonSession

Create a new instance of the entity type.

Parameters:
  • src_entity (Mapping[str, Any], optional) – Create entity from existing entity or other mapping object that implements entity properties. (the default is None)
  • src_event (Mapping[str, Any], optional) – Create entity from event properties (the default is None)
  • role (str, optional) – ‘new’ or ‘parent’ - only relevant if the entity is being constructed from an event. (the default is ‘new’)
Other Parameters:
 

kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.

ProcessFilePath

Return the name of the process file path.

ProcessName

Return the name of the process file.

description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.RegistryHive

Bases: enum.Enum

RegistryHive enumeration.

HKEY_A = 8
HKEY_CLASSES_ROOT = 1
HKEY_CURRENT_CONFIG = 2
HKEY_CURRENT_USER = 9
HKEY_CURRENT_USER_LOCAL_SETTINGS = 4
HKEY_LOCAL_MACHINE = 0
HKEY_PERFORMANCE_DATA = 5
HKEY_PERFORMANCE_NLSTEXT = 6
HKEY_PERFORMANCE_TEXT = 7
HKEY_USERS = 3
class msticpy.nbtools.entityschema.RegistryKey(src_entity: Mapping[str, Any] = None, **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

RegistryKey Entity class.

Hive

RegistryKey Hive

Type:RegistryHive
Key

RegistryKey Key

Type:str

Create a new instance of the entity type.

Parameters:src_entity (Mapping[str, Any], optional) – Create entity from existing entity or other mapping object that implements entity properties. (the default is None)
Other Parameters:
 kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.
description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.RegistryValue(src_entity: Mapping[str, Any] = None, **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

RegistryValue Entity class.

Key

RegistryValue Key

Type:str
Name

RegistryValue Name

Type:str
Value

RegistryValue Value

Type:str
ValueType

RegistryValue ValueType

Type:str

Create a new instance of the entity type.

Parameters:src_entity (Mapping[str, Any], optional) – Create entity from existing entity or other mapping object that implements entity properties. (the default is None)
Other Parameters:
 kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.
description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.SecurityGroup(src_entity: Mapping[str, Any] = None, **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

SecurityGroup Entity class.

DistinguishedName

SecurityGroup DistinguishedName

Type:str
SID

SecurityGroup SID

Type:str
ObjectGuid

SecurityGroup ObjectGuid

Type:str

Create a new instance of the entity type.

Parameters:src_entity (Mapping[str, Any], optional) – Create entity from existing entity or other mapping object that implements entity properties. (the default is None)
Other Parameters:
 kwargs (Dict[str, Any]) – Supply the entity properties as a set of kw arguments.
description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.Threatintelligence(src_entity: Mapping[str, Any] = None, **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

Threatintelligence Entity class.

ProviderName

Threatintelligence ProviderName

Type:str
ThreatType

Threatintelligence ThreatType

Type:str
ThreatName

Threatintelligence ThreatName

Type:str
Confidence

Threatintelligence Confidence

Type:str

Threatintelligence ReportLink

Type:str
ThreatDescription

Threatintelligence ThreatDescription

Type:str

Create a new instance of the entity type.

param src_entity:
 instantiate entity using properties of src entity
param kwargs:key-value pair representation of entity
description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str
class msticpy.nbtools.entityschema.UnknownEntity(src_entity: Mapping[str, Any] = None, **kwargs)

Bases: msticpy.nbtools.entityschema.Entity

Generic Entity class.

Create a new instance of the entity type.

param src_entity:
 instantiate entity using properties of src entity
param kwargs:key-value pair representation of entity
description_str

Return Entity Description.

classmethod instantiate_entity(raw_entity: Mapping[str, Any]) → Union[msticpy.nbtools.entityschema.Entity, Mapping[str, Any]]

Class factory to return entity from raw dictionary representation.

Parameters:raw_entity (Mapping[str, Any]) – A mapping object (e.g. dictionary or pandas Series) that contains the properties of the entity.
Returns:The instantiated entity
Return type:Entity
properties

Return dictionary properties of entity.

Returns:Entity properties.
Return type:dict
to_html() → str

Return HTML representation of entity.

Returns:HTML representation of entity
Return type:str

msticpy.nbtools.security_alert module

Module for SecurityAlert class.

class msticpy.nbtools.security_alert.SecurityAlert(src_row: pandas.core.series.Series = None)

Bases: msticpy.nbtools.security_base.SecurityBase

Security Alert Class.

Instantiates a security alert from a pandas Series and provides convenience access methods to retrieve properties.

Instantiate a security alert from a pandas Series.

computer

Return the Computer name of the host associated with the alert.

(host FQDN, if available)

data_environment

Return the data environment of the alert for subsequent queries.

data_family

Return the data family of the alert for subsequent queries.

entities

Return a list of the Security Alert entities.

get_all_entities() → pandas.core.frame.DataFrame

Return a DataFrame of the Alert or Event entities.

Returns:Pandas DataFrame of the Alert or Event entities.
Return type:DataFrame
get_entities_of_type(entity_type: str) → List[msticpy.nbtools.entityschema.Entity]

Return entity collection for a give entity type.

Parameters:entity_type (str, optional) – The entity type.
Returns:The entities matching entity_type.
Return type:List[Entity]
get_logon_id(account: msticpy.nbtools.entityschema.Account = None) → Union[str, int, None]

Get the logon Id for the alert or the account, if supplied.

If account is not supplied, return the logon id of the first host-logon-session or account entity.

Parameters:account (Account, optional) – Account objec to use (the default is None)
Returns:The logon Id for primary account
Return type:Optional[Union[str, int]]
host_filter(operator='==')

Return a KQL host filter clause derived from the alert properties.

param operator=’==’:
 the operator to use in the filter clause. ‘==’ and ‘!=’ typically.
hostname

Return the Hostname (not FQDN) of the host associated with the alert.

ids

Return a collection of Identity properties for the alert.

is_in_azure_sub

Return True if the alert originates from an Azure Security Center host.

is_in_log_analytics

Return True if the alert originates from a Log Analytics Workspace host.

is_in_workspace

Return True if the alert has a Log Analytics WorkspaceID.

origin_time

Return the datetime of event.

primary_account

Return the primary account entity (if any) associated with this object.

Returns:primary account entity (if any)
Return type:Optional[Process]
primary_host

Return the primary host entity (if any) associated with this object.

Returns:primary host entity (if any)
Return type:Optional[Host]
primary_process

Return the primary process entity (if any) associated with this object.

Returns:primary process entity (if any)
Return type:Optional[Process]
properties

Return a dictionary of the Alert or Event properties.

Returns:dictionary of the Alert or Event properties.
Return type:Dict[str, Any]
query_params

Query parameters derived from alert.

Returns:Dictionary of parameter names/value
Return type:Dict[str, Any]
subscription_filter(operator='==')

Return a KQL subscription filter clause derived from the alert properties.

to_html(show_entities=False) → str

Return the item as HTML string.

msticpy.nbtools.security_alert_graph module

security_alert_graph.

Creates an entity graph for the alert.

Add related alerts to the graph.

Link to the entity that is common to both alerts.

msticpy.nbtools.security_alert_graph.create_alert_graph(alert: msticpy.nbtools.security_alert.SecurityAlert)

Create a networkx graph from the alert and contained entities.

msticpy.nbtools.security_base module

Module for SecurityAlert class.

class msticpy.nbtools.security_base.SecurityBase(src_row: pandas.core.series.Series = None)

Bases: msticpy.data.query_defns.QueryParamProvider

Security Base Class for alerts and events.

Instantiates a security event or alert from a pandas Series and provides convenience access methods to retrieve properties.

Instantiate a security alert from a pandas Series.

computer

Return the Computer name of the host associated with the alert.

(host FQDN, if available)

data_environment

Return the data environment of the alert for subsequent queries.

data_family

Return the data family of the alert for subsequent queries.

entities

Return a list of the Alert or Event entities.

Returns:List of the Alert or Event entities.
Return type:List[Entity]
get_all_entities() → pandas.core.frame.DataFrame

Return a DataFrame of the Alert or Event entities.

Returns:Pandas DataFrame of the Alert or Event entities.
Return type:DataFrame
get_entities_of_type(entity_type: str) → List[msticpy.nbtools.entityschema.Entity]

Return entity collection for a give entity type.

Parameters:entity_type (str, optional) – The entity type.
Returns:The entities matching entity_type.
Return type:List[Entity]
get_logon_id(account: msticpy.nbtools.entityschema.Account = None) → Union[str, int, None]

Get the logon Id for the alert or the account, if supplied.

If account is not supplied, return the logon id of the first host-logon-session or account entity.

Parameters:account (Account, optional) – Account objec to use (the default is None)
Returns:The logon Id for primary account
Return type:Optional[Union[str, int]]
host_filter(operator='==')

Return a KQL host filter clause derived from the alert properties.

param operator=’==’:
 the operator to use in the filter clause. ‘==’ and ‘!=’ typically.
hostname

Return the Hostname (not FQDN) of the host associated with the alert.

ids

Return a collection of Identity properties for the alert.

is_in_azure_sub

Return True if the alert originates from an Azure Security Center host.

is_in_log_analytics

Return True if the alert originates from a Log Analytics Workspace host.

is_in_workspace

Return True if the alert has a Log Analytics WorkspaceID.

origin_time

Return the datetime of event.

primary_account

Return the primary account entity (if any) associated with this object.

Returns:primary account entity (if any)
Return type:Optional[Process]
primary_host

Return the primary host entity (if any) associated with this object.

Returns:primary host entity (if any)
Return type:Optional[Host]
primary_process

Return the primary process entity (if any) associated with this object.

Returns:primary process entity (if any)
Return type:Optional[Process]
properties

Return a dictionary of the Alert or Event properties.

Returns:dictionary of the Alert or Event properties.
Return type:Dict[str, Any]
query_params

Query parameters derived from alert.

Returns:Dictionary of parameter names/values
Return type:Dict[str, Any]
subscription_filter(operator='==')

Return a KQL subscription filter clause derived from the alert properties.

to_html(show_entities: bool = False) → str

Return the item as HTML string.

msticpy.nbtools.security_event module

Module for SecurityEvent class.

class msticpy.nbtools.security_event.SecurityEvent(src_row: pandas.core.series.Series = None)

Bases: msticpy.nbtools.security_base.SecurityBase

SecurityEvent class.

Instantiate new instance of SecurityEvent.

param src_row:Pandas series containing single security event
computer

Return the Computer name of the host associated with the alert.

(host FQDN, if available)

data_environment

Return the data environment of the alert for subsequent queries.

data_family

Return the data family of the alert for subsequent queries.

entities

Return the list of entities extracted from the event.

Returns:The list of entities extracted from the event.
Return type:List[Entity]
get_all_entities() → pandas.core.frame.DataFrame

Return a DataFrame of the Alert or Event entities.

Returns:Pandas DataFrame of the Alert or Event entities.
Return type:DataFrame
get_entities_of_type(entity_type: str) → List[msticpy.nbtools.entityschema.Entity]

Return entity collection for a give entity type.

Parameters:entity_type (str, optional) – The entity type.
Returns:The entities matching entity_type.
Return type:List[Entity]
get_logon_id(account: msticpy.nbtools.entityschema.Account = None) → Union[str, int, None]

Get the logon Id for the alert or the account, if supplied.

If account is not supplied, return the logon id of the first host-logon-session or account entity.

Parameters:account (Account, optional) – Account objec to use (the default is None)
Returns:The logon Id for primary account
Return type:Optional[Union[str, int]]
host_filter(operator='==')

Return a KQL host filter clause derived from the alert properties.

param operator=’==’:
 the operator to use in the filter clause. ‘==’ and ‘!=’ typically.
hostname

Return the Hostname (not FQDN) of the host associated with the alert.

ids

Return a collection of Identity properties for the alert.

is_in_azure_sub

Return True if the alert originates from an Azure Security Center host.

is_in_log_analytics

Return True if the alert originates from a Log Analytics Workspace host.

is_in_workspace

Return True if the alert has a Log Analytics WorkspaceID.

origin_time

Return the datetime of event.

primary_account

Return the primary account entity (if any) associated with this object.

Returns:primary account entity (if any)
Return type:Optional[Process]
primary_host

Return the primary host entity (if any) associated with this object.

Returns:primary host entity (if any)
Return type:Optional[Host]
primary_process

Return the primary process entity (if any) associated with this object.

Returns:primary process entity (if any)
Return type:Optional[Process]
properties

Return a dictionary of the Alert or Event properties.

Returns:dictionary of the Alert or Event properties.
Return type:Dict[str, Any]
query_params

Query parameters derived from alert.

Returns:Dictionary of parameter names
Return type:Dict[str, Any]
subscription_filter(operator='==')

Return a KQL subscription filter clause derived from the alert properties.

to_html(show_entities: bool = False) → str

Return the item as HTML string.

msticpy.data.data_providers module

Data provider loader.

class msticpy.data.data_providers.AttribHolder

Bases: object

Empty class used to create hierarchical attributes.

class msticpy.data.data_providers.QueryProvider(data_environment: Union[str, msticpy.data.query_defns.DataEnvironment], driver: msticpy.data.drivers.driver_base.DriverBase = None, query_paths: List[str] = None, **kwargs)

Bases: object

Container for query store and query execution provider.

Instances of this class hold the query set and execution methods for a specific data environment.

Query provider interface to queries.

Parameters:
  • data_environment (Union[str, DataEnvironment]) – Name or Enum of environment for the QueryProvider
  • driver (DriverBase, optional) – Override the builtin driver (query execution class) and use your own driver (must inherit from DriverBase)
  • query_paths (List[str]) – Additional paths to look for query definitions.
  • kwargs – Other arguments are passed to the data provider driver.

See also

DataProviderBase
base class for data query providers.
connect(connection_str: str = None, **kwargs)

Connect to data source.

Parameters:connection_str (str) – Connection string for the data source
connected

Return True if the provider is connected.

Returns:True if the provider is connected.
Return type:bool
connection_string

Return provider connection string.

Returns:Provider connection string.
Return type:str
exec_query(query: str) → Union[pandas.core.frame.DataFrame, Any]

Execute simple query string.

Parameters:query (str) – [description]
Returns:Query results - a DataFrame if successful or a KqlResult if unsuccessful.
Return type:Union[pd.DataFrame, Any]
import_query_file(query_file: str)

Import a yaml data source definition.

Parameters:query_file (str) – Path to the file to import
classmethod list_data_environments() → List[str]

Return list of current data environments.

Returns:List of current data environments
Return type:List[str]
list_queries() → List[str]

Return list of family.query in the store.

Returns:List of queries
Return type:Iterable[str]
query_help(query_name)

Print help for query.

schema

Return current data schema of connection.

Returns:Data schema of current connection.
Return type:Dict[str, Dict]
schema_tables

Return list of tables in the data schema of the connection.

Returns:Tables in the of current connection.
Return type:List[str]

msticpy.data.azure_data module

Uses the Azure Python SDK to collect and return details related to Azure.

class msticpy.data.azure_data.AzureData(connect: bool = False)

Bases: object

Class for returning data on an Azure tenant.

Initialize connector for Azure Python SDK.

connect(client_id: str = None, tenant_id: str = None, secret: str = None)

Authenticate with the SDK.

get_metrics(metrics: str, resource_id: str, sub_id: str, sample_time: str = 'hour', start_time: int = 30) → Dict[str, pandas.core.frame.DataFrame]

Return specified metrics on Azure Resource.

Parameters:
  • metrics (str) – A string list of metrics you wish to collect (https://docs.microsoft.com/en-us/azure/azure-monitor/platform/metrics-supported)
  • resource_id (str) – The resource ID of the resource to collet the metrics from
  • sub_id (str) – The subscription ID that the resource is part of
  • sample_time (str (Optional)) – You can select to collect the metrics every hour of minute - default is hour Accepted inputs = ‘hour’ or ‘minute’
  • start_time (int (Optional)) – The number of days prior to today to collect metrics for, default is 30
Returns:

results – A Dictionary of DataFrames containing the metrics details

Return type:

dict

get_network_details(network_id: str, sub_id: str) → Tuple[pandas.core.frame.DataFrame, pandas.core.frame.DataFrame]

Return details related to an Azure network interface and associated NSG.

Parameters:
  • network_id (str) – The ID of the network interface to return details on
  • sub_id (str) – The subscription ID that the network interface is part of
Returns:

details – A dictionary of items related to the network interface

Return type:

dict

get_resource_details(sub_id: str, resource_id: str = None, resource_details: dict = None) → dict

Return the details of a specific Azure resource.

Parameters:
  • resource_id (str, optional) – The ID of the resource to get details on
  • resource_details (dict, optional) –
    If ID is unknown provide the following details:
    -resource_group_name -resource_provider_namespace -resource_type -resource_name -parent_resource_path
  • sub_id (str) – The ID of the subscription to get resources from
Returns:

resource_deatils – The details of the requested resource

Return type:

dict

get_resources(sub_id: str, rgroup: str = None, get_props: bool = False) → pandas.core.frame.DataFrame

Return details on all resources in a subscription or Resoruce Group.

Parameters:
  • sub_id (str) – The subscription ID to get resources for
  • rgroup (str (Optional)) – The name of a Resource Group to get resources for
  • get_props (bool (Optional)) – Set to True if you want to get the full properties of every resource Warning this may be a slow process depending on the number of resources
Returns:

resrouce_df – A dataframe of resource details

Return type:

pd.DataFrame

get_subscription_info(sub_id: str) → dict

Get information on a specific subscription.

Parameters:sub_id (str) – The ID of the subscription to return details on.
get_subscriptions() → pandas.core.frame.DataFrame

Get details of all subscriptions within the tenant.

class msticpy.data.azure_data.InterfaceItems(interface_id, private_ip, private_ip_allocation, public_ip, public_ip_allocation, app_sec_group, subnet, subnet_nsg, subnet_route_table)

Bases: object

attr class to build network interface details dictionary.

class msticpy.data.azure_data.Items(resource_id, name, resource_type, location, tags, plan, properties, kind, managed_by, sku, identity, state)

Bases: object

attr class to build resource details dictionary.

class msticpy.data.azure_data.NsgItems(rule_name, description, protocol, direction, src_ports, dst_ports, src_addrs, dst_addrs, action)

Bases: object

attr class to build NSG rule dictionary.

msticpy.data.data_query_reader module

Data query definition reader.

msticpy.data.data_query_reader.find_yaml_files(source_path: str, recursive: bool = False) → Iterable[pathlib.Path]

Return iterable of yaml files found in source_path.

Parameters:
  • source_path (str) – The source path to search in.
  • recursive (bool, optional) – Whether to recurse through subfolders. By default False
Returns:

File paths of yanl files found.

Return type:

Iterable[str]

msticpy.data.data_query_reader.read_query_def_file(query_file: str) → Tuple[Dict[KT, VT], Dict[KT, VT], Dict[KT, VT]]

Read a yaml data query definition file.

Parameters:query_file (str) – Path to yaml query defintion file
Returns:Tuple of dictionaries. sources - dictionary of query definitions defaults - the default parameters from the file metadata - the global metadata from the file
Return type:Tuple[Dict, Dict, Dict]
msticpy.data.data_query_reader.validate_query_defs(query_def_dict: Dict[str, Any]) → bool

Validate content of query definition.

Parameters:query_def_dict (dict) – Dictionary of query definition yaml file contents.
Returns:True if validation succeeds.
Return type:bool
Raises:ValueError – The validation failure reason is returned in the exception message (arg[0])

msticpy.data.param_extractor module

Parameter extractor helper functions for use with IPython/Juptyer queries.

msticpy.data.param_extractor.extract_query_params(query_source: msticpy.data.query_source.QuerySource, *args, **kwargs) → Tuple[Dict[str, Any], List[str]]

Get the parameters needed for the query.

Parameters:
  • query_source (QuerySource) – Query source
  • args (Tuple[QueryParamProvider]) – objects that implement QueryParamProvider (from which query parameters can be extracted).
  • kwargs (Dict[str, Any]) – custom parameter list to populate queries (override default values and values extracted from QueryParamProviders).
Returns:

Dictionary of parameter names and values to be used in the query. List of any missing parameters

Return type:

Tuple[Dict[str, Any], List[str]]

msticpy.data.query_store module

QueryStore class - holds a collection of QuerySources.

class msticpy.data.query_store.QueryStore(environment: str)

Bases: object

Repository for query definitions for a data environment.

environment

The data environment for the queries.

Type:str
data_families

The set of data families and associated queries for each.

Type:Dict[str, Dict[str, QuerySource]]

Intialize a QueryStore for a new environment.

Parameters:environment (str) – The data environment
add_data_source(source: msticpy.data.query_source.QuerySource)

Add a datasource/query to the store.

Parameters:source (QuerySource) – The source to add. An existing item with the same name will be overwritten
find_query(query_name: str) → Set[Optional[msticpy.data.query_source.QuerySource]]

Return set of queries with name query_name.

Parameters:query_name (str) – Name of the query
Returns:Set (distinct) queries matching name.
Return type:Set[QuerySource]
get_query(query_name: str, data_family: Union[str, msticpy.data.query_defns.DataFamily] = None) → msticpy.data.query_source.QuerySource

Return query with name data_family and query_name.

Parameters:
  • query_name (str) – Name of the query
  • data_family (Union[str, DataFamily]) – The data family for the query
Returns:

Query matching name and family.

Return type:

QuerySource

import_file(query_file: str)

Import a yaml data source definition.

Parameters:query_file (str) – Path to the file to import
Raises:ImportError – File read error or Syntax or semantic error found in the source file.
classmethod import_files(source_path: list, recursive: bool = False) → Dict[str, msticpy.data.query_store.QueryStore]

Import multiple query definition files from directory path.

Parameters:
  • source_path (str) – The folder containing the yaml definition files.
  • recursive (bool, optional) – True to recurse sub-directories (the default is False, which only reads from the top level)
Returns:

Dictionary of one or more environments and the QueryStore containing the queries for each environment.

Return type:

Dict[str, ‘QueryStore’]

Raises:

FileNotFoundError – File read error or Syntax or semantic error found in a source file.

query_names

Return list of family.query in the store.

Returns:List of queries
Return type:Iterable[str]

msticpy.data.drivers.driver_base module

Data driver base class.

class msticpy.data.drivers.driver_base.DriverBase(**kwargs)

Bases: abc.ABC

Base class for data providers.

Initialize new instance.

connect(connection_str: Optional[str] = None, **kwargs)

Connect to data source.

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

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.

loaded

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: msticpy.data.query_source.QuerySource = None) → Union[pandas.core.frame.DataFrame, Any]

Execute query string and return DataFrame of results.

Parameters:
  • query (str) – The query to execute
  • query_source (QuerySource) – The query definition object
Returns:

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

Return type:

Union[pd.DataFrame, Any]

query_with_results(query: str, **kwargs) → Tuple[pandas.core.frame.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]
schema

Return current data schema of connection.

Returns:Data schema of current connection.
Return type:Dict[str, Dict]

msticpy.data.drivers.kql_driver module

KQL Driver class.

class msticpy.data.drivers.kql_driver.KqlDriver(connection_str: str = None, **kwargs)

Bases: msticpy.data.drivers.driver_base.DriverBase

KqlDriver class to execute kql queries.

Instantiaite KqlDriver and optionally connect.

Parameters:connection_str (str, optional) – Connection string
connect(connection_str: Optional[str] = None, **kwargs)

Connect to data source.

Parameters:connection_str (str) – Connect to a data source
connected

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.

loaded

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: msticpy.data.query_source.QuerySource = None) → Union[pandas.core.frame.DataFrame, Any]

Execute query string and return DataFrame of results.

Parameters:
  • query (str) – The query to execute
  • query_source (QuerySource) – The query definition object
Returns:

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

Return type:

Union[pd.DataFrame, results.ResultSet]

query_with_results(query: str, **kwargs) → Tuple[pandas.core.frame.DataFrame, Any]

Execute query string and return DataFrame of results.

Parameters:query (str) – The kql query to execute
Returns:A DataFrame (if successfull) and Kql ResultSet.
Return type:Tuple[pd.DataFrame, results.ResultSet]
schema

Return current data schema of connection.

Returns:Data schema of current connection.
Return type:Dict[str, Dict]

msticpy.data.drivers.local_data_driver module

Local Data Driver class - for testing and demos.

class msticpy.data.drivers.local_data_driver.LocalDataDriver(connection_str: str = None, **kwargs)

Bases: msticpy.data.drivers.driver_base.DriverBase

LocalDataDriver class to execute kql queries.

Instantiaite LocalDataDriver and optionally connect.

Parameters:
  • connection_str (str, optional) – Connection string (not used)
  • data_paths (List[str], optional) – Paths from which to load data files
connect(connection_str: Optional[str] = None, **kwargs)

Connect to data source.

Parameters:connection_str (str) – Connect to a data source
connected

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.

loaded

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: msticpy.data.query_source.QuerySource = None) → Union[pandas.core.frame.DataFrame, Any]

Execute query string and return DataFrame of results.

Parameters:
  • query (str) – The query to execute
  • query_source (QuerySource) – The query definition object
Returns:

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

Return type:

Union[pd.DataFrame, results.ResultSet]

query_with_results(query, **kwargs)

Return query with fake results.

schema

Return current data schema of connection.

Returns:Data schema of current connection.
Return type:Dict[str, Dict]

msticpy.data.drivers.security_graph_driver module

Security Graph OData Driver class.

class msticpy.data.drivers.security_graph_driver.SecurityGraphDriver(connection_str: str = None, **kwargs)

Bases: msticpy.data.drivers.odata_driver.OData

Driver to query security graph.

Instantiaite KqlDriver and optionally connect.

Parameters:connection_str (str, optional) – Connection string
connect(connection_str: str = None, **kwargs)

Connect to oauth data source.

Parameters:connection_str (str, optional) – Connect to a data source

Notes

Connection string fields: tenant_id client_id clien_secret apiRoot apiVersion

connected

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.

loaded

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: msticpy.data.query_source.QuerySource = None) → Union[pandas.core.frame.DataFrame, Any]

Execute query string and return DataFrame of results.

Parameters:
  • query (str) – The query to execute
  • query_source (QuerySource) – The query definition object
Returns:

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

Return type:

Union[pd.DataFrame, results.ResultSet]

query_with_results(query: str, **kwargs) → Tuple[pandas.core.frame.DataFrame, Any]

Execute query string and return DataFrame of results.

Parameters:query (str) – The kql query to execute
Returns:A DataFrame (if successfull) and Kql ResultSet.
Return type:Tuple[pd.DataFrame, results.ResultSet]
schema

Return current data schema of connection.

Returns:Data schema of current connection.
Return type:Dict[str, Dict]

msticpy.data.drivers.odata_driver module

OData Driver class.

class msticpy.data.drivers.odata_driver.OData(**kwargs)

Bases: msticpy.data.drivers.driver_base.DriverBase

Parent class to retreive date from an oauth based API.

Instantiaite MDATPDriver and optionally connect.

Parameters:connect (bool, optional) – Set true if you want to connect to the provider at initialization
connect(connection_str: str = None, **kwargs)

Connect to oauth data source.

Parameters:connection_str (str, optional) – Connect to a data source

Notes

Connection string fields: tenant_id client_id clien_secret apiRoot apiVersion

connected

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.

loaded

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: msticpy.data.query_source.QuerySource = None) → Union[pandas.core.frame.DataFrame, Any]

Execute query string and return DataFrame of results.

Parameters:
  • query (str) – The query to execute
  • query_source (QuerySource) – The query definition object
Returns:

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

Return type:

Union[pd.DataFrame, Any]

query_with_results(query: str, **kwargs) → Tuple[pandas.core.frame.DataFrame, Any]

Execute query string and return DataFrame of results.

Parameters:query (str) – The kql query to execute
Returns:A DataFrame (if successfull) and Kql ResultSet.
Return type:Tuple[pd.DataFrame, results.ResultSet]
schema

Return current data schema of connection.

Returns:Data schema of current connection.
Return type:Dict[str, Dict]

msticpy.data.drivers.mdatp_driver module

MDATP OData Driver class.

class msticpy.data.drivers.mdatp_driver.MDATPDriver(connection_str: str = None, **kwargs)

Bases: msticpy.data.drivers.odata_driver.OData

KqlDriver class to retreive date from MDATP.

Instantiaite MDATPDriver and optionally connect.

Parameters:connection_str (str, optional) – Connection string
connect(connection_str: str = None, **kwargs)

Connect to oauth data source.

Parameters:connection_str (str, optional) – Connect to a data source

Notes

Connection string fields: tenant_id client_id clien_secret apiRoot apiVersion

connected

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.

loaded

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: msticpy.data.query_source.QuerySource = None) → Union[pandas.core.frame.DataFrame, Any]

Execute query string and return DataFrame of results.

Parameters:
  • query (str) – The query to execute
  • query_source (QuerySource) – The query definition object
Returns:

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

Return type:

Union[pd.DataFrame, results.ResultSet]

query_with_results(query: str, **kwargs) → Tuple[pandas.core.frame.DataFrame, Any]

Execute query string and return DataFrame of results.

Parameters:query (str) – The kql query to execute
Returns:A DataFrame (if successfull) and Kql ResultSet.
Return type:Tuple[pd.DataFrame, results.ResultSet]
schema

Return current data schema of connection.

Returns:Data schema of current connection.
Return type:Dict[str, Dict]

msticpy.data.query_defns module

Query helper definitions.

class msticpy.data.query_defns.DataEnvironment

Bases: enum.Enum

Enumeration of data environments.

Used to identify which queries are relevant for which data sources.

AzureSecurityCenter = 3
AzureSentinel = 1
Kusto = 2
LocalData = 6
LogAnalytics = 1
MDATP = 5
SecurityGraph = 4
Unknown = 0
parse = <bound method DataEnvironment.parse of <enum 'DataEnvironment'>>
class msticpy.data.query_defns.DataFamily

Bases: enum.Enum

Enumeration of data families.

Used to identify which queries are relevant for which data sources.

AzureNetwork = 6
LinuxSecurity = 2
LinuxSyslog = 5
MDATP = 7
SecurityAlert = 3
SecurityGraphAlert = 4
Unknown = 0
WindowsSecurity = 1
parse = <bound method DataFamily.parse of <enum 'DataFamily'>>
class msticpy.data.query_defns.QueryParamProvider

Bases: abc.ABC

Abstract type for QueryParamProvider.

Method query_params must be overridden by derived classes.

query_params

Return dict of query parameters.

These parameters are sourced in the object implementing this method.

Returns:
Return type:dict – dictionary of query parameter values.

msticpy.nbtools.query_mgr module

Deprecated since version version: 0.2.0 Use msticpy.data.QueryProvider instead.

msticpy.nbtools.query_schema module

Deprecated since version version: 0.2.0 Use msticpy.data.QueryProvider instead.