Metadata-Version: 2.4
Name: kp-analysis-toolkit
Version: 2.0.0
Summary: Python utilities to parse technical information for security audits
Author-email: Randy Bartels <rjbartels@outlook.com>
Project-URL: Homepage, https://github.com/kirkpatrickprice/analysis-toolkit
Project-URL: Issues, https://github.com/kirkpatrickprice/analysis-toolkit/issues
Keywords: pii discovery,data discovery,credit card discovery
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Requires-Python: <4,>=3.12
Description-Content-Type: text/markdown
Requires-Dist: charset-normalizer>=3.4.0
Requires-Dist: click>=8.1.8
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: packaging>=21.0
Requires-Dist: pandas>=1.5.1
Requires-Dist: pydantic>=2.11.5
Requires-Dist: pyyaml>=6.0
Requires-Dist: striprtf>=0.0.26
Provides-Extra: dev
Requires-Dist: pytest>=8.3.5; extra == "dev"

# 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](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](src/kp_analysis_toolkit/process_scripts/README.md)**

### 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](src/kp_analysis_toolkit/nipper_expander/README.md)**

### 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](src/kp_analysis_toolkit/rtf_to_text/README.md)**

## Requirements

### System Requirements
The toolkit is built on Python and supports cross-platform operation:
- **Primary development platform**: Windows
- **Supported platforms**: Windows, macOS, Linux

### 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

### Installing pipx

**Windows and other platforms:**
```powershell
pip install pipx
```

**Ubuntu and Debian-based systems:**
```bash
sudo apt install pipx
```

### Installing the Toolkit

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

**Windows PowerShell:**
```powershell
pip install pipx
pipx ensurepath
# Restart PowerShell to update PATH
pipx install kp-analysis-toolkit
```

**Linux/macOS:**
```bash
# 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, you'll be prompted to upgrade:

```
📦 Update available: 2.0.0 → 2.0.1
Current version: 2.0.0
Latest version:  2.0.1

Would you like to upgrade now? [y/N]:
```

**Upgrade Process:**
- The toolkit uses `pipx` to upgrade automatically
- After successful upgrade, the application restarts with the new version
- If upgrade fails (e.g. no Internet connection), you'll see an error message and can continue with the current version

### Manual Updates
Update manually using `pipx`:
```bash
pipx upgrade kp-analysis-toolkit
```

### Disabling Update Checks
Skip update checks for automated scripts:
```bash
kpat_cli --skip-update-check scripts --help
```

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

## 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

### 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

## 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.
