Installation

Requirements

  • Python 3.10 or higher

  • pip package manager

  • Virtual environment (recommended)

Installation from PyPI

Create and activate a virtual environment (recommended):

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

The recommended way to install HiveTraceRed is via pip:

pip install hivetracered

This will install the package and make the following CLI commands available:

  • hivetracered - Main CLI for running attack pipelines

  • hivetracered-report - Generate HTML reports from results

Note

The hivetracered-recorder command for recording browser interactions requires the web extras: pip install 'hivetracered[web]'

Optional Dependencies

Install with optional dependencies for development, documentation, or web-based model testing:

# For web-based model testing (browser automation, required for hivetracered-recorder)
pip install 'hivetracered[web]'

# For development (includes build tools)
pip install 'hivetracered[dev]'

# For building documentation
pip install 'hivetracered[docs]'

# Install everything
pip install 'hivetracered[all]'

Development Installation

If you want to contribute to HiveTraceRed or modify the source code, install from source:

Clone the repository:

git clone https://github.com/HiveTrace/HiveTraceRed.git
cd HiveTraceRed

Install in editable mode with development dependencies:

pip install -e '.[dev]'

Build Documentation Locally

If you want to build the documentation:

pip install -e '.[docs]'
cd docs
make html

Environment Setup

Create a .env file in the project root with your API keys:

cp .env.template .env

Edit .env and add your API credentials:

# OpenAI
OPENAI_API_KEY=your_openai_api_key_here

# GigaChat
GIGACHAT_CREDENTIALS=your_gigachat_credentials_here

# Yandex Cloud
YANDEX_FOLDER_ID=your_folder_id
YANDEX_API_KEY=your_api_key

# Google Gemini
GOOGLE_API_KEY=your_google_api_key_here

Note

You only need to configure API keys for the LLM providers you plan to use.

Next Steps

Quickstart - API-based Testing - Run your first test with cloud APIs

Quickstart - On-Premise Testing - Run your first test on-premise with Ollama