Merge branch 'develop' into linux_proc_dump

Author: eve-mem

.github/workflows/black.yml

@@ -6,7 +6,7 @@ jobs:
   lint:
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: psf/black@stable
         with:
           options: "--check --diff --verbose"

.github/workflows/codeql.yml

@@ -17,8 +17,8 @@ on:
   pull_request:
     # The branches below must be a subset of the branches above
     branches: [ "develop" ]
-  schedule:
-    - cron: '16 8 * * 0'
+#   schedule:
+#     - cron: '16 8 * * 0'
 
 jobs:
   analyze:

.readthedocs.yml

@@ -12,8 +12,12 @@ sphinx:
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: all
 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
 # Optionally set the version of Python and requirements required to build your docs
 python:
-  version: 3.7
   install:
     - requirements: doc/requirements.txt

README.md

@@ -107,7 +107,7 @@ The latest generated copy of the documentation can be found at: <https://volatil
 
 ## Licensing and Copyright
 
-Copyright (C) 2007-2022 Volatility Foundation
+Copyright (C) 2007-2023 Volatility Foundation
 
 All Rights Reserved
 

doc/requirements.txt

@@ -1,4 +1,8 @@
 # These packages are required for building the documentation.
-sphinx>=4.0.0
+sphinx>=4.0.0,<7
 sphinx_autodoc_typehints>=1.4.0
 sphinx-rtd-theme>=0.4.3
+
+yara-python
+pycryptodome
+pefile

doc/source/getting-started-mac-tutorial.rst

@@ -0,0 +1,153 @@
+macOS Tutorial
+==============
+
+This guide will give you a brief overview of how volatility3 works as well as a demonstration of several of the plugins available in the suite.
+
+Acquiring memory
+----------------
+
+Volatility3 does not provide the ability to acquire memory. The example below is an open source tool. Other commercial tools are also available.
+
+* `osxpmem <https://github.com/Velocidex/c-aff4/releases/download/3.2/osxpmem_3.2.zip>`_
+
+
+
+Procedure to create symbol tables for macOS
+--------------------------------------------
+
+To create a symbol table please refer to :ref:`symbol-tables:Mac or Linux symbol tables`.
+
+.. tip:: It may be possible to locate pre-made ISF files from the `download link <https://downloads.volatilityfoundation.org/volatility3/symbols/mac.zip>`_ ,
+    which is built and maintained by `volatilityfoundation <https://www.volatilityfoundation.org/>`_.
+    After creating the file or downloading it from the link, place the file under the directory ``volatility3/symbols/``.
+
+
+Listing plugins
+---------------
+
+The following is a sample of the macOS plugins available for volatility3, it is not complete and more plugins may
+be added.  For a complete reference, please see the volatility 3 :doc:`list of plugins <volatility3.plugins>`.
+For plugin requests, please create an issue with a description of the requested plugin.
+
+.. code-block:: shell-session
+
+    $ python3 vol.py --help | grep -i mac. | head -n 4
+        mac.bash.Bash       Recovers bash command history from memory.
+        mac.check_syscall.Check_syscall
+        mac.check_sysctl.Check_sysctl
+        mac.check_trap_table.Check_trap_table
+
+.. note:: Here the the command is piped to grep and head in-order to provide the start of the list of macOS plugins.
+
+
+Using plugins
+-------------
+
+The following is the syntax to run the volatility CLI.
+
+.. code-block:: shell-session
+
+    $ python3 vol.py -f <path to memory image> <plugin_name> <plugin_option>
+
+
+Example
+-------
+
+banners
+~~~~~~~
+
+In this example we will be using a memory dump from the Securinets CTF Quals 2019 Challenge called Contact_me.  We will limit the discussion to memory forensics with volatility 3 and not extend it to other parts of the challenge.
+Thanks go to `stuxnet <https://github.com/stuxnet999/>`_ for providing this memory dump and `writeup <https://stuxnet999.github.io/securinets-ctf/2019/08/24/SecurinetsQuals2019-Contact-Me.html>`_.
+
+
+.. code-block:: shell-session
+
+    $ python3 vol.py -f contact_me banners.Banners
+        
+        Volatility 3 Framework 2.4.2
+
+        Progress:  100.00               PDB scanning finished
+        Offset  Banner
+        
+        0x4d2c7d0       Darwin Kernel Version 16.7.0: Thu Jun 15 17:36:27 PDT 2017; root:xnu-3789.70.16~2/RELEASE_X86_64
+        0xb42b180       Darwin Kernel Version 16.7.0: Thu Jun 15 17:36:27 PDT 2017; root:xnu-3789.70.16~2/RELEASE_X86_64
+        0xcda9100       Darwin Kernel Version 16.7.0: Thu Jun 15 17:36:27 PDT 2017; root:xnu-3789.70.16~2/RELEASE_X86_64
+        0x1275e7d0      Darwin Kernel Version 16.7.0: Thu Jun 15 17:36:27 PDT 2017; root:xnu-3789.70.16~2/RELEASE_X86_64
+        0x1284fba4      Darwin Kernel Version 16.7.0: Thu Jun 15 17:36:27 PDT 2017; root:xnu-3789.70.16~2/RELEASE_X86_64
+        0x34ad0180      Darwin Kernel Version 16.7.0: Thu Jun 15 17:36:27 PDT 2017; root:xnu-3789.70.16~2/RELEASE_X86_64
+        
+
+The above command helps us to find the memory dump's Darwin kernel version. Now using the above banner we can search for the needed ISF file.
+If ISF file cannot be found then, follow the instructions on :ref:`getting-started-macos-tutorial:Procedure to create symbol tables for macOS`. After that, place the ISF file under the ``volatility3/symbols`` directory.
+
+mac.pslist
+~~~~~~~~~~~~
+
+.. code-block:: shell-session
+
+    $ python3 vol.py -f contact_me mac.pslist.PsList
+
+        Volatility 3 Framework 2.4.2
+        Progress:  100.00               Stacking attempts finished
+
+        PID     PPID    COMM
+
+        0       0       kernel_task
+        1       0       launchd
+        35      1       UserEventAgent
+        38      1       kextd
+        39      1       fseventsd
+        37      1       uninstalld
+        45      1       configd
+        46      1       powerd
+        52      1       logd
+        58      1       warmd
+        .....
+
+``mac.pslist`` helps us to list the processes which are running, their PIDs and PPIDs.
+
+mac.pstree
+~~~~~~~~~~~~
+
+.. code-block:: shell-session
+
+    $ python3 vol.py -f contact_me mac.pstree.PsTree
+        Volatility 3 Framework 2.4.2
+        Progress:  100.00               Stacking attempts finished
+        PID     PPID    COMM
+
+        35      1       UserEventAgent
+        38      1       kextd
+        39      1       fseventsd
+        37      1       uninstalld
+        204     1       softwareupdated
+        * 449   204     SoftwareUpdateCo
+        337     1       system_installd
+        * 455   337     update_dyld_shar
+
+``mac.pstree`` helps us to display the parent child relationships between processes.
+
+mac.ifconfig
+~~~~~~~~~~
+
+.. code-block:: shell-session
+
+    $ python3 vol.py -f contact_me mac.ifconfig.Ifconfig
+
+        Volatility 3 Framework 2.4.2
+        Progress:  100.00               Stacking attempts finished
+        Interface       IP Address      Mac Address     Promiscuous
+
+        lo0                     False
+        lo0     127.0.0.1               False
+        lo0     ::1             False
+        lo0     fe80:1::1               False
+        gif0                    False
+        stf0                    False
+        en0     00:0C:29:89:8B:F0       00:0C:29:89:8B:F0       False
+        en0     fe80:4::10fb:c89d:217f:52ae     00:0C:29:89:8B:F0       False
+        en0     192.168.140.128 00:0C:29:89:8B:F0       False
+        utun0                   False
+        utun0   fe80:5::2a95:bb15:87e3:977c             False
+        
+we can use the ``mac.ifconfig`` plugin to get information about the configuration of the network interfaces of the host under investigation.

doc/source/index.rst

@@ -25,6 +25,7 @@ There is also some information to get you started quickly:
     :caption: Getting Started
 
     getting-started-linux-tutorial
+    getting-started-mac-tutorial
     getting-started-windows-tutorial
 
 

doc/source/simple-plugin.rst

@@ -259,7 +259,7 @@ The plugin then takes the process's ``BaseDllName`` value, and calls :py:meth:`~
 as defined by the symbols, are directly accessible and use the case-style of the symbol library it came from (in Windows,
 attributes are CamelCase), such as ``entry.BaseDllName`` in this instance.  Any attributes not defined by the symbol but added
 by Volatility extensions cannot be properties (in case they overlap with the attributes defined in the symbol libraries)
-and are therefore always methods and pretended with ``get_``, in this example ``BaseDllName.get_string()``.
+and are therefore always methods and prepended with ``get_``, in this example ``BaseDllName.get_string()``.
 
 Finally, ``FullDllName`` is populated.  These operations read from memory, and as such, the memory image may be unable to
 read the data at a particular offset.  This will cause an exception to be thrown.  In Volatility 3, exceptions are thrown

requirements-dev.txt

@@ -20,7 +20,3 @@ jsonschema>=2.3.0
 
 # This is required for memory acquisition via leechcore/pcileech.
 leechcorepyc>=2.4.0
-
-# This is required for analyzing Linux samples compressed using AVMLs native
-# compression format.  It is not required for AVML's standard LiME compression.
-python-snappy==0.6.0

requirements.txt

@@ -16,7 +16,3 @@ pycryptodome
 
 # This is required for memory acquisition via leechcore/pcileech.
 leechcorepyc>=2.4.0
-
-# This is required for analyzing Linux samples compressed using AVMLs native
-# compression format.  It is not required for AVML's standard LiME compression.
-python-snappy==0.6.0