Hack Smarter Swarm: AI Pentesting Assistant

Author: Tyler Ramsbey
Organizations: Kairos Sec | Hack Smarter

Note from Tyler: I wouldn't use this in a client environment (yet). This initially started as a small project because I wanted to learn LangGraph; but I decide to expand it and make it available for others to learn from. I'll be adding to it extensively in the near future.

Overview

Hack Smarter Swarm is a multi-agent AI penetration testing assistant built to assist (not replace) ethical hackers and security professionals. Powered by LangGraph and Gemini, the swarm acts as your automated reconnaissance and initial vulnerability assessment assistant.

It orchestrates industry-standard open-source tools to autonomously map attack surfaces, verify live web servers, probe for vulnerabilities, and eliminate false positives, saving you time and giving you a head-start on deeper, manual exploitation.

Changing the LLM Model

Hack Smarter Swarm is built using Gemini, but since it uses LangChain, it is very easy to swap to another model provider (like OpenAI or Anthropic).

1. Open agents.py.
2. Locate the llm initialization near the top of the file: llm = ChatGoogleGenerativeAI(...).
3. Import the required Chat model from LangChain (e.g., from langchain_openai import ChatOpenAI).
4. Replace the llm variable with your new model (e.g., llm = ChatOpenAI(model="gpt-4o", temperature=0)).
5. Add your new API key to the .env file and install the corresponding LangChain partner package via pip.

The Philosophy: Assisting, NEVER Replacing

Unlike many open-source projects that chase full autonomy or try to completely abstract away the human element with a "black box" hack button, this swarm is built purely to be an assistant. It handles the tedious, time-consuming tasks:

• Deduplicating subdomains.
• Correlating nmap outputs with live httpx findings.
• Running nuclei and then actively weeding out false positives for you.

You get a clean, validated dradis_import.json and a Markdown report with concrete Proof of Concepts (PoCs). You do the deep-dive manual exploitation.

Features

• Multi-Agent Architecture:
  • Tactical Recon Specialist: Handles domain discovery, port scanning, and WordPress-specific vulnerability checks.
  • Vuln Worker: Identifies web surfaces, runs Nuclei, and verifies vulnerabilities using LLM logic.
  • Strategy & Reporting Node: Analyzes results, determines if it should pivot deeper, and generates professional summaries.
• Deduplication & State Management: Maintains a persistent local ledger (recon.db via SQLite) of findings across loops.
• False-Positive Reduction: Actively verifies potential vulnerabilities using an AI agent armed with curl, nmap, nc (Netcat), ssh-audit, hydra, and testssl.sh. It will then provide the full PoC to make it easy to reproduce.
• Engagement Organization: Automatically organizes all outputs into client-specific folders.
• Reporting Ready: Automatically outputs:
  • clients/<client_name>/final_report.md: A high-level, human-readable executive summary.
  • clients/<client_name>/dradis_import.json: A structured JSON file ready for ingestion into reporting platforms like Dradis.

Running with Docker (Recommended)

To avoid installing all system dependencies manually, you can run the entire swarm using Docker.

1. Build the Image

docker build -t hacksmarter .

2. Run the Swarm

Ensure you mount your .env file for API keys and the clients/ directory for persistence.

docker run --rm -it \
  -v $(pwd)/.env:/app/.env \
  -v $(pwd)/clients:/app/clients \
  hacksmarter -t example.com -c My_Client -v

Prerequisites

Python Dependencies

Python 3.10+ is recommended. Install the required Python libraries:

pip install -r requirements.txt

System Dependencies (Pentesting Tools)

The AI interacts with the following command-line binaries. Ensure they are installed and accessible in your system's $PATH:

• Subfinder
• Nmap
• HTTPX Toolkit (Make sure the alias is httpx-toolkit)
• Nuclei
• curl
• nc (Netcat)
• Hydra
• WPScan
• testssl.sh
• feroxbuster

Environment Variables

You need a Google Gemini API Key. Ensure it is placed in a .env file in the root of the project:

GOOGLE_API_KEY="your_api_key_here"
WPSCAN_API_TOKEN="your_wpscan_token_here"

Usage

python hacksmarter.py -t <target>

You can pass a single domain, a comma-separated list of domains, or a .txt file containing your scope:

# Single Target
python hacksmarter.py -t example.com

# Multiple Targets
python hacksmarter.py -t "example.com, 192.168.1.1"

# Target File
python hacksmarter.py -t scope.txt

Organised Engagements

Use the -c or --client flag to save all results (database, JSON, and Markdown reports) into a dedicated folder under clients/.

python hacksmarter.py -t example.com -c AcmeCorp
# Findings saved to clients/AcmeCorp/recon.db

Excluding Tools

You can exclude specific tools using the -x or --exclude flag. It supports substrings (e.g., ferox will skip run_feroxbuster_tool).

# Excluding tools
python hacksmarter.py -t example.com -x nuclei,ferox

Combined Example

# Watch Nuclei progress and save everything to a client folder
python hacksmarter.py -t example.com -c InternalAudit -v

---

Verbose Output

python hacksmarter.py -t example.com -v

Task Management (Signal Handling)

• Single Ctrl+C: Skips the current running task (e.g., its current feroxbuster scan) and moves to the next one. The skip is recorded in the database so the AI won't retry it.
• Double Ctrl+C: Pressing Ctrl+C twice within 2 seconds triggers an Emergency Exit, terminating all background processes and the AI swarm immediately.

Contributing

Hack Smarter Swarm is designed to be easily extensible. You can easily add more tools or modify the existing agents.

Adding New Tools

1. Open tools.py and define a new Python function that executes your desired tool (e.g., via subprocess).
2. Decorate the function with @tool from langchain_core.tools.
3. Include a detailed docstring explaining what the tool does and what its arguments are, as the LLM uses this to understand how to call it.
4. If your tool finds new subdomains, ports, or vulnerabilities, make sure to save the results to the shared state using update_db(key, data).

Modifying Agents

1. Open agents.py.
2. Locate the node for the agent you want to modify (e.g., recon_node or vuln_node).
3. Import your newly created tool from tools.py at the top of the file.
4. Add your tool to the agent's tool list (e.g., recon_tools or verification_tools).
5. Update the agent's system_prompt to give the AI context on when and how to use your tool, or how its overall strategy should change.