Modules

KAPE Modules Skills Guide

This document describes the skills and knowledge required to understand, analyze, and create KAPE Module files (.mkape).

Overview

KAPE Modules are YAML-like configuration files that define parsing and processing steps for collected artifacts. Each Module specifies one or more processors (executables and command-line arguments) that transform raw artifacts into processed outputs in various formats (CSV, JSON, XML, etc.).

File Format and Structure

Module files use a YAML-like format with the following structure:

Description: <string>
Category: <string>
Author: <string>
Version: <float>
Id: <GUID>
ExportFormat: <format>
[Optional fields]
Processors:
    - Executable: <string>
      CommandLine: <string>
      ExportFormat: <format>
    - [Additional processors...]

# Documentation
# <Links and references>

Required Fields

Top-Level Fields

Optional Top-Level Fields

Processor Item Fields

Understanding Export Formats

Modules support multiple output formats. Each processor can generate one format:

Path Variables and Placeholders

Modules use the following placeholders in CommandLine arguments:

Example

CommandLine: -d %sourceDirectory% --csv %destinationDirectory%

When executed:

• -d flag points to the folder containing collected artifacts
• --csv flag tells the tool to output CSV format
• Results are written to %destinationDirectory%

Understanding Artifact Parsing

To determine what artifacts a Module parses:

1. Read the Description: Summarizes what the Module processes
2. Check the Category: Indicates the output data type
3. Examine the Executable: Identifies the parsing tool
4. Review CommandLine: Shows which input artifacts/options are used
5. Check ExportFormats: Determines available output formats
6. Review Documentation links: References provide deeper context

Example: What does a Module parse?

# From Modules/Windows/PowerShell_AccessibilityFeatures.mkape
Description: Checks for Debugger registry value and file integrity
Executable: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
CommandLine: -Command "$features = @(...); ..."
ExportFormat: csv

This Module:

1. Executes a PowerShell script
2. Reads Windows registry for accessibility features
3. Checks file integrity using sfc
4. Outputs results as CSV

Processor Types

Binary Executables

Most Modules use pre-compiled tools:

Processors:
    -
        Executable: EvtxECmd.exe
        CommandLine: -d %sourceDirectory% --csv %destinationDirectory%
        ExportFormat: csv

Binary executables must be placed in .\KAPE\Modules\bin\ with subdirectory support:

• Root binary: Executable: tool.exe
• In subfolder: Executable: folder\tool.exe (path relative to bin\)

PowerShell Scripts

Modules can execute PowerShell commands:

Processors:
    -
        Executable: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
        CommandLine: -Command "script code here"
        ExportFormat: csv

Python Scripts

Some Modules execute Python:

Processors:
    -
        Executable: python.exe
        CommandLine: script.py %sourceDirectory% %destinationDirectory%
        ExportFormat: json

Creating New Modules

Step 1: Identify the Parser

• Determine what artifact you want to parse
• Find or develop a tool that parses this artifact
• Ensure the tool is available and can be distributed
• Verify the tool supports your desired output format(s)

Step 2: Determine Command Syntax

Test the tool locally with actual artifacts:

tool.exe -d input_folder --csv output_folder

Document:

• Input parameter(s)
• Output format options
• Output location parameter(s)
• Any required file types/extensions

Step 3: Plan Output Formats

Identify which export formats the tool supports:

• CSV: Spreadsheet analysis
• JSON: Programmatic processing
• XML: Enterprise integration
• TXT: Human-readable reports

Create a Processor for each format:

Processors:
    -
        Executable: tool.exe
        CommandLine: -d %sourceDirectory% --csv %destinationDirectory%
        ExportFormat: csv
    -
        Executable: tool.exe
        CommandLine: -d %sourceDirectory% --json %destinationDirectory%
        ExportFormat: json
    -
        Executable: tool.exe
        CommandLine: -d %sourceDirectory% --xml %destinationDirectory%
        ExportFormat: xml

Step 4: Write the Module File

Description: <Tool Name> - <Artifact Type>
Category: <Category>
Author: Your Name
Version: 1.0
Id: <Generate GUID via: kape.exe --guid>
BinaryUrl: https://github.com/user/tool/releases/
ExportFormat: csv
Processors:
    -
        Executable: tool.exe
        CommandLine: -d %sourceDirectory% --csv %destinationDirectory%
        ExportFormat: csv
    -
        Executable: tool.exe
        CommandLine: -d %sourceDirectory% --json %destinationDirectory%
        ExportFormat: json

# Documentation
# https://github.com/user/tool
# <Add additional documentation links>

Step 5: Validation

• Verify YAML syntax is valid
• Test with actual collected artifacts
• Verify output in all formats
• Run the KAPE Pull Request template checks
• Ensure blank line after last comment before end of file

Common Module Patterns

Single Format Output

Processors:
    -
        Executable: tool.exe
        CommandLine: -d %sourceDirectory% --csv %destinationDirectory%
        ExportFormat: csv

Multiple Format Support

Processors:
    -
        Executable: tool.exe
        CommandLine: -d %sourceDirectory% --csv %destinationDirectory%
        ExportFormat: csv
    -
        Executable: tool.exe
        CommandLine: -d %sourceDirectory% --json %destinationDirectory%
        ExportFormat: json
    -
        Executable: tool.exe
        CommandLine: -d %sourceDirectory% --xml %destinationDirectory%
        ExportFormat: xml

PowerShell-Based Processing

Processors:
    -
        Executable: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
        CommandLine: >
            -Command "Get-ChildItem %sourceDirectory% | 
            ConvertTo-Csv | 
            Out-File %destinationDirectory%\output.csv"
        ExportFormat: csv

File Type Filtering

FileMask: regex:.*\.(evtx|log)$
Processors:
    -
        Executable: parser.exe
        CommandLine: -d %sourceDirectory% --csv %destinationDirectory%
        ExportFormat: csv

Analyzing Existing Modules

Finding Modules by Type

Search for Modules in the appropriate category:

• Modules/Windows/ - Windows native tools and artifacts
• Modules/Apps/ - Third-party application parsers
• Modules/EZTools/ - Eric Zimmerman's forensic tools
• Modules/KapeResearch/ - Research and development modules
• Modules/KapeSync/ - KAPE update and synchronization
• Modules/Compound/ - Modules that reference other Modules

Extracting Information from Module Files

1. List all processors: Parse the YAML and iterate through Processors array
2. Find modules by category: Filter by Category field
3. Find modules using specific tool: Search for Executable values
4. Determine output formats: Check each Processor's ExportFormat
5. Identify artifacts parsed: Examine tool documentation and descriptions

Example: What does an EvtxECmd Module parse?

# Hypothetical Module for Event Log parsing
Description: Windows Event Logs - CSV Format
Category: EventLogs
Executable: EvtxECmd.exe
CommandLine: -d %sourceDirectory% --csv %destinationDirectory%
ExportFormat: csv

This Module:

1. Uses EvtxECmd tool to parse Event Logs
2. Takes all .evtx files from the source directory
3. Outputs parsed data as CSV for analysis in spreadsheets
4. Writes results to the destination directory

Compound Modules

Compound Modules reference other Modules rather than defining processors:

Description: Complete Windows Analysis Suite
Category: Analysis
Author: Someone
Version: 1.0
Id: <GUID>
Processors:
    -
        Name: Event Logs
        Category: EventLogs
        Path: EventLogs_Parsing.mkape
    -
        Name: Registry Analysis
        Category: Registry
        Path: Registry_Analysis.mkape

Use Compound Modules to group related Modules for convenience.

Best Practices

1. Test thoroughly: Verify the Module works with typical collected artifacts
2. Support multiple formats: Provide CSV, JSON, and XML when possible
3. Document the tool: Include URL to tool repository/documentation
4. Use meaningful categories: Maintain consistency with existing categorization
5. Provide clear descriptions: Help analysts understand what's being parsed
6. Include command-line options: Document any special flags or requirements
7. Handle errors gracefully: Plan for missing or malformed input files
8. Version your Modules: Track changes as tool versions change
9. Test on different systems: Verify Module works across OS versions

Common Pitfalls and Solutions

Integration with Targets

Modules work together with Targets:

1. Targets collect raw artifacts (files from disk)
2. Modules parse collected artifacts into structured data
3. User chooses which Modules to run and output format

Example workflow:

Target: Windows/WindowsDefender.tkape
  ↓ Collects: Defender logs and event files
  ↓
Module: Windows/Windows_EventLogs_Defender.mkape
  ↓ Parses: Event log files with EvtxECmd
  ↓
Output: parsed_output/EventLogs/Defender.csv

Resources

• Full KAPE Module Documentation
• KAPE GitHub Repository
• EvtxECmd Documentation
• Eric Zimmerman's Tools

Tools and Commands

Generate a GUID for New Modules

kape.exe --guid

Test Module Locally

1. Place parsed tool output in a test directory
2. Create Module with test command
3. Run with: kape.exe --module module_name --msource test_dir --mdest output_dir
4. Verify output format and content

Common KAPE Module Tools

• EvtxECmd: Parse Windows Event Logs
• RECmd: Parse Windows Registry hives
• SQLECmd: Parse SQLite databases
• JLECmd: Parse Jump List artifacts
• MFTECmd: Parse MFT records
• ShellBagsExplorer: Shell Bag analysis
• AmcacheParser: Amcache hive parsing
• AppCompatCacheParser: AppCompatCache parsing

Executable Best Practices

Organizing Binaries

.\KAPE\Modules\bin\
  ├── EvtxECmd.exe
  ├── RECmd.exe
  ├── YourTool\
  │   ├── tool.exe
  │   └── dependency.dll

Executable Path Reference

• Root binary: Executable: YourTool.exe
• In subfolder: Executable: YourTool\tool.exe
• System PATH: Executable: system_tool.exe

PowerShell Execution

Always use full path for PowerShell:

Executable: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe

Or on PowerShell 6+:

Executable: C:\Program Files\PowerShell\7\pwsh.exe