hackbox — a portable, self-contained pentest/red-team toolkit

Clone it, source it, hack. The python env, native binaries, and tool config are kept inside the repo instead of scattered across your machine, so your setup is reproducible and easy to wipe by deleting the folder.

git clone <your-remote> hackbox && cd hackbox
source activate           # first run sets everything up; later runs are instant
nuclei -version           # tools are just on PATH
deactivate                # leave

Scope — read this first

hackbox runs on your operator machine (your laptop, a jump box, a cloud VM), not on a target. It is a portable toolbox, not an anti-forensics or "leave no trace on the victim" tool.

"Self-contained" means best-effort containment of your own setup, so tools don't pollute your $HOME and your kit stays reproducible — not a guarantee of zero footprint:

• activate redirects the config/creds of the tools it knows about (aws, gcloud, gau, powershell, uv) into the repo. Other tools, and anything you install into the venv, may still write to $HOME, $TMPDIR, system keychains, or leave logs/caches elsewhere on the operator host.
• Running a tool still produces normal artifacts on the target (auth logs, web/WAF logs, process history, files you drop, etc.). Containing your config does nothing about that. OPSEC on an engagement is a separate discipline.
• Only use these tools against systems you are authorized to test.

The one command

source activate does the whole setup and is idempotent:

1. fetches uv (a single static binary) into .tools/bin/
2. runs uv sync → builds .venv/ with the python tools from pyproject.toml (uv even downloads its own Python — no system python3 needed)
3. downloads the native binaries (nuclei, httpx, gcloud, …) into .tools/
4. puts .tools/bin and .venv/bin on PATH

First run downloads; a marker (.tools/.synced) makes every later source activate instant. source activate again after editing pyproject.toml just reconciles python deps.

Why native binaries aren't part of uv sync

uv sync manages Python packages only. Tools like nuclei/httpx/gau (Go), jadx (Java), gcloud/aws/pwsh/nmap/radare2/ipsw are compiled native binaries — not pip-installable, and not committable to git portably (a mac-arm64 binary won't run on linux-x64). So they're fetched per machine into .tools/ (git- ignored). That fetch is folded into activate, so you still only run one command.

Layout

hackbox/
├── activate            # source this (bash/zsh)          ← the entry point
├── activate.ps1        # dot-source this (native Windows)
├── pyproject.toml      # python tools (uv sync)   + uv.lock (commit it)
├── versions.env        # pinned native-tool versions
├── bootstrap.sh        # `hackbox` CLI: explicit fetch/update (optional)
├── lib/                # common.sh · recipes.sh · engine.sh
├── vendor/             # tools YOU supply: jeb, CRTE kit, PowerShell modules
├── .venv/   (ignored)  # uv-managed python env
├── .tools/  (ignored)  # native binaries + uv's python/cache
└── state/   (ignored)  # tool config + credentials, contained in-repo

Managing tools

Inside an active shell the hackbox command wraps the fetcher:

hackbox --list            # everything available on this platform
hackbox nuclei httpx      # (re)fetch specific native tools
hackbox android           # a group: android/ios, extra, manual
hackbox --force gau       # re-fetch
hackbox --python --group ad   # uv sync with an optional python bundle

What's covered

Area	Auto-installed	Notes
Web / cloud	nuclei, httpx, gau, sqlmap, mitmproxy, gcloud, aws-cli	nmap: no clean static build everywhere — manual/system
Android / iOS	jadx (+repo-local JRE), ipsw, radare2	radare2 builds from source (needs cc/make)
Windows / AD	pwsh (PowerShell 7)	AD modules + your CRTE kit → vendor/psmodules/ (see vendor/README.md)
Python	impacket + opt-in groups	pyproject.toml; `hackbox --python --group <ad
Licensed	—	jeb → drop into vendor/jeb/
Apple-only	—	otool/plutil are macOS system tools; on Linux use ipsw/radare2

Credentials stay in the repo

activate points aws, gcloud, and friends at state/ (AWS_CONFIG_FILE, CLOUDSDK_CONFIG, …) instead of $HOME, so engagement creds travel with the clone and never leak into the host's global config. state/ is git-ignored — do not commit it if it holds secrets.

Adding a tool

• Python: add it to pyproject.toml, run hackbox --python (or re-source activate).
• Native: copy a recipe_<name> in lib/recipes.sh, add it to a HB_GROUP_*, pin a version in versions.env. A recipe downloads/extracts into .tools/pkg/<tool>/ and calls hb_link <binary> <name>.

Windows

Native Windows can't source bash — dot-source activate.ps1 (handles uv sync + PowerShell/AD modules + cloud config). For the auto-downloaded native binary set, easiest is WSL + ./activate.