@poolzin/pool-bot 2026.3.14 → 2026.3.16

package/extensions/hexstrike-ai/README.md

@@ -1,66 +1,214 @@
 # HexStrike AI Extension for PoolBot
 
-Security scanning platform with 150+ integrated scanners (nmap, nuclei, sqlmap, gobuster, wpscan, etc.) now fully integrated into PoolBot.
+**Versão:** 6.0.0  
+**Status:** ⚠️ **Beta - Apenas para Desenvolvimento**  
+**Licença:** MIT
 
-## Features
+---
 
-- **150+ Security Scanners**: nmap, nuclei, sqlmap, gobuster, wpscan, nikto, dirb, and more
-- **Integrated Server**: Python server runs embedded within PoolBot
-- **CLI Commands**: Full CLI integration via `poolbot security`
-- **Gateway RPC**: Remote procedure calls for distributed setups
-- **Telemetry**: Events and metrics integrated with PoolBot telemetry
+## 🚀 Visão Geral
 
-## Installation
+HexStrike AI é uma plataforma de segurança ofensiva integrada ao PoolBot, com **150+ scanners** de segurança (nmap, nuclei, sqlmap, gobuster, wpscan, nikto, dirb, etc.) e inteligência artificial para automação de pentest.
 
-The extension is automatically installed with PoolBot. Python dependencies:
+### ⚠️ Importante
+
+> **Esta extensão está em BETA e requer:**
+> - ✅ Python 3.10+ instalado
+> - ✅ Servidor Python rodando (iniciado automaticamente)
+> - ✅ 150+ ferramentas de segurança instaladas separadamente
+> - ✅ ~5GB de espaço em disco
+> - ✅ 2-4 horas para instalação completa
+>
+> **Recomendado apenas para:**
+> - ✅ Desenvolvimento local
+> - ✅ Ambientes de teste isolados
+> - ✅ Pesquisa de segurança
+> - ✅ Profissionais de segurança
+
+---
+
+## 📋 Índice
+
+- [Funcionalidades](#-funcionalidades)
+- [Arquitetura](#-arquitetura)
+- [Instalação](#-instalação)
+- [Configuração](#-configuração)
+- [Uso](#-uso)
+- [API Reference](#-api-reference)
+- [Ferramentas Suportadas](#-ferramentas-suportadas)
+- [Troubleshooting](#-troubleshooting)
+- [Segurança](#-segurança)
+- [Licença](#-licença)
+
+---
+
+## ✨ Funcionalidades
+
+### Principais
+
+- **150+ Scanners Integrados**: nmap, nuclei, sqlmap, gobuster, wpscan, nikto, e mais
+- **Servidor Python Embutido**: Flask server roda automaticamente com PoolBot
+- **CLI Commands**: Integração completa via `poolbot security`
+- **Gateway RPC**: Suporte para setups distribuídos
+- **Telemetria**: Eventos e métricas integrados com PoolBot
+- **AI-Powered**: Seleção inteligente de ferramentas baseada no alvo
+
+### Categorias de Scanners
+
+| Categoria | Ferramentas | Exemplos |
+|-----------|-------------|----------|
+| **Network & Recon** | 25+ | nmap, masscan, rustscan, amass |
+| **Web Application** | 40+ | nuclei, sqlmap, gobuster, wpscan |
+| **Authentication** | 12+ | hydra, john, hashcat, medusa |
+| **Binary Analysis** | 25+ | ghidra, radare2, gdb, angr |
+| **Cloud Security** | 20+ | prowler, trivy, kube-hunter |
+| **CTF & Forensics** | 20+ | volatility3, autopsy, steghide |
+| **OSINT** | 20+ | sherlock, recon-ng, maltego |
+
+---
+
+## 🏗️ Arquitetura
 
-```bash
-cd extensions/hexstrike-ai
-pip3 install -r src/server/requirements.txt
 ```
+┌─────────────────┐
+│   PoolBot CLI   │
+│    (Node.js)    │
+└────────┬────────┘
+         │ HTTP
+         │ localhost:8888
+         ▼
+┌─────────────────┐
+│  HexStrike AI   │
+│  Python Server  │
+│    (Flask)      │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  150+ Security  │
+│     Tools       │
+│ nmap, nuclei... │
+└─────────────────┘
+```
+
+### Componentes
+
+| Componente | Descrição | Tecnologia |
+|------------|-----------|------------|
+| **PoolBot CLI** | Interface de comando | Node.js + TypeScript |
+| **HexStrike Client** | HTTP client para API | Node.js fetch |
+| **Server Manager** | Gerencia processo Python | Node.js child_process |
+| **Python Server** | API Flask + scanners | Python 3.10+ Flask |
+| **Security Tools** | Ferramentas externas | 150+ tools |
+
+---
 
-## Usage
+## 📦 Instalação
 
-### Check Server Status
+### Pré-requisitos
+
+**Obrigatórios:**
+- ✅ Node.js 22+
+- ✅ Python 3.10+
+- ✅ pip3 (Python package manager)
+- ✅ 5GB+ espaço em disco
+- ✅ 2-4 horas para instalação
+
+**Recomendados:**
+- ✅ Kali Linux 2024.1+ (já inclui maioria das tools)
+- ✅ 8GB+ RAM
+- ✅ CPU multi-core
+
+### Passo 1: Instalar Extensão
 
 ```bash
-poolbot security status
+# A extensão já vem com PoolBot
+# Verificar se está instalada
+poolbot extensions list | grep hexstrike
 ```
 
-### List Available Scanners
+### Passo 2: Instalar Dependências Python
 
 ```bash
-poolbot security tools
+cd extensions/hexstrike-ai
+pip3 install -r src/server/requirements.txt
+```
+
+**Tempo estimado:** 5-10 minutos  
+**Espaço necessário:** ~50MB
+
+### Passo 3: Instalar Ferramentas de Segurança
+
+#### Opção A: Kali Linux (Recomendado)
+
+```bash
+# Kali já inclui maioria das ferramentas
+sudo apt update
+sudo apt install -y \
+  nmap sqlmap gobuster wpscan nikto \
+  nuclei hydra john hashcat \
+  ghidra radare2 volatility3
 ```
 
-### Run Security Scan
+#### Opção B: Ubuntu/Debian
 
 ```bash
-# Quick scan with default scanners
-poolbot security scan https://example.com
+# Instalar ferramentas básicas
+sudo apt update
+sudo apt install -y nmap sqlmap gobuster wpscan nikto
 
-# Scan with specific scanners
-poolbot security scan https://example.com --scanners nmap,nuclei
+# Instalar Go tools (requer Go instalado)
+go install github.com/gobusterio/gobuster@latest
+go install github.com/projectdiscovery/nuclei/cmd/nuclei@latest
 
-# Full scan with all scanners
-poolbot security scan https://example.com --full
+# Instalar Python tools
+pip3 install pwntools angr
+
+# Ver instalação completa em docs/security-tools-install.md
 ```
 
-### Get Scan Report
+#### Opção C: Script Automatizado (Em Desenvolvimento)
 
 ```bash
-poolbot security report <scan-id>
+# Script será disponibilizado futuramente
+./scripts/install-security-tools.sh
 ```
 
-### Stop Server
+### Passo 4: Verificar Instalação
 
 ```bash
-poolbot security stop
+# Verificar servidor
+poolbot security status
+
+# Listar ferramentas disponíveis
+poolbot security tools
 ```
 
-## Configuration
+**Saída esperada:**
+```
+✅ HexStrike AI is running
+   Status: healthy
+   Version: 6.0.0
+   Uptime: 5m
 
-Add to your PoolBot config (`~/.poolbot/config.json`):
+🔧 Available security scanners:
+   • nmap
+   • nuclei
+   • sqlmap
+   • gobuster
+   • wpscan
+   ... (150+ tools)
+
+Total: 152 scanners
+```
+
+---
+
+## ⚙️ Configuração
+
+### Configuração Padrão
+
+Adicione ao seu `~/.poolbot/config.json`:
 
 ```json
 {
@@ -69,30 +217,531 @@ Add to your PoolBot config (`~/.poolbot/config.json`):
     "host": "127.0.0.1",
     "autoStart": true,
     "pythonPath": "python3",
+    "token": "seu-token-opcional",
     "maxConcurrentScans": 3,
     "scanTimeout": 3600
   }
 }
 ```
 
-## Architecture
+### Opções de Configuração
+
+| Opção | Tipo | Padrão | Descrição |
+|-------|------|--------|-----------|
+| `port` | number | `8888` | Porta do servidor Flask |
+| `host` | string | `"127.0.0.1"` | Host do servidor |
+| `autoStart` | boolean | `true` | Iniciar servidor automaticamente |
+| `pythonPath` | string | `"python3"` | Caminho para Python |
+| `token` | string | `undefined` | Token de autenticação (opcional) |
+| `maxConcurrentScans` | number | `3` | Máximo de scans simultâneos |
+| `scanTimeout` | number | `3600` | Timeout por scan (segundos) |
+
+### Configuração Avançada
+
+```json
+{
+  "hexstrikeAi": {
+    "port": 8888,
+    "host": "0.0.0.0",
+    "autoStart": true,
+    "pythonPath": "/usr/bin/python3.11",
+    "maxConcurrentScans": 5,
+    "scanTimeout": 7200,
+    "tools": {
+      "nmap": {
+        "timeout": 300,
+        "threads": 10
+      },
+      "nuclei": {
+        "rateLimit": 100,
+        "concurrency": 25
+      }
+    }
+  }
+}
+```
+
+---
+
+## 💻 Uso
+
+### Comandos CLI
+
+#### 1. Verificar Status
+
+```bash
+poolbot security.status
+```
+
+**Saída:**
+```
+✅ HexStrike AI is running
+   Status: healthy
+   Version: 6.0.0
+   Uptime: 15m
+```
+
+#### 2. Listar Ferramentas
+
+```bash
+poolbot security.tools
+```
+
+**Saída:**
+```
+🔧 Available security scanners:
+   • nmap
+   • nuclei
+   • sqlmap
+   • gobuster
+   • wpscan
+   • nikto
+   • dirb
+   ... (150+ tools)
+
+Total: 152 scanners
+```
+
+#### 3. Executar Scan
+
+```bash
+# Scan rápido com scanners padrão
+poolbot security.scan https://example.com
+
+# Scan com scanners específicos
+poolbot security.scan https://example.com --scanners nmap,nuclei
+
+# Scan completo com todas ferramentas
+poolbot security.scan https://example.com --full
+
+# Scan com output para arquivo
+poolbot security.scan https://example.com --output report.json
+```
+
+**Saída:**
+```
+🚀 Starting security scan on https://example.com...
+   Scanners: nmap, nuclei
+✅ Scan started: scan-abc123
+   Use 'poolbot security.report scan-abc123' to check results
+   Report will be saved to: report.json
+```
+
+#### 4. Ver Relatório
+
+```bash
+# Formato tabela (padrão)
+poolbot security.report scan-abc123
+
+# Formato JSON
+poolbot security.report scan-abc123 --format json
+```
+
+**Saída:**
+```
+📊 Scan Report: scan-abc123
+   Status: completed
+   Started: 2026-03-12T10:00:00Z
+   Completed: 2026-03-12T10:30:00Z
+
+🔍 Findings (5):
+   🔴 [CRITICAL] SQL Injection in /login
+   🟠 [HIGH] XSS Vulnerability in /search
+   🟡 [MEDIUM] Missing Security Headers
+   🟢 [LOW] Server Version Disclosure
+   ⚪ [INFO] SSL Certificate Valid
+```
+
+#### 5. Parar Servidor
+
+```bash
+poolbot security.stop
+```
+
+**Saída:**
+```
+✅ HexStrike AI server stopped
+```
+
+---
+
+## 📚 API Reference
+
+### HexStrikeClient
+
+#### Constructor
+
+```typescript
+const client = new HexStrikeClient({
+  host?: string;      // Default: '127.0.0.1'
+  port?: number;      // Default: 8888
+  token?: string;     // Default: undefined
+});
+```
+
+#### Methods
+
+##### `health()`
+
+Verifica status do servidor.
+
+```typescript
+const health = await client.health();
+// Returns: { status: 'healthy', version: '6.0.0', uptime: 3600 }
+```
+
+##### `getTools()`
+
+Lista ferramentas disponíveis.
+
+```typescript
+const tools = await client.getTools();
+// Returns: ['nmap', 'nuclei', 'sqlmap', ...]
+```
+
+##### `scan(target)`
+
+Inicia novo scan.
+
+```typescript
+const result = await client.scan({
+  target: 'https://example.com',
+  scanners?: ['nmap', 'nuclei'],
+  options?: { timeout: 300, threads: 10 }
+});
+// Returns: { scanId: 'scan-abc123' }
+```
+
+##### `getScanResult(scanId)`
+
+Obtém resultado do scan.
+
+```typescript
+const result = await client.getScanResult('scan-abc123');
+// Returns: {
+//   id: 'scan-abc123',
+//   status: 'completed',
+//   findings: [...],
+//   metadata: { startedAt, completedAt, duration }
+// }
+```
+
+---
+
+## 🛠️ Ferramentas Suportadas
+
+### Network & Reconnaissance (25+)
+
+| Ferramenta | Descrição | Instalação |
+|------------|-----------|------------|
+| `nmap` | Network scanner | `apt install nmap` |
+| `masscan` | Fast port scanner | `apt install masscan` |
+| `rustscan` | Modern port scanner | `cargo install rustscan` |
+| `amass` | DNS enumeration | `apt install amass` |
+| `subfinder` | Subdomain finder | `go install subfinder` |
+| `theharvester` | Email harvester | `apt install theharvester` |
+
+### Web Application Security (40+)
+
+| Ferramenta | Descrição | Instalação |
+|------------|-----------|------------|
+| `nuclei` | Vulnerability scanner | `go install nuclei` |
+| `sqlmap` | SQL injection tool | `apt install sqlmap` |
+| `gobuster` | Directory brute-forcer | `go install gobuster` |
+| `wpscan` | WordPress scanner | `gem install wpscan` |
+| `nikto` | Web server scanner | `apt install nikto` |
+| `dirb` | Directory scanner | `apt install dirb` |
+
+### Authentication & Password (12+)
+
+| Ferramenta | Descrição | Instalação |
+|------------|-----------|------------|
+| `hydra` | Login cracker | `apt install hydra` |
+| `john` | Password cracker | `apt install john` |
+| `hashcat` | GPU password cracker | `apt install hashcat` |
+| `medusa` | Parallel login cracker | `apt install medusa` |
+
+### Binary Analysis & RE (25+)
+
+| Ferramenta | Descrição | Instalação |
+|------------|-----------|------------|
+| `ghidra` | Reverse engineering | [Download](https://ghidra-sre.org/) |
+| `radare2` | Reverse engineering | `apt install radare2` |
+| `gdb` | Debugger | `apt install gdb` |
+| `angr` | Binary analysis | `pip install angr` |
+| `pwntools` | CTF framework | `pip install pwntools` |
+
+### Cloud Security (20+)
+
+| Ferramenta | Descrição | Instalação |
+|------------|-----------|------------|
+| `prowler` | AWS security | `pip install prowler` |
+| `trivy` | Container scanner | `apt install trivy` |
+| `kube-hunter` | Kubernetes scanner | `pip install kube-hunter` |
+| `checkov` | IaC scanner | `pip install checkov` |
+
+### CTF & Forensics (20+)
+
+| Ferramenta | Descrição | Instalação |
+|------------|-----------|------------|
+| `volatility3` | Memory forensics | `pip install volatility3` |
+| `autopsy` | Digital forensics | `apt install autopsy` |
+| `steghide` | Steganography | `apt install steghide` |
+| `exiftool` | Metadata viewer | `apt install exiftool` |
+
+### OSINT (20+)
+
+| Ferramenta | Descrição | Instalação |
+|------------|-----------|------------|
+| `sherlock` | Username finder | `pip install sherlock-project` |
+| `recon-ng` | Reconnaissance framework | `apt install recon-ng` |
+| `maltego` | Link analysis | [Download](https://maltego.com/) |
+| `shodan-cli` | Shodan client | `pip install shodan` |
+
+---
+
+## 🔧 Troubleshooting
+
+### Problemas Comuns
+
+#### 1. Servidor Não Inicia
+
+**Sintoma:**
+```
+❌ HexStrike AI is not running
+   Error: python3 not found
+```
+
+**Solução:**
+```bash
+# Verificar Python instalado
+python3 --version
+
+# Se não instalado:
+# Ubuntu/Debian
+sudo apt install python3 python3-pip
+
+# macOS
+brew install python3
+
+# Ou usar caminho alternativo na config
+{
+  "hexstrikeAi": {
+    "pythonPath": "/usr/local/bin/python3.11"
+  }
+}
+```
+
+#### 2. Ferramentas Não Encontradas
+
+**Sintoma:**
+```
+❌ Tool 'nmap' not found in PATH
+```
+
+**Solução:**
+```bash
+# Instalar ferramenta específica
+sudo apt install nmap
+
+# Ou verificar PATH
+echo $PATH
+
+# Adicionar ao PATH se necessário
+export PATH=$PATH:/usr/local/go/bin
+```
+
+#### 3. Porta Já em Uso
+
+**Sintoma:**
+```
+Error: Port 8888 is already in use
+```
+
+**Solução:**
+```bash
+# Matar processo usando porta
+lsof -ti:8888 | xargs kill -9
+
+# Ou usar porta diferente na config
+{
+  "hexstrikeAi": {
+    "port": 9999
+  }
+}
+```
+
+#### 4. Scan Timeout
 
+**Sintoma:**
 ```
-PoolBot CLI → Extension HexStrike AI → Python Server (port 8888)
-                    ↓
-            Gateway RPC (distributed)
-                    ↓
-            Telemetry Events
+Scan failed: Timeout after 3600s
 ```
 
-## API Endpoints
+**Solução:**
+```bash
+# Aumentar timeout na config
+{
+  "hexstrikeAi": {
+    "scanTimeout": 7200
+  }
+}
+
+# Ou usar menos scanners
+poolbot security.scan target.com --scanners nmap
+```
+
+#### 5. Memória Insuficiente
+
+**Sintoma:**
+```
+Killed
+# ou
+OOMKilled
+```
+
+**Solução:**
+```bash
+# Reduzir scanners simultâneos
+{
+  "hexstrikeAi": {
+    "maxConcurrentScans": 1
+  }
+}
+
+# Ou aumentar memória swap
+sudo fallocate -l 4G /swapfile
+sudo chmod 600 /swapfile
+sudo mkswap /swapfile
+sudo swapon /swapfile
+```
+
+### Logs e Debug
+
+#### Ver Logs do Servidor
+
+```bash
+# Logs em tempo real
+tail -f extensions/hexstrike-ai/hexstrike.log
+
+# Ou via systemd (se instalado como serviço)
+journalctl -u hexstrike -f
+```
+
+#### Modo Debug
+
+```bash
+# Iniciar com debug
+HEXSTRIKE_DEBUG=1 poolbot security.status
+```
+
+### FAQ
+
+**Q: Posso usar em produção?**  
+R: ⚠️ **Não recomendado**. Use apenas em ambientes de teste controlados.
+
+**Q: Preciso de todas 150 ferramentas?**  
+R: Não. Instale apenas as que você usa. Scanners são detectados automaticamente.
+
+**Q: Funciona em Windows?**  
+R: ⚠️ Suporte limitado. Recomendado Linux (Kali) ou macOS.
+
+**Q: Quanto tempo demora um scan?**  
+R: Varia de 1 minuto (scan rápido) a 2+ horas (scan completo).
+
+**Q: É legal usar essas ferramentas?**  
+R: ⚠️ **Apenas em sistemas que você possui ou tem autorização escrita.**
+
+---
+
+## ⚠️ Segurança
+
+### Avisos Legais
+
+> **IMPORTANTE:** HexStrike AI é uma ferramenta de segurança ofensiva. Use apenas:
+> - ✅ Em sistemas que você possui
+> - ✅ Com autorização escrita do proprietário
+> - ✅ Para fins educacionais em ambientes controlados
+> - ✅ Em compliance com leis locais
+>
+> **NUNCA use em:**
+> - ❌ Sistemas de terceiros sem autorização
+> - ❌ Redes que você não possui
+> - ❌ Para atividades ilegais
+>
+> **Responsabilidade:** Você é responsável pelo uso ético e legal desta ferramenta.
+
+### Melhores Práticas
+
+1. **Sempre use em ambiente isolado** (VM, container, laboratório)
+2. **Nunca escaneie alvos sem autorização**
+3. **Mantenha ferramentas atualizadas**
+4. **Revise resultados antes de tomar ação**
+5. **Documente todas as atividades**
+
+---
+
+## 📄 Licença
+
+MIT License - veja [LICENSE](LICENSE) para detalhes.
+
+---
+
+## 🤝 Contribuindo
+
+Contribuições são bem-vindas! Por favor:
+
+1. Fork o repositório
+2. Crie branch para feature (`git checkout -b feature/AmazingFeature`)
+3. Commit mudanças (`git commit -m 'Add AmazingFeature'`)
+4. Push para branch (`git push origin feature/AmazingFeature`)
+5. Open Pull Request
+
+### Desenvolvimento
+
+```bash
+# Clone repositório
+git clone https://github.com/poolbot/pool-bot.git
+cd pool-bot/extensions/hexstrike-ai
+
+# Instalar dependências dev
+pnpm install
+
+# Rodar testes
+pnpm test
+
+# Build
+pnpm build
+```
+
+---
+
+## 📞 Suporte
+
+- **Documentação:** `docs/hexstrike/`
+- **Issues:** https://github.com/poolbot/pool-bot/issues
+- **Discord:** https://discord.gg/poolbot
+- **Twitter:** @poolbot
+
+---
+
+## 🙏 Créditos
+
+HexStrike AI integra 150+ ferramentas open-source de segurança. Obrigado a todos os mantenedores!
+
+**Ferramentas Principais:**
+- [nmap](https://nmap.org/)
+- [nuclei](https://nuclei.projectdiscovery.io/)
+- [sqlmap](http://sqlmap.org/)
+- [Metasploit](https://metasploit.com/)
+- [Burp Suite](https://portswigger.net/burp)
 
-- `GET /health` - Health check
-- `GET /api/tools` - List available scanners
-- `POST /api/scan` - Start new scan
-- `GET /api/scan/:id` - Get scan results
-- `GET /api/scans` - List all scans
+**E inspirado por:**
+- [Kali Linux](https://kali.org/)
+- [Parrot Security](https://parrotsec.org/)
+- [BlackArch](https://blackarch.org/)
 
-## License
+---
 
-MIT
+*Documento gerado em Março de 2026.*  
+*HexStrike AI v6.0.0 - Blood-Red Offensive Intelligence Core*