Forensic helper scripts for KAPE and RegRipper

If you use KAPE or RegRipper for forensic analysis, then Invoke-Forensics could help you by providing PowerShell commands to simplify working with these tools. They speed up your work when

you deal with multiple evidence files in that commands are provided for unzipping and mounting VHDX images and run KAPE against them or let you getting files from them.
you are tired of searching for the correct name to provide to these tools in that the commands have tab-completion support which lets you quickly find available RegRipper plugins or KAPE's Targets and Modules (KapeFiles) ("what was that Module name again?"), run them or let you show the content of the files for inspection
you need to search for specific KAPE files based on a given filter ("Is there already a PowerShell console Target available?")

What exactly do these scripts provide?
Requirements
Functions
Usage
Tips & Tricks
Changelog
- [Unreleased]
- [0.1.0] - 2021-03-22

What exactly do these scripts provide?

The main advantage using the scripts is that they allow running KAPE against or collecting files from multiple collected KAPE images in one command which includes unzipping, mounting the VHDX and running the command (KAPE itself or file copy) against the corresponding drive letter and unmounting the VHDX image again. Using these function against multiple collections reduce the time severely compared to running these commands manually.

The other purpose of the scripts is to quickly jump through the available plugins or KAPE files using the tab-completion support and to be able to print the content of the files to inspect those directly in the shell.

Important note: These scripts do only provide a subset of KAPE's and RegRippers arguments. For more specific needs use the binaries directly to be able to use all the available options, make a Pull Request or file an Issue to request the inclusion of further arguments.

The wrapper scripts provide:

Tab-completion support for plugin and artifact names which helps finding them without the need to navigate into subfolders.
Run KAPE against one or multiple evidence ZIP files or VHDX images which includes unzipping evidence ZIP files, mounting VHDX images and run KAPE with given Modules against those (Invoke-KapeOnMultipleImages).
Copy files from one or multiple evidence ZIP files or VHDX images which includes unzipping evidence ZIP files, mounting VHDX images and run a copy command with a given (regex) pattern against those (Invoke-KapeFileCollection).
Run one or multiple RegRipper plugins or profiles against a given hive. RegRipper only allows using one plugin or a profile per execution, but not multiple plugins in one command outside of profiles (Invoke-RegRipper).
Search for KAPE files based on keywords in a KAPE field (e.g. Description, FileMask, ...) or the whole file and print either a short list with the name and the location, the file content or a file listing for further processing in PowerShell (Search-KapeFile). gkape.exe could also be used for searching Targets or Modules.
Printing the content of plugins or artifact files without the need for navigating into subfolders (Invoke-Kape*, Search-KapeFile and Invoke-RegRipper functions using -Print).
Mounting VHDX files and return drive letter
Handling unpacking of evidence ZIP files and VHDX ZIP file in target folder in one command.

Requirements

Unzip program from e.g. Git for Windows found in the path. The Expand-Archive PowerShell command fail when extracting the VHDX ZIP files.

For mounting VHDX images install the required PowerShell module. Native PowerShell command Mount-DiskImage is used within the provided Mount-VHDX. The advantage of Mount-VHDX over Mount-DiskImage is that it returns the used drive letter.

PS> Enable-WindowsOptionalFeature -FeatureName "Hyper-V Module for Windows PowerShell"

Functions

Invoke-Kape - Run KAPE with given Targets or Modules
Invoke-KapeOnMultipleImages - Run KAPE against multiple VHDX containers, including unzipping evidence ZIP and VHDX zip and mounting VHDX files first
Invoke-KapeFileCollection - Collect files based on a given pattern from VHDX containers
Search-KapeFile - Search for KAPE files based on either a pattern in a field or in the whole file
Invoke-KapeUnpack - Unpack KAPE evidence ZIP and included VHDX zip file
Mount-VHDX - Mount VHDX container and return drive letter
Remove-VHDX - Remove VHDX files from given path and all its subfolders
Invoke-RegRipper - Run one or more RegRipper plugins against a hive

Usage

Navigate into KAPE or RegRipper folder

Load scripts into PowerShell

# Load both RegRipper and KAPE functions
. .\Invoke-Forensics\Invoke-Forensics.ps1
# Load KAPE functions
. .\Invoke-Forensics\Invoke-Kape.ps1
# Load RegRipper functions
. .\Invoke-Forensics\Invoke-RegRipper.ps1

Run commands, see below

Invoke-Kape

Change into KAPE's directory first.

Run a KAPE command or show the content of a Target or Module file. The Target and Module parameters have tab-completion support. You can pass module variables with -mvars similar as it is used with KAPE, see KAPE's doc.

# List all Targets which starts with an 'a' in the name and print the one which was choosen
Invoke-Kape -Target a<ctrl-space> -Print

# Jump through all Targets which starts with an 'a' in the name and print the content
Invoke-Kape -Print -Target a<tab>

# Example for printing Amcache Target
PS> Invoke-Kape -Target Amcache -print
Description: Amcache.hve
Author: Eric Zimmerman
Version: 1.0
Id: 13ba1e33-4899-4843-adf1-c7e6b20d759a
RecreateDirectories: true
...

# Jump through all remaining Modules besides AmcacheParser and print the selected
Invoke-Kape -Print -Target Amcache -Module AmcacheParser,<tab>

# Invoke KAPE using the Target Amcache
Invoke-Kape -tsource C: -tdest C:\temp\ -Target Amcache

# Invoke KAPE using the Module AmcacheParser
Invoke-Kape -msource C:\temp -mdest C:\temp\ -Module AmcacheParser

# Invoke KAPE using two Modules
invoke-kape -msource C:\WindowsTimelineTest -mdest C:\WindowsTimelineTestTemp -Module SQLECmd,WxTCmd

Invoke-KapeOnMultipleImages

Change into KAPE's directory first.

The function provides the following:

Unpacks all KAPE evidence zip files (unless -SkipUnzip or -SkipUnzipEvidenceZip is given)
Unpacks all VHDX zip files found in the target output folder (-TOutPattern) (unless -SkipUnzip is given)
Extracts the hostname from the path to use it in KAPE commands and for output folder name
Loop over all VHDX files
- Mounts VHDX file and provide the drive letter to the KAPE command
- Run KAPE with the given Modules (-Module has tab-completion support for Module names)
- Unmounts the VHDX file

Sample directory and file structure:

C:\evidence-folder\
- server1-evidence.zip
  - include mout and tout folders
  - tout includes the VHDX ZIP
- server2-evidence.zip

PS> $zip="C:\evidence-folder\"
PS> $tout="*\tout"
PS> $dest="C:\kape-parsing-output"
PS> $serverPattern="\\(\w*)-evidence"
PS> $modules=@("JLECmd","LECmd")
PS> Invoke-KapeOnMultipleImages -KapeEvidenceFolder $zip -TOut $tout -Destination $dest -HostnamePattern $serverPattern -Module $modules -SkipUnzip

Invoke-KapeFileCollection

Change into KAPE's directory first.

The function copies files based on a pattern (-FileNamePattern) from the mounted VHDX image into a destination directory. This can be used if you need to extract a given file from an KAPE image.

The function provides the following:

Unpacks all KAPE evidence zip files (unless -SkipUnzip or -SkipUnzipEvidenceZip is given)
Unpacks all VHDX zip files found in the target output folder (-TOutPattern) (unless -SkipUnzip is given)
Loop over all VHDX files
- Mounts VHDX file and provide the drive letter to the copy command
- Copy given files based on filename pattern into destination directory. The source directory is replicated in the destination directory
- Unmounts the VHDX file

# Unzip evidence zip file, navigate into new subfolders, unzip VHDX ZIP files, mount VHDX images and collect files into destination directory
PS> Invoke-KapeFileCollection -KapeEvidenceFolder C:\kape-output\ -TOutPattern *\tout -Destination C:\kape-output\fs -HostnamePattern "\\(\w*)-evidence" -FileNamePattern "*console*history*"

# Skip unzipping of evidence zip file, just navigate into already unzipped envidence subfolders, mount VHDX images and collect files into destination directory
PS> Invoke-KapeFileCollection -KapeEvidenceFolder C:\kape-output\ -TOutPattern *\tout -Destination C:\kape-output\fs -HostnamePattern "\\(\w*)-evidence" -FileNamePattern "*console*history*" -SkipUnzip

Search-KapeFile

Search through all Target and Module files, either by pattern in a specific field or the whole file.

Basic usage, there is a generic -Filter parameter to search the whole file for a keyword or more specific filters, like -FilterDescription, -FilterFileMask, ...

If you would like to print the found files use -Print.

Use -MatchAllOfThem to match all of the given filters.

# Search for powershell in description field or history in the file mask field and use a short list as output.
PS> Search-KapeFile -FilterDescription powershell -FilterFileMask history -ShortList
!SANS_Triage.tkape .\Targets\Compound\!SANS_Triage.tkape
Chrome.tkape .\Targets\Browsers\Chrome.tkape
CombinedLogs.tkape .\Targets\Compound\CombinedLogs.tkape
Debian.tkape .\Targets\WSL\Debian.tkape
...

# Print the content of the found KAPE files
PS> Search-KapeFile -FilterDescription powershell -FilterPath psreadline  -MatchAllOfThem -Print

# Search for powershell in description field or history in the file mask field and return file listing object.
PS> Search-KapeFile -FilterDescription powershell -FilterFileMask history

Name                                        FullName
----                                        --------
PowerShellOperationalFullEventLogView.mkape C:\KAPE\Modules\Eve...
PowerShell5SecondPause.mkape                C:\KAPE\Modules\Mis...
DoubleCommander.tkape                       C:\KAPE\Targets\App...
Dropbox.tkape                               C:\KAPE\Targets\App...
...

# Post processing search by using native PowerShell
PS> Search-KapeFile -FilterDescription powershell -FilterFileMask history | select name
...

# Search for a KAPE file which matches all of the provided patterns.
PS> Search-KapeFile -FilterDescription powershell -FilterFileMask history -MatchAllOfThem

# Other searches to limit the scope
PS> Search-KapeFile -FilterDescription powershell -OnlyTargets
PS> Search-KapeFile -FilterPath psreadline -OnlyModules
PS> Search-KapeFile -FilterDescription mozilla -FilterPath thunderbird -OnlyTargets -MatchAllOfThem -ShortList
Thunderbird.tkape .\Targets\Apps\Thunderbird.tkape

Invoke-KapeUnpack

Unzip evidence output ZIP file and then unzip the VHDX zip file inside the Targets folder.

PS> Invoke-KapeUnpack -Path C:\kape-files\ -TOutPattern *\tout -Verbose
PS> Invoke-KapeUnpack -Path C:\kape-files\ -TOutPattern *\tout -Verbose -SkipUnzipEvidenceZip

Mount-VHDX

Mount the given image and provide the used drive letter. The native mount command doesn't provide the drive letter, therefore we use Get-Volume before and after and diff the used drive letters on the system to see which was given to our VHDX image.

PS> Mount-VHDX -VHDXFile C:\kape-files\server\tout\2021-03-11T152024_server_20210311T152024.vhdx
PS> Mount-VHDX -VHDXFile C:\kape-files\server\tout\2021-03-11T152024_server_20210311T152024.vhdx -verbose

Remove-VHDX

Remove VHDX files recursively.

Remove-VHDX C:\kape-files

Invoke-RegRipper

Change into RegRipper's directory first.

Run a RegRipper plugin or profile against a hive.

# Print plugin content
PS> Invoke-RegRipper -Hive E:\C\Windows\System32\config\SOFTWARE -Plugin appcertdlls -Print
appcertdlls
#-----------------------------------------------------------
# appcertdlls.pl
#
# History:
#  20200427 - updated output date format
#  20120912 - created

# Print multiple plugins
PS> Invoke-RegRipper -Hive E:\C\Windows\System32\config\SOFTWARE -Plugin appcertdlls,clsid -Print

# Invoke RegRipper with given plugin
PS> Invoke-RegRipper -Hive E:\C\Windows\System32\config\SOFTWARE -Plugin app<tab>
PS> Invoke-RegRipper -Hive E:\C\Windows\System32\config\SOFTWARE -Plugin appcertdlls

# Run multiple plugins after each other
PS> Invoke-RegRipper -Hive E:\C\Windows\System32\config\SOFTWARE -Plugin appcertdlls,clsid

# list all plugins
PS> Invoke-RegRipper -Hive E:\C\Windows\System32\config\SOFTWARE -Plugin <ctrl-space>
adobe                   cached                  gpohist                 ...
allowedenum             cached_tln              gpohist_tln             ...
amcache                 calibrator              heap                    ...
amcache_tln             clsid                   heidisql                ...
...

Tips & Tricks

If you work with Vim and would like to use folding for RegRipper output, use the following snippet in your vimrc. Use :RRFolding to enable plugin folding

" folds on <pluginname> v.XXXXXX
func! SetRegRipper()
   setlocal foldexpr=getline(v:lnum)=~\'^\\w\\+.*\\sv\\.'?'>1':'='
   setlocal foldmethod=expr
endfunc
command! RRFolding :call SetRegRipper()

If you would like to get crazy, put that autocmd in your vimrc to activate folding for filenames containing "regripper".

au BufRead,BufNewFile * if (expand('<afile>') =~ 'regripper') | call SetRegRipper() | endif

Changelog

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

[Unreleased]

Changed

Rename Invoke-Forensic.ps1 to Invoke-Forensics.ps1

[0.1.0] - 2021-03-22

Added

Add initial version of the helper scripts, allow working with evidence ZIP files, VHDX images, running KAPE against multiple ZIP or VHDX files, search for Targets or Modules using different filters, run RegRipper commands, all the commands support tab-completion for RegRipper's plugins and KAPE's Targets and Modules.

swisscom/Invoke-Forensics

Forensic helper scripts for KAPE and RegRipper

What exactly do these scripts provide?

Requirements

Functions

Usage

Invoke-Kape

Invoke-KapeOnMultipleImages

Invoke-KapeFileCollection

Search-KapeFile

Invoke-KapeUnpack

Mount-VHDX

Remove-VHDX

Invoke-RegRipper

Tips & Tricks

Changelog

[Unreleased]

[0.1.0] - 2021-03-22