v2.0.0Apache 2.0

RabbitHole

Universal Cybersecurity Environment Installer / Provisioning Framework

Role-based. Opinionated. Production-Ready. Modular.

Project Overview

RabbitHole provisions combat-ready cybersecurity environments in minutes. Originally a single-file Bash installer, it has evolved into a modular, extensible Cybersecurity Environment Provisioning Framework with a plugin system, state management, rollback, supply-chain security, and full CLI tooling.

Operational Roles

Config Profiles

CLI Commands

50+

Test Cases

Distro Agnostic — Auto-detects Debian/Kali/Ubuntu/Parrot, Fedora, Arch/Manjaro.

Plugin Architecture — Roles are defined as YAML manifests under roles/. Add a new role by creating a directory with plugin.yaml — no code changes needed.

State Management — Tracks installed roles, tools, versions, and dates in ~/.rabbithole/state.json. Supports verify, doctor, snapshot, restore.

Resume Capability — If installation is interrupted (power loss, Ctrl+C, network failure), re-running resumes from the last successful package.

Supply Chain Security — SHA256 verification, pinned versions, secure auto-generated Docker credentials.

Rollback — rabbithole remove <role> cleans packages, symlinks, pipx apps, Go binaries, Git repos, and Docker resources.

Operational Roles

RabbitHole organizes tools into strictly defined operational roles. Install multiple roles simultaneously.

OSINT Analyst

Deep dive information gathering and reconnaissance.

Stack: amass, theHarvester, maltego, spiderfoot, sherlock, maigret, holehe, social-analyzer, shodan, censys

Bug Bounty Hunter

Web application reconnaissance and vulnerability scanning.

Stack: nuclei, katana, gau, ffuf, burpsuite, sqlmap, dalfox, xsstrike, dirsearch, arjun

Pentester

Standard network and infrastructure assessment toolkit.

Stack: nmap, masscan, rustscan, impacket, bloodhound, crackmapexec, hashcat, john, seclists

Red Team Operator

RESTRICTED USE. Advanced C2 and adversary emulation.

Stack: metasploit, sliver, empire, HunterX, ligolo-ng, chisel, ansible, terraform, donut, scarecrow

Blue Team / SOC Analyst

Defense, monitoring, and log analysis.

Stack: wazuh-agent, osquery, velociraptor, sigma-cli, chainsaw, hayabusa, thehive, cortex

DFIR Analyst

Digital Forensics and Incident Response.

Stack: volatility3, autopsy, sleuthkit, plaso, timesketch, yara, ghidra, radare2, capa

Threat Intelligence Analyst

Threat data platforms and intelligence tools.

Stack: misp, opencti, yeti, intelmq, threatfox, virustotal-cli, otx-cli

Architecture

RabbitHole/
├── rabbithole.sh         # Legacy single-file installer (unchanged)
├── bin/
│   └── rabbithole        # New framework entrypoint
├── lib/
│   ├── logging.sh        # Structured & colored logging
│   ├── package_manager.sh # OS detection & base dependency installation
│   ├── helpers.sh        # Native/Go/pipx/Git/Cargo/wget install helpers
│   ├── docker.sh         # Docker Compose stack management
│   ├── plugins.sh        # Plugin discovery & YAML parsing
│   ├── state.sh          # State management (~/.rabbithole/state.json)
│   ├── dependency.sh     # Dependency resolution & tracking
│   └── security.sh       # Secure credential generation & checksums
├── roles/
│   ├── osint/            # OSINT Analyst plugin
│   ├── bugbounty/        # Bug Bounty Hunter plugin
│   ├── pentest/          # Pentester plugin
│   ├── redteam/          # Red Team Operator plugin
│   ├── soc/              # Blue Team / SOC plugin
│   ├── dfir/             # DFIR Analyst plugin
│   └── threatintel/      # Threat Intelligence Analyst plugin
├── config/
│   ├── settings.conf     # User configuration
│   └── rabbit.lock       # Version lock file
├── plugins/              # User/custom plugin directory
├── cache/                # Download cache
├── logs/                 # Log files
├── state/                # State files
├── tests/                # Automated tests (50+ test cases)
├── AGENTS.md             # Developer guide for AI agents and contributors
└── .github/workflows/    # CI/CD (ShellCheck, YAML lint, manifest validation)

CLI Commands

Command	Description
rabbithole	Interactive role-based installer
rabbithole install <role>	Install specific role(s)
rabbithole remove <role>	Remove specific role(s)
rabbithole status	Show installation status
rabbithole verify	Verify installed tools and dependencies
rabbithole doctor	Comprehensive health check
rabbithole update	Update installed tools
rabbithole snapshot	Export state snapshot to JSON
rabbithole restore <file>	Restore state from snapshot
rabbithole cache build\|clean	Manage download cache
rabbithole benchmark	Run system benchmarks
rabbithole --dry-run	Preview without installing
rabbithole --version	Show version
rabbithole --help	Show help

Supply Chain Security

SHA256 checksum verification for downloaded binaries via verify_sha256()

Pinned versions in Docker Compose images — no :latest except where unavoidable

Secure credential generation via openssl rand -base64 with configurable length and character sets

.env files created with chmod 600 — not world-readable

No hardcoded passwords — OpenCTI, MISP, MinIO, RabbitMQ, and Elasticsearch credentials are all auto-generated

Pinned Git tags and commits supported in plugin manifests for reproducible builds

eval avoidance — commands use explicit argument passing; custom commands are opt-in only

Safe path handling — sanitize_path_component() strips dangerous characters from user-provided paths

Infrastructure & Docker Profiles

Production-grade infrastructure stack using Docker Compose for Threat Intelligence deployments.

misp

Malware Information Sharing Platform

Services: misp-core, misp-db

opencti

Open Cyber Threat Intelligence Platform

Services: opencti, elasticsearch, redis, minio, rabbitmq

Management

cd /opt/rabbithole/infra/threat-intel docker compose --profile misp --profile opencti up -d docker compose --profile opencti up -d

All credentials are auto-generated with openssl rand and stored in a 600-permission .env file. No hardcoded passwords.

Configuration Profiles

minimal

Core tools only

research

OSINT + DFIR + Threat Intel

lab

Full lab environment

redteam

Offensive toolkit

blueteam

Defensive toolkit

enterprise

Production-grade deployment

Installation

New Framework

# Clone the repository
git clone https://github.com/NullC0d3/rabbithole.git
cd rabbithole
chmod +x bin/rabbithole
sudo ./bin/rabbithole

Legacy Installer

sudo ./rabbithole.sh

The original single-file installer remains fully functional and unchanged.

Plugin Development

Adding a new role is as simple as creating a directory with a plugin.yaml manifest.

name: "My Custom Role"
description: "Description of my custom role"
version: "1.0.0"
author: "Your Name"
warning: false
docker: false

native:
  - "toolname/pkgname/pkgname"

go:
  - "toolname github.com/user/toolname@latest"

pipx:
  - "toolname pip-package-name"

git:
  - "toolname https://github.com/user/toolname.git"

cargo:
  - "toolname crate-name"

wget:
  - "toolname https://example.com/toolname-linux-amd64"

custom:
  - "echo 'Custom install command'"

Place your plugin in either roles/ (built-in) or plugins/ (user/custom). The framework discovers plugins automatically.

Testing

# Run the full test suite ./tests/test_runner.sh # Run with verbose output ./tests/test_runner.sh -v

Directory structure integrity

Library module function exports

Plugin manifest validation (all 7 roles)

YAML parsing (name, description, version, author fields)

State management (create, record, read, remove)

Helper function existence and signatures

Security module output verification

Configuration file presence

Project Roadmap

Current Work

Continuous expansion of OSINT, Blue Team, and DFIR capabilities
Integration with MISP and OpenCTI platforms
Enhanced state management and snapshot/restore functionality
Supply chain security improvements with SHA256 verification

Near-Term Goals

Community plugin marketplace with versioning
Cross-platform compatibility improvements
Performance optimization for large-scale deployments
Enhanced Docker Compose infrastructure

Long-Term Vision

Enterprise-grade deployment with role-based access control
AI-assisted role recommendation and optimization
Integration with cloud security platforms
Comprehensive security testing automation

State & Lock Files

State File: ~/.rabbithole/state.json

Framework version
Installed roles with timestamps
Installed tools with method, source, version, exit code
Docker services

Snapshot & Restore

# Export full environment state rabbithole snapshot > ~/rabbithole-backup-$(date +%Y%m%d).json # Restore on a different machine rabbithole restore ~/rabbithole-backup-20260727.json

Lock file: config/rabbit.lock pins tool versions for reproducible installations.

Get Started with RabbitHole

Follow the white rabbit.

GitHub Docker