Moved to use a python package

* Renamed sections package
* Updated all references
* Fixed issue in autodoc for Evtx/Section 3
* Renamed docssrc to doc_src
* Updated makefiles
* Added package file with version information
* Moved requirements to setup.py

.github/workflows/gh-pages.yml

@@ -29,21 +29,18 @@ jobs:
         uses: actions/cache@v2
         with:
           path: ${{ steps.pip-cache.outputs.dir }}
-          key: ${{ runner.os }}-pip-${{ hashFiles('**/*requirements.txt') }}
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
           restore-keys: |
             ${{ runner.os }}-pip-
 
       - name: Install dependencies
         run: python3 -m pip install -r ./requirements.txt
 
-      - name: Install dev dependencies
-        run: python3 -m pip install -r ./dev_requirements.txt
-
       - name: Build docs
-        run: (cd docssrc && make html)
+        run: (cd doc_src && make html)
 
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs
+          publish_dir: ./doc_src/_build/html

.gitignore

@@ -1,7 +1,7 @@
 # Exclude locally built docs
 docs/
 .vscode/
-docssrc/_build/
+doc_src/_build/
 .idea/
 
 # Byte-compiled / optimized / DLL files

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 Chapin Bryce
+Copyright (c) 2020 Chapin Bryce
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

dev_requirements.txt

@@ -1,4 +0,0 @@
-alabaster==0.7.12
-Sphinx==3.2.1
-sphinx-rtd-theme==0.5.0
-black==20.8b1

doc_src/Makefile

@@ -18,7 +18,6 @@ help:
 html: Makefile
 	# @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	@$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html"
-	cp -r $(BUILDDIR)/html/* ../docs
 
 epub: Makefile
 	@$(SPHINXBUILD) -M epub "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc_src/conf.py

@@ -10,19 +10,17 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-import os
-import sys
 import datetime
-sys.path.insert(0, os.path.abspath('..'))
+from pyforhandbook import version as version_info
 
 # -- Project information -----------------------------------------------------
 
 project = 'Python Forensics Handbook'
-copyright = '2019, Chapin Bryce'
+copyright = version_info.__copyright__
-author = 'Chapin Bryce'
+author = version_info.__author__
 
 # The full version, including alpha/beta/rc tags
-release = datetime.datetime.now().strftime('%Y%m%d')
+release = version_info.__version__
 version = datetime.datetime.now().strftime('%Y%m%d')
 
 # -- General configuration ---------------------------------------------------

doc_src/index.rst

@@ -20,7 +20,7 @@ A guide for developing Python scripts in DFIR
 
 Handbook Sections
 ==============================
-.. automodule:: sections
+.. automodule:: pyforhandbook
    :members:
 
 Indices and tables

doc_src/make.bat

@@ -1,38 +1,35 @@
-@ECHO OFF
+@ECHO OFF
-
+
-pushd %~dp0
+pushd %~dp0
-
+
-REM Command file for Sphinx documentation
+REM Command file for Sphinx documentation
-
+
-if "%SPHINXBUILD%" == "" (
+if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
+	set SPHINXBUILD=sphinx-build
-)
+)
-set SOURCEDIR=.
+set SOURCEDIR=.
-set BUILDDIR=_build
+set BUILDDIR=_build
-
+
-if "%1" == "" goto help
+if "%1" == "" goto help
-
+
-%SPHINXBUILD% >NUL 2>NUL
+%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
+if errorlevel 9009 (
-	echo.
+	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
+	echo.may add the Sphinx directory to PATH.
-	echo.
+	echo.
-	echo.If you don't have Sphinx installed, grab it from
+	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
+	echo.http://sphinx-doc.org/
-	exit /b 1
+	exit /b 1
-)
+)
-
+
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
-goto end
+goto end
-
+
-:help
+:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
-
+
-:end
+:end
-popd
+popd
-
-REM copy HTML to docs folder
-robocopy _build\html ..\docs /S /E /NFL /NDL /NJH /NJS

doc_src/section1.rst

@@ -6,27 +6,27 @@ Section 1 - Essential Scripts
 
 Section 1.1 - Argparse Example
 --------------------------------
-.. automodule:: sections.section_01.argparse_example
+.. automodule:: pyforhandbook.section_01.argparse_example
    :members:
 
 Section 1.2 - Logging Example
 --------------------------------
-.. automodule:: sections.section_01.logging_example
+.. automodule:: pyforhandbook.section_01.logging_example
    :members:
 
 Section 1.3 - Open Files
 ------------------------
-.. automodule:: sections.section_01.open_files
+.. automodule:: pyforhandbook.section_01.open_files
    :members:
 
 Section 1.4 - CSV Example
 --------------------------------
-.. automodule:: sections.section_01.csv_example
+.. automodule:: pyforhandbook.section_01.csv_example
    :members:
 
 Section 1.5 - Directory Recursion
 ---------------------------------
-.. automodule:: sections.section_01.recursion_example
+.. automodule:: pyforhandbook.section_01.recursion_example
    :members:
 
 Indices and tables

doc_src/section2.rst

@@ -6,12 +6,12 @@ Section 2 - Registry Parsing
 
 Section 2.1 - Opening a Hive
 --------------------------------
-.. automodule:: sections.section_02.yarp_base
+.. automodule:: pyforhandbook.section_02.yarp_base
    :members:
 
 Section 2.2 - Parsing Hive Values
 ----------------------------------
-.. automodule:: sections.section_02.yarp_ntuser
+.. automodule:: pyforhandbook.section_02.yarp_ntuser
    :members:
 
 Indices and tables

doc_src/section3.rst

@@ -0,0 +1,17 @@
+Section 3 - Windows Event Log Parsing
+=====================================
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+Section 3.1 - Using python-evtx
+----------------------------------
+.. automodule:: pyforhandbook.section_03.using_python_evtx
+   :members:
+
+Indices and tables
+--------------------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc_src/section6.rst

@@ -6,7 +6,7 @@ Section 6 - Sqlite & MacOS/Mobile/Browsers
 
 Section 6.1 - Opening Sqlite
 --------------------------------
-.. automodule:: sections.section_06.opening_sqlite
+.. automodule:: pyforhandbook.section_06.opening_sqlite
    :members:
 
 Indices and tables

docssrc/section3.rst

@@ -1,27 +0,0 @@
-Section 3 - Windows Event Log Parsing
-=====================================
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
-Section 3.1 - Opening an Event Log
-----------------------------------
-.. automodule:: sections.section_03.open_evtx
-   :members:
-
-Section 3.2 - Iterate over events
----------------------------------
-.. automodule:: sections.section_03.get_events
-   :members:
-
-Section 3.3 - Filter event data
--------------------------------
-.. automodule:: sections.section_03.filter_events_json
-   :members:
-
-Indices and tables
---------------------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

pyforhandbook/section_01/argparse_example.py

@@ -19,7 +19,7 @@ how to set default values and boolean arguments. the ``argparse``
 module has many more features documented at
 https://docs.python.org/3/library/argparse.html
 
-.. literalinclude:: ../sections/section_01/argparse_example.py
+.. literalinclude:: ../pyforhandbook/section_01/argparse_example.py
     :pyobject: setup_argparse
 
 """

pyforhandbook/section_01/csv_example.py

@@ -34,7 +34,7 @@ generate the header information. The latter option may produce
 a new order each iteration and is not prefered if you can
 determine the headers in advance.
 
-.. literalinclude:: ../sections/section_01/csv_example.py
+.. literalinclude:: ../pyforhandbook/section_01/csv_example.py
     :pyobject: write_csv_dicts
 
 List of ordered lists to CSV
@@ -58,7 +58,7 @@ information. Unlike the dictionary option, you cannot filter
 column data by adjusting the provided headers, you must write all
 columns to the CSV.
 
-.. literalinclude:: ../sections/section_01/csv_example.py
+.. literalinclude:: ../pyforhandbook/section_01/csv_example.py
     :pyobject: write_csv_lists
 
 
@@ -138,11 +138,10 @@ def write_csv_lists(outfile, data, headers=None):
         # Write only provided headers, ignore others
         csvfile = csv.writer(open_file)
         for count, entry in enumerate(data):
-            if count == 0:
+            if count == 0 and headers:
                 # If headers are defined, write them, otherwise
                 # continue as they will be written anyways
-                if headers:
+                csvfile.writerow(headers)
-                    csvfile.writerow(headers)
             csvfile.writerow(entry)
 
 sample_dict_data = [

pyforhandbook/section_01/logging_example.py

@@ -20,7 +20,7 @@ set different logging levels for the two handlers - generally you
 keep debugging information in the log file while writing more
 critical messages to the console in STDERR.
 
-.. literalinclude:: ../sections/section_01/logging_example.py
+.. literalinclude:: ../pyforhandbook/section_01/logging_example.py
     :pyobject: setup_logging
 
 Docstring References

pyforhandbook/section_01/open_files.py

@@ -22,7 +22,7 @@ magic value/file signature, this low-tech method will help with parsing a
 collection of files that may be UTF-8, UTF-16-LE, and UTF-16-BE, three very
 common text file encodings. Feel free to build and share on this.
 
-.. literalinclude:: ../sections/section_01/open_files.py
+.. literalinclude:: ../pyforhandbook/section_01/open_files.py
     :pyobject: open_file
 
 Docstring References

pyforhandbook/section_01/recursion_example.py

@@ -19,7 +19,7 @@ folders within a single directory. From here you can further
 interact with individual files and folders or iterate recursively
 by calling the function on identified subdirectories.
 
-.. literalinclude:: ../sections/section_01/recursion_example.py
+.. literalinclude:: ../pyforhandbook/section_01/recursion_example.py
     :pyobject: list_directory
 
 List a directory recursively
@@ -33,7 +33,7 @@ handling the processing of files. This sample shows a method of
 counting the number of files, subdirectories, and files ending in
 ".py" as an example.
 
-.. literalinclude:: ../sections/section_01/recursion_example.py
+.. literalinclude:: ../pyforhandbook/section_01/recursion_example.py
     :pyobject: iterate_files
 
 """

pyforhandbook/section_02/yarp_base.py

@@ -21,7 +21,7 @@ leverage any available transaction logs to include additional information
 otherwise available on the Window's system. This class handles both the opening
 of the primary hive and attempted recovery of the transaction logs.
 
-.. literalinclude:: ../sections/section_02/yarp_base.py
+.. literalinclude:: ../pyforhandbook/section_02/yarp_base.py
     :pyobject: RegistryBase
 
 Docstring References

pyforhandbook/section_02/yarp_ntuser.py

@@ -22,7 +22,7 @@ NTUSER.DAT files, though could get more specific on Windows versions, etc. In
 this class we store a few useful details including fixed values used by other
 methods and metadata about the class.
 
-.. literalinclude:: ../sections/section_02/yarp_ntuser.py
+.. literalinclude:: ../pyforhandbook/section_02/yarp_ntuser.py
     :pyobject: NTUSER.__init__
 
 Reading Hive String Values
@@ -36,7 +36,7 @@ continue to recurse on subkeys here. Instead we return this cursory information
 for the caller to display as they wish. Since the values within MountPoints2
 store string data, we don't need to perform further parsing of the record.
 
-.. literalinclude:: ../sections/section_02/yarp_ntuser.py
+.. literalinclude:: ../pyforhandbook/section_02/yarp_ntuser.py
     :pyobject: NTUSER.parse_mountpoints2
 
 Reading Hive Binary Values
@@ -51,7 +51,7 @@ method) using Struct to extract a timestamp and integer marking whether a
 trusted macro was used. These parsed attributes are then returned to the caller
 to be displayed.
 
-.. literalinclude:: ../sections/section_02/yarp_ntuser.py
+.. literalinclude:: ../pyforhandbook/section_02/yarp_ntuser.py
     :pyobject: NTUSER.parse_trustrecords
 
 Docstring References
@@ -63,7 +63,7 @@ import struct
 
 import yarp
 try:
-    from sections.section_02.yarp_base import RegistryBase
+    from pyforhandbook.section_02.yarp_base import RegistryBase
 except ImportError:
     from yarp_base import RegistryBase
 
@@ -131,9 +131,9 @@ class NTUSER(RegistryBase):
             key_name = subkey.name()
             is_ver_num = False
             try:
-                float_val = float(key_name)
+                _ = float(key_name)
                 is_ver_num = True
-            except ValueError as e:
+            except ValueError:
                 is_ver_num = False
 
             if is_ver_num:

pyforhandbook/section_03/using_python_evtx.py

@@ -1,4 +1,4 @@
-"""Example for opening EVTX files.
+"""Example for opening EVTX files, iterating over events, and filtering events.
 
 Demonstrates how to open an EVTX file and get basic details about the event log.
 This section makes use of python-evtx, a python library for reading event log
@@ -9,7 +9,7 @@ add snippets that showcase how to make use of them in reading EVTX files.
 
 Example Usage:
 
-    ``$ python open_evtx.py System.evtx``
+    ``$ python using_python_evtx.py System.evtx``
 
 References:
 
@@ -22,7 +22,7 @@ Open Windows Event Logs (EVTX)
 This function shows an example of opening an EVTX file and parsing out several
 header metadata parameters about the file.
 
-.. literalinclude:: ../sections/section_03/open_evtx.py
+.. literalinclude:: ../pyforhandbook/section_03/using_python_evtx.py
     :pyobject: open_evtx
 
 Iterate over record XML data (EVTX)
@@ -38,7 +38,7 @@ which will then call the ``.lxml()`` method on the individual event record.
 This requires the installation of the lxml Library, as it returns a lxml.etree
 object that you can interact with.
 
-.. literalinclude:: ../sections/section_03/open_evtx.py
+.. literalinclude:: ../pyforhandbook/section_03/using_python_evtx.py
     :pyobject: get_events
 
 Filtering records within events logs
@@ -55,7 +55,7 @@ filters, and return values. Some examples include:
 - Identify PowerShell events and expose arguments for further processing
   (ie. Base64 decoding, shellcode analysis)
 
-.. literalinclude:: ../sections/section_03/open_evtx.py
+.. literalinclude:: ../pyforhandbook/section_03/using_python_evtx.py
     :pyobject: filter_events_json
 
 Docstring References

pyforhandbook/section_06/opening_sqlite.py

@@ -17,7 +17,7 @@ This function shows an example of opening a Sqlite database with Python.
 Additional information regarding Sqlite modules can be
 seen at https://docs.python.org/3/library/sqlite3.html.
 
-.. literalinclude:: ../sections/section_06/opening_sqlite.py
+.. literalinclude:: ../pyforhandbook/section_06/opening_sqlite.py
     :pyobject: open_sqlite
 
 Listing Tables configuration
@@ -25,7 +25,7 @@ Listing Tables configuration
 
 This function shows an example of listing available tables in an opened Sqlite database.
 
-.. literalinclude:: ../sections/section_06/opening_sqlite.py
+.. literalinclude:: ../pyforhandbook/section_06/opening_sqlite.py
     :pyobject: list_tables
 """
 import argparse

pyforhandbook/version.py

@@ -0,0 +1,5 @@
+__author__ = 'Chapin Bryce'
+__authors__ = ['Chapin Bryce', 'Brittney Argirakis']
+__license__ = ''
+__version__ = '0.1.0'
+__copyright__ = '2020, Chapin Bryce'

requirements.txt

@@ -1,3 +1,5 @@
--e git+https://github.com/msuhanov/yarp@1.0.28#egg=yarp
+.
-python-evtx==0.6.1
+alabaster==0.7.12
-lxml==4.5.2
+Sphinx==3.2.1
+sphinx-rtd-theme==0.5.0
+black==20.8b1