@poolzin/pool-bot 2026.3.6 → 2026.3.9

package/docs/integrations/HEXSTRIKE_PLAN.md

@@ -0,0 +1,796 @@
+# HexStrike AI Integration - Implementation Plan
+
+**Status**: Ready for implementation  
+**Priority**: High  
+**Estimated Duration**: 3 weeks  
+**Dependencies**: Python Gateway Node SDK
+
+---
+
+## Overview
+
+Integrate HexStrike AI's 150+ security tools as a Gateway Node to enable security scanning, penetration testing, and CTF solving within PoolBot.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     PoolBot Core                            │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │              Gateway Server (WebSocket)               │    │
+│  └──────────────────────┬──────────────────────────────┘    │
+└─────────────────────────┼───────────────────────────────────┘
+                          │
+                          │ WebSocket (JSON-RPC)
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│              HexStrike Gateway Node (Python)                │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
+│  │  Node Client │  │  FastMCP     │  │  Security    │       │
+│  │  (WebSocket) │──│  Server      │──│  Tools       │       │
+│  └──────────────┘  └──────────────┘  └──────────────┘       │
+│         │                                                   │
+│         │         ┌──────────────┐  ┌──────────────┐       │
+│         │         │  nmap        │  │  nuclei      │       │
+│         │         │  sqlmap      │  │  metasploit  │       │
+│         │         │  burpsuite   │  │  ...         │       │
+│         │         └──────────────┘  └──────────────┘       │
+│         │                                                   │
+│         └───────────────────────────────────────────────────┘
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Tool Categories
+
+| Category | Tools | Use Case |
+|----------|-------|----------|
+| **Reconnaissance** | nmap, subfinder, amass | Network discovery |
+| **Vulnerability Scanning** | nuclei, openvas, nessus | Find vulnerabilities |
+| **Web Testing** | sqlmap, burpsuite, zap | Web app security |
+| **Exploitation** | metasploit, beef, commix | Proof of concept |
+| **CTF** | Custom solvers | Capture The Flag |
+| **Bug Bounty** | Recon + vuln scanners | Automated hunting |
+
+## Implementation Steps
+
+### Week 1: Python Gateway Node SDK
+
+#### Day 1-2: Core SDK
+```python
+# extensions/python-sdk/poolbot_node/__init__.py
+from typing import Any, Callable, Dict, List, Optional
+from websocket import WebSocketApp
+import json
+import asyncio
+
+class GatewayNode:
+    def __init__(self, config: NodeConfig):
+        self.node_id = config.node_id
+        self.gateway_url = config.gateway_url
+        self.token = config.token
+        self.tools: Dict[str, Tool] = {}
+        self.ws: Optional[WebSocketApp] = None
+    
+    def register_tool(self, name: str, handler: Callable, schema: Dict):
+        self.tools[name] = Tool(name, handler, schema)
+    
+    async def connect(self):
+        self.ws = WebSocketApp(
+            self.gateway_url,
+            header={"Authorization": f"Bearer {self.token}"},
+            on_open=self._on_open,
+            on_message=self._on_message,
+            on_error=self._on_error,
+            on_close=self._on_close
+        )
+        self.ws.run_forever()
+    
+    async def _on_open(self, ws):
+        await self._register()
+    
+    async def _register(self):
+        registration = {
+            "type": "register",
+            "payload": {
+                "nodeId": self.node_id,
+                "capabilities": ["tools.security.*"],
+                "tools": [
+                    {
+                        "name": name,
+                        "description": tool.schema.get("description"),
+                        "parameters": tool.schema
+                    }
+                    for name, tool in self.tools.items()
+                ]
+            }
+        }
+        self.ws.send(json.dumps(registration))
+```
+
+#### Day 3-4: Tool Wrappers
+```python
+# extensions/hexstrike-gateway/src/tools/nmap_tool.py
+from poolbot_node import GatewayNode
+import subprocess
+import json
+import xml.etree.ElementTree as ET
+
+class NmapTool:
+    def __init__(self):
+        self.schema = {
+            "description": "Network discovery and security auditing",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "target": {
+                        "type": "string",
+                        "description": "Target IP or hostname"
+                    },
+                    "ports": {
+                        "type": "string",
+                        "description": "Port range (e.g., '1-65535' or '80,443')",
+                        "default": "1-1000"
+                    },
+                    "options": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Additional nmap options",
+                        "default": ["-sV", "-sC"]
+                    }
+                },
+                "required": ["target"]
+            }
+        }
+    
+    async def execute(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        target = params["target"]
+        ports = params.get("ports", "1-1000")
+        options = params.get("options", ["-sV", "-sC"])
+        
+        cmd = ["nmap", "-oX", "-"] + options + ["-p", ports, target]
+        
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=300
+            )
+            
+            if result.returncode != 0:
+                return {
+                    "success": False,
+                    "error": result.stderr
+                }
+            
+            # Parse XML output
+            parsed = self._parse_xml(result.stdout)
+            
+            return {
+                "success": True,
+                "data": parsed,
+                "raw": result.stdout
+            }
+        except subprocess.TimeoutExpired:
+            return {
+                "success": False,
+                "error": "Scan timed out after 5 minutes"
+            }
+        except Exception as e:
+            return {
+                "success": False,
+                "error": str(e)
+            }
+    
+    def _parse_xml(self, xml_output: str) -> Dict:
+        root = ET.fromstring(xml_output)
+        hosts = []
+        
+        for host in root.findall("host"):
+            host_data = {
+                "address": host.find("address").get("addr"),
+                "ports": []
+            }
+            
+            ports = host.find("ports")
+            if ports:
+                for port in ports.findall("port"):
+                    port_data = {
+                        "port": port.get("portid"),
+                        "protocol": port.get("protocol"),
+                        "state": port.find("state").get("state"),
+                        "service": port.find("service").get("name") if port.find("service") else None
+                    }
+                    host_data["ports"].append(port_data)
+            
+            hosts.append(host_data)
+        
+        return {"hosts": hosts}
+```
+
+#### Day 5: Security Scanner Tool
+```python
+# extensions/hexstrike-gateway/src/tools/security_scanner.py
+from typing import List, Dict, Any
+import asyncio
+
+class SecurityScanner:
+    """Orchestrates multiple security tools"""
+    
+    def __init__(self, tools: Dict[str, Any]):
+        self.tools = tools
+        self.schema = {
+            "description": "Run comprehensive security scan using multiple tools",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "target": {
+                        "type": "string",
+                        "description": "Target URL or IP"
+                    },
+                    "scan_type": {
+                        "type": "string",
+                        "enum": ["quick", "full", "web", "network"],
+                        "default": "quick"
+                    },
+                    "tools": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Specific tools to run (default: auto-select)"
+                    }
+                },
+                "required": ["target"]
+            }
+        }
+    
+    async def execute(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        target = params["target"]
+        scan_type = params.get("scan_type", "quick")
+        selected_tools = params.get("tools")
+        
+        # Auto-select tools based on scan type
+        if not selected_tools:
+            selected_tools = self._select_tools(scan_type, target)
+        
+        # Run tools in parallel
+        results = await asyncio.gather(*[
+            self._run_tool(tool_name, target)
+            for tool_name in selected_tools
+        ])
+        
+        # Aggregate results
+        return {
+            "success": True,
+            "scan_type": scan_type,
+            "target": target,
+            "results": {
+                name: result
+                for name, result in zip(selected_tools, results)
+            },
+            "summary": self._generate_summary(results)
+        }
+    
+    def _select_tools(self, scan_type: str, target: str) -> List[str]:
+        if scan_type == "quick":
+            return ["nmap"]
+        elif scan_type == "full":
+            return ["nmap", "nuclei", "subfinder"]
+        elif scan_type == "web":
+            return ["nuclei", "sqlmap", "nikto"]
+        elif scan_type == "network":
+            return ["nmap", "masscan"]
+        return ["nmap"]
+    
+    async def _run_tool(self, tool_name: str, target: str) -> Dict:
+        if tool_name not in self.tools:
+            return {"error": f"Tool {tool_name} not available"}
+        
+        tool = self.tools[tool_name]
+        return await tool.execute({"target": target})
+    
+    def _generate_summary(self, results: List[Dict]) -> Dict:
+        total_findings = sum(
+            len(r.get("data", {}).get("hosts", []))
+            for r in results
+        )
+        return {
+            "total_tools": len(results),
+            "successful": sum(1 for r in results if r.get("success")),
+            "failed": sum(1 for r in results if not r.get("success")),
+            "total_findings": total_findings
+        }
+```
+
+### Week 2: HexStrike Integration
+
+#### Day 6-7: Main Node
+```python
+# extensions/hexstrike-gateway/src/node.py
+from poolbot_node import GatewayNode
+from tools.nmap_tool import NmapTool
+from tools.nuclei_tool import NucleiTool
+from tools.security_scanner import SecurityScanner
+from tools.ctf_solver import CTFSolver
+from tools.bug_bounty import BugBountyHunter
+
+class HexStrikeNode(GatewayNode):
+    def __init__(self, config: NodeConfig):
+        super().__init__(config)
+        self._setup_tools()
+    
+    def _setup_tools(self):
+        # Individual tools
+        nmap = NmapTool()
+        self.register_tool("security.nmap", nmap.execute, nmap.schema)
+        
+        nuclei = NucleiTool()
+        self.register_tool("security.nuclei", nuclei.execute, nuclei.schema)
+        
+        # Composite tools
+        scanner = SecurityScanner({
+            "nmap": nmap,
+            "nuclei": nuclei
+        })
+        self.register_tool("security.scan", scanner.execute, scanner.schema)
+        
+        # AI agents
+        ctf = CTFSolver()
+        self.register_tool("pentest.ctf", ctf.execute, ctf.schema)
+        
+        bounty = BugBountyHunter()
+        self.register_tool("pentest.bugbounty", bounty.execute, bounty.schema)
+    
+    async def handle_tool_call(self, call: ToolCall) -> ToolResult:
+        tool_name = call.tool
+        
+        # Map PoolBot tool names to HexStrike tools
+        tool_map = {
+            "security.nmap": self.tools.get("security.nmap"),
+            "security.nuclei": self.tools.get("security.nuclei"),
+            "security.scan": self.tools.get("security.scan"),
+            "pentest.ctf": self.tools.get("pentest.ctf"),
+            "pentest.bugbounty": self.tools.get("pentest.bugbounty"),
+        }
+        
+        tool = tool_map.get(tool_name)
+        if not tool:
+            return {"success": False, "error": f"Unknown tool: {tool_name}"}
+        
+        try:
+            result = await tool.handler(call.params)
+            return {"success": True, "data": result}
+        except Exception as e:
+            return {"success": False, "error": str(e)}
+
+if __name__ == "__main__":
+    import asyncio
+    
+    config = NodeConfig(
+        node_id="hexstrike-1",
+        gateway_url="ws://localhost:8080/gateway",
+        token=os.getenv("POOLBOT_GATEWAY_TOKEN")
+    )
+    
+    node = HexStrikeNode(config)
+    asyncio.run(node.connect())
+```
+
+#### Day 8-9: CTF Solver Agent
+```python
+# extensions/hexstrike-gateway/src/tools/ctf_solver.py
+import openai
+import re
+
+class CTFSolver:
+    """AI-powered CTF challenge solver"""
+    
+    def __init__(self):
+        self.client = openai.AsyncOpenAI()
+        self.schema = {
+            "description": "Solve CTF challenges using AI analysis",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "challenge": {
+                        "type": "string",
+                        "description": "Challenge description or file content"
+                    },
+                    "category": {
+                        "type": "string",
+                        "enum": ["crypto", "web", "pwn", "reverse", "forensics", "misc"],
+                        "description": "Challenge category"
+                    },
+                    "hints": {
+                        "type": "boolean",
+                        "default": True,
+                        "description": "Provide hints instead of full solution"
+                    }
+                },
+                "required": ["challenge"]
+            }
+        }
+    
+    async def execute(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        challenge = params["challenge"]
+        category = params.get("category")
+        hints_only = params.get("hints", True)
+        
+        prompt = self._build_prompt(challenge, category, hints_only)
+        
+        response = await self.client.chat.completions.create(
+            model="gpt-4",
+            messages=[
+                {"role": "system", "content": "You are a CTF expert. Analyze challenges and provide solutions."},
+                {"role": "user", "content": prompt}
+            ]
+        )
+        
+        analysis = response.choices[0].message.content
+        
+        return {
+            "success": True,
+            "analysis": analysis,
+            "category": category,
+            "hints": hints_only,
+            "flag": self._extract_flag(analysis) if not hints_only else None
+        }
+    
+    def _build_prompt(self, challenge: str, category: Optional[str], hints: bool) -> str:
+        parts = [
+            "Analyze this CTF challenge:",
+            "",
+            challenge,
+            ""
+        ]
+        
+        if category:
+            parts.append(f"Category: {category}")
+        
+        if hints:
+            parts.append("\nProvide hints and approach guidance. Do not give the full solution immediately.")
+        else:
+            parts.append("\nProvide a complete solution with the flag if possible.")
+        
+        return "\n".join(parts)
+    
+    def _extract_flag(self, text: str) -> Optional[str]:
+        # Common flag formats
+        patterns = [
+            r'flag\{[^}]+\}',
+            r'FLAG\{[^}]+\}',
+            r'ctf\{[^}]+\}',
+            r'CTF\{[^}]+\}'
+        ]
+        
+        for pattern in patterns:
+            match = re.search(pattern, text)
+            if match:
+                return match.group(0)
+        
+        return None
+```
+
+#### Day 10: Bug Bounty Hunter
+```python
+# extensions/hexstrike-gateway/src/tools/bug_bounty.py
+class BugBountyHunter:
+    """Automated bug bounty hunting workflow"""
+    
+    def __init__(self):
+        self.schema = {
+            "description": "Automated bug bounty reconnaissance and scanning",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "target": {
+                        "type": "string",
+                        "description": "Target domain (e.g., example.com)"
+                    },
+                    "scope": {
+                        "type": "string",
+                        "description": "Bug bounty scope (in-scope domains/paths)"
+                    },
+                    "depth": {
+                        "type": "string",
+                        "enum": ["passive", "active", "aggressive"],
+                        "default": "passive"
+                    }
+                },
+                "required": ["target", "scope"]
+            }
+        }
+    
+    async def execute(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        target = params["target"]
+        scope = params["scope"]
+        depth = params.get("depth", "passive")
+        
+        workflow = []
+        
+        # Phase 1: Subdomain enumeration
+        if depth in ["passive", "active", "aggressive"]:
+            workflow.append({"phase": "subdomain_enum", "tool": "subfinder"})
+        
+        # Phase 2: Port scanning
+        if depth in ["active", "aggressive"]:
+            workflow.append({"phase": "port_scan", "tool": "nmap"})
+        
+        # Phase 3: Web scanning
+        if depth in ["active", "aggressive"]:
+            workflow.append({"phase": "web_scan", "tool": "nuclei"})
+        
+        # Phase 4: Vulnerability scanning
+        if depth == "aggressive":
+            workflow.append({"phase": "vuln_scan", "tool": "nuclei"})
+        
+        return {
+            "success": True,
+            "target": target,
+            "scope": scope,
+            "depth": depth,
+            "workflow": workflow,
+            "findings": [],  # Populated during execution
+            "report_url": None  # Generated after completion
+        }
+```
+
+### Week 3: PoolBot Integration
+
+#### Day 11-12: Security Agent Type
+```typescript
+// src/agents/types/security.ts
+export const securityAgentConfig: AgentConfig = {
+  type: 'security',
+  name: 'Security Analyst',
+  description: 'Specialized agent for security testing and analysis',
+  
+  systemPrompt: `
+You are a security analyst with access to professional security tools.
+Your capabilities include:
+- Network reconnaissance (nmap)
+- Vulnerability scanning (nuclei)
+- Web application testing (sqlmap, burpsuite)
+- CTF challenge solving
+- Bug bounty hunting
+
+Always:
+1. Get explicit authorization before scanning
+2. Respect scope and rules of engagement
+3. Document findings clearly
+4. Provide actionable remediation advice
+
+Never:
+- Scan without permission
+- Exploit vulnerabilities without authorization
+- Expose sensitive data in reports
+`,
+
+  availableSkills: [
+    'security.nmap',
+    'security.nuclei',
+    'security.scan',
+    'pentest.ctf',
+    'pentest.bugbounty'
+  ],
+  
+  defaultOptions: {
+    model: 'claude-3-opus',
+    temperature: 0.2, // More deterministic for security
+    maxTokens: 4000
+  }
+};
+```
+
+#### Day 13-14: Report Generation
+```typescript
+// src/security/report-generator.ts
+export interface SecurityReport {
+  id: string;
+  target: string;
+  scanType: string;
+  startTime: Date;
+  endTime: Date;
+  findings: SecurityFinding[];
+  summary: {
+    critical: number;
+    high: number;
+    medium: number;
+    low: number;
+    info: number;
+  };
+  recommendations: string[];
+}
+
+export class SecurityReportGenerator {
+  generate(report: SecurityReport): string {
+    return `
+# Security Assessment Report
+
+**Target**: ${report.target}  
+**Scan Type**: ${report.scanType}  
+**Date**: ${report.startTime.toISOString()}  
+
+## Executive Summary
+
+${this.generateSummary(report.summary)}
+
+## Findings
+
+${report.findings.map(f => this.formatFinding(f)).join('\n\n')}
+
+## Recommendations
+
+${report.recommendations.map(r => `- ${r}`).join('\n')}
+
+## Methodology
+
+This assessment was conducted using automated security tools including:
+- Nmap for network discovery
+- Nuclei for vulnerability scanning
+- Custom security analyzers
+
+---
+*Generated by PoolBot Security Module*
+`;
+  }
+  
+  private generateSummary(summary: SecurityReport['summary']): string {
+    const total = summary.critical + summary.high + summary.medium + summary.low + summary.info;
+    
+    return `
+| Severity | Count |
+|----------|-------|
+| Critical | ${summary.critical} |
+| High | ${summary.high} |
+| Medium | ${summary.medium} |
+| Low | ${summary.low} |
+| Info | ${summary.info} |
+| **Total** | **${total}** |
+`;
+  }
+  
+  private formatFinding(finding: SecurityFinding): string {
+    return `
+### ${finding.title} (${finding.severity})
+
+**Description**: ${finding.description}
+
+**Evidence**:
+\`\`\`
+${finding.evidence}
+\`\`\`
+
+**Remediation**: ${finding.remediation}
+`;
+  }
+}
+```
+
+#### Day 15: Testing & Documentation
+- Unit tests for Python SDK
+- Integration tests with Gateway
+- Security agent tests
+- Documentation
+
+## File Structure
+
+```
+extensions/
+├── python-sdk/                    # Shared Python SDK
+│   ├── poolbot_node/
+│   │   ├── __init__.py
+│   │   ├── node.py
+│   │   ├── types.py
+│   │   └── utils.py
+│   ├── setup.py
+│   └── README.md
+├── hexstrike-gateway/             # HexStrike integration
+│   ├── src/
+│   │   ├── node.py
+│   │   ├── tools/
+│   │   │   ├── __init__.py
+│   │   │   ├── nmap_tool.py
+│   │   │   ├── nuclei_tool.py
+│   │   │   ├── security_scanner.py
+│   │   │   ├── ctf_solver.py
+│   │   │   └── bug_bounty.py
+│   │   └── utils/
+│   ├── requirements.txt
+│   ├── Dockerfile
+│   └── README.md
+```
+
+## Usage Examples
+
+### Example 1: Network Scan
+```typescript
+const agent = await createAgent({ type: 'security' });
+
+const result = await agent.execute({
+  skill: 'security.nmap',
+  params: {
+    target: '192.168.1.1',
+    ports: '1-1000',
+    options: ['-sV', '-sC']
+  }
+});
+```
+
+### Example 2: Comprehensive Security Scan
+```typescript
+const result = await agent.execute({
+  skill: 'security.scan',
+  params: {
+    target: 'https://example.com',
+    scan_type: 'web'
+  }
+});
+```
+
+### Example 3: CTF Challenge
+```typescript
+const result = await agent.execute({
+  skill: 'pentest.ctf',
+  params: {
+    challenge: `
+      We found a file encrypted with AES-256.
+      The key is derived from a 4-digit PIN.
+      How do we decrypt it?
+    `,
+    category: 'crypto',
+    hints: true
+  }
+});
+```
+
+### Example 4: Bug Bounty
+```typescript
+const result = await agent.execute({
+  skill: 'pentest.bugbounty',
+  params: {
+    target: 'example.com',
+    scope: '*.example.com',
+    depth: 'active'
+  }
+});
+```
+
+## Security Considerations
+
+1. **Authorization**: Require explicit scope confirmation
+2. **Rate Limiting**: Prevent abuse of scanning tools
+3. **Sandboxing**: Run tools in isolated containers
+4. **Audit Logging**: Log all security operations
+5. **Responsible Disclosure**: Guide users on proper disclosure
+
+## Success Criteria
+
+- [ ] Python Gateway Node SDK functional
+- [ ] 150+ tools accessible via Gateway
+- [ ] Security agent type implemented
+- [ ] Report generation working
+- [ ] CTF solver functional
+- [ ] Bug bounty workflow working
+- [ ] Tests pass (>80% coverage)
+- [ ] Documentation complete
+
+## Docker Support
+
+```dockerfile
+# extensions/hexstrike-gateway/Dockerfile
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y \
+    nmap \
+    nuclei \
+    sqlmap \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+
+COPY src/ ./src/
+
+CMD ["python", "-m", "src.node"]
+```