hackbot: Automated Penetration Testing Robot

An intelligent automated penetration testing robot with AI-powered security testing capabilities

English | 中文

---

⚠️ Security Warning

This tool is intended for authorized security testing only. Unauthorized use of this tool for network attacks is illegal.

• ✅ Only use on systems you own or have explicit written authorization to test
• ✅ Ensure you comply with all applicable laws and regulations
• ✅ Use responsibly and ethically

初始化界面展示

启动交互模式后的界面示意（uv run secbot 或 python main.py）：

🚀 Features

Core Capabilities

• 🤖 Multiple Agent Patterns: ReAct, Plan-Execute, Multi-Agent, Tool-Using, Memory-Augmented
• 🌐 AI Web Research Agent: Independent sub-agent with ReAct loop for internet research—smart search, page extraction, multi-page crawling, and API interaction
• 💻 CLI Interface: Built with Typer for intuitive command-line interaction
• 🎤 Voice Interaction: Complete speech-to-text and text-to-speech functionality
• 🕷️ AI Web Crawler: Real-time web information capture and monitoring
• 💻 OS Control: File operations, process management, system information

Penetration Testing

• 🔍 Reconnaissance: Automated information gathering (hostname, IP, ports, services)
• 🔍 Vulnerability Scanning: Port scanning, service detection, vulnerability identification
• ⚔️ Exploit Engine: Automated exploitation of SQL injection, XSS, command injection, file upload, path traversal, SSRF
• 🔗 Automated Attack Chain: Complete penetration testing workflow automation
  • Information Gathering → Vulnerability Scanning → Exploitation → Post-Exploitation
• 📦 Payload Generator: Automatic generation of attack payloads
• 🎯 Post-Exploitation: Privilege escalation, persistence, lateral movement, data exfiltration
• ⚔️ Network Attacks: Brute force, DoS testing, buffer overflow (authorized testing only)

Security & Defense

• 🛡️ Active Defense: Information collection, vulnerability scanning, network analysis, intrusion detection
• 📊 Security Reports: Automated detailed security analysis reports
• 🔍 Network Discovery: Automatic discovery of all hosts in the network
• 🎯 Authorization Management: Manage legal authorization for target hosts
• 🖥️ Remote Control: Remote command execution and file transfer on authorized hosts

Web Research (Internet Capabilities)

• 🔎 Smart Search: DuckDuckGo search → fetch result pages → AI summarization and synthesis
• 📄 Page Extract: Extract page content by mode—plain text, structured (tables/lists), or custom AI schema
• 🕸️ Deep Crawl: BFS multi-page crawling from a start URL with depth/URL filter and optional AI extraction
• 🔌 API Client: Generic REST client with presets (weather, IP info, GitHub, exchange rates, DNS, etc.)
• 🤖 Web Research Tool: Delegate to the Web Research sub-agent for autonomous research or call tools directly

Additional Features

• 📝 Prompt Chain Management: Flexible agent prompt configuration
• 💾 SQLite Database: Persistent storage for conversation history, prompt chains, configurations
• ⏰ Task Scheduling: Support for scheduled penetration testing tasks
• 🎨 Beautiful Terminal Output: Rich formatting with Rich library

📋 Requirements

• Python 3.10+
• uv - Fast Python package manager
• Ollama (for LLM inference)
• Dependencies are managed in pyproject.toml

🛠️ Installation

1. Clone the Repository

git clone https://github.com/iammm0/hackbot.git
cd hackbot

2. Install Dependencies

uv is a fast Python package installer and resolver.

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies using uv
uv sync

3. Install and Start Ollama

# Install Ollama from https://ollama.ai

# Pull required models
ollama pull gpt-oss:20b
ollama pull nomic-embed-text

# Ollama service runs on http://localhost:11434 by default

4. Configure Environment

cp .env.example .env

Edit .env file:

• OLLAMA_MODEL: Inference model (default: gpt-oss:20b)
• OLLAMA_EMBEDDING_MODEL: Embedding model (default: nomic-embed-text)

5. Build and Install (Optional)

# Build package using uv
uv run python -m build

# Install package
uv pip install dist/hackbot-1.0.0-py3-none-any.whl

# Now you can use 'hackbot' command directly
hackbot --help

🎯 Quick Start

Basic Usage

# View help
hackbot --help

# Interactive chat
hackbot interactive

# Text chat
hackbot chat "Hello, introduce yourself"

# List available agents
hackbot list-agents

Web Research (via Chat)

# Delegate to Web Research sub-agent (auto search → crawl → summarize)
hackbot chat "Research the latest CVE-2024 vulnerabilities and summarize"

# Direct smart search
hackbot chat "Use smart_search to find Python asyncio best practices"

# Extract content from a URL
hackbot chat "Use page_extract to get the main content from https://example.com"

# Call a public API (e.g. weather)
hackbot chat "Use api_client with preset weather and query Beijing"

Penetration Testing Commands

# Network discovery
hackbot discover

# Port scanning (via chat)
hackbot chat "Scan ports on 192.168.1.1"

# List authorized targets
hackbot list-targets

# Revoke authorization
hackbot revoke 192.168.1.100

# Note: Advanced exploitation commands (exploit, attack-chain, generate-payload) 
# are available in experimental versions. Run 'hackbot --help' for full command list.

Remote Control Commands

# Execute remote command on authorized host
hackbot remote-execute 192.168.1.100 "ls -la"

# Upload file to remote host
hackbot upload-file 192.168.1.100 local.txt /remote/path/

# Download file from remote host
hackbot download-file 192.168.1.100 /remote/file.txt local_copy.txt

# List all authorizations
hackbot list-authorizations

Defense System Commands

# Perform comprehensive security scan
hackbot defense-scan

# Start defense monitoring
hackbot defense-monitor --start --interval 60

# View defense status
hackbot defense-monitor --status

# List blocked IPs
hackbot defense-blocked --list

# Generate defense report
hackbot defense-report --type vulnerability

System Operations

# System information
hackbot system-info

# System status
hackbot system-status

# List processes
hackbot list-processes --filter python

# Execute command
hackbot execute "ls -la"

# List files in directory
hackbot file-list /path/to/dir --recursive

Database Management

# View statistics
hackbot db-stats

# View conversation history
hackbot db-history --limit 20

# Clear history (requires confirmation)
hackbot db-clear --yes

Voice Interaction Commands

# Speech-to-text transcription
hackbot transcribe audio.wav --output transcript.txt

# Text-to-speech synthesis
hackbot synthesize "Hello world" --output speech.wav --language en

# Voice chat with agent
hackbot voice audio.wav --agent hackbot

Prompt Management Commands

# List available prompt templates and chains
hackbot prompt-list

# Create a new prompt chain
hackbot prompt-create my_chain --role "Security Expert" --instruction "Perform penetration testing"

# Load prompt chain from file
hackbot prompt-load my_prompt.yaml

🔧 Development

Running Tests

pytest tests/

Building Package

# Using uv (recommended)
uv run python -m build

# Or using the build script
./build.sh

📚 Documentation

• Quick Start Guide
• API Documentation
• Mobile App Guide
• Skills & Memory System
• Database Guide
• Docker Setup
• Ollama Setup
• Security Warning
• Virtual Test Environment (VMware + Ubuntu) — prompts and setup for testing secbot in a VM
• Prompt Guide
• Speech Guide
• SQLite Setup
• Deployment Guide

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

赵明俊 (Zhao Mingjun)

• GitHub: @iammm0
• Email: wisewater5419@gmail.com

🙏 Acknowledgments

• Built with LangChain
• Powered by Ollama
• CLI built with Typer
• Beautiful output with Rich

⚠️ Disclaimer

This tool is provided for educational and authorized security testing purposes only. The authors and contributors are not responsible for any misuse or damage caused by this tool. Users must ensure they have proper authorization before using this tool on any system.

---

⭐ If you find this project useful, please consider giving it a star! ⭐