rdump ===== With ``rdump`` you can read, write, interact, and manipulate records from ``stdin`` or from record files saved on disk. .. hint:: Don't know yet what a record is? Read more :ref:`here ` for a detailed explanation. Records are the primary output type when using the various functions of :doc:`/tools/target-query`. Keep in mind that not all functions in ``target-query`` output records. You can check the output type of a function by using ``target-query -l`` and searching for your function. The output type is specified on the end, and looks something like this: .. code-block:: :class: no-copybutton runkeys - Iterate various run key locations. See source for all locations. (output: records) ^^^^^^^^^^^^^^^^^ If the output type is ``records`` you can use ``rdump``! Basic usage ----------- Since ``target-query`` primarily outputs records it is often used in conjunction with ``rdump``. Common usage is to pipe the record output from ``target-query`` into ``rdump``: .. code-block:: console $ target-query -f runkeys targets/EXAMPLE.vmx | rdump <...> By default, records will be serialized into a binary format when piped to a different command or file so that they can be deserialized and consumed by another command. This is how ``rdump`` interacts with the records from ``target-query``. Without specifying any arguments to ``rdump`` the resulting output will be grep-able text. **NOTE:** The same can be achieved by passing ``target-query`` the ``-s`` flag, so it's recommended you use that if that is all you want. You can use ``rdump`` on (multiple) files as well. Just point ``rdump`` to the record file(s) in question: .. code-block:: console $ target-query -f runkeys targets/EXAMPLE.vmx > runkeys.rec $ target-query -f services targets/EXAMPLE.vmx > services.rec $ rdump runkeys.rec [...] $ rdump *.rec [...] The file extension of the record file can be anything you want. Timeline & datetime fields -------------------------- ``target-query`` functions that have a ``record`` with the fieldtype ``datetime`` are outputed in a single record. As shown below with the function ``mft``: .. code-block:: console $ target-query -f mft -t targets/EXAMPLE.tar --limit 1 | rdump The single record contains four different events that occured on the filesystem: * ``creation_time`` * ``last_modification_time`` * ``last_change_time`` * ``last_access_time`` To analyze a timeline of events that occured every record needs a single ``datetime`` field on which can be filtered to view records in chronological order. For this purpose the argument ``--multi-timestamp`` can be used to output multiple ``ts`` enriched records based on the ``datetime`` fields of the original record. .. code-block:: console $ target-query -f mft -t targets/EXAMPLE.tar --limit 1 | rdump --multi-timestamp [reading from stdin] Filtering & manipulating records -------------------------------- One of the things you can do with ``rdump`` is filtering records. This can be done with the ``-s`` or ``--selector`` argument. This argument takes a Python statement which must evaluate to ``True`` or ``False``. This statement is used to filter records. You can interact with the fields of a record using the magic ``r`` variable. .. code-block:: console $ rdump services.rec -s '"%systemroot%" not in r.imagepath.lower()' [...] To manipulate the output generated by ``rdump`` the ``-f (--format)`` and ``-F (--fields)`` arguments can be used. The ``-f`` behaves as a Python format-string, record fields can be referred to by their field name in braces (e.g. ``{path}``). For example, we can output just the hostname, name and image path of a Windows service: .. code-block:: console $ rdump services.rec -f '{hostname} - {name}:{imagepath}' EXAMPLE - 1394ohci:/SystemRoot/System32/drivers/1394ohci.sys EXAMPLE - 3ware:System32/drivers/3ware.sys EXAMPLE - ACPI:System32/drivers/ACPI.sys EXAMPLE - AcpiDev:/SystemRoot/System32/drivers/AcpiDev.sys [...] .. seealso:: Please refer to :doc:`/usage/use-cases` for more examples of how to use ``rdump``. Writing records --------------- ``rdump`` can write records to a file, which can be used as input for ``rdump`` at a later stage. To write records to a file, the ``-w`` or ``--writer`` argument can be used. The output format and compression type are automatically detected based on the filename extension. For example, to write to a gzip compressed file, simply use the ``.gz`` extension in your output file. .. code-block:: console $ rdump services.rec -w services.rec.gz This will read the records from ``services.rec`` and write them to a new gzip compressed file named ``services.rec.gz``. Other supported compression formats are ``.bz2``, ``.zst`` (zstandard), and ``.lz4``. If you want to write the records to a file without any compression, just use a filename without a compression extension. .. code-block:: console $ rdump services.rec -w services.rec.out When the ``-w`` argument is omitted, ``rdump`` prints the string representation of the records to standard output, which is useful for piping to tools like ``grep`` or ``less``. If you want to output the record output to another ``rdump`` process you need to use ``-w -``, which will write the records in binary stream format to standard output. For example, you can chain ``rdump`` with common Linux command-line tools to analyze records. In this example, we extract image paths from a record source, sort them, count occurrences, and display the top 5 most common paths: .. code-block:: console $ rdump services.rec -w - | rdump -f "{imagepath}" | sort | uniq -c | sort -rn | head -n 5 [reading from stdin] 104 %SystemRoot%\system32\svchost.exe 71 %SystemRoot%\System32\svchost.exe 28 %systemroot%\system32\svchost.exe 12 None 3 %SystemRoot%\system32\lsass.exe Usage ----- .. sphinx_argparse_cli:: :module: flow.record.tools.rdump :func: main :prog: rdump :hook: