# How to Contribute to Z4nzu/hackingtool: A Complete Developer's Guide

> Learn how to contribute to Z4nzu/hackingtool by adding new tool modules and submitting a pull request. Follow our developer's guide to join the project.

- Repository: [Hardik Zinzuvadiya/hackingtool](https://github.com/Z4nzu/hackingtool)
- Tags: how-to-guide
- Published: 2026-03-06

---

**Yes, you can contribute to Z4nzu/hackingtool by creating new tool modules that inherit from the base `HackingTool` class, registering them in the main entry point, and submitting a pull request through GitHub.**

The Z4nzu/hackingtool repository is an open-source Python framework that aggregates dozens of security utilities into a unified, menu-driven CLI. To contribute to Z4nzu/hackingtool effectively, you need to understand its modular architecture built around base classes in [`core.py`](https://github.com/Z4nzu/hackingtool/blob/main/core.py) and tool definitions organized under the `tools/` directory.

## Understanding the HackingTool Architecture

The project follows a layered design that separates the CLI entry point, core abstractions, and individual tool implementations.

### CLI Entry Point

The [`hackingtool.py`](https://github.com/Z4nzu/hackingtool/blob/main/hackingtool.py) file serves as the application bootstrap. It contains the `main()` function that determines the host OS, prompts for an installation directory via `choose_path()`, and renders the **AllTools** collection. This file also maintains the `all_tools` list that aggregates every available tool collection.

### Core Abstractions

The [`core.py`](https://github.com/Z4nzu/hackingtool/blob/main/core.py) file defines the fundamental classes that every contributor must subclass:

- **`HackingTool`**: Represents a single security utility. You must implement `TITLE`, `DESCRIPTION`, `INSTALL_COMMANDS`, and `RUN_COMMANDS`. Optional custom actions can be passed to the constructor.
- **`HackingToolsCollection`**: Groups related tools under a single menu entry. It aggregates multiple `HackingTool` instances in its `TOOLS` list.

These classes handle Rich-styled UI rendering, shell command execution, and common helpers like `show_options()`.

### Tool Modules

Each logical category lives as a separate Python file under `tools/` (e.g., [`tools/anonsurf.py`](https://github.com/Z4nzu/hackingtool/blob/main/tools/anonsurf.py), [`tools/webattack.py`](https://github.com/Z4nzu/hackingtool/blob/main/tools/webattack.py), [`tools/other_tools.py`](https://github.com/Z4nzu/hackingtool/blob/main/tools/other_tools.py)). These modules instantiate concrete subclasses of `HackingTool` and organize them into collections.

## How to Add a New Tool to Z4nzu/hackingtool

Follow this five-step workflow to integrate a new security utility into the framework.

### 1. Create a Module Under `tools/`

Create a new Python file in the `tools/` directory. Use a descriptive name that matches the tool's category, such as [`tools/my_new_tool.py`](https://github.com/Z4nzu/hackingtool/blob/main/tools/my_new_tool.py).

### 2. Define a `HackingTool` Subclass

Import the base class from [`core.py`](https://github.com/Z4nzu/hackingtool/blob/main/core.py) and implement the required attributes:

```python
from core import HackingTool

class MyNewTool(HackingTool):
    TITLE = "My New Tool"
    DESCRIPTION = "Brief description of what the tool does."
    INSTALL_COMMANDS = [
        "sudo git clone https://github.com/example/mynewtool.git",
        "cd mynewtool && sudo ./install.sh && cd .. && sudo rm -rf mynewtool",
    ]
    RUN_COMMANDS = ["sudo mynewtool --run"]
    PROJECT_URL = "https://github.com/example/mynewtool"

```

Optional: Add custom actions by passing a list of `(name, function)` tuples to `super().__init__()`, such as `[("Stop", self.stop)]`.

### 3. Expose the Tool in a Collection

Wrap your tool in a `HackingToolsCollection` subclass:

```python
from core import HackingToolsCollection

class MyToolCollection(HackingToolsCollection):
    TITLE = "My Category"
    TOOLS = [MyNewTool()]

```

### 4. Register the Collection in [`hackingtool.py`](https://github.com/Z4nzu/hackingtool/blob/main/hackingtool.py)

Open [`hackingtool.py`](https://github.com/Z4nzu/hackingtool/blob/main/hackingtool.py) and add your import near the top:

```python
from tools.my_new_tool import MyToolCollection

```

Then append the collection to the `all_tools` list in the order you want it to appear in the UI:

```python
all_tools.append(MyToolCollection())

```

### 5. Update Documentation

Add your tool to [`README.md`](https://github.com/Z4nzu/hackingtool/blob/main/README.md) following the existing format, and update [`README_template.md`](https://github.com/Z4nzu/hackingtool/blob/main/README_template.md) if the project structure has changed. Include the tool name, description, and installation requirements.

## Testing Your Contribution

The repository uses GitHub Actions for continuous integration. Before submitting, verify your changes pass automated checks.

### Linting with flake8

The CI runs `flake8` via [`.github/workflows/lint_python.yml`](https://github.com/Z4nzu/hackingtool/blob/main/.github/workflows/lint_python.yml). Ensure your code follows PEP 8 standards:

```bash
pip install flake8
flake8 tools/my_new_tool.py

```

### Import Testing

While the project lacks unit tests, you can add a simple import test to prevent broken dependencies. Create or update [`tests/test_imports.py`](https://github.com/Z4nzu/hackingtool/blob/main/tests/test_imports.py):

```python
import importlib

def test_tool_imports():
    modules = [
        "tools.anonsurf",
        "tools.webattack",
        "tools.my_new_tool",  # add your new module here

    ]
    for m in modules:
        importlib.import_module(m)

```

Push this file to trigger the CI pipeline defined in [`.github/workflows/test_install.yml`](https://github.com/Z4nzu/hackingtool/blob/main/.github/workflows/test_install.yml).

## Submitting a Pull Request to Z4nzu/hackingtool

Follow the standard GitHub workflow to propose your changes.

1. **Fork** the repository to your GitHub account.
2. **Create a new branch** with a descriptive name: `git checkout -b feature/my-new-tool`.
3. **Commit** your changes with clear messages explaining what the tool does and why it fits the project.
4. **Push** to your fork: `git push origin feature/my-new-tool`.
5. **Open a Pull Request** against `Z4nzu/hackingtool:master`.

In your PR description, include:
- A summary of the tool's functionality.
- The installation and run commands you defined.
- Any new Python dependencies (add these to [`requirements.txt`](https://github.com/Z4nzu/hackingtool/blob/main/requirements.txt) if required).
- Confirmation that you tested the tool locally and it passes `flake8` linting.

A maintainer will review for code style, security implications of the shell commands, and alignment with the project's scope. Minor style fixes may be requested before merging.

## Summary

- **Z4nzu/hackingtool** uses a modular architecture with base classes `HackingTool` and `HackingToolsCollection` defined in [`core.py`](https://github.com/Z4nzu/hackingtool/blob/main/core.py).
- To contribute, create a new module under `tools/`, subclass `HackingTool` with `TITLE`, `DESCRIPTION`, `INSTALL_COMMANDS`, and `RUN_COMMANDS`, then wrap it in a collection.
- Register your collection in [`hackingtool.py`](https://github.com/Z4nzu/hackingtool/blob/main/hackingtool.py) by importing it and appending it to the `all_tools` list.
- Validate your code with `flake8` and add import tests to ensure CI passes via [`.github/workflows/test_install.yml`](https://github.com/Z4nzu/hackingtool/blob/main/.github/workflows/test_install.yml).
- Submit changes via a GitHub Pull Request with clear documentation and dependency updates.

## Frequently Asked Questions

### Do I need to be a cybersecurity expert to contribute to Z4nzu/hackingtool?

No, you do not need to be an expert. While the project aggregates security tools, contributing requires only basic Python knowledge and the ability to write shell commands for installation and execution. You can add existing open-source security tools by wrapping them in the `HackingTool` class without writing complex attack logic yourself.

### What Python version does Z4nzu/hackingtool require?

The project is built for **Python 3** and uses modern features like type hints and the `Rich` library for terminal UI. You should develop and test your contributions using Python 3.8 or higher to ensure compatibility with the [`requirements.txt`](https://github.com/Z4nzu/hackingtool/blob/main/requirements.txt) dependencies and the GitHub Actions CI environment.

### How do I test my new tool without installing system-wide?

You can test your tool in an isolated environment using the provided **Docker** configuration. Build the image with `docker build -t hackingtool .` and run it with `docker-compose up -d`, or use a Python virtual environment (`python -m venv venv`) to install dependencies locally without affecting your system packages. Always test installation commands in a sandbox before submitting a PR.

### Why was my pull request rejected?

Common reasons for rejection include failing the automated `flake8` linting checks, missing documentation updates in [`README.md`](https://github.com/Z4nzu/hackingtool/blob/main/README.md), hardcoded paths that break on non-Debian systems, or security concerns with installation commands (such as downloading unverified scripts with `curl | bash`). Ensure your code follows PEP 8, includes proper error handling, and clearly describes any new dependencies in your PR description.