Installation Guide¶

This guide walks you through installing SSF Tools using pipx, the recommended method for installing Python applications that provide command-line tools.

What is pipx?¶

pipx installs Python applications in isolated environments while making their CLI commands available globally. This prevents dependency conflicts and keeps your system Python clean.

Additional information on pipx

Prerequisites¶

Python 3.13 or higher
Internet connection for downloading packages

Platform-Specific Installation¶

This section provides: 1. Detailed instructions for installing pipx for popular operating systems 2. Using pipx install to install the SSF Tools package from PyPI

If you already have pipx installed, you can skip directly to Install SSF Tools.

Windows¶

Install Python (if not already installed)¶

Download Python 3.13+ from python.org
Run the installer and check "Add Python to PATH"
Verify installation:

python --version

Install pipx¶

# Install pipx using pip
python -m pip install --user pipx

# Add pipx binary directory to PATH
python -m pipx ensurepath

Restart your PowerShell session to apply PATH changes.

Verify pipx installation¶

pipx --version

Skip to Install SSF Tools

macOS¶

Install Python (if not already installed)¶

Using Homebrew (recommended):

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python@3.13

Alternatively, download from python.org.

Install pipx¶

Using Homebrew (recommended):

brew install pipx
pipx ensurepath

Using pip:

python3 -m pip install --user pipx
python3 -m pipx ensurepath

Verify pipx installation¶

pipx --version

Skip to Install SSF Tools

Linux¶

Ubuntu/Debian¶

# Update package list
sudo apt update

# Install Python 3.13 and pipx
sudo apt install python3.13 python3.13-venv pipx

# Ensure pipx is in PATH
pipx ensurepath

Skip to Install SSF Tools

Alternative: Install pipx using pip¶

If pipx is not available in your distribution's package manager:

python3 -m pip install --user pipx
python3 -m pipx ensurepath

Verify pipx installation¶

pipx --version

Install SSF Tools¶

Once pipx is installed on your platform, install SSF Tools:

pipx install kp-ssf-tools

Verify Installation¶

Confirm SSF Tools is installed correctly:

ssf_tools --version
ssf_tools --help

You should see the version information and available commands.

Quick Start¶

Test your installation with a simple command:

# View available analysis commands
ssf_tools analyze --help

# Check configuration
ssf_tools config --help

Upgrade SSF Tools¶

Use pipx to update to the latest version:

pipx upgrade kp-ssf-tools

Uninstall SSF Tools¶

To remove SSF Tools:

pipx uninstall kp-ssf-tools

Troubleshooting¶

Command not found¶

If ssf_tools command is not recognized after installation:

Check if pipx binary directory is in your PATH:
```
pipx ensurepath
```
Restart your terminal session

Permission errors during installation¶

On Linux/macOS, if you encounter permission errors:

# Don't use sudo with pipx - install in user space
pipx install kp-ssf-tools --user

Python version conflicts¶

If you have multiple Python versions:

Specify the Python version for pipx:

# Linux/macOS
python3.13 -m pipx install kp-ssf-tools

# Windows
py -3.13 -m pipx install kp-ssf-tools

Network connectivity issues¶

If installation fails due to network issues:

Check your internet connection

Try installing with increased timeout:

pipx install kp-ssf-tools --pip-args="--timeout 300"

If behind a corporate firewall, configure pip with your proxy settings

Development Installation¶

For development or contributing to SSF Tools:

# Clone the repository
git clone https://github.com/kirkpatrickprice/ssf-tools.git
cd ssf-tools

# Use uv
uv sync --extra docs --dev

# Serve the documentation
uv run mkdocs serve

# Run ssf_tools
uv run ssf_tools --help

Next Steps¶

Configuration Guide - Set up SSF Tools for your environment
CLI Overview - Learn about available commands
Analyze Credentials - Start analyzing files for credentials
Analyze Entropy - Detect high-entropy regions in files

Getting Help¶

If you encounter issues not covered in this guide:

Check the troubleshooting section above
Review the CLI Overview for command usage
Visit the GitHub Issues page
Consult the API documentation for technical details