How z4nzu/hackingtool works
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: tool_manager.py Tool Manager · core.py Menu Core · os_detect.py OS Detect · generate_readme.py Doc Generator
Components 22
Core CLI
Python launcher, shared configuration, and environment gating.
- Launcher · Top-level command that starts the application.
hackingtool.py - Menu Core · Interactive menu flow, selection, and dispatch logic.
core.py - Config · Shared runtime settings and tool metadata.
config.py - Constants · Global command, path, and label definitions.
constants.py - OS Detect · Detects host platform and hides unsupported tools.
os_detect.py
Tool Catalog
Curated security-tool modules organized by category.
- Tool Manager · Coordinates listing, install state, updates, and navigation.
tools/tool_manager.py - Info Gathering · Reconnaissance and discovery integrations.
tools/information_gathering.py - Web Attack · Web exploitation and HTTP-focused tooling.
tools/web_attack.py - Wireless · Wireless and radio-related tooling.
tools/wireless_attack.py - Phishing · Social engineering and credential capture tooling.
tools/phishing_attack.py - Payloads · Payload creation and injection integrations.
tools/payload_creator.py - Post-Exploitation · Persistence, access, and follow-on operator tooling.
tools/post_exploitation.py - Forensics · Artifact analysis and incident-response tooling.
tools/forensics.py - Mobile Security · Android and mobile reverse-analysis tooling.
tools/mobile_security.py - Other Tools · Overflow catalog for specialized subdomains.
tools/other_tools.py
Bootstrap & Docs
Installation, containerization, and generated documentation paths.
- Install · Scripted local setup for the launcher and dependencies.
install.py - Shell Setup · One-line shell installation path.
install.sh - Update · Maintenance script for refreshing the installation.
update.sh - Dockerfile · Builds the local container image for isolated execution.
Dockerfile - Compose · Container orchestration entry for the packaged runtime.
docker-compose.yml - Doc Generator · Generates catalog documentation from structured metadata.
generate_readme.py - README Template · Source template for rendered project documentation.
README_template.md
Connections 23
- 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.