Added session exporting.

Author: casework

case.py

@@ -1,5 +1,6 @@
 """An API to the CASE ontology."""
 
+import datetime
 import rdflib
 from rdflib import RDF, XSD
 import rdflib.term
@@ -29,25 +30,31 @@ def _json_ld_context(self):
         context['@vocab'] = str(CASE)
         return context
 
+    def create_uco_object(self, type=None, **properties):
+        """Creates and returns a UcoObject."""
+        return UcoObject(self.graph, rdf_type=type, **properties)
+
+    # Make separate function for creating Trace because it's very common.
     def create_trace(self, **properties):
         """Creates and returns a Trace object."""
         return Trace(self.graph, **properties)
 
-    def create_relationship(self, **properties):
-        """Creates and returns a Relationship object."""
-        return Relationship(self.graph, **properties)
-
     # Manually specify properties to help inforce both properties are supplied.
     def create_hash(self, hashMethod, hashValue):
-        return Node(
-            self.graph, rdf_type=CASE.Hash, hashMethod=hashMethod, hashValue=hashValue)
+        return self.create_node(CASE.Hash, hashMethod=hashMethod, hashValue=hashValue)
+
+    def create_node(self, type=None, **properties):
+        return Node(self.graph, rdf_type=type, **properties)
 
     # We are going to default to json-ld instead of rdflib's default of xml.
     def serialize(self, format='json-ld', **kwargs):
         """Serializes the document's graph to a destination.
         (Follows same arguments as rdflib.Graph().serialize())"""
-        if format == 'json-ld' and 'context' not in kwargs:
-            kwargs['context'] = self._json_ld_context()
+        if format == 'json-ld':
+            if 'context' not in kwargs:
+                kwargs['context'] = self._json_ld_context()
+            if 'auto_compact' not in kwargs:
+                kwargs['auto_compact'] = True
         return self.graph.serialize(format=format, **kwargs)
 
     def validate(self):
@@ -78,10 +85,12 @@ def __init__(self, graph, rdf_type=None, **properties):
         super(Node, self).__init__()
         self._node = rdflib.BNode()
         self._graph = graph
-        if rdf_type:
-            self.add(RDF.type, rdf_type)
-        elif self.RDF_TYPE:
-            self.add(RDF.type, self.RDF_TYPE)
+        if not rdf_type:
+            rdf_type = self.RDF_TYPE
+        # Add namespace prefix to non URIRef to allow abstraction from rdflib.
+        if not isinstance(rdf_type, rdflib.term.Node):
+            rdf_type = self.NAMESPACE[rdf_type]
+        self.add(RDF.type, rdf_type)
         for key, value in iter(properties.items()):
             self.add(key, value)
 
@@ -119,6 +128,21 @@ def add(self, property, value):
 class UcoObject(Node):
     RDF_TYPE = CASE.UcoObject
 
+    def __init__(self, graph, rdf_type=None, **properties):
+        """Initializes and adds a node to the graph.
+        NOTE: At least the type or a property must be supplied for the Node
+        to exist in the graph.
+
+        Args:
+            graph: The graph to add this node to. (instance of rdflib.Graph)
+            rdf_type: The RDF type to set this node to.
+            properties: Extra properties to add to this node.
+            (More properties can be set after initialization by using the add() function.)
+        """
+        super(UcoObject, self).__init__(graph, rdf_type=rdf_type, **properties)
+        self.add('createdTime', datetime.datetime.now())
+        # TODO: Add "createdBy" property.
+
     def create_property_bundle(self, type=None, **properties):
         """Convenience function for adding property bundles to this Trace.
 
@@ -129,21 +153,15 @@ def create_property_bundle(self, type=None, **properties):
         Returns:
             The property bundle created (instance of PropertyBundle).
         """
-        # Add case prefix to non URIRef to allow abstraction from rdflib.
-        if not isinstance(type, rdflib.term.Node):
-            type = CASE[type]
         pb = PropertyBundle(self._graph, rdf_type=type, **properties)
         self.add(CASE.propertyBundle, pb)
         return pb
 
 
+# TODO: Do we need these extra classes?
 class Trace(UcoObject):
     RDF_TYPE = CASE.Trace
 
 
-class Relationship(UcoObject):
-    RDF_TYPE = CASE.Relationship
-
-
 class PropertyBundle(Node):
     RDF_TYPE = CASE.PropertyBundle

case_plaso/event_exporters/filestat.py

@@ -52,7 +52,8 @@ def export_path_spec(self, path_spec):
         # object pointing to its parent.
         if path_spec.HasParent():
             parent_trace, _ = self.export_path_spec(path_spec.parent)
-            relationship = self.document.create_relationship(
+            relationship = self.document.create_uco_object(
+                'Relationship',
                 source=trace,
                 target=parent_trace,
                 kindOfRelationship=mappings.kindOfRelationship.get(
@@ -99,7 +100,7 @@ def export_event(self, event):
         content_data = self._content_data_pbs[event.pathspec]
         for name, value in event.GetAttributes():
             if name in mappings.HashMethod and (content_data, name, value) not in self._processed_hashes:
-                # Keep trace of processed hashes, so we don't add the same hash twice.
+                # Keep track of processed hashes, so we don't add the same hash twice.
                 # TODO: Refactor this out when github.com/log2timeline/plaso/issues/910 is solved.
                 self._processed_hashes.add((content_data, name, value))
                 hash = self.document.create_hash(

case_plaso/plaso_exporter.py

@@ -1,8 +1,9 @@
 
 from dfvfs.lib import definitions as dfvfs_definitions
+from plaso.engine.knowledge_base import KnowledgeBase
 from plaso.storage import zip_file
 
-from case_plaso import PLASO
+from case_plaso import PLASO, lib
 from case_plaso.event_exporter import EventExporter
 
 # Import event exporters to get them registered.
@@ -12,6 +13,18 @@
 class PlasoExporter(object):
     """Exports plaso data into a RDF graph using the CASE ontology."""
 
+    # Configuration attributes stored in a plaso Session object.
+    _CONFIGURATION_ATTRIBUTES = [
+        'identifier',
+        'command_line_arguments',
+        'debug_mode',
+        'enabled_parser_names',
+        'filter_expression',
+        'filter_file',
+        'parser_filter_expression',
+        'preferred_encoding',
+        'preferred_year']
+
     def __init__(self, document):
         """Initializes PlasoExporter.
 
@@ -59,12 +72,55 @@ def export_event(self, event):
         event_exporter = self.get_event_exporter(event.data_type)
         event_exporter.export_event(event)
 
+    def export_session(self, session):
+        """Exports the given plaso storage Session into the graph."""
+        instrument = self.document.create_uco_object(
+            'Tool',
+            name=session.product_name,
+            version=session.product_version,
+            toolType='parser?',
+            creator='Joachim Metz')
+        config = instrument.create_property_bundle('ToolConfiguration')
+        for attribute in self._CONFIGURATION_ATTRIBUTES:
+            if hasattr(session, attribute):
+                value = getattr(session, attribute)
+                if value is None:
+                    # None is technically a configuration, but we don't want to print "None".
+                    value = ''
+                value = str(value)
+                setting = self.document.create_node(
+                    'ConfigurationSetting', itemName=attribute, itemValue=value)
+                config.add('configurationSetting', setting)
+
+        # TODO: How do we know who performed the Plaso action? That information
+        # is not in the plaso storage file...
+        performer = self.document.create_uco_object('Identity')
+        performer.create_property_bundle(
+            'SimpleName',
+            givenName='John',
+            familyName='Doe')
+
+        action = self.document.create_uco_object(
+            'ForensicAction',
+            startTime=lib.convert_timestamp(session.start_time),
+            endTime=lib.convert_timestamp(session.completion_time))
+        action.create_property_bundle(
+            'ActionReferences',
+            performer=performer,
+            instrument=instrument,
+            result=None,   # TODO: We can't fill this in because we don't know what session created what event objects...
+            location=None)  # TODO: How am I supposed to be able to get this information?
+
     def export_storage_file(self, storage_file):
         """Extracts and exports plaso event data and sources into the graph."""
         with zip_file.ZIPStorageFileReader(storage_file) as storage_reader:
-            # TODO: Do stuff with metadata
+            knowledge_base = KnowledgeBase()
+            storage_reader.ReadPreprocessingInformation(knowledge_base)
+            # TODO: Export knowledge base.
+
+            for session in storage_reader._storage_file.GetSessions():
+                self.export_session(session)
 
-            # Convert path specs into CASE Traces containgin file-type property bundles.
             for source in storage_reader.GetEventSources():
                 self.export_event_source(source)
 

notes.md

@@ -2,6 +2,10 @@
 
 - Why is `fileSystemType` in both `File` and `FileSystem` property bundles?
 - Clarifications on when to use "PhoneAccount" or "EmailAccount" vs "Contact" is needed.
-- Why is there a separate `isRead` for `SMSMessage`? A regular message like "WhatsApp" could
-also have this field.
-- Why is there only a `sentTime` timestamp in `Message`? I have other potential timestamps such as "created", "received", "uploaded", "downloaded", "deleted", etc. Having specific hardcoded timestamps in property bundles makes this very limiting. And having some hardcoded timestamps and some not (using Action traces?) is very discombobulated for timelined data. I suggest rethinking this approach to separating timestamp information from data.
+- Why is there a separate `isRead` for `SMSMessage`? A regular message like "WhatsApp" could also have this field.
+- Why is there only a `sentTime` timestamp in `Message`? I have other potential timestamps such as "created", "received", "uploaded", "downloaded", "deleted", etc. Having specific hardcoded timestamps in property bundles makes this very limiting. And having some hardcoded timestamps and some not (using Action traces?) is very discombobulated for timelined data. I suggest rethinking this approach to separating timestamp information from data.
+- What do some of the UcoObject properties mean? eg. `granularMarking` and `objectMarking`
+- Why is there an `id` and `type` property in `UcoObject`? Those properties already exists. `id` is the URI of the node itself, `type` is the "rdf:type" property.
+- I still can't remember the difference between `result` and `object` properties...
+- Why do all UcoObjects have a `name` property? That property only makes sense for things like `Tool`. It doesn't make sense for things like `Trace` and `Action`.
+- Why does the `description` property exist? It already exists with "rdfs:comment".