​

Contributing to HackingTool

​

Getting Started

​

Prerequisites

• Python 3.x installed
• Git installed and configured
• A GitHub account
• Familiarity with Python object-oriented programming
• Understanding of the tool you want to add

​

Fork and Clone

​

Project Structure

hackingtool/
├── core.py                    # Core classes: HackingTool, HackingToolsCollection
├── hackingtool.py            # Main entry point
├── install.py                # Installation script
├── requirements.txt          # Python dependencies
├── tools/                    # All tool implementations
│   ├── anonsurf.py          # Anonymity tools
│   ├── information_gathering_tools.py
│   ├── wireless_attack_tools.py
│   ├── sql_tools.py
│   ├── phising_attack.py
│   ├── webattack.py
│   ├── post_exploitation.py
│   ├── forensic_tools.py
│   ├── payload_creator.py
│   ├── exploit_frameworks.py
│   ├── reverse_engineering.py
│   ├── ddos.py
│   ├── remote_administration.py
│   ├── xss_attack.py
│   ├── steganography.py
│   ├── wordlist_generator.py
│   ├── other_tools.py
│   └── others/              # Subcategory tools
│       ├── android_attack.py
│       ├── email_verifier.py
│       ├── hash_crack.py
│       ├── homograph_attacks.py
│       ├── mix_tools.py
│       ├── payload_injection.py
│       ├── socialmedia.py
│       ├── socialmedia_finder.py
│       ├── web_crawling.py
│       └── wifi_jamming.py
└── .github/
    ├── workflows/            # CI/CD workflows
    └── ISSUE_TEMPLATE/      # Issue templates

​

Understanding core.py

​

HackingTool Class

class HackingTool(object):
    TITLE: str = ""                      # Tool display name
    DESCRIPTION: str = ""                # Tool description
    INSTALL_COMMANDS: List[str] = []     # Installation commands
    INSTALLATION_DIR: str = ""           # Where tool is installed
    UNINSTALL_COMMANDS: List[str] = []   # Uninstall commands
    RUN_COMMANDS: List[str] = []         # Commands to run the tool
    OPTIONS: List[Tuple[str, Callable]] = []  # Custom options
    PROJECT_URL: str = ""                # GitHub/project URL

• install() - Executes installation commands (core.py:104)
• run() - Executes run commands (core.py:130)
• uninstall() - Removes the tool (core.py:118)
• show_options() - Displays tool menu (core.py:64)
• show_info() - Shows tool information (core.py:58)

​

HackingToolsCollection Class

class HackingToolsCollection(object):
    TITLE: str = ""           # Collection name
    DESCRIPTION: str = ""     # Collection description  
    TOOLS: List = []          # List of HackingTool instances

​

Adding a New Tool

​

Step 1: Choose the Right Category

• Anonymity (anonsurf.py)
• Information Gathering (information_gathering_tools.py)
• Wireless Attacks (wireless_attack_tools.py)
• SQL Injection (sql_tools.py)
• Phishing (phising_attack.py)
• Web Attacks (webattack.py)
• Post Exploitation (post_exploitation.py)
• Forensics (forensic_tools.py)
• Payload Creation (payload_creator.py)
• Exploit Frameworks (exploit_frameworks.py)
• Reverse Engineering (reverse_engineering.py)
• DDoS (ddos.py)
• Remote Administration (remote_administration.py)
• XSS Attacks (xss_attack.py)
• Steganography (steganography.py)
• Wordlist Generation (wordlist_generator.py)
• Other Tools (other_tools.py or subcategories in others/)

​

Step 2: Create Your Tool Class

# In tools/information_gathering_tools.py

from core import HackingTool

class YourNewTool(HackingTool):
    TITLE = "Your Tool Name"
    DESCRIPTION = "Brief description of what this tool does"
    
    # Installation commands - executed in order
    INSTALL_COMMANDS = [
        "git clone https://github.com/author/tool-repo.git",
        "cd tool-repo && pip install -r requirements.txt",
    ]
    
    # Commands to run the tool
    RUN_COMMANDS = [
        "cd tool-repo && python3 tool.py"
    ]
    
    # Project URL for reference
    PROJECT_URL = "https://github.com/author/tool-repo"
    
    def __init__(self):
        super(YourNewTool, self).__init__()

​

Step 3: Add to Collection

# Find the collection class in the same file
class InformationGatheringTools(HackingToolsCollection):
    TITLE = "Information Gathering Tools"
    DESCRIPTION = "Tools for reconnaissance and information gathering"
    TOOLS = [
        NetworkMapper(),
        PortScanner(),
        # ... other existing tools ...
        YourNewTool(),  # Add your tool here
    ]

​

Step 4: Advanced Tool Options

class AdvancedTool(HackingTool):
    TITLE = "Advanced Tool"
    DESCRIPTION = "Tool with custom options"
    INSTALL_COMMANDS = ["git clone https://github.com/example/tool.git"]
    RUN_COMMANDS = ["cd tool && ./run.sh"]
    PROJECT_URL = "https://github.com/example/tool"
    
    def __init__(self):
        # Add custom options
        super(AdvancedTool, self).__init__([
            ("Custom Action 1", self.custom_action_1),
            ("Custom Action 2", self.custom_action_2),
        ])
    
    def custom_action_1(self):
        """Implement your custom action"""
        console.print("[cyan]Running custom action 1...[/cyan]")
        os.system("your-custom-command")
    
    def custom_action_2(self):
        """Another custom action"""
        console.print("[yellow]Running custom action 2...[/yellow]")
        os.system("another-command")

​

Step 5: Lifecycle Hooks

class CustomTool(HackingTool):
    TITLE = "Custom Tool"
    DESCRIPTION = "Tool with lifecycle hooks"
    INSTALL_COMMANDS = ["git clone https://example.com/tool.git"]
    RUN_COMMANDS = ["./tool"]
    
    def before_install(self):
        """Called before installation"""
        console.print("[yellow]Preparing to install...[/yellow]")
        # Create directories, check prerequisites, etc.
    
    def after_install(self):
        """Called after installation"""
        console.print("[green]Tool installed successfully![/green]")
        console.print("[cyan]Running post-install configuration...[/cyan]")
        # Post-installation setup
    
    def before_run(self):
        """Called before running"""
        console.print("[yellow]Starting tool...[/yellow]")
        # Pre-run checks
    
    def after_run(self):
        """Called after running"""
        console.print("[green]Tool execution completed[/green]")
        # Cleanup, save results, etc.
    
    def before_uninstall(self) -> bool:
        """Called before uninstall - return False to cancel"""
        return console.input("Are you sure? [y/n]: ").lower() == 'y'
    
    def after_uninstall(self):
        """Called after uninstall"""
        console.print("[red]Tool removed[/red]")

​

Code Style Guidelines

​

Follow Python Conventions

1. Use Rich library for output:
   from rich.console import Console
   console = Console()
   console.print("[green]Success![/green]")
   
2. Follow PEP 8 naming:
   • Classes: PascalCase
   • Functions/variables: snake_case
   • Constants: UPPER_CASE
3. Add docstrings:
   def custom_function(self):
       """Brief description of what this function does."""
       pass
   
4. Use type hints (Python 3.7+):
   from typing import List, Tuple, Callable
   
   OPTIONS: List[Tuple[str, Callable]] = []
   

​

Testing Your Changes

# Run the tool locally
sudo python3 hackingtool.py

# Navigate to your tool and test:
# - Installation
# - Running
# - Uninstallation (if applicable)
# - Custom options

# Format code with black
pip install black
black .

# Run linting
pip install ruff
ruff .

# Check types
pip install mypy
mypy --ignore-missing-imports .

​

Submitting Pull Requests

​

Create a Feature Branch

# Update your fork
git checkout master
git pull upstream master

# Create a feature branch
git checkout -b add-new-tool-name

​

Make Your Changes

​

Push and Create PR

# Push to your fork
git push origin add-new-tool-name

1. Go to your fork on GitHub
2. Click “Compare & pull request”
3. Fill out the PR template with:
   • Description of the tool
   • Category it belongs to
   • Why it should be included
   • Testing performed
   • Screenshots (if applicable)

​

PR Review Process

1. Automated checks will run:
   • Installation test (test_install.yml)
   • Python linting (lint_python.yml)
2. Maintainer review:
   • Code quality check
   • Tool relevance verification
   • Security considerations
3. Address feedback:
   # Make requested changes
   git add .
   git commit -m "Address PR feedback"
   git push origin add-new-tool-name
   

​

Contributing Beyond Code

​

Documentation

• Improve README.md
• Add usage examples
• Write tutorials
• Translate documentation

​

Bug Reports

• OS and version
• Python version
• Steps to reproduce
• Expected vs actual behavior
• Error messages/logs

​

Feature Requests

• The problem you’re trying to solve
• Your proposed solution
• Alternative approaches considered
• Additional context

​

Suggest New Tools

​

Community Guidelines

​

Be Respectful

• Treat all contributors with respect
• Provide constructive feedback
• Be patient with newcomers
• Follow the code of conduct

​

Stay On Topic

• Keep discussions relevant to the project
• Use appropriate channels (issues, PRs, discussions)
• Don’t spam or self-promote

​

Ethical Considerations

​

Development Tips

​

Debug Mode

# Enable rich tracebacks (already enabled in core.py)
from rich.traceback import install
install(show_locals=True)

​

Testing Individual Tools

# Test your tool class directly
if __name__ == "__main__":
    tool = YourNewTool()
    tool.show_options()

​

Check Existing Implementations

• Simple tool: tools/anonsurf.py:17-36 (AnonymouslySurf)
• Tool with options: tools/anonsurf.py:30-36 (custom stop method)
• Non-runnable tool: tools/anonsurf.py:39-53 (Multitor)

​

Resources

• Project Repository: https://github.com/Z4nzu/hackingtool
• Report Issues: GitHub Issues
• Feature Requests: Google Form
• Python Rich Documentation: https://rich.readthedocs.io/

​

Thank You!