Merge pull request #2 from Microsoft/AddingNewV3Entities

Adding new V3 entities

Author: ianhelle

msticpy/_version.py

@@ -1,2 +1,2 @@
 """Version file."""
-VERSION = "0.0.71"
+VERSION = "0.0.73"

msticpy/nbtools/entityschema.py

@@ -54,6 +54,13 @@ def __init__(self, src_entity=None, **kwargs):
                             self[k] = ElevationToken(src_entity[k])
                         elif v == GeoLocation.__name__:
                             self[k] = GeoLocation(src_entity[k])
+                        elif v == Algorithm.__name__:
+                            self[k] = Algorithm(src_entity[k])
+                        elif isinstance(v, tuple):
+                            entity_list = []
+                            for col_entity in src_entity[k]:
+                                entity_list.append(Entity.instantiate_entity(col_entity))
+                            self[k] = entity_list
                         else:
                             self[k] = Entity.instantiate_entity(src_entity[k])
             # add AdditionalData dictionary if it's populated
@@ -193,8 +200,14 @@ def instantiate_entity(cls, raw_entity: dict):
         elif (raw_entity['Type'] == 'registry-value' or
               raw_entity['Type'] == 'registryvalue'):
             return RegistryValue(raw_entity)
-        elif raw_entity['Type'] == 'host-logon-session':
+        elif (raw_entity['Type'] == 'host-logon-session' or
+              raw_entity['Type'] == 'hostlogonsession'):
             return HostLogonSession(raw_entity)
+        elif raw_entity['Type'] == 'filehash':
+            return FileHash(raw_entity)
+        elif (raw_entity['Type'] == 'security-group' or
+              raw_entity['Type'] == 'securitygroup'):
+            return SecurityGroup(raw_entity)
         elif (raw_entity['Type'] == 'alerts' or
               raw_entity['Type'] == 'alert'):
             return Alert(raw_entity)
@@ -213,6 +226,7 @@ def __init__(self, src_entity=None, src_event=None, role='subject', **kwargs):
 
             :param src_entity: instantiate entity using properties of src entity
             :param src_event: instantiate entity using properties of src event
+            :param kwargs: key-value pair representation of entity
         """
 # pylint: disable=locally-disabled, C0301
         super().__init__(src_entity=src_entity, **kwargs)
@@ -279,6 +293,34 @@ def qualified_name(self) -> str:
     }
 
 
+@export
+class SecurityGroup(Entity):
+    """SecurityGroup Entity class."""
+
+    def __init__(self, src_entity=None, **kwargs):
+        """
+        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
+        """
+        super().__init__(src_entity=src_entity, **kwargs)
+
+    @property
+    def description_str(self):
+        """Return Entity Description."""
+        return self.DistinguishedName
+
+    _entity_schema = {
+        # DistinguishedName (type System.String)
+        'DistinguishedName': None,
+        # SID (type System.String)
+        'SID': None,
+        # ObjectGuid (type System.String)
+        'ObjectGuid': None,
+    }
+
+
 @export
 class HostLogonSession(Entity):
     """HostLogonSession Entity class."""
@@ -289,6 +331,7 @@ def __init__(self, src_entity=None, src_event=None, **kwargs):
 
             :param src_entity: instantiate entity using properties of src entity
             :param src_event: instantiate entity using properties of src event
+            :param kwargs: key-value pair representation of entity
         """
         super().__init__(src_entity=src_entity, **kwargs)
 
@@ -328,6 +371,7 @@ def __init__(self, src_entity=None, **kwargs):
         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
         """
         super().__init__(src_entity=src_entity, **kwargs)
 
@@ -382,6 +426,7 @@ def __init__(self, src_entity=None, src_event=None, role='new', **kwargs):
 
             :param src_entity: instantiate entity using properties of src entity
             :param src_event: instantiate entity using properties of src event
+            :param kwargs: key-value pair representation of entity
         """
         super().__init__(src_entity=src_entity, **kwargs)
 
@@ -426,7 +471,8 @@ def description_str(self) -> str:
         # Sha256 (type System.String)
         'Sha256': None,
         # Sha256Ac (type System.String)
-        'Sha256Ac': None
+        'Sha256Ac': None,
+        'FileHashes': (list, 'FileHash')
     }
 
     def _add_paths(self, full_path):
@@ -442,6 +488,42 @@ def _add_paths(self, full_path):
         self.Directory = full_path.split(self.PathSeparator)[:-1]
 
 
+@export
+class FileHash(Entity):
+    """File Hash class."""
+
+    def __init__(self, src_entity=None, **kwargs):
+        """
+        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
+        """
+        super().__init__(src_entity=src_entity, **kwargs)
+
+    @property
+    def description_str(self) -> str:
+        """Return Entity Description."""
+        return f'{self.Algorithm}: {self.Value}'
+
+    _entity_schema = {
+        # The hash algorithm (type System.String)
+        'Algorithm': 'Algorithm',
+        # Value (type System.String)
+        'Value': None,
+    }
+
+
+@export
+class Algorithm(Enum):
+    """FileHash Algorithm Enumeration."""
+    Unknown = 0
+    MD5 = 1
+    SHA1 = 2
+    SHA256 = 3
+    SHA256AC = 4
+
+
 @export
 class Host(Entity):
     """Host Entity class."""
@@ -514,6 +596,7 @@ def __init__(self, src_entity=None, src_event=None, **kwargs):
 
             :param src_entity: instantiate entity using properties of src entity
             :param src_event: instantiate entity using properties of src event
+            :param kwargs: key-value pair representation of entity
         """
         super().__init__(src_entity=src_entity, **kwargs)
 
@@ -555,6 +638,7 @@ def __init__(self, src_entity=None, **kwargs):
         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
         """
         super().__init__(src_entity=src_entity, **kwargs)
 
@@ -590,6 +674,7 @@ def __init__(self, src_entity=None, **kwargs):
         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
         """
         super().__init__(src_entity=src_entity, **kwargs)
 
@@ -604,7 +689,9 @@ def description_str(self) -> str:
         # Category (type System.String)
         'Category': None,
         # File (type Microsoft.Azure.Security.Detection.AlertContracts.V3.Entities.File)
-        'File': 'File'
+        'File': 'File',
+        'Files': (list, 'File'),
+        'Processes': (list, 'Process'),
     }
 
 
@@ -617,6 +704,7 @@ def __init__(self, src_entity=None, **kwargs):
         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
         """
         super().__init__(src_entity=src_entity, **kwargs)
 
@@ -654,6 +742,7 @@ def __init__(self, src_entity=None, src_event=None, role='new', **kwargs):
 
             :param src_entity: instantiate entity using properties of src entity
             :param src_event: instantiate entity using properties of src event
+            :param kwargs: key-value pair representation of entity
         """
         super().__init__(src_entity=src_entity, **kwargs)
 # pylint: disable=locally-disabled, C0301
@@ -720,7 +809,9 @@ def description_str(self) -> str:
         # .V3.Entities.Process)
         'ParentProcess': 'Process',
         # Host (type Microsoft.Azure.Security.Detection.AlertContracts.V3.Entities.Host)
-        'Host': 'Host'
+        'Host': 'Host',
+        # Host (type Microsoft.Azure.Security.Detection.AlertContracts.V3.Entities.HostLogonSession)
+        'LogonSession': 'HostLogonSession',
     }
 
 
@@ -759,6 +850,7 @@ def __init__(self, src_entity=None, **kwargs):
         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
         """
         super().__init__(src_entity=src_entity, **kwargs)
 
@@ -784,6 +876,7 @@ def __init__(self, src_entity=None, **kwargs):
         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
         """
         super().__init__(src_entity=src_entity, **kwargs)
 
@@ -830,6 +923,7 @@ def __init__(self, src_entity=None, **kwargs):
         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
         """
         super().__init__(src_entity=src_entity, **kwargs)
 
@@ -857,6 +951,7 @@ def __init__(self, src_entity=None, **kwargs):
         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
         """
         super().__init__(src_entity=src_entity, **kwargs)
 
@@ -888,6 +983,54 @@ def description_str(self) -> str:
         'ProviderName': None
     }
 
+
+@export
+class Threatintelligence(Entity):
+    """Threatintelligence Entity class."""
+
+    def __init__(self, src_entity=None, **kwargs):
+        """
+        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
+        """
+        super().__init__(src_entity=src_entity, **kwargs)
+
+    def description_str(self) -> str:
+        """Return Entity Description."""
+        return f'{self.DisplayName} ({self.StartTimeUtc}) {self.CompromisedEntity}'
+
+    _entity_schema = {
+        # String Name of the provider from whom this Threat Intelligence information was received
+        'ProviderName': None,
+
+        'ThreatType': None,
+        'ThreatName': None,
+        'Confidence': None,
+        'ReportLink': None,
+        'ThreatDescription': None,
+    }
+
+@export
+class UnknownEntity(Entity):
+    """Generic Entity class."""
+
+    def __init__(self, src_entity=None, **kwargs):
+        """
+        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
+        """
+        super().__init__(src_entity=src_entity, **kwargs)
+
+    def description_str(self) -> str:
+        """Return Entity Description."""
+        return 'OtherEntity'
+
+    _entity_schema = {}
+
 # # test code
 # if __name__ == '__main__':
 #     import json

msticpy/nbtools/security_alert.py

@@ -10,7 +10,7 @@
 import pandas as pd
 
 from .._version import VERSION
-from .entityschema import Entity
+from .entityschema import Entity, UnknownEntity
 from .security_base import SecurityBase
 from .utility import export
 
@@ -157,7 +157,7 @@ def _extract_entities(self, src_row):
             except TypeError:
                 # if we didn't instantiate a known entity
                 # just add it as it is
-                entity = ent
+                entity = UnknownEntity(**ent)
             if '$id' in ent:
                 self._src_entities[ent['$id']] = entity
 

msticpy/nbtools/security_alert_graph.py

@@ -49,7 +49,13 @@ def create_alert_graph(alert: SecurityAlert):
         # relationships between entities and child entities
         # So if this entity has a property that is an entity, we add an edge to it
         # and prune any edge that it might have to the alert
-        for prop, rel_entity in [(p, v) for (p, v) in entity.properties.items()
+        if isinstance(entity, Entity):
+            ent_props = entity.properties
+        elif isinstance(entity, dict):
+            ent_props = entity
+        else:
+            continue
+        for prop, rel_entity in [(p, v) for (p, v) in ent_props.items()
                                  if isinstance(v, Entity)]:
             if rel_entity['Type'] == 'host':
                 # don't add a new edge to the host
@@ -204,10 +210,17 @@ def _get_other_name_desc(entity):
     else:
         e_name = entity['Type']
 
+    if isinstance(entity, Entity):
+        ent_props = entity.properties
+    elif isinstance(entity, dict):
+        ent_props = entity
+    else:
+        ent_props = {'unknown': None}
+
     # Nasty dict comprehension to join all other items in the dictionary into a string
     e_properties = '\n'.join({'{}:{}'.format(k, v) for (k, v)
-                              in entity.properties.items() if (k not in ('Type', 'Name') and
-                                                               isinstance(v, str))})
+                              in ent_props.items() if (k not in ('Type', 'Name') and
+                                                       isinstance(v, str))})
     e_description = '{}\n{})'.format(e_name, e_properties)
     return e_name, e_description
 

msticpy/nbtools/security_base.py

@@ -266,7 +266,8 @@ def get_logon_id(self, account=None):
         if the account entity is not supplied, return the logon id
         of the first host-logon-session or account entity.
         """
-        for session in [e for e in self.entities if e['Type'] == 'host-logon-session']:
+        for session in [e for e in self.entities if
+                        e['Type'] == 'host-logon-session' or e['Type'] == 'hostlogonsession']:
             if account is None or session['Account'] == account:
                 return session['SessionId']
         if account is None:
@@ -342,7 +343,8 @@ def to_html(self, show_entities=False):
             html_doc = html_doc + entity_title + entity_html
         else:
             e_counts = Counter([ent['Type'] for ent in self.entities])
-            e_counts_str = ', '.join([f'{e}: {c}' for e, c in e_counts.items()])
+            e_counts_str = ', '.join(
+                [f'{e}: {c}' for e, c in e_counts.items()])
             html_doc = html_doc + f'<h3>Entity counts: </h3>{e_counts_str}'
         return html_doc
 

msticpy/nbtools/wsconfig.py

@@ -11,11 +11,17 @@
 __version__ = '0.1'
 __author__ = 'Ian Hellen'
 
-
 @export
 class WorkspaceConfig(object):
     """Workspace configuration class."""
 
+    # Constants
+    TENANT_ID = "{{cookiecutter.tenant_id}}"
+    SUBSCRIPTION_ID = "{{cookiecutter.subscription_id}}"
+    RESOURCE_GROUP = "{{cookiecutter.resource_group}}"
+    WORKSPACE_ID = "{{cookiecutter.workspace_id}}"
+    WORKSPACE_NAME = "{{cookiecutter.workspace_name}}"
+
     def __init__(self, config_file: str):
         """
         Load current Azure Notebooks configuration for Log Analytics.