Noureddine RAMDI / Hackingtool Plugin: a smart dispatcher for 183 pentesting tools with native, WSL, and Docker backends

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
1209 Words
github-stars python pentesting docker cli security automation

AKCodez/hackingtool-plugin

If you’ve ever wrestled with managing dozens of pentesting and OSINT tools across different environments, you know how frustrating dependencies and platform quirks can be. The hackingtool-plugin takes a pragmatic approach: it wraps a comprehensive arsenal of 183 security tools into a Claude Code plugin, making them callable from natural language prompts. Under the hood, it uses a smart dispatcher that picks the best execution environment for each tool — native Bash, WSL on Windows, or purpose-built Docker containers — avoiding complex installation chains and delivering structured JSON output.

What hackingtool-plugin does and its architecture

Hackingtool-plugin is essentially a Claude Code plugin that brings together the complete hackingtool suite by Z4nzu, which includes a wide range of pentesting and OSINT utilities. Instead of requiring users to install and configure each tool manually, this plugin exposes the entire arsenal through natural language commands processed by Claude AI.

The core of the plugin lies in its dispatch layer, primarily implemented in the Python scripts ht_run.py and ht_env.py. These components intelligently determine how to run a given tool based on the user’s environment and the tool’s requirements. On Linux and macOS systems, tools run natively via Bash. On Windows, WSL (Windows Subsystem for Linux) is used to provide a compatible Bash environment. When native execution is not feasible or when a tool has complex dependencies, the plugin falls back to running the tool inside one of over 22 curated Docker containers.

These Docker containers are purpose-built images optimized for specific tools or tool categories. Examples include instrumentisto/nmap for network scanning, projectdiscovery/nuclei for vulnerability scanning, and megadose/holehe for email enumeration. This containerized approach ensures consistent, isolated environments without polluting the host system or forcing users into tedious manual installs.

Each tool in the hackingtool arsenal is classified into two categories: plug-and-play (green), which work out of the box in the user’s native or WSL environment, and environment-dependent (yellow), which require Docker containers for proper execution. This classification helps the dispatcher choose the optimal backend dynamically.

One of the standout architectural features is the automatic privilege escalation retry mechanism. If a tool execution fails due to permission errors, the dispatcher attempts to rerun it with elevated privileges, reducing friction for users who might otherwise need to manually invoke sudo or run shells as admin.

The plugin captures tool output and transforms it into structured JSON, which Claude Code then ingests. This approach drastically improves the developer experience by eliminating raw terminal noise and making results machine-readable for further automated reasoning or reporting.

How the smart dispatch system streamlines pentesting tool usage

The technical design of hackingtool-plugin revolves around its dispatch system, which is surprisingly clean and pragmatic given the complexity of integrating 183 different tools.

By supporting three execution backends — native Bash, WSL, and Docker — it covers the major operating system scenarios that pentesters are likely to encounter. This flexibility means users don’t have to manually install dozens of dependencies or manage conflicting versions.

The curated Docker images are a crucial part of the architecture. Instead of a single bloated container, the plugin uses over 22 specialized images, each tailored with just the right dependencies and configurations for their assigned tools. This minimizes container size and startup time, and reduces attack surface.

The classification of tools into plug-and-play vs environment-dependent is a practical tradeoff. It acknowledges that some tools can run directly on the host, while others are too complex or platform-specific. The dispatch layer’s logic encapsulates this complexity, so users see a unified command interface regardless of the underlying tool environment.

Another key strength is the automatic privilege escalation retry. Permission errors are a common pain point when running security tools, especially those requiring raw socket access, port scanning, or system inspection. The plugin detects these errors and transparently retries with elevated privileges, improving workflow smoothness.

The structured JSON output is particularly valuable when integrating with AI-driven workflows like Claude Code. Instead of parsing messy terminal logs, the AI gets clean, parseable data that can be used to generate reports, alerts, or next-step recommendations.

The code quality in ht_run.py and ht_env.py reflects careful engineering: clear separation of concerns, robust error handling, and modular design that would make extending or customizing the plugin feasible.

The tradeoff is the added complexity of managing multiple execution backends and Docker dependencies. Users on Windows need WSL installed, and those relying on Docker must keep their daemon running. Also, while the plugin handles privilege escalation retries, users still need to have the rights to elevate privileges.

Overall, the plugin’s architecture balances usability, environment flexibility, and tool coverage in a way that works well for the messy reality of pentesting environments.

Quick start

To get started with hackingtool-plugin, you install it directly from the Claude Code plugin marketplace with these commands:

/plugin marketplace add AKCODEZ/hackingtool-plugin
/plugin install hackingtool@hackingtool-marketplace

Once installed, you simply point Claude at your target and issue natural language commands like:

"recon example.com"
"hunt the username johndoe"
"scan my repo for vulnerabilies"
"crack my own wifi before my neighbor does"

Claude automatically picks the appropriate tools and execution backend. You then read the structured JSON output it returns, which is clean and easy to interpret.

verdict

Hackingtool-plugin is a solid practical tool for pentesters and security researchers who want access to a vast collection of tools without the usual hassle of environment setup and dependency management. Its smart dispatch system that picks between native Bash, WSL, and purpose-built Docker containers is a thoughtful solution to a common pain point.

The plugin shines where you need broad tool coverage and want to integrate pentesting workflows with AI assistants like Claude Code. However, the reliance on Docker and WSL may complicate setup for some users, and the automatic privilege escalation requires appropriate system rights.

If your workflow involves running multiple pentesting or OSINT tools regularly and you want a unified interface that abstracts away environment headaches, hackingtool-plugin is worth exploring. Otherwise, for lightweight or single-tool use cases, the overhead might be unnecessary.

The codebase is clean and modular, making it approachable for contributors or users wanting to extend the plugin. Its approach to structured JSON output is particularly useful for integrating tool results into automated pipelines or AI-driven analysis.

In sum, hackingtool-plugin solves a real problem pragmatically, with a clear focus on usability and environment flexibility — a welcome addition to the pentesting toolbox.

→ GitHub Repo: AKCodez/hackingtool-plugin ⭐ 637 · Python