Analysis Toolkit User Guide¶

Overview¶

The KP Analysis Toolkit (KPAT) is a collection of tools for working with the data we collect in our audits. Currently, this includes the following:

scripts -- Working with the kpmacaudit, kpnixaudit and kpwinaudit system configuration collection scripts
rtf-to-text -- Converting RTF-formatted files to plain text
nipper -- Reformat Nipper CSV result files into a more usable format

Each of these tools are presented in their own user guide page.

Prerequisites¶

System Requirements¶

Windows 10 or later (recommended: Windows 11)
PowerShell 5.1 or later
Python 3.14 or later
KP Analysis Toolkit installed (see Installation Guide)
Windows Terminal (recommended) as a replacement for the legacy Windows Console terminal

Getting Started¶

kpat_cli is a command line tool, so you'll spend time at the command prompt (Powershell for Windows and Bash for Linux/MacOS). If you neeed a refresher, some PowerShell basics are presented below

PowerShell Basics¶

Open the Command Prompt

Run Windows Terminal from your Start Menu.

If Windows Terminal isn't installed, you can start Powershell directly.

# Powershell starts in your home folder
PS C:\Users\YourNameHere> # Awaiting your next command

# Change to a new folder
cd "Downloads\Customers\Project Name"

# Change to a new disk drive (N/A probably for KP laptops)
D:

# Change back to the C drive
C:

See the PowerShell Primer for additional help on getting started with PowerShell.

Running `kpat_cli`¶

After installation, the kpat_cli command will be available. Test it by displaying the help page.

kpat_cli --help

KPAT Help

Working with Files¶

KPAT is built around working with files and folders. Each tool receives input file(s), transforms it, and produces output files.

flowchart LR A[Input Data Files] --> B[KPAT Command] B --> C[Result Files]

See the PowerShell Primer for additional help on getting started with PowerShell.

Advanced Options¶

Automatic Updates¶

The toolkit will automatically check for an upgrade each time you run it. If an update is found, it will provide instructions for how to upgrade and immediately exit

Upgrade Notice

You can override this check by including --skip-update-check on the command line

# Skip the upgdate check
kpat_cli --skip-update-check scripts

Configuration¶

Each command comes with its own options that you can use to alter the default behavior. Use the --help pages to see what those options are:

# Options for script result processing
kpat_cli scripts --help

# Options for RTF-to-Text conversion
kpat_cli rtf-to-text --help

# Options for Nipper results expansion
kpat_cli nipper --help

Troubleshooting¶

Common Issues¶

Command not found¶

Symptoms: Powershell or Bash reports that it cannot find the kpat_cli command

Solutions:

Reinstate the uv system path variable with uv tool update-shell
Restart your Terminal session
Check that KPAT is intalled with

# Check for uv-managed programs
uv tool list

UV Tool List

Slow Performance¶

Symptoms: Very slow performance in WSL

Solutions:

Don't use WSL to access files from your Windows partition (e.g. through /mnt/c/users/YourUserName/...). This isn't a KPAT limitation, but is a known problem with WSL accessing Windows files
Install the toolkit in Windows -- see installation instructions

Getting Help¶

An extensive help system is built into the tool and is invoked by appending --help to any command.

Top-Level Help

kpat_cli [module] --help

Examples and Use Cases¶

Example 1: Process results from one of the collector scripts¶

Use Case: Customer has returned their script results based on the sample chosen by the auditor

Steps:

Unzip and organize the files into the most meaningful arrangement based on your project. For example, create folders for:
- Different operating systems
- Function group such as "Workstations", "Developers" or "HR"
Launch Windows Terminal

Change to your project folder and run kpat_cli

# Change to scripts folder
cd "Downloads\Customers\Acme Corp\scripts"

# Run kpat_cli
kpat_cli scripts

Review the results