Code review: 259660043: Added LNK distributed link tracking support l…

…og2timeline#316

config/dpkg/changelog

@@ -2,4 +2,4 @@ python-plaso (1.3.1-1) unstable; urgency=low
 
   * Auto-generated
 
- -- Log2Timeline <[email protected]>  Tue, 01 Sep 2015 23:10:22 +0200
+ -- Log2Timeline <[email protected]>  Thu, 03 Sep 2015 08:27:39 +0200

plaso/__init__.py

@@ -3,7 +3,7 @@
 __version__ = '1.3.1'
 
 VERSION_DEV = True
-VERSION_DATE = '20150901'
+VERSION_DATE = '20150903'
 
 
 def GetVersion():

plaso/dependencies.py

@@ -17,7 +17,7 @@
     u'pyevtx': 20141112,
     u'pyewf': 20131210,
     u'pyfwsi': 20150606,
-    u'pylnk': 20141026,
+    u'pylnk': 20150830,
     u'pymsiecf': 20150314,
     u'pyolecf': 20150413,
     u'pyqcow': 20131204,

plaso/events/time_events.py

@@ -6,14 +6,21 @@
 
 
 class TimestampEvent(event.EventObject):
-  """Convenience class for a timestamp-based event."""
+  """Convenience class for a timestamp-based event.
+
+  Attributes:
+    data_type: the event data type.
+    timestamp: the timestamp, contains the number of microseconds from
+               January 1, 1970 00:00:00 UTC.
+    timestamp_desc: the description of the usage of the timestamp.
+  """
 
   def __init__(self, timestamp, usage, data_type=None):
     """Initializes an event object.
 
     Args:
-      timestamp: The timestamp value.
-      usage: The description of the usage of the time value.
+      timestamp: the timestamp value.
+      usage: the description of the usage of the time value.
       data_type: Optional event data type. If not set data_type is
                  derived from the DATA_TYPE attribute.
     """
@@ -32,9 +39,9 @@ def __init__(self, cocoa_time, usage, data_type=None):
     """Initializes an event object.
 
     Args:
-      cocoa_time: The Cocoa time value.
-      usage: The description of the usage of the time value.
-      data_type: Optional event data type. If not set data_type is
+      cocoa_time: the Cocoa time value.
+      usage: the description of the usage of the time value.
+      data_type: optional event data type. If not set data_type is
                  derived from the DATA_TYPE attribute.
     """
     super(CocoaTimeEvent, self).__init__(
@@ -49,9 +56,9 @@ def __init__(self, fat_date_time, usage, data_type=None):
     """Initializes an event object.
 
     Args:
-      fat_date_time: The FAT date time value.
-      usage: The description of the usage of the time value.
-      data_type: Optional event data type. If not set data_type is
+      fat_date_time: the FAT date time value.
+      usage: the description of the usage of the time value.
+      data_type: optional event data type. If not set data_type is
                  derived from the DATA_TYPE attribute.
     """
     super(FatDateTimeEvent, self).__init__(
@@ -66,9 +73,9 @@ def __init__(self, filetime, usage, data_type=None):
     """Initializes an event object.
 
     Args:
-      filetime: The FILETIME timestamp value.
-      usage: The description of the usage of the time value.
-      data_type: Optional event data type. If not set data_type is
+      filetime: the FILETIME timestamp value.
+      usage: the description of the usage of the time value.
+      data_type: optional event data type. If not set data_type is
                  derived from the DATA_TYPE attribute.
     """
     super(FiletimeEvent, self).__init__(
@@ -82,9 +89,9 @@ def __init__(self, java_time, usage, data_type=None):
     """Initializes an event object.
 
     Args:
-      java_time: The Java time value.
-      usage: The description of the usage of the time value.
-      data_type: Optional event data type. If not set data_type is
+      java_time: the Java time value.
+      usage: the description of the usage of the time value.
+      data_type: optional event data type. If not set data_type is
                  derived from the DATA_TYPE attribute.
     """
     super(JavaTimeEvent, self).__init__(
@@ -98,9 +105,9 @@ def __init__(self, posix_time, usage, data_type=None):
     """Initializes an event object.
 
     Args:
-      posix_time: The POSIX time value.
-      usage: The description of the usage of the time value.
-      data_type: Optional event data type. If not set data_type is
+      posix_time: the POSIX time value.
+      usage: the description of the usage of the time value.
+      data_type: optional event data type. If not set data_type is
                  derived from the DATA_TYPE attribute.
     """
     super(PosixTimeEvent, self).__init__(
@@ -114,26 +121,56 @@ def __init__(self, datetime_time, usage, data_type=None):
     """Initializes an event object.
 
     Args:
-      datetime_time: The datetime object (instance of datetime.datetime).
-      usage: The description of the usage of the time value.
-      data_type: Optional event data type. If not set data_type is
+      datetime_time: the datetime object (instance of datetime.datetime).
+      usage: the description of the usage of the time value.
+      data_type: optional event data type. If not set data_type is
                  derived from the DATA_TYPE attribute.
     """
     super(PythonDatetimeEvent, self).__init__(
         timelib.Timestamp.FromPythonDatetime(datetime_time), usage,
         data_type=data_type)
 
 
+class UUIDTimeEvent(TimestampEvent):
+  """Convenience class for an UUID version time-based event.
+
+  Attributes:
+    mac_address: the MAC address stored in the UUID.
+  """
+
+  def __init__(self, uuid, usage):
+    """Initializes an event object.
+
+    Args:
+      uuid: a uuid object (instance of uuid.UUID).
+      usage: the description of the usage of the time value.
+
+    Raises:
+      ValueError: if the UUID version is not supported.
+    """
+    if not uuid.version == 1:
+      raise ValueError(u'Unsupported UUID version.')
+
+    timestamp = timelib.Timestamp.FromUUIDTime(uuid.time)
+    mac_address = u'{0:s}:{1:s}:{2:s}:{3:s}:{4:s}:{5:s}'.format(
+        uuid.hex[20:22], uuid.hex[22:24], uuid.hex[24:26], uuid.hex[26:28],
+        uuid.hex[28:30], uuid.hex[30:32])
+    super(UUIDTimeEvent, self).__init__(timestamp, usage)
+
+    self.mac_address = mac_address
+    self.uuid = u'{0!s}'.format(uuid)
+
+
 class WebKitTimeEvent(TimestampEvent):
   """Convenience class for a WebKit time-based event."""
 
   def __init__(self, webkit_time, usage, data_type=None):
     """Initializes an event object.
 
     Args:
-      webkit_time: The WebKit time value.
-      usage: The description of the usage of the time value.
-      data_type: Optional event data type. If not set data_type is
+      webkit_time: the WebKit time value.
+      usage: the description of the usage of the time value.
+      data_type: optional event data type. If not set data_type is
                  derived from the DATA_TYPE attribute.
     """
     super(WebKitTimeEvent, self).__init__(

plaso/events/windows_events.py

@@ -5,25 +5,21 @@
 from plaso.lib import eventdata
 
 
-class WindowsVolumeCreationEvent(time_events.FiletimeEvent):
-  """Convenience class for a Windows volume creation event."""
+class WindowsDistributedLinkTrackingCreationEvent(time_events.UUIDTimeEvent):
+  """Convenience class for a Windows distributed link creation event."""
 
-  DATA_TYPE = 'windows:volume:creation'
+  DATA_TYPE = 'windows:distributed_link_tracking:creation'
 
-  def __init__(self, filetime, device_path, serial_number, origin):
+  def __init__(self, uuid, origin):
     """Initializes an event object.
 
     Args:
-      filetime: The FILETIME timestamp value.
-      device_path: A string containing the volume device path.
-      serial_number: A string containing the volume serial number.
+      uuid: A uuid object (instance of uuid.UUID).
       origin: A string containing the origin of the event (event source).
     """
-    super(WindowsVolumeCreationEvent, self).__init__(
-        filetime, eventdata.EventTimestamp.CREATION_TIME)
+    super(WindowsDistributedLinkTrackingCreationEvent, self).__init__(
+        uuid, eventdata.EventTimestamp.CREATION_TIME)
 
-    self.device_path = device_path
-    self.serial_number = serial_number
     self.origin = origin
 
 
@@ -78,3 +74,25 @@ def __init__(
 class WindowsRegistryServiceEvent(WindowsRegistryEvent):
   """Convenience class for service entries retrieved from the registry."""
   DATA_TYPE = 'windows:registry:service'
+
+
+class WindowsVolumeCreationEvent(time_events.FiletimeEvent):
+  """Convenience class for a Windows volume creation event."""
+
+  DATA_TYPE = 'windows:volume:creation'
+
+  def __init__(self, filetime, device_path, serial_number, origin):
+    """Initializes an event object.
+
+    Args:
+      filetime: The FILETIME timestamp value.
+      device_path: A string containing the volume device path.
+      serial_number: A string containing the volume serial number.
+      origin: A string containing the origin of the event (event source).
+    """
+    super(WindowsVolumeCreationEvent, self).__init__(
+        filetime, eventdata.EventTimestamp.CREATION_TIME)
+
+    self.device_path = device_path
+    self.serial_number = serial_number
+    self.origin = origin

plaso/formatters/windows.py

@@ -5,6 +5,25 @@
 from plaso.formatters import manager
 
 
+class WindowsDistributedLinkTrackingCreationEventFormatter(
+    interface.ConditionalEventFormatter):
+  """Formatter for a Windows distributed link creation event."""
+
+  DATA_TYPE = u'windows:distributed_link_tracking:creation'
+
+  FORMAT_STRING_PIECES = [
+      u'{uuid}',
+      u'MAC address: {mac_address}',
+      u'Origin: {origin}']
+
+  FORMAT_STRING_SHORT_PIECES = [
+      u'{uuid}',
+      u'Origin: {origin}']
+
+  SOURCE_LONG = u'System'
+  SOURCE_SHORT = u'LOG'
+
+
 class WindowsVolumeCreationEventFormatter(interface.ConditionalEventFormatter):
   """Formatter for a Windows volume creation event."""
 
@@ -23,4 +42,6 @@ class WindowsVolumeCreationEventFormatter(interface.ConditionalEventFormatter):
   SOURCE_SHORT = u'LOG'
 
 
-manager.FormattersManager.RegisterFormatter(WindowsVolumeCreationEventFormatter)
+manager.FormattersManager.RegisterFormatters([
+    WindowsDistributedLinkTrackingCreationEventFormatter,
+    WindowsVolumeCreationEventFormatter])

plaso/lib/timelib.py

@@ -77,9 +77,12 @@ class Timestamp(object):
   # The difference between Jan 1, 1601 and Jan 1, 1970 in micro seconds
   WEBKIT_TIME_TO_POSIX_BASE = 11644473600L * 1000000
 
-  # The difference between Jan 1, 1601 and Jan 1, 1970 in 100s of nanoseconds.
+  # The difference between Jan 1, 1601 and Jan 1, 1970 in 100 nanoseconds.
   FILETIME_TO_POSIX_BASE = 11644473600L * 10000000
 
+  # The difference between Nov 10, 1582 and Jan 1, 1970 in 100 nanoseconds.
+  UUID_TIME_TO_POSIX_BASE = 12219292800L * 10000000
+
   # The number of seconds between January 1, 1904 and Jan 1, 1970.
   # Value confirmed with sleuthkit:
   #  http://svn.sleuthkit.org/repos/sleuthkit/trunk/tsk3/fs/tsk_hfs.h
@@ -669,6 +672,28 @@ def FromTimeString(
 
     return cls.FromPythonDatetime(datetime_object)
 
+  @classmethod
+  def FromUUIDTime(cls, uuid_time):
+    """Converts a UUID verion 1 time into a timestamp.
+
+    The UUID version 1 time is a 60-bit value containing:
+      100th nano seconds since 1582-10-15 00:00:00
+
+    Args:
+      uuid_time: The 60-bit UUID version 1 timestamp.
+
+    Returns:
+      An integer containing the timestamp or 0 on error.
+    """
+    # TODO: Add a handling for if the timestamp equals to zero.
+    if uuid_time < 0:
+      return 0
+    timestamp = (uuid_time - cls.UUID_TIME_TO_POSIX_BASE) / 10
+
+    if timestamp > cls.TIMESTAMP_MAX_MICRO_SECONDS:
+      return 0
+    return timestamp
+
   @classmethod
   def FromWebKitTime(cls, webkit_time):
     """Converts a WebKit time into a timestamp.