kp-analysis-toolkit 2.0.6

Python utilities to parse technical information for security audits

KP Analysis Toolkit

The KP Analysis Toolkit is a comprehensive Python application designed to assist auditors with analyzing and processing various types of data encountered during security assessments. The toolkit provides specialized modules for different data formats and analysis tasks.

Overview

The toolkit currently includes three main modules:

Process Scripts

Formerly known as adv-searchfor, this module processes text files generated by KirkpatrickPrice's OS-specific collection scripts. It provides flexible search capabilities, automated analysis, and comprehensive reporting through Excel workbooks.

Supported Collection Scripts:

• Linux Audit Scripts
• Windows Audit Scripts
• MacOS Auditor

📖 View Process Scripts Documentation

Nipper Expander

A specialized tool for processing Nipper CSV export files. It transforms Nipper's compact CSV format (where multiple devices may be listed in a single row) into an expanded format with one row per device per finding, making it easier to analyze vulnerabilities using Excel pivot tables and other analysis tools.

📖 View Nipper Expander Documentation

RTF to Text Converter

Converts Rich Text Format (RTF) files to plain text files using ASCII encoding. This is particularly useful when customers provide router/firewall configurations as RTF documents instead of plaintext files.

📖 View RTF Converter Documentation

Requirements

System Requirements

The toolkit is built on Python and supports cross-platform operation:

• Primary development platform: Windows
• Supported platforms: Windows, macOS, Linux
• Testing coverage: All platforms tested via CI/CD pipeline

Prerequisites

• Python 3.12 or higher
• pipx (Python application installer)

Recommended Tools

For Windows users, we recommend using the Windows Terminal from the Microsoft Store for a better command-line experience.

Installation

Installing pipx

Windows and other platforms:

pip install pipx

Ubuntu and Debian-based systems:

sudo apt install pipx

Installing the Toolkit

The toolkit is distributed via PyPI and can be installed using pipx:

Windows PowerShell:

pip install pipx
pipx ensurepath
# Restart PowerShell to update PATH
pipx install kp-analysis-toolkit

Linux/macOS:

# Install pipx (if not already installed via package manager)
sudo apt install pipx  # or use the package manager appropriate to your OS (e.g. brew)
pipx ensurepath
# Restart terminal to update PATH
pipx install kp-analysis-toolkit

Updates

Automatic Update Checking

Starting with version 2.0, the toolkit automatically checks for updates on PyPI each time you run it. If a newer version is available, the toolkit will display upgrade instructions and exit:

📦 Update Available

┌─ Upgrade Instructions ──────────────────────────────────┐
│ Current version: 2.0.0                                  │
│ Latest version:  2.0.1                                  │
│                                                         │
│ To upgrade, run:                                        │
│ pipx upgrade kp-analysis-toolkit                        │
│                                                         │
│ Or if you want to skip this check in the future:        │
│ kpat_cli --skip-update-check                            │
└─────────────────────────────────────────────────────────┘

The application will now exit. Please run the upgrade command above 
and then run your command again.

Note: Upgrade checks can be disabled using the --skip-update-check option.

Why does the toolkit exit instead of upgrading automatically?

• File locking: When Python applications upgrade themselves while running, file locks can cause upgrade failures
• Reliability: Manual upgrades using pipx upgrade are more reliable and consistent
• User control: You have full control over when and how upgrades happen
• Error handling: pipx provides better error messages and troubleshooting information

Manual Updates

Update manually using pipx:

pipx upgrade kp-analysis-toolkit

Disabling Update Checks

Skip update checks for automated scripts or when you don't want to be prompted:

kpat_cli --skip-update-check scripts --help

Note: Update checking requires a network connection. Without network access, you may see a brief warning but the program continues normally.

Keep-Awake Feature

The toolkit includes an automatic keep-awake feature that prevents your system from going to sleep during long-running analysis tasks. This is particularly useful when processing large datasets or running extensive searches that might take a long time to complete.

How It Works

• Automatic: The keep-awake feature is enabled by default for all commands
• Cross-platform: Works on Windows, macOS, and Linux systems
• Non-intrusive: Only prevents sleep/hibernation, doesn't affect screen savers or manual power management
• Fallback protection: If the keep-awake feature fails (e.g., due to permissions), the command continues normally, but your system could sleep mid-task

Disabling Keep-Awake

You can disable the keep-awake feature if needed:

# Disable keep-awake for a single command
kpat_cli --no-keep-awake scripts --start-dir /path/to/data

# Example: Long-running analysis without keep-awake
kpat_cli --no-keep-awake scripts --start-dir "C:\Audit\Data"

When you might want to disable it:

• Running on battery power and want to allow normal power management
• Running in automated scripts where sleep prevention isn't needed
• System policy restrictions that prevent sleep control
• Troubleshooting power management issues

Usage

Getting Started

After installation, the toolkit is available as kpat_cli (or kpat_cli.exe on Windows):

Note: Aliases are provided for legacy commands (e.g. adv-searchfor). They will be deprecated in a later version.

# Show main help
kpat_cli --help

# Show help for specific modules
kpat_cli scripts --help
kpat_cli nipper --help
kpat_cli rtf-to-text --help

Quick Examples

Process Scripts:

# Analyze files with default configuration
kpat_cli scripts

# Use specific configuration
kpat_cli scripts --conf audit-windows.yaml

Nipper Expander:

# Auto-detect CSV files in current directory
kpat_cli nipper

# Process specific file
kpat_cli nipper --in-file network-audit.csv

RTF Converter:

# Convert specific RTF file
kpat_cli rtf-to-text --in-file config.rtf

# Scan directory for RTF files
kpat_cli rtf-to-text --start-dir /path/to/files

Module Documentation

For detailed usage instructions, configuration options, and examples for each module:

• Process Scripts - Comprehensive analysis of OS audit data
• Nipper Expander - Network device vulnerability report processing
• RTF to Text - Document format conversion utilities

Development

Development Environment

• Primary development platform: Windows
• Testing: Comprehensive CI testing on Windows, macOS, and Linux
• Cross-platform compatibility: Ensured through automated testing

While development is primarily conducted on Windows, the toolkit is designed to be cross-platform compatible. Continuous Integration (CI) testing is performed against all three major operating systems (Windows, macOS, and Linux) to ensure proper functionality across platforms.

Running from Source

For development or testing purposes:

# Clone the repository
git clone https://github.com/kirkpatrickprice/analysis-toolkit.git
cd analysis-toolkit

# Install with uv (recommended)
uv sync

# Or install with pip
pip install -e .

# Run directly
python -m kp_analysis_toolkit.cli --help

Dependencies

The toolkit automatically installs required dependencies:

• pandas and openpyxl for Excel processing
• PyYAML for configuration files
• click for command-line interface
• pydantic for data validation
• charset-normalizer for encoding detection
• striprtf for RTF processing

Publishing and Releases

The toolkit uses automated publishing to PyPI:

• Cross-platform testing: Full test suite runs on Windows, macOS, and Linux before publishing
• Automatic publishing: When the version in src/kp_analysis_toolkit/__init__.py is updated and pushed to the main branch
• GitHub Actions: Handles testing, building, and publishing automatically
• GitHub Releases: Automatically created with version tags and changelogs
• Quality assurance: Cross-platform tests must pass before publishing

📖 View Publishing Setup Guide for maintainers

Related Projects

• Linux Audit Scripts - Data collection for Linux systems
• Windows Audit Scripts - Data collection for Windows systems
• macOS Auditor - Data collection for macOS systems

Support

For issues, feature requests, or questions:

• Check the module-specific documentation linked above
• Review troubleshooting sections in individual module READMEs
• Consult the CHANGELOG.md for version history

Version History

See CHANGELOG.md for a complete history of changes starting with version 2.0.0.