# z4nzu/hackingtool architecture

> Architecture diagram of the GitHub repository z4nzu/hackingtool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/z4nzu/hackingtool
- Repository: https://github.com/z4nzu/hackingtool

## Overview

1. **What this repository is**
   - This is a Python 3.10+ command-line launcher and installer for a large catalog of security tools, not a single-purpose scanner.
   - Its core job is to present categorized menus, detect the local environment, install third-party tools, and then hand off to those external tools.

2. **Primary orchestration layer**
   - `hackingtool.py`, `core.py`, `config.py`, `constants.py`, and `os_detect.py` form the central application layer.
   - `core.py` is the likely runtime entry point for the interactive menu system; `config.py` and `constants.py` hold shared settings, tool metadata, paths, and command definitions.
   - `os_detect.py` gates features by platform so Linux-only tools can be hidden on macOS, matching the README’s OS-aware menu behavior.

3. **Tool catalog as the main subsystem**
   - The `tools/` package is the repo’s largest architectural boundary: each module maps to a security domain such as web attack, wireless, phishing, reverse engineering, cloud security, and active directory.
   - The structure is category-first, not protocol-first: each file acts as a curated adapter layer around many independent upstream tools.
   - `tools/tool_manager.py` likely centralizes listing, selection, install status, updates, and category navigation.

4. **Category boundaries**
   - The repository is organized around about 20 categories, including information gathering, wordlist generation, SQL injection, XSS, payload creation, post-exploitation, forensics, mobile security, and “other tools.”
   - `tools/others/` holds additional subcategories that don’t fit the main menu buckets, such as social media, email verification, hash cracking, web crawling, homograph attacks, payload injection, and Android-related utilities.
   - This implies the app is designed as a navigational shell over an ecosystem of separate utilities rather than a monolithic framework.

5. **Execution model**
   - The app does not reimplement offensive/security functionality itself; it shells out to installed binaries, clone targets, or language-specific tool entrypoints.
   - The runtime flow is: user selects a category/tool → the manager checks install state → the tool module constructs or invokes the appropriate install/run/update command → control is delegated to the external tool.
   - The README’s “install status” and “update” features indicate command execution and package-manager integration are first-class behaviors.

6. **Dependency and environment handling**
   - `requirements.txt` defines the Python-side dependencies for the launcher.
   - The README also shows non-Python dependencies are important to the architecture: Go, Ruby, and Docker are used because many bundled tools are implemented in those ecosystems.
   - This means the repo’s operational boundary crosses multiple runtimes, with Python acting as the orchestrator.

7. **Installation and bootstrap path**
   - `install.py` and `install.sh` are the bootstrap layer for local setup, while `update.sh` supports maintenance.
   - The Dockerfile and `docker-compose.yml` provide an isolated packaging/runtime path, with the image built locally rather than pulled from a third party.
   - The install flow is therefore multi-modal: manual Python install, scripted one-liner install, or containerized execution.

8. **Generated documentation and metadata**
   - `generate_readme.py` and `README_template.md` suggest the catalog documentation is generated from structured tool metadata rather than maintained manually.
   - That implies tool definitions likely exist in code as a registry, and the README is a rendered view of that registry.
   - `images/` and `images/demo/` support documentation and UX presentation rather than core logic.

9. **Tool integration pattern**
   - Each file in `tools/` likely declares the tool’s title, description, supported OS, install command, and run command, as described in the contributing section.
   - The project expects contributors to add a new Python class/module per tool, which reinforces a plug-in style architecture.
   - Because tool entries include update and folder-open actions, each tool behaves like a managed integration, not just a static menu item.

10. **User interaction and menu semantics**
   - The main interface is keyboard-driven, with search, tag filtering, recommendation, help, back, quit, and “install all” shortcuts.
   - This suggests a stateful CLI UI that maintains menu depth and selection context.
   - The architecture likely centers on a loop in the core layer that renders menus, receives commands, and dispatches into the tool registry.

11. **External services and upstream tool boundaries**
   - The “real work” happens in many third-party projects such as Nmap, sqlmap, nuclei, ffuf, BloodHound, MobSF, Ghidra, and others.
   - Those integrations are the main external boundary of the system: this repo bundles discovery, install, and invocation for tools it does not own.
   - The README’s starred items indicate tools that may require extra installation or are more tightly integrated with package managers.

12. **What an architecture diagram should emphasize**
   - Show a thin Python CLI core in the center.
   - Surround it with a registry of category/tool modules.
   - Add separate paths for environment detection, install/update automation, and documentation generation.
   - Treat all security utilities in `tools/` as downstream external executables/services, with Docker and shell scripts as packaging/bootstrapping layers.

Main entry points: [`tools/tool_manager.py`](https://github.com/z4nzu/hackingtool/blob/master/tools/tool_manager.py) (Tool Manager), [`core.py`](https://github.com/z4nzu/hackingtool/blob/master/core.py) (Menu Core), [`os_detect.py`](https://github.com/z4nzu/hackingtool/blob/master/os_detect.py) (OS Detect), [`generate_readme.py`](https://github.com/z4nzu/hackingtool/blob/master/generate_readme.py) (Doc Generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Core CLI"]
  node_n_hackingtool["Launcher<br/>cli entrypoint<br/>[hackingtool.py]"]
  node_n_core["Menu Core<br/>runtime loop<br/>[core.py]"]
  node_n_config["Config<br/>settings<br/>[config.py]"]
  node_n_constants["Constants<br/>definitions<br/>[constants.py]"]
  node_n_os_detect{{"OS Detect<br/>platform gate<br/>[os_detect.py]"}}
end

subgraph group_group_tools["Tool Catalog"]
  node_n_tool_manager["Tool Manager<br/>catalog manager<br/>[tool_manager.py]"]
  node_n_information["Info Gathering<br/>tool category"]
  node_n_web_attack["Web Attack<br/>tool category<br/>[web_attack.py]"]
  node_n_wireless["Wireless<br/>tool category<br/>[wireless_attack.py]"]
  node_n_phishing["Phishing<br/>tool category<br/>[phishing_attack.py]"]
  node_n_payloads["Payloads<br/>tool category<br/>[payload_creator.py]"]
  node_n_post["Post-Exploitation<br/>tool category"]
  node_n_forensics["Forensics<br/>tool category<br/>[forensics.py]"]
  node_n_mobile["Mobile Security<br/>tool category<br/>[mobile_security.py]"]
  node_n_others["Other Tools<br/>tool category<br/>[other_tools.py]"]
end

subgraph group_group_ops["Bootstrap & Docs"]
  node_n_install["Install<br/>bootstrap script<br/>[install.py]"]
  node_n_shell_install["Shell Setup<br/>bootstrap script<br/>[install.sh]"]
  node_n_update["Update<br/>maintenance script<br/>[update.sh]"]
  node_n_dockerfile["Dockerfile<br/>container build"]
  node_n_compose["Compose<br/>container runtime<br/>[docker-compose.yml]"]
  node_n_readmegen["Doc Generator<br/>documentation pipeline<br/>[generate_readme.py]"]
  node_n_template["README Template<br/>documentation template<br/>[README_template.md]"]
end

node_n_hackingtool -->|"starts"| node_n_core
node_n_core -->|"loads"| node_n_config
node_n_core -->|"uses"| node_n_constants
node_n_core -->|"gates"| node_n_os_detect
node_n_core -->|"dispatches"| node_n_tool_manager
node_n_tool_manager -->|"navigates"| node_n_information
node_n_tool_manager -->|"navigates"| node_n_web_attack
node_n_tool_manager -->|"navigates"| node_n_wireless
node_n_tool_manager -->|"navigates"| node_n_phishing
node_n_tool_manager -->|"navigates"| node_n_payloads
node_n_tool_manager -->|"navigates"| node_n_post
node_n_tool_manager -->|"navigates"| node_n_forensics
node_n_tool_manager -->|"navigates"| node_n_mobile
node_n_tool_manager -->|"navigates"| node_n_others
node_n_information -->|"filters"| node_n_os_detect
node_n_web_attack -->|"filters"| node_n_os_detect
node_n_tool_manager -->|"bootstraps"| node_n_install
node_n_tool_manager -->|"bootstraps"| node_n_shell_install
node_n_tool_manager -->|"maintains"| node_n_update
node_n_tool_manager -->|"packages"| node_n_dockerfile
node_n_dockerfile -->|"pairs with"| node_n_compose
node_n_readmegen -->|"renders"| node_n_template
node_n_readmegen -->|"reads"| node_n_config

click node_n_hackingtool "https://github.com/z4nzu/hackingtool/blob/master/hackingtool.py"
click node_n_core "https://github.com/z4nzu/hackingtool/blob/master/core.py"
click node_n_config "https://github.com/z4nzu/hackingtool/blob/master/config.py"
click node_n_constants "https://github.com/z4nzu/hackingtool/blob/master/constants.py"
click node_n_os_detect "https://github.com/z4nzu/hackingtool/blob/master/os_detect.py"
click node_n_tool_manager "https://github.com/z4nzu/hackingtool/blob/master/tools/tool_manager.py"
click node_n_information "https://github.com/z4nzu/hackingtool/blob/master/tools/information_gathering.py"
click node_n_web_attack "https://github.com/z4nzu/hackingtool/blob/master/tools/web_attack.py"
click node_n_wireless "https://github.com/z4nzu/hackingtool/blob/master/tools/wireless_attack.py"
click node_n_phishing "https://github.com/z4nzu/hackingtool/blob/master/tools/phishing_attack.py"
click node_n_payloads "https://github.com/z4nzu/hackingtool/blob/master/tools/payload_creator.py"
click node_n_post "https://github.com/z4nzu/hackingtool/blob/master/tools/post_exploitation.py"
click node_n_forensics "https://github.com/z4nzu/hackingtool/blob/master/tools/forensics.py"
click node_n_mobile "https://github.com/z4nzu/hackingtool/blob/master/tools/mobile_security.py"
click node_n_others "https://github.com/z4nzu/hackingtool/blob/master/tools/other_tools.py"
click node_n_install "https://github.com/z4nzu/hackingtool/blob/master/install.py"
click node_n_shell_install "https://github.com/z4nzu/hackingtool/blob/master/install.sh"
click node_n_update "https://github.com/z4nzu/hackingtool/blob/master/update.sh"
click node_n_dockerfile "https://github.com/z4nzu/hackingtool/tree/master/Dockerfile"
click node_n_compose "https://github.com/z4nzu/hackingtool/blob/master/docker-compose.yml"
click node_n_readmegen "https://github.com/z4nzu/hackingtool/blob/master/generate_readme.py"
click node_n_template "https://github.com/z4nzu/hackingtool/blob/master/README_template.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_hackingtool,node_n_core,node_n_config,node_n_constants,node_n_os_detect toneBlue
class node_n_tool_manager,node_n_information,node_n_web_attack,node_n_wireless,node_n_phishing,node_n_payloads,node_n_post,node_n_forensics,node_n_mobile,node_n_others toneAmber
class node_n_install,node_n_shell_install,node_n_update,node_n_dockerfile,node_n_compose,node_n_readmegen,node_n_template toneMint
```

## Components

### Core CLI

Python launcher, shared configuration, and environment gating.

- [Launcher](https://github.com/z4nzu/hackingtool/blob/master/hackingtool.py): cli entrypoint · Top-level command that starts the application. · `hackingtool.py`
- [Menu Core](https://github.com/z4nzu/hackingtool/blob/master/core.py): runtime loop · Interactive menu flow, selection, and dispatch logic. · `core.py`
- [Config](https://github.com/z4nzu/hackingtool/blob/master/config.py): settings · Shared runtime settings and tool metadata. · `config.py`
- [Constants](https://github.com/z4nzu/hackingtool/blob/master/constants.py): definitions · Global command, path, and label definitions. · `constants.py`
- [OS Detect](https://github.com/z4nzu/hackingtool/blob/master/os_detect.py): platform gate · Detects host platform and hides unsupported tools. · `os_detect.py`

### Tool Catalog

Curated security-tool modules organized by category.

- [Tool Manager](https://github.com/z4nzu/hackingtool/blob/master/tools/tool_manager.py): catalog manager · Coordinates listing, install state, updates, and navigation. · `tools/tool_manager.py`
- [Info Gathering](https://github.com/z4nzu/hackingtool/blob/master/tools/information_gathering.py): tool category · Reconnaissance and discovery integrations. · `tools/information_gathering.py`
- [Web Attack](https://github.com/z4nzu/hackingtool/blob/master/tools/web_attack.py): tool category · Web exploitation and HTTP-focused tooling. · `tools/web_attack.py`
- [Wireless](https://github.com/z4nzu/hackingtool/blob/master/tools/wireless_attack.py): tool category · Wireless and radio-related tooling. · `tools/wireless_attack.py`
- [Phishing](https://github.com/z4nzu/hackingtool/blob/master/tools/phishing_attack.py): tool category · Social engineering and credential capture tooling. · `tools/phishing_attack.py`
- [Payloads](https://github.com/z4nzu/hackingtool/blob/master/tools/payload_creator.py): tool category · Payload creation and injection integrations. · `tools/payload_creator.py`
- [Post-Exploitation](https://github.com/z4nzu/hackingtool/blob/master/tools/post_exploitation.py): tool category · Persistence, access, and follow-on operator tooling. · `tools/post_exploitation.py`
- [Forensics](https://github.com/z4nzu/hackingtool/blob/master/tools/forensics.py): tool category · Artifact analysis and incident-response tooling. · `tools/forensics.py`
- [Mobile Security](https://github.com/z4nzu/hackingtool/blob/master/tools/mobile_security.py): tool category · Android and mobile reverse-analysis tooling. · `tools/mobile_security.py`
- [Other Tools](https://github.com/z4nzu/hackingtool/blob/master/tools/other_tools.py): tool category · Overflow catalog for specialized subdomains. · `tools/other_tools.py`

### Bootstrap & Docs

Installation, containerization, and generated documentation paths.

- [Install](https://github.com/z4nzu/hackingtool/blob/master/install.py): bootstrap script · Scripted local setup for the launcher and dependencies. · `install.py`
- [Shell Setup](https://github.com/z4nzu/hackingtool/blob/master/install.sh): bootstrap script · One-line shell installation path. · `install.sh`
- [Update](https://github.com/z4nzu/hackingtool/blob/master/update.sh): maintenance script · Maintenance script for refreshing the installation. · `update.sh`
- [Dockerfile](https://github.com/z4nzu/hackingtool/tree/master/Dockerfile): container build · Builds the local container image for isolated execution. · `Dockerfile`
- [Compose](https://github.com/z4nzu/hackingtool/blob/master/docker-compose.yml): container runtime · Container orchestration entry for the packaged runtime. · `docker-compose.yml`
- [Doc Generator](https://github.com/z4nzu/hackingtool/blob/master/generate_readme.py): documentation pipeline · Generates catalog documentation from structured metadata. · `generate_readme.py`
- [README Template](https://github.com/z4nzu/hackingtool/blob/master/README_template.md): documentation template · Source template for rendered project documentation. · `README_template.md`

## Connections

- Launcher → Menu Core: starts · Launcher hands execution to the interactive core.
- Menu Core → Config: loads · Core reads shared settings and catalog metadata.
- Menu Core → Constants: uses · Core relies on command and label definitions.
- Menu Core → OS Detect: gates · Platform checks filter menus and tool availability.
- Menu Core → Tool Manager: dispatches · Core delegates category selection and tool actions.
- Tool Manager → Info Gathering: navigates · Manager exposes the info-gathering category.
- Tool Manager → Web Attack: navigates · Manager exposes the web-attack category.
- Tool Manager → Wireless: navigates · Manager exposes the wireless category.
- Tool Manager → Phishing: navigates · Manager exposes the phishing category.
- Tool Manager → Payloads: navigates · Manager exposes payload creation and injection.
- Tool Manager → Post-Exploitation: navigates · Manager exposes post-exploitation tooling.
- Tool Manager → Forensics: navigates · Manager exposes forensics tooling.
- Tool Manager → Mobile Security: navigates · Manager exposes mobile security tooling.
- Tool Manager → Other Tools: navigates · Manager exposes the overflow category.
- Info Gathering → OS Detect: filters · Category modules respect platform constraints.
- Web Attack → OS Detect: filters · Category modules respect platform constraints.
- Tool Manager → Install: bootstraps · Install path sets up the launcher and dependencies.
- Tool Manager → Shell Setup: bootstraps · Shell path provides quick environment setup.
- Tool Manager → Update: maintains · Update path refreshes installed tools and assets.
- Tool Manager → Dockerfile: packages · Container image provides isolated execution.
- Dockerfile → Compose: pairs with · Compose defines the container runtime wiring.
- Doc Generator → README Template: renders · Generator turns structured metadata into docs.
- Doc Generator → Config: reads · Documentation generation uses catalog data.
