kp-analysis-toolkit 2.1.0
Python utilities to parse technical information for security audits
Requires Python: <4,>=3.12
Keywords: pii discovery, data discovery, credit card discovery

# 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.

[View the full documentation](https://kirkpatrickprice.github.io/analysis-toolkit)

## 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](https://github.com/kirkpatrickprice/linux-audit-scripts)
- [Windows Audit Scripts](https://github.com/kirkpatrickprice/windows-audit-scripts)
- [MacOS Auditor](https://github.com/kirkpatrickprice/macos-auditor)

📖 **[View Process Scripts Documentation](https://kirkpatrickprice.github.io/analysis-toolkit/user-guides/scripts/)**

### 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](https://kirkpatrickprice.github.io/analysis-toolkit/user-guides/nipper-expander/)**

### 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](https://kirkpatrickprice.github.io/analysis-toolkit/user-guides/nipper-expander/)**

## 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](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701) from the Microsoft Store for a better command-line experience.

## Installation

See the [full installation instructions](https://kirkpatrickprice.github.io/analysis-toolkit/user-guides/installation)

## 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`:
```bash
pipx upgrade kp-analysis-toolkit
```

### Disabling Update Checks
Skip update checks for automated scripts or when you don't want to be prompted:
```bash
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:

```bash
# 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.

```bash
# 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:**
```bash
# Analyze files with default configuration
kpat_cli scripts

# Use specific configuration
kpat_cli scripts --conf audit-windows.yaml
```

**Nipper Expander:**
```bash
# Auto-detect CSV files in current directory
kpat_cli nipper

# Process specific file
kpat_cli nipper --in-file network-audit.csv
```

**RTF Converter:**
```bash
# 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](src/kp_analysis_toolkit/process_scripts/README.md)** - Comprehensive analysis of OS audit data
- **[Nipper Expander](src/kp_analysis_toolkit/nipper_expander/README.md)** - Network device vulnerability report processing
- **[RTF to Text](src/kp_analysis_toolkit/rtf_to_text/README.md)** - 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:

```bash
# 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](.github/PYPI_SETUP.md)** for maintainers

## Related Projects

- [Linux Audit Scripts](https://github.com/kirkpatrickprice/linux-audit-scripts) - Data collection for Linux systems
- [Windows Audit Scripts](https://github.com/kirkpatrickprice/windows-audit-scripts) - Data collection for Windows systems
- [macOS Auditor](https://github.com/kirkpatrickprice/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](CHANGELOG.md) for version history

## Version History

See [CHANGELOG.md](CHANGELOG.md) for a complete history of changes starting with version 2.0.0.