README

AI-guided, all-in-one toolkit for authorized security testing

215 curated tools across 21 categories — recon, OSINT, web, wireless, phishing, forensics, post-exploitation and more — with an AI layer that turns plain English into the right tool and the exact command.

Built for penetration testers · red teamers · blue-team/SOC and DFIR analysts · OSINT researchers · bug-bounty hunters · CTF players · security researchers and students — all working legally, on systems they own or are authorised to test.

<a href="https://trendshift.io/repositories/869" target="_blank" rel="noopener noreferrer"></a> <a href="https://trendshift.io/repositories/869" target="_blank" rel="noopener noreferrer"></a> <a href="https://trendshift.io/repositories/869" target="_blank" rel="noopener noreferrer"></a>

<a href="#installation"></a>  <a href="docs/HOW-TO-USE.md"></a>  <a href="docs/TOOLS.md"></a>  <a href="#support--sponsor"></a>

Contents

• Why hackingtool
• Tool Categories
• Installation
  • From source with pipx (recommended)
  • For development
  • Docker
  • Optional runtimes
• Quick Commands
  • Command reference
• Features
  • 🔎 /find — a tool for a need you don't have yet
  • 🎯 /goal — plan an objective, run it one step at a time
  • 🧠 Recommendations — say what you want in plain English
  • 🏷 Tags and search
  • ▶ Background panes (tmux)
  • ⚙ Settings and the AI layer
  • 📋 Headless engagements
• Documentation
• Contributing
• Support & Sponsor
• Social

Why hackingtool

• 🧠 AI-guided workflow — describe what you want ("find subdomains of example.com") and it maps your intent to the right tools, hands you the exact documented command, plans an objective step by step, then summarizes findings and drafts an engagement report. Bring your own key or run a local model — nothing auto-executes and nothing is fabricated.
• 🗂 215 curated tools, one console — install and run across 21 categories without hunting down Git repos; a fixed tag taxonomy (63 tags in use) makes every tool discoverable.
• 🔎 It knows what it doesn't have — /find searches your catalog first, then the GitHub API, and shows real maintained projects with the reason each was ranked.
• 🛡 Safe by default — standard installs, no curl | bash, downloads pinned + SHA-256 verified, list-form subprocess, no forced sudo, and signed releases with an SBOM.
• 🎯 For the whole spectrum — red team, blue team, OSINT, bug bounty, CTF/THM, forensics/IR — all on authorized targets only.

_{The console on launch — live system readout, and <code>/</code> opens the command palette.}

Tool Categories

215 tools across 21 categories — the full list, with links and tags, is in docs/TOOLS.md.

_{59 further entries are archived (unmaintained or dead upstream) and hidden unless you set show_archived true via /config. The in-app header counts 22 categories / 217 tools because it also counts the built-in Update / Uninstall menu.}

Installation

Requires Python 3.10+ on Linux or macOS (Kali, Parrot, Debian/Ubuntu, Arch, …). Windows is not supported — the app tells you so and exits. No curl | bash: every path below is a standard, verifiable install.

From source with pipx (recommended)

pipx installs hackingtool into its own isolated environment and puts the hackingtool command on your PATH, so you can launch it from any directory.

# 1 — get the code
git clone https://github.com/Z4nzu/hackingtool.git
cd hackingtool

# 2 — install it onto your PATH (isolated venv, no system Python touched)
pipx install .

# 3 — run it from anywhere
hackingtool

No pipx yet?

# macOS
brew install pipx && pipx ensurepath

# Debian / Ubuntu / Kali
sudo apt install pipx && pipx ensurepath

Open a new shell after pipx ensurepath so the PATH change takes effect. To update later: git pull && pipx install . --force. To remove it: pipx uninstall hackingtool.

git clone https://github.com/Z4nzu/hackingtool.git
cd hackingtool
uv tool install .        # installs the `hackingtool` executable on your PATH
hackingtool

git clone https://github.com/Z4nzu/hackingtool.git
cd hackingtool
python3 -m venv .venv && . .venv/bin/activate
pip install .            # or: pip install -e .   for an editable dev install
hackingtool

The command is only on your PATH while that venv is activated.

For development

uv creates the virtualenv and installs everything from pyproject.toml / uv.lock in one step:

git clone https://github.com/Z4nzu/hackingtool.git
cd hackingtool
uv sync
uv run hackingtool

No uv yet? pipx install uv (or see the uv install docs).

Contributing? make setup wires the pre-push hook and make check runs the full gate (lint + tests + catalog validation). See CONTRIBUTING.md.

Docker

Pull and run the published image:

docker run -it --rm hardikzinzu/hackingtool:latest

Or build it locally from a checkout:

git clone https://github.com/Z4nzu/hackingtool.git && cd hackingtool
docker build -t hackingtool .
docker run -it --rm hackingtool

Optional runtimes

Some individual tools need a language runtime to install/run; the core app doesn't.

Quick Commands

Launch hackingtool and type. There are only three kinds of input:

_{<code>@</code> completes tool names — <code>@tag:</code> completes tags, <code>/</code> completes commands.}

Command reference

Inside a category: 1–N pick a tool · 97 install everything not yet installed · 98 archived tools · 99 back. Inside a tool: 1 install · 2 run · c ask for the exact command for your goal · 98 project page · 99 back.

_{<code>/help</code> — the same card, in the app.}

On a non-interactive terminal (or without prompt_toolkit) hackingtool falls back to the classic numbered menu, where / or s searches, t filters by tag, r or a recommends, ? helps and q quits. Force it with hackingtool --classic.

New here? docs/HOW-TO-USE.md walks through each of these start to finish with numbered steps.

Features

🔎 /find — a tool for a need you don't have yet

Searches the 215 curated tools first, then the GitHub search API, and ranks the results explainably. Suggest-only — it never clones, installs or runs anything — and it makes zero model calls.

/find crack a wpa handshake

In your toolbox (vetted)
  • aircrack-ng (WiFi security suite)
  • Kismet (wireless detector / WIDS)
  • Reaver (WPS PIN attack)
  • WiGLE (wardriving map & API)
  • hashcat example hashes (WPA mode 22000)

Found on GitHub — NOT vetted by us

  wifiphisher/wifiphisher  14713★  GPL-3.0
    The Rogue Access Point Framework
    14713★ · trusted author (ships in our catalog) · active · matches: security, wifi
    git clone https://github.com/wifiphisher/wifiphisher
  …

Press a to keep a result: it is saved to ~/.hackingtool/found.yaml as a "Discovered tools" entry — title, tags, description, link, and no install or run command, so a discovered entry can never execute anything. It shows up in your menu and in /search next launch.

Out-of-scope asks (jamming, DoS, mass-targeting, malware) are refused before any network call, with an authorized alternative where one exists. Defensive/DFIR phrasing is never refused.

Works anonymously at 10 GitHub searches/minute; a no-scope, no-permission token raises that to 30 — see /config github.

🎯 /goal — plan an objective, run it one step at a time

/goal find live subdomains of example.com

hackingtool drafts a short plan of real commands (with the reason for each step and an install hint for tools you don't have), asks you to confirm you are authorized to test the target, then walks the steps: [y] run · [s] skip · [e] edit · [q] abort. Every step runs list-form — never through a shell — and each goal gets a timestamped workspace under ~/.hackingtool/goals/ holding plan.json, a UTC-stamped run.log, and the raw output of each step.

The model is called once, for planning; tool output is never fed back to it. With no model configured, /goal degrades to tool recommendations for the same objective.

🧠 Recommendations — say what you want in plain English

Bare text (or /ai) maps intent to tools. The model may only return tags from the fixed taxonomy, and the catalog resolves tags → tools, so a tool can never be invented; with no model reachable a stdlib keyword matcher answers instead.

_{<code>/ai</code> — pick one of the common tasks, or type the job in your own words.}

🏷 Tags and search

/tags prints every tag in use with its live tool count; @tag:<name> opens the tools carrying it; /search <keyword> matches names, descriptions and tags.

_{<code>/tags</code> — 63 tags in use, with the number of tools behind each.}

▶ Background panes (tmux)

Long scans shouldn't block your console. With tmux installed, /run <tool> … & opens a labeled window in one detached hackingtool session:

/run nmap -sV -oA scan 10.0.0.5 &
▶ started 'nmap' in background — /attach to view

/panes lists them, /attach watches one (Ctrl-b d to come back), /kill <label> or /kill all stops them, and the status line under the prompt shows ▶ N running. No tmux? It says so and opens the tool inline instead; disable it entirely with /config background_runner off.

⚙ Settings and the AI layer

/config opens a full-screen settings editor (↑↓ move, ←→ change, Enter edit, t test the connection, Esc close); /config <key> <value> sets one key from the prompt. Settings live in ~/.hackingtool/config.json.

The AI layer is opt-in and bring-your-own-key: an OpenAI-compatible endpoint when ai_base_url + an API key are set, else a local Ollama, else nothing — every feature degrades to a deterministic offline behaviour instead of guessing. Your API key is written only to ~/.hackingtool/.env (mode 600), never to config.json, and never printed back. /config test reports the real failure if a probe fails.

📋 Headless engagements

The same catalog drives a non-interactive orchestrator that normalizes tool output into one findings.json:

hackingtool --engagement acme --targets example.com --pipeline recon
hackingtool --engagement acme --report          # deterministic Markdown report
hackingtool --engagement acme --ai-summary      # opt-in triage of the REAL findings
hackingtool --engagement acme --ai-report       # opt-in narrative draft (report.draft.md)

Out-of-scope targets are flagged and logged before anything runs, and the AI passes only ever summarize findings that exist.

Documentation

Contributing

New tools, fixes, and docs are all welcome — for authorized security testing only.

The easy path: most tools are just one YAML entry in src/hackingtool/catalog/ — no Python needed. Tags come from a fixed taxonomy, so your tool is instantly discoverable and searchable.

Before opening a PR, run make check (lint + tests + catalog validation) and use the title format [New Tool] Name — Category. The full guide — security rules and the one-entry catalog walkthrough — is in CONTRIBUTING.md.

_{📄 Contributing · Security · Code of Conduct}

Support & Sponsor

hackingtool is free and open-source. If it saves you time on an engagement or helps you learn, please consider sponsoring — funding goes to tool curation, the AI layer, and keeping installs safe and current.

<a href="https://github.com/sponsors/Z4nzu"></a>  <a href="https://buymeacoffee.com/hardikzinzu" target="_blank"></a>

⭐ Starring the repo is free and helps others discover the project.

Social

For authorized security testing only. Thanks to all original authors of the tools included in hackingtool.

Your favourite tool is not listed? Suggest it here