Add Rapid7 Velociraptor artifacts plugin

dissect/target/loaders/velociraptor.py

@@ -7,6 +7,7 @@
 
 from dissect.target.loaders.dir import DirLoader, find_dirs, map_dirs
 from dissect.target.plugin import OperatingSystem
+from dissect.target.plugins.apps.edr.velociraptor import VELOCIRAPTOR_RESULTS
 
 if TYPE_CHECKING:
     from dissect.target import Target
@@ -85,7 +86,6 @@ class VelociraptorLoader(DirLoader):
 
     def __init__(self, path: Path, **kwargs):
         super().__init__(path)
-
         if path.suffix == ".zip":
             log.warning(
                 f"Velociraptor target {path!r} is compressed, which will slightly affect performance. "
@@ -127,3 +127,16 @@ def map(self, target: Target) -> None:
             )
         else:
             map_dirs(target, dirs, os_type)
+
+        # Map artifact results collected by Velociraptor
+        target.fs.makedirs(VELOCIRAPTOR_RESULTS)
+
+        results = self.root.joinpath("results")
+        if results.exists() and results.is_dir():
+            # FIXME: The files do exists but can't be found: dissect.target.exceptions.FileNotFoundError
+            for artifact in results.glob("*.json"):
+                target.fs.map_file(str(target.fs.path(VELOCIRAPTOR_RESULTS).joinpath(artifact.name)), str(artifact))
+
+        uploads = self.root.joinpath("uploads.json")
+        if uploads.exists() and uploads.is_file():
+            target.fs.map_file(str(target.fs.path(VELOCIRAPTOR_RESULTS).joinpath(uploads.name)), str(uploads))

dissect/target/plugins/apps/edr/velociraptor.py

@@ -0,0 +1,98 @@
+import json
+import re
+import urllib
+from functools import lru_cache
+from typing import Iterator
+
+from flow.record import RecordDescriptor
+
+from dissect.target.exceptions import UnsupportedPluginError
+from dissect.target.helpers.record import DynamicDescriptor, TargetRecordDescriptor
+from dissect.target.plugin import Plugin, export
+from dissect.target.target import Target
+
+VELOCIRAPTOR_RESULTS = "/$velociraptor_results$"
+ISO_8601_PATTERN = r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?"
+
+
+class VelociraptorRecordBuilder:
+    def __init__(self, os_type: str, artifact_name: str):
+        self._create_event_descriptor = lru_cache(4096)(self._create_event_descriptor)
+        self.RECORD_NAME = f"velociraptor/{os_type}/{artifact_name}"
+
+    def read_record(self, object: dict, target: Target):
+        """Builds a Velociraptor record"""
+        record_values = {}
+        record_fields = []
+
+        record_values["_target"] = target
+
+        for key, value in object.items():
+            # Reserved by flow.record
+            if key.startswith("_"):
+                continue
+
+            key = key.lower()
+
+            if re.match(ISO_8601_PATTERN, str(value)):
+                record_type = "datetime"
+            elif isinstance(value, list):
+                record_type = "string[]"
+            elif isinstance(value, int):
+                record_type = "varint"
+            elif key == "hash":
+                record_type = "digest"
+                value = (value["md5"] or None, value["sha1"] or None, value["sha256"] or None)
+            elif isinstance(value, str):
+                record_type = "string"
+            # FIXME: Why is there no record type dict?
+            elif isinstance(value, dict):
+                record_type = "string"
+            else:
+                record_type = "dynamic"
+
+            record_fields.append((record_type, key))
+            record_values[key] = value
+
+        # tuple conversion here is needed for lru_cache
+        desc = self._create_event_descriptor(tuple(record_fields))
+        return desc(**record_values)
+
+    def _create_event_descriptor(self, record_fields: tuple) -> TargetRecordDescriptor:
+        return TargetRecordDescriptor(self.RECORD_NAME, record_fields)
+
+
+class VelociraptorPlugin(Plugin):
+    def __init__(self, target: Target):
+        super().__init__(target)
+        self.results = target.fs.path(VELOCIRAPTOR_RESULTS)
+
+    def check_compatible(self) -> None:
+        if not self.results.exists():
+            raise UnsupportedPluginError("No Velociraptor artifacts found")
+
+    @export(record=DynamicDescriptor(["datetime"]))
+    def velociraptor(self) -> Iterator[RecordDescriptor]:
+        """Return Rapid7 Velociraptor artifacts.
+
+        References:
+            - https://docs.velociraptor.app/docs/vql/artifacts/
+        """
+        for artifact in self.results.glob("*.json"):
+            fh = self.target.fs.path(artifact).open("rt")
+
+            # "Windows.KapeFiles.Targets%2FAll\ File\ Metadata.json" becomes "windows_kapefiles_targets"
+            artifact_name = urllib.parse.unquote(artifact.name.rstrip(".json")).split("/")[0].lower().replace(".", "_")
+            velociraptor_record_builder = VelociraptorRecordBuilder(self.target.os, artifact_name)
+
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+
+                try:
+                    object = json.loads(line)
+                    yield velociraptor_record_builder.read_record(object, self.target)
+                except json.decoder.JSONDecodeError:
+                    self.target.log.warning("Could not decode Velociraptor JSON log line: %s (%s)", line, artifact)
+                    continue

tests/loaders/test_velociraptor.py

@@ -17,6 +17,7 @@ def create_root(sub_dir: str, tmp_path: Path) -> Path:
         f"uploads/{sub_dir}/%5C%5C%3F%5CGLOBALROOT%5CDevice%5CHarddiskVolumeShadowCopy1/",
         f"uploads/{sub_dir}/%5C%5C%3F%5CGLOBALROOT%5CDevice%5CHarddiskVolumeShadowCopy1/$Extend",
         f"uploads/{sub_dir}/%5C%5C%3F%5CGLOBALROOT%5CDevice%5CHarddiskVolumeShadowCopy1/windows/system32",
+        f"results",
     ]
     root = tmp_path
     mkdirs(root, paths)

tests/plugins/apps/edr/test_velociraptor.py

@@ -0,0 +1,31 @@
+from pathlib import Path
+
+from dissect.target import Target
+from dissect.target.loaders.velociraptor import VelociraptorLoader
+from dissect.target.plugins.apps.edr.velociraptor import VelociraptorPlugin
+from tests._utils import absolute_path
+from tests.loaders.test_velociraptor import create_root
+
+
+def test_windows_velociraptor(target_bare: Target, tmp_path: Path) -> None:
+    root = create_root("ntfs", tmp_path)
+
+    with open(absolute_path("_data/plugins/apps/edr/velociraptor/windows-uploads.json"), "rb") as fh:
+        root.joinpath("uploads.json").write_bytes(fh.read())
+
+    with open(absolute_path("_data/plugins/apps/edr/velociraptor/Windows.Memory.ProcessInfo.json"), "rb") as fh:
+        root.joinpath("results/Windows.Memory.ProcessInfo.json").write_bytes(fh.read())
+
+    assert VelociraptorLoader.detect(root) is True
+
+    loader = VelociraptorLoader(root)
+    loader.map(target_bare)
+    target_bare.apply()
+
+    target_bare.add_plugin(VelociraptorPlugin)
+
+    results = list(target_bare.velociraptor())
+
+    record = results[0]
+
+    # FIXME: assert