HackingTool

https://github.com/z4nzu/hackingtool
Admin
HackingTool is an all-in-one suite containing 185+ security tools organized across 20 categories...
Tokens:32,346
Snippets:474
Trust Score:9.2
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install tool

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Method signature and usage for executing installation commands.

```python
def install(self) -> None
```

```python
tool = MyTool()
tool.install()
```

--------------------------------

### Define an Installable Tool Entry

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/05-catalog-yaml-schema.md

Full schema example for an installable tool including category metadata, system package detection, and usage examples.

```yaml
category:
  title: "Information gathering tools"
  icon: "🔍"
  menu_label: "Information Gathering"
  description: "Tools for reconnaissance and enumeration"
  merge_into: null

tools:
  - title: nmap
    description: Network reconnaissance and port scanning tool
    kind: install
    tags: [port-scan, scanner, network]
    system_pkgs:
      which: nmap
      apt: nmap
      brew: nmap
    install:
      apt: nmap
      brew: nmap
    run: [nmap]
    usage:
      - [ping-sweep a subnet, nmap -sn 10.10.10.0/24]
      - [TCP full connect scan, nmap -sT target.com]
    project_url: https://nmap.org/
```

--------------------------------

### Define a Git Clone and Manual Install

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/05-catalog-yaml-schema.md

Configuration for tools requiring repository cloning and custom shell commands for setup.

```yaml
- title: Empire
  description: Powershell-based post-exploitation framework
  kind: install
  tags: [c2, post-exploitation]
  install:
    git: https://github.com/BC-SECURITY/Empire.git
    commands:
      - cd Empire
      - pip install -r requirements.txt
  run: [empire]
  project_url: https://github.com/BC-SECURITY/Empire
```

--------------------------------

### Check installation status

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Property definition and usage example for verifying if a tool is installed.

```python
@property
def is_installed(self) -> bool
```

```python
from hackingtool.core import HackingTool

tool = MyCustomTool()
if tool.is_installed:
    print(f"{tool.TITLE} is ready to use")
else:
    tool.install()
```

--------------------------------

### Complete Headless Workflow Example

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/04-engagement-api.md

A comprehensive example demonstrating engagement creation, pipeline execution, report generation, and optional AI-assisted documentation.

```python
from hackingtool.engagement import get_or_create
from hackingtool.orchestrator import run_pipeline
from hackingtool.report import generate_report
from hackingtool.ai_report import draft_report
from hackingtool.ai_summary import summarize

# 1. Create/load engagement
e = get_or_create("acme-recon", targets=["example.com"])

# 2. Run pipeline
findings = run_pipeline(e, pipeline_name="recon")
print(f"✓ {len(findings)} findings collected")

# 3. Generate deterministic report
report_path = generate_report(e)
print(f"✓ Report: {report_path}")

# 4. Optional: AI-drafted narrative (verify before use)
draft_path = draft_report(e)
if draft_path:
    print(f"✓ Draft narrative: {draft_path}")

# 5. Optional: AI summary
summary = summarize(e)
if summary:
    (e.workspace / "summary.md").write_text(summary)
    print(f"✓ Summary: {e.workspace / 'summary.md'}")

# 6. Results
print(f"\nWorkspace: {e.workspace}")
```

--------------------------------

### Define installation commands

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/05-catalog-yaml-schema.md

Standard installation commands executed as specified in the YAML configuration.

```yaml
install:
  commands:
    - wget https://example.com/tool.tar.gz -O /tmp/tool.tar.gz
    - tar -xz -C /opt -f /tmp/tool.tar.gz
    - /opt/tool/install.sh
```

--------------------------------

### Define a Go Binary Install

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/05-catalog-yaml-schema.md

Configuration for tools installed via the Go language toolchain.

```yaml
- title: httpx
  description: Fast HTTP prober with filtering
  kind: install
  tags: [scanner, http, recon]
  install:
    go: github.com/projectdiscovery/httpx/cmd/httpx@latest
  run: [httpx]
  project_url: https://github.com/projectdiscovery/httpx
```

--------------------------------

### Install hackingtool via uv

Source: https://github.com/z4nzu/hackingtool/blob/master/README.md

Alternative installation method using the uv tool.

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

--------------------------------

### HackingTool.install

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Executes the installation process for the tool.

```APIDOC
## HackingTool.install()

### Description
Executes the defined install commands in order. For tools with an INSTALL_URL, it performs a safe URL-fetch-and-verify sequence using SHA256.
```

--------------------------------

### Setup development environment with uv

Source: https://github.com/z4nzu/hackingtool/blob/master/README.md

Commands to sync dependencies and run the tool for development purposes.

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

--------------------------------

### Open tool directory

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Method signature for accessing the installation folder.

```python
def open_folder(self) -> None
```

--------------------------------

### Complete catalog file structure

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/05-catalog-yaml-schema.md

A comprehensive example showing category definitions, tool configurations, and overlay metadata.

```yaml
category:
  title: "Wireless attack tools"
  icon: "📡"
  menu_label: "Wireless Attack"
  description: "WiFi enumeration, WPS, handshake cracking"
  merge_into: null

tools:
  - title: aircrack-ng
    description: WiFi cracking suite (WEP/WPA/WPA2)
    kind: install
    tags: [wireless, password-attack]
    system_pkgs:
      which: aircrack-ng
      apt: aircrack-ng
      brew: aircrack-ng
    install:
      apt: aircrack-ng
      brew: aircrack-ng
    run: [aircrack-ng]
    usage:
      - [capture handshake, airodump-ng wlan0]
      - [crack WPA2 handshake, "aircrack-ng -w wordlist.txt handshake.cap"]
    project_url: https://aircrack-ng.org/

  - title: Kismet
    description: Wireless detector, sniffer, and IDS system
    kind: install
    tags: [wireless, scanner, enumeration]
    install:
      apt: kismet
      brew: kismet
    run: [kismet]
    usage:
      - [start monitoring, kismet -c wlan0]
    project_url: https://www.kismetwireless.net/

  - title: hashcat example hashes
    description: Example password hashes for testing and reference
    kind: resource
    tags: [hash-crack, reference]
    url: https://hashcat.net/wiki/doku.php?id=example_hashes
    project_url: https://hashcat.net/

overlay:
  - title: aircrack-ng
    lab_safe_notes: "Fully safe on lab networks. Use your own WiFi for testing, never test on others' networks without permission."
```

--------------------------------

### Install pipx dependency

Source: https://github.com/z4nzu/hackingtool/blob/master/README.md

Commands to install pipx on supported operating systems.

```bash
# macOS
brew install pipx && pipx ensurepath

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

--------------------------------

### YAML Catalog Entry Example

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Example of a YAML configuration used to define a tool in the catalog.

```yaml
- title: nmap
  description: Port scanner and network reconnaissance tool
  kind: install
  tags: [port-scan, scanner, network]
  system_pkgs:
    which: nmap
    apt: nmap
    brew: nmap
  run: [nmap]
  usage:
    - [ping-sweep a subnet, nmap -sn 10.10.10.0/24]
    - [TCP full connect scan, nmap -sT target.com]
  project_url: https://nmap.org/
```

--------------------------------

### Define a Simple Package Manager Install

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/05-catalog-yaml-schema.md

Configuration for tools available via standard system package managers like apt or brew.

```yaml
- title: hashcat
  description: GPU-accelerated password cracking
  kind: install
  tags: [hash-crack, bruteforce]
  system_pkgs:
    which: hashcat
    apt: hashcat
    brew: hashcat
  install:
    apt: hashcat
    brew: hashcat
  run: [hashcat]
  project_url: https://hashcat.net/
```

--------------------------------

### Install hackingtool via pipx

Source: https://github.com/z4nzu/hackingtool/blob/master/README.md

Recommended method for installing the tool into an isolated environment with PATH access.

```bash
# 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
```

--------------------------------

### Use file placeholders in URL installs

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/05-catalog-yaml-schema.md

Utilize the {file} placeholder for verified downloads when using url and sha256 fields.

```yaml
install:
  url: https://example.com/tool.bin
  sha256: abc123...
  commands:
    - chmod +x {file}
    - ./{file} --install
```

--------------------------------

### Displaying Collection Options

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Example usage of the show_options method on a collection instance.

```python
collection = InformationGatheringTools()
collection.show_options()
```

--------------------------------

### Launch Interactive Mode

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/06-cli-reference.md

Starts the default Rich-based terminal UI.

```bash
hackingtool
```

--------------------------------

### Ollama Setup and Configuration

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/03-ai-api.md

Commands to pull and serve the Ollama model, followed by the JSON configuration required to enable it.

```bash
ollama pull llama3
ollama serve  # starts at :11434
```

```json
{
  "ai_provider": "ollama",
  "ai_model": "llama3"
}
```

--------------------------------

### Iterate through tool collections

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/07-tool-class-reference.md

Iterates over all available tool collections and prints their status, checking for installation state.

```python
from hackingtool.cli import all_tools

for collection in all_tools:
    if hasattr(collection, 'TOOLS'):
        print(f"\n{collection.TITLE}")
        for tool in collection.TOOLS:
            if hasattr(tool, 'TITLE'):  # Skip nested collections
                status = "✓" if tool.is_installed else "✘"
                print(f"  {status} {tool.TITLE}")
            else:
                print(f"  ➤ {tool.TITLE}")
```

--------------------------------

### Install hackingtool via venv and pip

Source: https://github.com/z4nzu/hackingtool/blob/master/README.md

Standard installation using a local virtual environment without modifying system PATH.

```bash
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
```

--------------------------------

### Generate Report Usage Example

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/04-engagement-api.md

Basic usage for loading an engagement and generating a report file.

```python
from hackingtool.engagement import load
from hackingtool.report import generate_report

e = load("acme-recon")
path = generate_report(e)
print(f"Report: {path}")
```

--------------------------------

### HackingTool.open_folder

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Opens the tool's installation directory.

```APIDOC
## HackingTool.open_folder()

### Description
Opens the tool's installation directory in the system file manager or prints the path if no GUI is available.
```

--------------------------------

### Update tool

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Method signature for re-running installation commands to pull updates.

```python
def update(self) -> None
```

--------------------------------

### Get Field Choices

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/02-configuration-api.md

Retrieves allowed values for constrained configuration keys.

```python
from hackingtool.config import field_choices

theme_choices = field_choices("theme")
# Returns: ['blue', 'cyan', 'green', 'magenta']

model_choices = field_choices("ai_model")
# Returns: None (free-text)
```

--------------------------------

### Execute a security plan

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/03-ai-api.md

Example usage of the run_plan function to execute a plan within an engagement workspace.

```python
from hackingtool.engagement import get_or_create
from hackingtool.ai_goal import plan, run_plan

e = get_or_create("acme_recon", targets=["example.com"])
plan_data = plan("find subdomains of example.com")
findings = run_plan(e, plan_data, confirm_each=True)
```

--------------------------------

### HackingTool.is_installed

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Checks if the tool is currently installed on the system.

```APIDOC
## HackingTool.is_installed

### Description
Returns True if the tool is already installed on the system. It checks if the tool is a resource, verifies binary existence on PATH, or attempts to run the tool with a --help flag.

### Returns
- **bool** - True if installed, False otherwise.
```

--------------------------------

### Generate a security plan

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/03-ai-api.md

Example usage of the plan function to generate and iterate through steps for a security objective.

```python
from hackingtool.ai_goal import plan

plan_data = plan("enumerate open ports on 10.0.0.0/24")
if plan_data:
    for step in plan_data["steps"]:
        print(f"{step['tool']} — {step['reason']}")
else:
    print("No model reachable; use /recommend instead")
```

--------------------------------

### Get Allowed Values Hint

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/02-configuration-api.md

Retrieves a human-readable string of legal values for a configuration key.

```python
from hackingtool.config import allowed_values

hint = allowed_values("background_runner")
print(f"Allowed: {hint}")  # Output: "Allowed: auto, off"
```

--------------------------------

### Test AI connection

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/03-ai-api.md

Example usage of test_connection to verify AI provider availability.

```python
from hackingtool.ai_recommend import test_connection

ok, detail = test_connection()
if ok:
    print(f"✓ AI connection OK")
else:
    print(f"✗ {detail}")
    # Output: "Connection refused: http://localhost:11434"
```

--------------------------------

### Engagement Directory Structure

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/06-cli-reference.md

Example of the file structure generated within an engagement directory.

```text
~/.hackingtool/engagements/acme-phase1/
├── engagement.json        # Metadata
├── findings.json          # Normalized findings (JSON array)
├── report.md              # Deterministic Markdown report
├── report.draft.md        # AI-drafted narrative (if --ai-report)
├── summary.md             # AI summary (if --ai-summary)
├── run.log                # Operation log
└── raw/
    ├── subfinder.txt
    ├── httpx.json
    └── nuclei.json
```

--------------------------------

### Resource Entry YAML Structure

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/05-catalog-yaml-schema.md

Example of a resource entry definition for a web-based service.

```yaml
- title: VirusTotal
  description: File and URL analysis service
  kind: resource
  tags: [online-service, malware-analysis]
  url: https://www.virustotal.com/
  project_url: https://www.virustotal.com/
```

--------------------------------

### JSON serialization format for Finding

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/08-types-reference.md

Example of a serialized Finding object in JSON format.

```json
{
  "kind": "vulnerability",
  "target": "api.example.com",
  "name": "SQL Injection",
  "severity": "high",
  "source_tool": "nuclei",
  "details": {
    "template_id": "cves/2024/CVE-1234",
    "matched_at": "api.example.com/login"
  },
  "raw": "{\"template-id\": \"cves/2024/CVE-1234\", ...}",
  "timestamp": "2024-01-15T10:30:00Z"
}
```

--------------------------------

### Auto Provider Usage

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/03-ai-api.md

Example of using the auto provider which dynamically selects between configured AI services or local fallbacks.

```python
from hackingtool.ai_recommend import resolve
from hackingtool.tags import TAXONOMY

# Auto uses whatever is configured
tags = resolve("enumerate a network", TAXONOMY)
# Works with Ollama OR OpenAI-compat OR offline keyword matcher
```

--------------------------------

### Tool Not Found Error

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/06-cli-reference.md

Displays the error message when a requested command-line tool is not installed on the system.

```text
hackingtool> /run nmap
⚠ Command 'nmap' not found. Install it with: /run nmap
```

--------------------------------

### HackingToolsCollection.show_options()

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Displays a paginated menu of tools within a collection, allowing users to select tools, install all, or navigate menus.

```APIDOC
## HackingToolsCollection.show_options()

### Description
Displays a paginated menu of tools in the collection. Users can select a tool by index, install all tools, view archives, or return to the previous menu.

### Method
`show_options(self) -> None`

### Returns
- **None**

### Example
```python
collection = InformationGatheringTools()
collection.show_options()
```
```

--------------------------------

### Initialize development environment

Source: https://github.com/z4nzu/hackingtool/blob/master/CONTRIBUTING.md

Commands to clone the repository, configure git hooks, and run the project using uv.

```bash
git clone https://github.com/Z4nzu/hackingtool.git
cd hackingtool
make setup            # one-time: point git at .githooks (pre-push runs the gate)
uv run hackingtool    # run from source (uv provides rich/pyyaml/platformdirs)
```

--------------------------------

### Ensure User Files

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/02-configuration-api.md

Initializes the configuration directory and default files if they are missing.

```python
from hackingtool.config import ensure_user_files

ensure_user_files()  # Safe to call multiple times
```

--------------------------------

### get_tools_dir()

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/02-configuration-api.md

Retrieves the absolute path to the directory where external tools are installed.

```APIDOC
## get_tools_dir()

### Description
Returns the absolute path to the directory where external tools are installed. Creates the directory if it does not exist.

### Returns
- **Path** - An absolute Path object.
```

--------------------------------

### Manage Configuration Settings

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/06-cli-reference.md

Commands for viewing, updating, and testing application configurations.

```bash
# View all settings
hackingtool /config

# View one setting
hackingtool /config theme

# Set a value
hackingtool /config theme cyan

# Test AI connection
hackingtool /config test

# Test GitHub token
hackingtool /config github
```

--------------------------------

### describe()

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/02-configuration-api.md

Returns metadata about all known configuration keys for use in the UI.

```APIDOC
## describe()

### Description
Returns metadata about every known configuration key for the /config UI.

### Returns
- **list[tuple[str, Any, bool]]** - A list of tuples containing (key_name, current_value, is_editable).
```

--------------------------------

### Verify release artifacts and SBOM

Source: https://github.com/z4nzu/hackingtool/blob/master/SECURITY.md

Use the GitHub CLI to verify build provenance attestations for release artifacts and the CycloneDX SBOM.

```bash
# PyPI wheel/sdist and the GitHub release .deb carry build-provenance attestations
gh attestation verify <artifact> --repo Z4nzu/hackingtool

# The SBOM (attached to each GitHub release as hackingtool.cdx.json) is attested too
gh attestation verify dist/hackingtool-*.whl --repo Z4nzu/hackingtool --predicate-type https://cyclonedx.org/bom
```

--------------------------------

### Load Configuration

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/02-configuration-api.md

Retrieves the current configuration, merging with defaults if necessary.

```python
from hackingtool.config import load

config = load()
tools_dir = config["tools_dir"]
ai_model = config["ai_model"]
```

--------------------------------

### Findings JSON Format

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/06-cli-reference.md

Example structure of findings exported in JSON format.

```json
[
  {
    "kind": "vulnerability",
    "target": "api.acme.com",
    "name": "SQL Injection",
    "severity": "high",
    "source_tool": "nuclei",
    "details": {
      "template_id": "cves/2024/CVE-1234",
      "type": "injection"
    },
    "raw": "{\"template-id\": \"cves/2024/CVE-1234\", ...}",
    "timestamp": "2024-01-15T10:30:00Z"
  }
]
```

--------------------------------

### run_plan(e: Engagement, plan: dict, confirm_each: bool = True)

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/03-ai-api.md

Executes a generated plan step-by-step within an engagement context.

```APIDOC
## run_plan(e: Engagement, plan: dict, confirm_each: bool = True)

### Description
Executes a plan step by step in the context of an engagement. Runs commands in list form and collects findings.

### Parameters
- **e** (Engagement) - Required - Engagement workspace for output/logs
- **plan** (dict) - Required - Plan dictionary generated from the plan() function
- **confirm_each** (bool) - Optional - If True, prompts the user to confirm, skip, or edit each step

### Returns
- **list[Finding]** - A list of normalized Finding objects.
```

--------------------------------

### load()

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/02-configuration-api.md

Loads the configuration from disk, merging it with default values. If the configuration file is missing or corrupted, it falls back to the default configuration.

```APIDOC
## load()

### Description
Loads configuration from disk, merging with defaults for missing keys. Falls back to DEFAULT_CONFIG if the file is missing or corrupted.

### Returns
- **dict** - A dictionary containing all configuration keys.
```

--------------------------------

### Python Version Error

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/06-cli-reference.md

Displays the error message when the installed Python version is below 3.10.

```text
[ERROR] Python 3.10 or newer is required.
You are running Python 3.9.
Upgrade with: sudo apt install python3.10
```

--------------------------------

### Quick Help Reference

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/06-cli-reference.md

Visual representation of the quick help menu displayed when pressing '?' or typing '/help'.

```text
╭───────── ? Quick Help ───────────╮
│ Main menu                         │
│ ─────────────────────────────────│
│ type          just say what you  │
│ 1–N           open a category    │
│ / or s        search tools       │
│ t             filter by tag      │
│ r / a         recommend tools    │
│ /goal         AI-plan objective  │
│ /find         find new tools     │
│ ...                              │
╰──────────────────────────────────╯
```

--------------------------------

### Initialize HackingTool

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Constructor signature for creating a new tool instance.

```python
def __init__(self, options=None, installable=True, runnable=True)
```

--------------------------------

### Deterministic Report Format

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/06-cli-reference.md

Example structure of a generated engagement report in Markdown format.

```markdown
# Engagement Report: acme-phase1

**Scope:** api.acme.com  
**Excluded:** None  
**Created:** 2024-01-15T10:30:00Z

## Summary

- **Critical:** 1
- **High:** 3
- **Medium:** 5
- **Low:** 12
- **Info:** 42

## Vulnerabilities

### SQL Injection in Login Form

**Target:** api.acme.com  
**Source Tool:** nuclei  
**Severity:** high  
**Details:**
- Template ID: cves/2024/CVE-1234
- Matched at: api.acme.com/login
- Type: injection

...
```

--------------------------------

### show_options Method Signature

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Method signature for displaying the tool collection menu.

```python
def show_options(self) -> None
```

--------------------------------

### Describe Configuration

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/02-configuration-api.md

Retrieves metadata for all configuration keys, useful for generating UI elements.

```python
from hackingtool.config import describe

for key, value, editable in describe():
    print(f"{key} = {value} (editable: {editable})")
```

--------------------------------

### Launch Classic Menu

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/06-cli-reference.md

Forces the use of readline-based numbered menus for limited terminal environments.

```bash
hackingtool --classic
```

--------------------------------

### HackingTool.__init__

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Initializes a new instance of a HackingTool.

```APIDOC
## HackingTool.__init__(options=None, installable=True, runnable=True)

### Description
Initializes a new HackingTool instance with specified configuration options.

### Parameters
- **options** (list[tuple[str, Callable]]) - Optional - Custom menu options beyond install/run/update.
- **installable** (bool) - Optional - Whether the tool supports installation (default: True).
- **runnable** (bool) - Optional - Whether the tool supports execution (default: True).

### Raises
- **TypeError** - If options is not a list of tuples.
```

--------------------------------

### Registry.apply_overlays(tool_pairs)

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Enriches tool instances by applying guidance overlays from the YAML catalog.

```APIDOC
## Method: `Registry.apply_overlays(tool_pairs: list[tuple]) -> list[str]`

### Description
Enriches already-built tools by applying guidance overlays from the YAML catalog (tags, usage examples, lab-safe notes).

### Parameters
- **tool_pairs** (list[tuple]) - Required - List of `(tool_instance, category_name)` pairs.

### Returns
- **list[str]** - List of tool titles that were enriched.

### Example
```python
all_tool_pairs = [(tool, "Information Gathering") for tool in tools]
applied = registry.apply_overlays(all_tool_pairs)
print(f"Enhanced {len(applied)} tools")
```
```

--------------------------------

### Get Tools Directory

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/02-configuration-api.md

Retrieves the absolute path to the external tools directory, creating it if it does not exist.

```python
from hackingtool.config import get_tools_dir

tools = get_tools_dir()  # e.g., /home/user/.hackingtool/tools
print(f"Tools installed to: {tools}")
```

--------------------------------

### Load tool catalog

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Initializes the registry by loading tool definitions from the default catalog and an optional user-specified directory.

```python
from pathlib import Path
from hackingtool.registry import load

registry = load(user_dir=Path.home() / ".hackingtool")
for tool in registry.new_collections:
    print(tool.TITLE)
```

--------------------------------

### Adding a discovered tool to the toolbox

Source: https://github.com/z4nzu/hackingtool/blob/master/docs/HOW-TO-USE.md

After running a search, use the 'a' command followed by the result number to bookmark a tool.

```text
[a] add one to your toolbox · [Enter] done: a
which? 1-5: 2
Added.  /Users/you/.hackingtool/found.yaml
```

--------------------------------

### Resolve intent to tags

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/03-ai-api.md

Example usage of the resolve function to map a user intent to a subset of the TAXONOMY.

```python
from hackingtool.ai_recommend import resolve
from hackingtool.tags import TAXONOMY

intent = "find subdomains of example.com"
tags = resolve(intent, TAXONOMY)
# Returns: ["recon", "osint"] or similar subset of TAXONOMY
```

--------------------------------

### ensure_user_files()

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/02-configuration-api.md

Initializes the user configuration directory and files if they do not exist.

```APIDOC
## ensure_user_files()

### Description
Performs first-run scaffolding by creating ~/.hackingtool/ with a default config.json and a .env template. This function is safe to call multiple times as it never overwrites existing files.
```

--------------------------------

### Engagement JSON Serialization Format

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/08-types-reference.md

Example of the JSON structure used to persist engagement data to disk.

```json
{
  "name": "acme-phase1",
  "created": "2024-01-15T10:30:00Z",
  "scope_in": ["*.example.com"],
  "scope_out": ["admin-*.example.com"],
  "targets": ["api.example.com"],
  "runs": [
    {
      "pipeline": "recon",
      "at": "2024-01-15T10:30:00Z",
      "findings": 42
    }
  ]
}
```

--------------------------------

### Define Pipeline Steps

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/08-types-reference.md

Configuration for chaining tools using YAML or Python dictionaries.

```yaml
steps:
  - tool: subfinder
    input: targets
    args: [-d]
    output: subfinder.txt
    parser: subfinder
  - tool: httpx
    input: forwarded
    args: [-i]
    output: httpx.json
    parser: httpx
```

```python
pipeline: dict = {
    "steps": [
        {
            "tool": "subfinder",
            "input": "targets",
            "args": ["-d"],
            "output": "subfinder.txt",
            "parser": "subfinder"
        },
        # ... more steps
    ]
}
```

--------------------------------

### Apply tool overlays

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Enriches tool instances with additional metadata such as tags and usage notes by applying overlays from the catalog.

```python
all_tool_pairs = [(tool, "Information Gathering") for tool in tools]
applied = registry.apply_overlays(all_tool_pairs)
print(f"Enhanced {len(applied)} tools")
```

--------------------------------

### Show interactive menu

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Method signature and usage for displaying the tool's action menu.

```python
def show_options(self) -> None
```

```python
tool.show_options()  # Interactive menu
```

--------------------------------

### Querying for tools with /find

Source: https://github.com/z4nzu/hackingtool/blob/master/docs/HOW-TO-USE.md

Use the /find command followed by a natural language query to search for relevant security tools.

```text
/find hidden directories on a website
```

--------------------------------

### Run tool

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Method signature and usage for executing the primary run command.

```python
def run(self) -> None
```

```python
tool.run()
```

--------------------------------

### Get or create an engagement

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/04-engagement-api.md

Retrieves an existing engagement or creates a new one if it is missing. If the engagement exists, providing targets will update the existing engagement's target list.

```python
def get_or_create(name: str, targets: list[str] | None = None) -> Engagement
```

```python
from hackingtool.engagement import get_or_create

# First call: creates with targets
e = get_or_create("acme-phase1", targets=["api.acme.com"])

# Second call: loads existing, updates targets
e = get_or_create("acme-phase1", targets=["api.acme.com", "web.acme.com"])
```

--------------------------------

### Load Engagement and Run Pipeline

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/README.md

Initializes an engagement, executes a named pipeline, and generates a report.

```python
from pathlib import Path
from hackingtool.engagement import get_or_create
from hackingtool.orchestrator import run_pipeline
from hackingtool.report import generate_report

# Create or load engagement
e = get_or_create("acme-recon", targets=["example.com"])

# Run pipeline
findings = run_pipeline(e, pipeline_name="recon")
print(f"✓ {len(findings)} findings collected")

# Generate report
path = generate_report(e)
print(f"✓ Report: {path}")
```

--------------------------------

### Multiple Targets from File

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/06-cli-reference.md

Runs a pipeline against multiple targets defined in a text file and generates a report.

```bash
# targets.txt:
# api.example.com
# web.example.com
# cdn.example.com

hackingtool --engagement acme-external \
  --targets targets.txt \
  --pipeline recon \
  --report
```

--------------------------------

### Build and Run Hackingtool Locally

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/06-cli-reference.md

Builds the Docker image from the local source and runs the resulting container.

```bash
docker build -t hackingtool .
docker run -it --rm hackingtool
```

--------------------------------

### Headless Mode with AI Enhancements

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/06-cli-reference.md

Runs a pipeline with AI summary and narrative report generation enabled.

```bash
hackingtool --engagement acme-external \
  --targets "10.0.0.0/24" \
  --pipeline recon \
  --report \
  --ai-summary \
  --ai-report
```

--------------------------------

### CatalogTool(entry)

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Initializes a new tool instance based on a provided YAML catalog entry.

```APIDOC
## CatalogTool(entry)

### Description
A HackingTool instance built from a YAML catalog entry. Inherits all HackingTool properties and methods.

### Parameters
- **entry** (dict) - Required - Parsed YAML catalog entry containing keys: title, description, kind, tags, install, run, system_pkgs, usage, lab_safe_notes, project_url/url.

### Example
```python
entry = {
  "title": "nmap",
  "description": "Port scanner",
  "kind": "install",
  "run": ["nmap"]
}
tool = CatalogTool(entry)
```
```

--------------------------------

### ask(prompt, default)

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Prompts the user for input using readline-backed reading.

```APIDOC
## ask(prompt, default)

### Description
Prompts the user for input, using readline-backed reading to avoid TTY issues. Supports Rich markup in the prompt text.

### Parameters
- **prompt** (str) - Required - Prompt text (supports Rich markup)
- **default** (str) - Optional - Default value if user presses Enter without typing (default: "")

### Returns
- **str** - The user input.
```

--------------------------------

### CatalogTool Class Initialization

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Constructor for creating a CatalogTool from a dictionary entry.

```python
class CatalogTool(HackingTool):
    def __init__(self, entry: dict)
```

--------------------------------

### Configure AI Settings via Python

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/02-configuration-api.md

Update AI provider settings programmatically. API keys should be stored in ~/.hackingtool/.env.

```python
from hackingtool.config import load, save

# Load current settings
cfg = load()

# Configure for OpenAI-compatible endpoint
cfg["ai_provider"] = "openai-compat"
cfg["ai_base_url"] = "https://api.anthropic.com/v1"
cfg["ai_model"] = "claude-haiku-4-5-20251001"

# Persist
save(cfg)

# API key goes in ~/.hackingtool/.env instead:
# HACKINGTOOL_AI_KEY=sk-ant-...
```

--------------------------------

### load(catalog_dir, user_dir)

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Loads the shipped catalog and an optional user catalog from the specified directories.

```APIDOC
## Function: `load(catalog_dir: Path = CATALOG_DIR, user_dir: Path | None = None) -> Registry`

### Description
Loads the shipped catalog and an optional user catalog (e.g., tools discovered with /find).

### Parameters
- **catalog_dir** (Path) - Optional - Directory containing *.yaml tool definitions. Defaults to `CATALOG_DIR`.
- **user_dir** (Path | None) - Optional - Optional directory for user-supplied catalog additions (e.g., `~/.hackingtool`).

### Returns
- **Registry** - The merged catalog.

### Example
```python
from pathlib import Path
from hackingtool.registry import load

registry = load(user_dir=Path.home() / ".hackingtool")
for tool in registry.new_collections:
    print(tool.TITLE)
```
```

--------------------------------

### CLI Entry Point Syntax

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/06-cli-reference.md

General syntax for invoking the hackingtool command with available flags.

```bash
hackingtool [--classic] [--engagement NAME] [--targets SPEC] [--pipeline NAME] [--report] [--ai-summary] [--ai-report] [-h|--help]
```

--------------------------------

### CLI Version and Maintenance Commands

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/06-cli-reference.md

Standard commands for checking the version, updating the tool, and uninstalling.

```bash
hackingtool --version          # Shows version
hackingtool /update            # Updates hackingtool and system packages
hackingtool /uninstall         # Removes hackingtool
```

--------------------------------

### ask(prompt: str) -> str | None

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/03-ai-api.md

Invokes the configured AI transport with a structured prompt and returns the model's response.

```APIDOC
## ask(prompt)

### Description
Invokes the configured AI transport (BYO-key OpenAI-compat or local Ollama) with a structured prompt. Returns the model's reply, or None if no provider is reachable.

### Parameters
- **prompt** (str) - Required - Full prompt (including task + guardrails)

### Returns
- **str | None** - Model reply as string, or None on timeout/connection failure.
```

--------------------------------

### Open Settings Editor

Source: https://github.com/z4nzu/hackingtool/blob/master/docs/HOW-TO-USE.md

Access the configuration menu to modify application settings.

```text
/config
```

--------------------------------

### load(name: str) -> Engagement | None

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/04-engagement-api.md

Loads an existing engagement from disk by name.

```APIDOC
## load(name: str)

### Description
Loads an existing engagement from disk by name.

### Parameters
- **name** (str) - Required - Engagement name

### Returns
- **Engagement** (object) - The engagement object, or None if not found.
```

--------------------------------

### Plan objectives with /goal

Source: https://github.com/z4nzu/hackingtool/blob/master/README.md

Generates a step-by-step plan for a security objective.

```text
/goal find live subdomains of example.com
```

--------------------------------

### AI Error Handling and Fallback

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/03-ai-api.md

Demonstrates how the system gracefully handles AI service failures by falling back to keyword matching.

```python
from hackingtool.ai_recommend import resolve
from hackingtool.tags import TAXONOMY

intent = "find hidden directories on a website"

# If AI is down, uses stdlib keyword matching
# If both fail, returns empty list
tags = resolve(intent, TAXONOMY)

if not tags:
    print("No tags matched (AI unreachable + no keyword matches)")
else:
    print(f"Recommended tags: {tags}")
```

--------------------------------

### Custom Scripting API Usage

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/06-cli-reference.md

Demonstrates how to use the Python API to create engagements, run pipelines, and generate reports.

```python
#!/usr/bin/env python3
from hackingtool.engagement import get_or_create
from hackingtool.orchestrator import run_pipeline
from hackingtool.report import generate_report

# Create engagement
e = get_or_create("custom-recon", targets=["example.com"])

# Run pipeline
findings = run_pipeline(e, pipeline_name="recon")
print(f"Collected {len(findings)} findings")

# Generate report
report_path = generate_report(e)
print(f"Report: {report_path}")
```

--------------------------------

### Define default configuration settings

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/02-configuration-api.md

The DEFAULT_CONFIG dictionary defines core application settings including paths, theme, and AI provider configurations.

```python
DEFAULT_CONFIG: dict = {
    "tools_dir":      str(USER_TOOLS_DIR),       # ~/.hackingtool/tools
    "version":        VERSION,                   # "3.0.0"
    "theme":          "magenta",                 # magenta | cyan | green | blue
    "show_archived":  False,                     # Show unmaintained tools
    "background_runner": "auto",                 # auto (on iff tmux) | off
    "ai_provider":    "auto",                    # auto | ollama | openai-compat
    "ai_model":       "llama3",                  # Model name
    "ai_base_url":    "",                        # Blank = Ollama; else OpenAI endpoint
    "sudo_binary":    "sudo",                    # Privilege escalation
    "go_bin_dir":     str(Path.home() / "go" / "bin"),
    "gem_bin_dir":    str(Path.home() / ".gem" / "ruby"),
}
```

--------------------------------

### HackingTool.show_options

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Displays an interactive menu for the tool.

```APIDOC
## HackingTool.show_options()

### Description
Displays an interactive menu of available actions (install, run, update, open folder, and custom options) where the user selects via numbered input.
```

--------------------------------

### Save Configuration

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/02-configuration-api.md

Persists modified configuration settings to the disk.

```python
from hackingtool.config import load, save

cfg = load()
cfg["show_archived"] = True
save(cfg)
```

--------------------------------

### Set GitHub Token Environment Variable

Source: https://github.com/z4nzu/hackingtool/blob/master/docs/HOW-TO-USE.md

Add the GitHub personal access token to the local environment file.

```bash
HACKINGTOOL_GITHUB_TOKEN=ghp_your-token-here
```

--------------------------------

### Using the Global Console Instance

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/01-core-api.md

Access the shared console instance to render styled terminal output using Rich components like Panels.

```python
from hackingtool.core import console
from rich.panel import Panel

console.print(Panel("Your message", border_style="magenta"))
```

--------------------------------

### OpenAI-Compatible Provider Configuration

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/03-ai-api.md

Configuration for using external OpenAI-compatible APIs and setting the required environment variable for the API key.

```json
{
  "ai_provider": "openai-compat",
  "ai_base_url": "https://api.anthropic.com/v1",
  "ai_model": "claude-haiku-4-5-20251001"
}
```

```text
HACKINGTOOL_AI_KEY=sk-ant-...
```

--------------------------------

### Approve execution steps

Source: https://github.com/z4nzu/hackingtool/blob/master/docs/HOW-TO-USE.md

Manage the execution of individual steps by running, skipping, editing, or aborting.

```text
─ step 1/4 ─ subfinder -d example.com -silent
  [y] run  [s] skip  [e] edit  [q] abort  ›
```

--------------------------------

### Run Catalog Validation

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/05-catalog-yaml-schema.md

Execute the test suite to verify catalog integrity and schema compliance.

```bash
make check      # Runs test suite, including schema validation
```

--------------------------------

### create(name: str, targets: list[str] | None = None, scope_in: list[str] | None = None, scope_out: list[str] | None = None) -> Engagement

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/04-engagement-api.md

Creates a new engagement with the specified parameters.

```APIDOC
## create(name: str, targets: list[str] | None = None, scope_in: list[str] | None = None, scope_out: list[str] | None = None)

### Description
Creates a new engagement with the given parameters.

### Parameters
- **name** (str) - Required - Engagement name
- **targets** (list[str]) - Optional - Initial target list
- **scope_in** (list[str]) - Optional - In-scope patterns
- **scope_out** (list[str]) - Optional - Out-of-scope patterns

### Returns
- **Engagement** (object) - New Engagement instance
```

--------------------------------

### Define an Overlay Entry

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/05-catalog-yaml-schema.md

Use this structure to append tags and define usage or system packages for existing tools without modifying their core commands.

```yaml
overlay:
  - title: nmap
    tags: [enumeration, recon]              # Appended to existing tags
    usage:
      - [UDP port scan, nmap -sU target]
      - [Service version detection, nmap -sV target]
    lab_safe_notes: "Safe on lab networks; be careful with -A flag"
    system_pkgs:
      which: nmap
      apt: nmap
      brew: nmap
```

--------------------------------

### Define Nested Tool Collections

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/07-tool-class-reference.md

Demonstrates how to organize multiple sub-collections within a single parent collection.

```python
class OtherTools(HackingToolsCollection):
    TITLE = "Other tools"
    TOOLS = [
        AndroidAttackTools(),      # Sub-collection
        EmailVerifierTools(),       # Sub-collection
        HashCrackTools(),           # Sub-collection
        SocialMediaTools(),         # Sub-collection
        WebCrawlingTools(),         # Sub-collection
        # ... more sub-collections
    ]
```

--------------------------------

### Load pipeline definition

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/04-engagement-api.md

Reads a pipeline configuration from a YAML file.

```python
def load_pipeline(name: str) -> dict
```

```yaml
steps:
  - tool: subfinder
    input: targets
    args: [-d]
    output: subfinder.txt
    parser: subfinder
  - tool: httpx
    input: forwarded
    args: [-i]
    output: httpx.json
    parser: httpx
  - tool: nuclei
    input: forwarded
    args: [-json, -t, templates/]
    output: nuclei.json
    parser: nuclei
```

--------------------------------

### Run Headless Pipeline

Source: https://github.com/z4nzu/hackingtool/blob/master/_autodocs/06-cli-reference.md

Automates engagement workflows and report generation via CLI flags.

```bash
#!/bin/bash

# 1. Create engagement and run pipeline
hackingtool --engagement acme-phase1 \
  --targets "api.acme.com" \
  --pipeline recon \
  --report

# 2. Review deterministic report
cat ~/.hackingtool/engagements/acme-phase1/report.md

# 3. (Optional) Generate AI summary
hackingtool --engagement acme-phase1 --ai-summary

# 4. (Optional) Generate AI-drafted narrative
hackingtool --engagement acme-phase1 --ai-report
```

--------------------------------

### Search for tools with /find

Source: https://github.com/z4nzu/hackingtool/blob/master/README.md

Searches curated tools and GitHub for specific security tasks without executing any code.

```text
/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
  …
```
Tokens:
Raw