HackBot

https://github.com/yashab-cyber/hackbot
Admin
HackBot is a production-ready AI-powered pentesting and cybersecurity assistant offering Agent,...
Tokens:161,315
Snippets:1,368
Trust Score:9.4
License:MIT
Update:17 hours ago
Show doc for...
Tokens:
Raw
### hackbot setup command example

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/02-cli-reference.md

Quick setup with an API key. The --provider and --model options specify the AI provider and model.

```bash
hackbot setup sk-xxxx --provider anthropic --model claude-sonnet-4-20250514
```

--------------------------------

### Campaign subcommand example

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/02-cli-reference.md

Example sequence for creating and managing a campaign: create a new campaign with targets, start it, advance to next target, show status, and generate a report.

```bash
/campaign new webapp_test app1.example.com app2.example.com api.example.com
/campaign start
/campaign next
/campaign status
/campaign report
```

--------------------------------

### Proxy subcommand example

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/02-cli-reference.md

Example sequence for using the proxy: start on port 8080, set scope, show traffic, show flags, show details, replay a request, export traffic, and stop.

```bash
/proxy start 8080
/proxy scope example.com
/proxy traffic 20
/proxy flags
/proxy detail 3
/proxy replay 3
/proxy export traffic_dump.json
/proxy stop
```

--------------------------------

### HttpClient usage example

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/15-zeroday-engine.md

Shows how to instantiate HttpClient with a ScanConfig, authenticate via login(), get a baseline, and make GET/POST requests with automatic cookie and auth persistence.

```python
from hackbot.core.zeroday_active import HttpClient, ScanConfig

config = ScanConfig(proxy="http://127.0.0.1:8080", request_delay=0.2)
client = HttpClient(config)

# Authenticate
client.login("http://target.com/login", "admin", "password123")

# Get baseline for an endpoint
baseline = client.get_baseline("http://target.com/api/search")

# Make requests (cookies and auth persist automatically)
resp = client.get("http://target.com/api/users")
resp = client.post("http://target.com/api/data", data={"key": "value"})
```

--------------------------------

### Start Hacking (Ethically!)

Source: https://github.com/yashab-cyber/hackbot/blob/main/README.md

Example of starting an agent session in the terminal UI.

```text
💬 hackbot> /agent scanme.nmap.org
```

--------------------------------

### Launch HackBot GUI with 'hackbot gui'

Source: https://github.com/yashab-cyber/hackbot/blob/main/README.md

Starts the native desktop GUI. If the GUI falls back to browser mode with errors like 'No module named qtpy' or 'No module named gi', install one of the native backends shown below.

```bash
hackbot gui
```

--------------------------------

### Full install with security tools

Source: https://github.com/yashab-cyber/hackbot/blob/main/website/index.html

Runs the installer with the 'full' argument to include security tools.

```bash
curl -sSL https://raw.githubusercontent.com/yashab-cyber/hackbot/main/install.sh | bash -s full
```

--------------------------------

### Add install action documentation to agent prompt

Source: https://github.com/yashab-cyber/hackbot/blob/main/docs/superpowers/plans/2026-06-22-autonomous-tool-install.md

Adds a numbered subsection to the agent prompt action documentation in hackbot/core/engine.py, describing autonomous tool installation with a JSON example and constraints.

```python
7. **Autonomous Tool Installation** — If a tool you need is not installed (a command
   returns "Tool not found"), you can install it autonomously:
   ```json
   {"action": "install", "tool": "<tool_name>", "explanation": "<why you need it>"}
   ```
   Only allowlisted security tools with a known install recipe can be installed.
   When safe_mode is on, the user confirms each install. After a successful install,
   re-run the original command. If the install fails or no recipe exists, adapt and
   use a different tool.
```

--------------------------------

### Install from Source (Developer Mode)

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/01-getting-started.md

Clones the repository and installs in editable mode with all and dev extras.

```bash
git clone https://github.com/yashab-cyber/hackbot.git
cd hackbot
pip install -e ".[all,dev]"
```

--------------------------------

### Install Qt backend for GUI fallback

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/10-troubleshooting.md

Install PyQt5 and qtpy in the virtual environment, then retry launching the GUI.

```bash
pip install PyQt5 qtpy
```

--------------------------------

### Run setup with provider and model flags

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/09-configuration.md

Terminal command to run setup with an API key, provider, and model.

```bash
hackbot setup YOUR_KEY --provider anthropic --model claude-sonnet-4-20250514
```

--------------------------------

### Install on Windows

Source: https://github.com/yashab-cyber/hackbot/blob/main/README.md

Two options for Windows: pip full install, or clone and run install.bat.

```powershell
# Option 1: pip (full install with GUI + all features)
pip install "hackbot[all] @ git+https://github.com/yashab-cyber/hackbot.git"

# Option 2: Download and run installer
git clone https://github.com/yashab-cyber/hackbot.git
cd hackbot
install.bat
```

--------------------------------

### Install PDF dependencies

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/07-reporting.md

Install the required packages for PDF report generation. The first command installs the optional PDF extras, the second installs the underlying libraries directly.

```bash
pip install hackbot[pdf]
# or
pip install reportlab matplotlib Pillow
```

--------------------------------

### Install security tools for 'No tools found'

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/10-troubleshooting.md

Install required security tools on Linux (Ubuntu/Debian) using apt, or run the full installer script. Check available tools with 'hackbot tools'.

```bash
# Linux (Ubuntu/Debian)
sudo apt install nmap nikto dirb hydra curl wget

# Full install with security tools
./install.sh full

# Check what's available
hackbot tools
```

--------------------------------

### Starting Agent Mode

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/04-modes.md

Commands to start Agent Mode with basic, scoped, or terminal options.

```bash
/agent 10.0.0.1                                        # Basic
/agent example.com --scope "Web app on port 443"        # With scope
hackbot agent 10.0.0.1 -s "DMZ network" -i "Focus on web apps"  # From terminal
```

--------------------------------

### Add Click install subcommand

Source: https://github.com/yashab-cyber/hackbot/blob/main/docs/superpowers/plans/2026-06-22-autonomous-tool-install.md

Adds a Click subcommand 'install' that takes a tool argument, builds a HackBotApp, and calls _install_tool.

```python
@main.command(name="install")
@click.argument("tool")
@click.pass_context
def install_cmd(ctx, tool):
    """Install a security tool that isn't present."""
    config = ctx.obj["config"]
    app = HackBotApp(config)
    app._install_tool(tool)
```

--------------------------------

### Full install via pip (GUI + PDF + all)

Source: https://github.com/yashab-cyber/hackbot/blob/main/website/index.html

Installs HackBot with all extras (GUI, PDF, and all) directly from the GitHub repository.

```bash
pip install "hackbot[all] @ git+https://github.com/yashab-cyber/hackbot.git"
```

--------------------------------

### Agent Mode Example

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/04-modes.md

Example interaction in Agent Mode showing the agent running tools and displaying findings.

```text
HackBot> /agent 10.0.0.1
🤖 Agent Mode — Starting assessment of 10.0.0.1

[Agent] Running: nmap -sV -sC 10.0.0.1
[Agent] Found 5 open ports. Analyzing services...
[Agent] Running: nikto -h http://10.0.0.1
[Agent] ⚠️ Finding: Outdated Apache 2.4.29 (HIGH)
[Agent] Running: sqlmap -u "http://10.0.0.1/search?q=test" --batch
...

HackBot> /findings
3 findings discovered:
  #1 [HIGH] Outdated Apache 2.4.29
  #2 [CRITICAL] SQL Injection in /search endpoint
  #3 [MEDIUM] Missing security headers
```

--------------------------------

### Run failing tests for install action

Source: https://github.com/yashab-cyber/hackbot/blob/main/docs/superpowers/plans/2026-06-22-autonomous-tool-install.md

Command to run the install-related tests and verify they fail. Expected failure: 'install' not parsed, AgentMode has no _process_install_action, or no installer attribute.

```bash
pytest tests/test_modes.py -k install -v
```

--------------------------------

### Agent Mode Start Commands

Source: https://github.com/yashab-cyber/hackbot/blob/main/README.md

Start Agent Mode directly from the command line or switch inside the app.

```bash
# Start directly
hackbot agent scanme.nmap.org

# Or switch inside the app
/agent 192.168.1.0/24
```

--------------------------------

### Install action JSON format

Source: https://github.com/yashab-cyber/hackbot/blob/main/docs/superpowers/specs/2026-06-22-autonomous-tool-install-design.md

The JSON format for the new 'install' agent action, documented in the agent system prompt. It includes the action name, the tool to install, and an explanation. The agent emits this action when a tool run returns 'Tool not found'.

```json
{"action": "install", "tool": "nuclei", "explanation": "needed to scan for known CVEs"}
```

--------------------------------

### Start the Ollama server

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/06-ai-providers.md

Starts the Ollama server, which runs on http://localhost:11434 by default.

```bash
ollama serve
# Runs on http://localhost:11434 by default
```

--------------------------------

### Lint and commit installer changes

Source: https://github.com/yashab-cyber/hackbot/blob/main/docs/superpowers/plans/2026-06-22-autonomous-tool-install.md

Runs ruff and black on the installer and test files, then stages and commits them with a conventional commit message.

```bash
ruff check hackbot/core/installer.py && black hackbot/core/installer.py tests/test_installer.py
git add hackbot/core/installer.py tests/test_installer.py
git commit -m "feat(installer): ToolInstaller manager detection and install planning"
```

--------------------------------

### /proxy start [port]

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/02-cli-reference.md

Starts the intercepting proxy, optionally on a specified port (default 8080).

```APIDOC
## /proxy start [port]

### Description
Starts the intercepting proxy, optionally on a specified port (default 8080).

### Method
CLI

### Endpoint
/proxy start

### Parameters
#### Arguments
- **port** (integer) - Optional - Port number (default 8080)

### Request Example
```
/proxy start 8080
```

### Response
No response body specified.
```

--------------------------------

### Start text-generation-webui with API and connect HackBot

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/06-ai-providers.md

Starts text-generation-webui with the API enabled on port 5000 and connects HackBot to the local provider using that base URL.

```bash
# Start with API enabled
python server.py --api --listen-port 5000

# Connect HackBot
hackbot --provider local --base-url http://localhost:5000/v1
```

--------------------------------

### Example /cve output

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/13-nvd-api-integration.md

Example output from the /cve command showing a summary of found vulnerabilities, including CVE IDs, CVSS scores, severity, and descriptions, followed by details for a specific CVE.

```text
## CVE Results

**5 vulnerabilities found**

| CVE ID | CVSS | Severity | Description |
|--------|------|----------|-------------|
| CVE-2021-44228 | 10.0 | Critical | Apache Log4j2 RCE via JNDI... |
| CVE-2021-45046 | 9.0 | Critical | Apache Log4j2 Thread Context... |
| CVE-2021-45105 | 7.5 | High | Apache Log4j2 DoS via... |

### CVE-2021-44228 — CVSS 10.0 (Critical)

Apache Log4j2 2.0-beta9 through 2.15.0 JNDI features do not protect
against attacker controlled LDAP and other JNDI related endpoints...

**Weaknesses:** CWE-502, CWE-400
**Published:** 2021-12-10

**Known Exploits:**
- kozmer/log4j-shell-poc ⭐ 1542
- fullhunt/log4j-scan ⭐ 3201
```

--------------------------------

### Quick Setup via CLI

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/01-getting-started.md

Sets API key and optional provider/model in one command.

```bash
hackbot setup YOUR_API_KEY --provider openai --model gpt-4o
```

--------------------------------

### GET /api/attack/from-agent JSON response

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/11-attack-mapping.md

Example JSON response from the GET /api/attack/from-agent endpoint. Contains a report object and a pre-formatted markdown string.

```json
{
    "report": { "target": "...", "by_tactic": {...}, ... },
    "markdown": "# MITRE ATT&CK Mapping\n..."
}
```

--------------------------------

### hackbot chat command example

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/02-cli-reference.md

Starts chat mode directly from the terminal.

```bash
hackbot chat
```

--------------------------------

### Quick Setup inside REPL

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/01-getting-started.md

Sets API key, provider, and model inside the interactive REPL.

```text
/key YOUR_API_KEY
/provider openai
/model gpt-4o
```

--------------------------------

### Install native GUI backends (PyQt5/qtpy and GTK)

Source: https://github.com/yashab-cyber/hackbot/blob/main/README.md

Two options to install a native backend for the GUI. Option A is a venv-friendly Qt backend using pip. Option B is a GTK backend for Debian/Kali/Ubuntu using apt. Choose one based on your environment.

```bash
# Option A (venv-friendly Qt backend)
pip install PyQt5 qtpy

# Option B (GTK backend on Debian/Kali/Ubuntu)
sudo apt install -y python3-gi python3-gi-cairo gir1.2-gtk-3.0 gir1.2-webkit2-4.1
```

--------------------------------

### hackbot agent command example

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/02-cli-reference.md

Starts an autonomous security assessment against a target. The --scope and --instructions options define the assessment scope and provide specific instructions for the agent.

```bash
hackbot agent 10.0.0.1 --scope "Web app on port 443" --instructions "Focus on SQLi"
```

--------------------------------

### Minimal implementation of ToolInstaller.install (hackbot/core/installer.py)

Source: https://github.com/yashab-cyber/hackbot/blob/main/docs/superpowers/plans/2026-06-22-autonomous-tool-install.md

Add this install method to ToolInstaller. It joins plan.command into a string, executes via self.runner.execute, and verifies the binary resolves via resolve_tool_path. Success requires both runner success and path not None.

```python
    def install(self, plan: InstallPlan) -> InstallResult:
        command_str = " ".join(plan.command)
        result = self.runner.execute(
            command_str,
            tool_name=plan.manager,
            explanation=f"Install {plan.tool}",
        )
        path = resolve_tool_path(plan.tool)
        success = result.success and path is not None
        if success:
            message = f"Installed {plan.tool} via {plan.manager} ({path})"
        elif result.success:
            message = (
                f"{plan.manager} reported success but {plan.tool} is still not on PATH"
            )
        else:
            message = f"Install of {plan.tool} via {plan.manager} failed"
        return InstallResult(
            tool=plan.tool,
            success=success,
            manager=plan.manager,
            path=path,
            message=message,
            stdout=(result.stdout or "")[:2000],
            stderr=(result.stderr or "")[:2000],
        )
```

--------------------------------

### Install GUI dependencies for pywebview

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/10-troubleshooting.md

Install hackbot with the gui extra or directly install flask and pywebview. Use when the GUI fails with 'pywebview not installed'.

```bash
pip install hackbot[gui]
# or
pip install flask pywebview
```

--------------------------------

### POST /api/proxy/start

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/03-gui-reference.md

Starts the proxy.

```APIDOC
## POST /api/proxy/start

### Description
Starts the proxy.

### Method
POST

### Endpoint
/api/proxy/start

```

--------------------------------

### Verify Installation

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/01-getting-started.md

Checks version, lists security tools, and shows config.

```bash
# Check version
hackbot --version

# Check available security tools
hackbot tools

# Show config
hackbot config
```

--------------------------------

### Running plugin from command runner in REPL

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/14-plugin-creation.md

Shows how to run the plugin using the /run command in the REPL.

```text
/run hackbot-plugin my_port_check --host example.com --port 443
```

--------------------------------

### Upgrade pip and install hackbot with --user or pipx

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/10-troubleshooting.md

Commands to upgrade pip, install hackbot with the --user flag, or use pipx for an isolated install. Use when pip install fails.

```bash
# Upgrade pip first
python3 -m pip install --upgrade pip

# Try with --user flag
python3 -m pip install --user "hackbot @ git+https://github.com/yashab-cyber/hackbot.git"

# Or use pipx for isolated install
pipx install "hackbot[all] @ git+https://github.com/yashab-cyber/hackbot.git"
```

--------------------------------

### Plan Mode Example Session

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/04-modes.md

Shows an interactive session where the user requests a web pentest plan and asks follow-up questions.

```text
HackBot> /plan
📋 Planning Mode

HackBot [plan]> Plan a web pentest for shop.example.com
AI: # Web Application Penetration Test Plan
## Target: shop.example.com

### Phase 1: Reconnaissance
- Objective: Map the application surface
- Tools: whatweb, wappalyzer, subfinder
- Duration: 2 hours
...

HackBot [plan]> What about API endpoints?
AI: Great question. Here's how to enumerate and test the API...
```

--------------------------------

### GET /api/vulndb/risk

Source: https://github.com/yashab-cyber/hackbot/blob/main/README.md

Gets risk score and history.

```APIDOC
## GET /api/vulndb/risk

### Description
Get risk score and history.

### Method
GET

### Endpoint
/api/vulndb/risk

```

--------------------------------

### GET /api/vulndb/stats

Source: https://github.com/yashab-cyber/hackbot/blob/main/README.md

Gets vulnerability database statistics.

```APIDOC
## GET /api/vulndb/stats

### Description
Vulnerability database statistics.

### Method
GET

### Endpoint
/api/vulndb/stats

```

--------------------------------

### Create initial release with git tag and gh release create

Source: https://github.com/yashab-cyber/hackbot/blob/main/RELEASE.md

Run these commands to tag the current state as v1.0.0 and create the GitHub release with the provided release notes. The release notes include installation and local model commands.

```bash
cd /path/to/hackbot

# Tag the current state as v1.0.0
git tag -a v1.0.0 -m "Release v1.0.0 — Initial production release"
git push origin v1.0.0

# Create the GitHub release
gh release create v1.0.0 \
  --title "HackBot v1.0.0 — Initial Release" \
  --notes "## 🎉 HackBot v1.0.0 — Initial Production Release

### Features
- 🤖 **Agent Mode** — Autonomous penetration testing with real tools
- 💬 **Chat Mode** — Interactive cybersecurity Q&A with memory
- 📋 **Plan Mode** — 8 structured pentest plan templates
- 🖥️ **Native Desktop GUI** — pywebview-powered dark theme interface
- 🛡️ **CVE/Exploit Lookup** — Real-time NVD search + GitHub PoC discovery
- 🌐 **OSINT Module** — Subdomains, DNS, WHOIS, tech stack, emails
- 🗺️ **Network Topology** — Interactive D3.js network visualization
- 📋 **Compliance Mapping** — PCI DSS, NIST 800-53, OWASP Top 10, ISO 27001
- 🔀 **Diff Reports** — Compare assessments (new/fixed/persistent findings)
- 🎯 **Multi-Target Campaigns** — Coordinated multi-host assessments
- 🧩 **Custom Plugins** — Python plugin system for custom tools
- 🔧 **AI Remediation** — Auto-generate fix commands and config patches
- 🔌 **HTTP Proxy** — Intercepting proxy with traffic capture and replay
- 🧠 **Memory & Sessions** — Auto-save, session history, conversation summarization
- 🌍 **10 AI Providers** — OpenAI, Anthropic, Gemini, Groq, Mistral, DeepSeek, Together, OpenRouter, Ollama, Local
- 🔧 **30+ Tool Integrations** — nmap, nikto, sqlmap, nuclei, ffuf, hydra, and more
- 📊 **Reports** — HTML, Markdown, JSON, and professional PDF reports
- 💻 **Cross-Platform** — Linux, macOS, Windows

### Installation
```bash
pip install "hackbot @ git+https://github.com/yashab-cyber/hackbot.git"
```

### Local Models (No API Key)
```bash
ollama pull xploiter/pentester
hackbot --provider ollama --model xploiter/pentester
```
"
```

--------------------------------

### GET /api/campaigns/active

Source: https://github.com/yashab-cyber/hackbot/blob/main/README.md

Gets the active campaign state.

```APIDOC
## GET /api/campaigns/active

### Description
Get active campaign state.

### Method
GET

### Endpoint
/api/campaigns/active

```

--------------------------------

### GET /api/topology/from-agent

Source: https://github.com/yashab-cyber/hackbot/blob/main/README.md

Gets topology from agent scans.

```APIDOC
## GET /api/topology/from-agent

### Description
Get topology from agent scans.

### Method
GET

### Endpoint
/api/topology/from-agent

```

--------------------------------

### GET /api/agent/findings

Source: https://github.com/yashab-cyber/hackbot/blob/main/README.md

Gets current findings from the agent.

```APIDOC
## GET /api/agent/findings

### Description
Get current findings.

### Method
GET

### Endpoint
/api/agent/findings

```

--------------------------------

### GET /api/vulndb/findings/<id>

Source: https://github.com/yashab-cyber/hackbot/blob/main/README.md

Gets finding detail by ID.

```APIDOC
## GET /api/vulndb/findings/<id>

### Description
Get finding detail.

### Method
GET

### Endpoint
/api/vulndb/findings/<id>

```

--------------------------------

### Implement _install_tool method

Source: https://github.com/yashab-cyber/hackbot/blob/main/docs/superpowers/plans/2026-06-22-autonomous-tool-install.md

Implements the _install_tool method that validates the tool argument, lazily creates an AgentMode if needed, delegates to _process_install_action, and prints the result as Markdown.

```python
    def _install_tool(self, args: str) -> bool:
        tool = args.strip()
        if not tool:
            print_error("Usage: /install <tool>")
            return True
        if self.mode != "agent" or not self.agent:
            self.agent = AgentMode(
                engine=self.engine,
                config=self.config,
                on_step=self._on_agent_step,
                on_confirm=self._on_confirm,
                on_output=self._on_tool_output,
            )
        result = self.agent._process_install_action({"action": "install", "tool": tool})
        console.print(Markdown(result))
        return True
```

--------------------------------

### GET /api/attack/technique/<id>

Source: https://github.com/yashab-cyber/hackbot/blob/main/README.md

Gets a specific technique by ID.

```APIDOC
## GET /api/attack/technique/<id>

### Description
Get a specific technique by ID.

### Method
GET

### Endpoint
/api/attack/technique/<id>

```

--------------------------------

### GET /api/compliance/controls/<fw>

Source: https://github.com/yashab-cyber/hackbot/blob/main/README.md

Gets controls for a specific framework.

```APIDOC
## GET /api/compliance/controls/<fw>

### Description
Get controls for a framework.

### Method
GET

### Endpoint
/api/compliance/controls/<fw>

```

--------------------------------

### Add _process_install_action handler method

Source: https://github.com/yashab-cyber/hackbot/blob/main/docs/superpowers/plans/2026-06-22-autonomous-tool-install.md

Add this handler method near _execute_action. It handles the install action with allowlist bounds, safe_mode confirmation, and returns formatted results.

```python
    def _process_install_action(self, action: Dict[str, Any]) -> str:
        """Autonomously install a missing security tool (allowlist-bounded)."""
        tool = (action.get("tool") or "").strip()
        if not tool:
            return "**[install]** No tool specified."

        # Allowlist bound (unless the user opted into arbitrary installs).
        if not self.config.agent.allow_arbitrary_install and not self.runner.is_tool_allowed(tool):
            return (
                f"**[install]** `{tool}` is not in the allowlist; cannot auto-install. "
                f"Use a different tool or ask the user to install it manually."
            )

        if resolve_tool_path(tool):
            return f"**[install]** `{tool}` is already installed — proceed to use it."

        plan = self.installer.plan_install(tool)
        if plan is None:
            return (
                f"**[install]** No install recipe for `{tool}` on this system "
                f"(unmapped tool or no supported package manager available). "
                f"Try a different tool."
            )

        # Respect safe_mode: one confirmation before installing.
        if self.config.agent.safe_mode and not self.config.agent.auto_confirm:
            confirm = getattr(self.runner, "on_confirm", None)
            cmd_str = " ".join(plan.command)
            reason = f"INSTALL {tool} via {plan.manager}"
            if confirm and not confirm(cmd_str, reason):
                return f"**[install]** User declined installation of `{tool}`."

        result: InstallResult = self.installer.install(plan)
        if result.success:
            return f"**[install]** SUCCESS — {result.message}. You may now use `{tool}`."
        detail = (result.stderr or result.stdout or "").strip()[:500]
        sudo_hint = ""
        if plan.needs_sudo and not self.runner.sudo_mode:
            sudo_hint = " (system installs need --sudo / sudo_mode; it appears disabled)"
        return f"**[install]** FAILED — {result.message}{sudo_hint}.\n```\n{detail}\n```"
```

--------------------------------

### GET /api/campaigns/active/findings

Source: https://github.com/yashab-cyber/hackbot/blob/main/README.md

Gets aggregated findings from the active campaign.

```APIDOC
## GET /api/campaigns/active/findings

### Description
Aggregated findings.

### Method
GET

### Endpoint
/api/campaigns/active/findings

```

--------------------------------

### Create release notes file and release with --notes-file (Option B)

Source: https://github.com/yashab-cyber/hackbot/blob/main/RELEASE.md

Creates a temporary markdown file with release notes using a heredoc, then creates the release referencing that file with `--notes-file`.

```bash
cat > /tmp/release-notes.md << 'EOF'
## What's New

- Added TinyLlama support for low-end PCs
- Added xploiter/pentester cybersecurity model
- Added Ollama & Local model usage guides
- Added screenshots to README

## Bug Fixes

- Fixed screenshot labels in README

## Full Changelog
https://github.com/yashab-cyber/hackbot/compare/v1.1.1...v1.1.2
EOF

gh release create v1.1.2 \
  --title "HackBot v1.1.2" \
  --notes-file /tmp/release-notes.md
```

--------------------------------

### Run failing test (pytest -k install)

Source: https://github.com/yashab-cyber/hackbot/blob/main/docs/superpowers/plans/2026-06-22-autonomous-tool-install.md

Run the installer tests to verify they fail initially. Expected failure: AttributeError: 'ToolInstaller' object has no attribute 'install'.

```bash
pytest tests/test_installer.py -k install -v
```

--------------------------------

### GET /api/proxy/traffic/<id>

Source: https://github.com/yashab-cyber/hackbot/blob/main/README.md

Gets a single request detail by ID.

```APIDOC
## GET /api/proxy/traffic/<id>

### Description
Get single request detail.

### Method
GET

### Endpoint
/api/proxy/traffic/<id>

```

--------------------------------

### TOOL_INSTALL_MAP: curated tool installation recipes

Source: https://github.com/yashab-cyber/hackbot/blob/main/docs/superpowers/plans/2026-06-22-autonomous-tool-install.md

Defines a mapping of tool names to installation recipes, with an order of preferred managers and per-manager package identifiers. Only tools in agent.allowed_tools are installable.

```python
# Curated tool -> package recipes for autonomous installation.
# `order` lists preferred managers; ToolInstaller picks the first one available
# on the host. Per-manager values are the package/module identifier for that
# manager. Only tools also present in agent.allowed_tools are installable.
TOOL_INSTALL_MAP: Dict[str, Dict[str, object]] = {
    "nuclei": {
        "order": ["go", "apt"],
        "go": "github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest",
        "apt": "nuclei",
    },
    "subfinder": {
        "order": ["go"],
        "go": "github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest",
    },
    "httpx": {
        "order": ["go"],
        "go": "github.com/projectdiscovery/httpx/cmd/httpx@latest",
    },
    "ffuf": {
        "order": ["go", "apt"],
        "go": "github.com/ffuf/ffuf/v2@latest",
        "apt": "ffuf",
    },
    "gobuster": {
        "order": ["go", "apt"],
        "go": "github.com/OJ/gobuster/v3@latest",
        "apt": "gobuster",
    },
    "katana": {
        "order": ["go"],
        "go": "github.com/projectdiscovery/katana/cmd/katana@latest",
    },
    "sqlmap": {"order": ["apt", "pipx"], "apt": "sqlmap", "pipx": "sqlmap"},
    "nikto": {"order": ["apt"], "apt": "nikto"},
    "nmap": {"order": ["apt", "dnf", "pacman", "brew"], "apt": "nmap",
             "dnf": "nmap", "pacman": "nmap", "brew": "nmap"},
    "whatweb": {"order": ["apt"], "apt": "whatweb"},
    "wpscan": {"order": ["apt"], "apt": "wpscan"},
    "hydra": {"order": ["apt"], "apt": "hydra"},
    "dnsrecon": {"order": ["apt", "pipx"], "apt": "dnsrecon", "pipx": "dnsrecon"},
    "amass": {"order": ["apt", "go"], "apt": "amass",
              "go": "github.com/owasp-amass/amass/v4/...@master"},
    "feroxbuster": {"order": ["apt"], "apt": "feroxbuster"},
    "masscan": {"order": ["apt", "dnf", "pacman"], "apt": "masscan",
                "dnf": "masscan", "pacman": "masscan"},
}
```

--------------------------------

### First Run

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/01-getting-started.md

Launches the interactive REPL with the HackBot banner.

```bash
hackbot
```

--------------------------------

### GET /api/attack/tool/<name>

Source: https://github.com/yashab-cyber/hackbot/blob/main/README.md

Gets ATT&CK techniques for a specific tool.

```APIDOC
## GET /api/attack/tool/<name>

### Description
Get ATT&CK techniques for a tool.

### Method
GET

### Endpoint
/api/attack/tool/<name>

```

--------------------------------

### Windows installer script

Source: https://github.com/yashab-cyber/hackbot/blob/main/website/index.html

Clones the repository and runs install.bat to install HackBot on Windows.

```bash
git clone https://github.com/yashab-cyber/hackbot.git
cd hackbot
install.bat
```

--------------------------------

### Lint and commit installer changes

Source: https://github.com/yashab-cyber/hackbot/blob/main/docs/superpowers/plans/2026-06-22-autonomous-tool-install.md

Run ruff and black on the modified files, then stage and commit with a descriptive message.

```bash
ruff check hackbot/core/installer.py && black hackbot/core/installer.py tests/test_installer.py
git add hackbot/core/installer.py tests/test_installer.py
git commit -m "feat(installer): execute install via runner and verify binary resolves"
```

--------------------------------

### One-Line Installer (Linux/macOS)

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/01-getting-started.md

Installs HackBot using a one-line curl command for Linux/macOS.

```bash
curl -fsSL https://raw.githubusercontent.com/yashab-cyber/hackbot/main/install.sh | bash
```

--------------------------------

### POST /api/proxy/start

Source: https://github.com/yashab-cyber/hackbot/blob/main/README.md

Starts the intercepting proxy.

```APIDOC
## POST /api/proxy/start

### Description
Start the intercepting proxy.

### Method
POST

### Endpoint
/api/proxy/start

```

--------------------------------

### Chat Mode Example

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/04-modes.md

Example interaction in Chat Mode showing a conversation with the AI.

```text
HackBot> /chat
💬 Chat Mode — Interactive cybersecurity Q&A

HackBot [chat]> How do I detect SQL injection vulnerabilities?
AI: SQL injection can be detected through several approaches...

HackBot [chat]> What tools can automate this?
AI: Here are the top tools for SQL injection detection...
```

--------------------------------

### Create venv with system site packages for GTK

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/10-troubleshooting.md

Create a virtual environment with system site packages so it can see the 'gi' module, then activate it.

```bash
python3 -m venv --system-site-packages hackbot
source hackbot/bin/activate
```

--------------------------------

### Install Ollama on Linux, macOS, and Windows

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/06-ai-providers.md

Commands to install Ollama on different operating systems. Linux uses a curl script, macOS uses Homebrew, and Windows requires downloading the installer from the official website.

```bash
# Linux
curl -fsSL https://ollama.com/install.sh | sh

# macOS
brew install ollama

# Windows — download installer from https://ollama.com/download
```

--------------------------------

### Create Pre-release

Source: https://github.com/yashab-cyber/hackbot/blob/main/RELEASE.md

Creates a pre-release (beta/RC) with the --prerelease flag.

```bash
gh release create v2.0.0-beta.1 \
  --title "HackBot v2.0.0 Beta 1" \
  --generate-notes \
  --prerelease
```

--------------------------------

### Isolated install with pipx

Source: https://github.com/yashab-cyber/hackbot/blob/main/website/index.html

Installs HackBot in an isolated environment using pipx, including all extras.

```bash
pipx install "hackbot[all] @ git+https://github.com/yashab-cyber/hackbot.git"
```

--------------------------------

### hackbot gui command example

Source: https://github.com/yashab-cyber/hackbot/blob/main/manual/02-cli-reference.md

Launches the desktop GUI. The --host and --port options set the server bind address and port, with defaults 127.0.0.1 and 1337 respectively.

```bash
hackbot gui --host 0.0.0.0 --port 8080
```
Tokens:
Raw