From 4028c6326e67c2ec9ef0247686459d0f1c7c4521 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 3 Dec 2025 13:27:16 +0000 Subject: [PATCH] Add comprehensive INSTALL.md with step-by-step installation guide Co-authored-by: mblanke <9078342+mblanke@users.noreply.github.com> --- INSTALL.md | 634 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 634 insertions(+) create mode 100644 INSTALL.md diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..fd40a03 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,634 @@ +# Installation Guide - StrikePackageGPT New Features + +This guide walks you through installing and setting up the new features added to StrikePackageGPT. + +## πŸ“‹ Table of Contents + +1. [Prerequisites](#prerequisites) +2. [Quick Start (Minimal Setup)](#quick-start-minimal-setup) +3. [Full Installation (All Features)](#full-installation-all-features) +4. [Optional Features Setup](#optional-features-setup) +5. [Verification & Testing](#verification--testing) +6. [Troubleshooting](#troubleshooting) + +--- + +## Prerequisites + +### Required +- **Docker & Docker Compose** - Already installed if you're using StrikePackageGPT +- **Python 3.12+** - Included in the containers +- **8GB+ RAM** - For running the services + +### Optional (for enhanced features) +- **Node.js & npm** - Only if you want to build React components from source +- **NVIDIA GPU** - For faster local Whisper transcription +- **OpenAI API Key** - For cloud-based voice and LLM features +- **Anthropic API Key** - For Claude LLM support + +--- + +## Quick Start (Minimal Setup) + +This gets you running with **all backend features** and **basic frontend** (no build system required). + +### Step 1: Start the Services + +```bash +cd /path/to/StrikePackageGPT +docker-compose up -d +``` + +This starts all services including the new API endpoints. + +### Step 2: Verify Installation + +```bash +# Check if services are running +docker-compose ps + +# Test the new API endpoints +curl http://localhost:8001/health + +# Test nmap parser endpoint +curl -X POST http://localhost:8001/api/nmap/parse \ + -H "Content-Type: application/json" \ + -d '{"format": "xml", "content": ""}' +``` + +### Step 3: View the Icons + +The new SVG icons are already accessible: + +```bash +# Open in browser +http://localhost:8080/static/windows.svg +http://localhost:8080/static/linux.svg +http://localhost:8080/static/mac.svg +http://localhost:8080/static/server.svg +http://localhost:8080/static/workstation.svg +http://localhost:8080/static/network.svg +http://localhost:8080/static/unknown.svg +``` + +### Step 4: Access the Dashboard + +```bash +# Open the dashboard +http://localhost:8080 +``` + +**That's it for basic setup!** All backend features are now available via API endpoints. + +--- + +## Full Installation (All Features) + +This enables **React components** and **voice control** with all optional features. + +### Step 1: Backend Setup + +The backend is already installed and running from the Quick Start. No additional steps needed! + +### Step 2: Optional - Install Voice Control Dependencies + +For **local Whisper** (speech-to-text without API): + +```bash +# SSH into the hackgpt-api container +docker exec -it strikepackage-hackgpt-api bash + +# Install Whisper (inside container) +pip install openai-whisper + +# Exit container +exit +``` + +For **local Coqui TTS** (text-to-speech without API): + +```bash +# SSH into the hackgpt-api container +docker exec -it strikepackage-hackgpt-api bash + +# Install Coqui TTS (inside container) +pip install TTS + +# Exit container +exit +``` + +**Note:** These are optional. The system will use OpenAI API as fallback if these aren't installed. + +### Step 3: Configure API Keys (Optional) + +If you want to use cloud-based LLM and voice features: + +```bash +# Edit the .env file +nano .env + +# Add these lines: +OPENAI_API_KEY=sk-your-key-here +ANTHROPIC_API_KEY=your-anthropic-key-here + +# Save and restart services +docker-compose restart +``` + +### Step 4: Frontend Integration (Choose One Option) + +#### Option A: Use Vanilla JavaScript (No Build Required) βœ… Recommended for Quick Setup + +This integrates the features using plain JavaScript without React build system. + +1. **Copy the integration code:** + +```bash +# Create the integration file +cat > services/dashboard/static/js/strikepackage-features.js << 'EOF' +// Voice Control Integration +class VoiceController { + constructor() { + this.isListening = false; + this.setupButton(); + } + + setupButton() { + const button = document.createElement('button'); + button.id = 'voice-button'; + button.innerHTML = 'πŸŽ™οΈ'; + button.style.cssText = ` + position: fixed; + bottom: 20px; + right: 20px; + width: 60px; + height: 60px; + border-radius: 50%; + border: none; + background: #3498DB; + color: white; + font-size: 24px; + cursor: pointer; + box-shadow: 0 4px 12px rgba(0,0,0,0.2); + z-index: 1000; + `; + button.onclick = () => this.toggleListening(); + document.body.appendChild(button); + } + + async toggleListening() { + if (!this.isListening) { + await this.startListening(); + } else { + this.stopListening(); + } + } + + async startListening() { + const stream = await navigator.mediaDevices.getUserMedia({ audio: true }); + this.mediaRecorder = new MediaRecorder(stream); + const chunks = []; + + this.mediaRecorder.ondataavailable = (e) => chunks.push(e.data); + this.mediaRecorder.onstop = async () => { + const blob = new Blob(chunks, { type: 'audio/webm' }); + await this.processAudio(blob); + stream.getTracks().forEach(track => track.stop()); + }; + + this.mediaRecorder.start(); + this.isListening = true; + document.getElementById('voice-button').innerHTML = '⏸️'; + } + + stopListening() { + if (this.mediaRecorder) { + this.mediaRecorder.stop(); + this.isListening = false; + document.getElementById('voice-button').innerHTML = 'πŸŽ™οΈ'; + } + } + + async processAudio(blob) { + const formData = new FormData(); + formData.append('audio', blob); + + const response = await fetch('/api/voice/transcribe', { + method: 'POST', + body: formData + }); + + const result = await response.json(); + console.log('Transcribed:', result.text); + alert('You said: ' + result.text); + } +} + +// Initialize on page load +document.addEventListener('DOMContentLoaded', () => { + window.voiceController = new VoiceController(); +}); +EOF +``` + +2. **Update the dashboard template:** + +```bash +# Edit the main template +nano services/dashboard/templates/index.html + +# Add before : +# +``` + +3. **Restart the dashboard:** + +```bash +docker-compose restart dashboard +``` + +#### Option B: Build React Components (Full Featured) + +This requires Node.js and npm to build the React components. + +1. **Install Node.js dependencies:** + +```bash +cd services/dashboard + +# Initialize npm if not already done +npm init -y + +# Install React and build tools +npm install react react-dom +npm install --save-dev @babel/core @babel/preset-react webpack webpack-cli babel-loader css-loader style-loader + +# Install Cytoscape for NetworkMap +npm install cytoscape +``` + +2. **Create webpack configuration:** + +```bash +cat > webpack.config.js << 'EOF' +const path = require('path'); + +module.exports = { + entry: './src/index.jsx', + output: { + path: path.resolve(__dirname, 'static/dist'), + filename: 'bundle.js' + }, + module: { + rules: [ + { + test: /\.jsx?$/, + exclude: /node_modules/, + use: { + loader: 'babel-loader', + options: { + presets: ['@babel/preset-react'] + } + } + } + ] + }, + resolve: { + extensions: ['.js', '.jsx'] + } +}; +EOF +``` + +3. **Create the React entry point:** + +```bash +mkdir -p src + +cat > src/index.jsx << 'EOF' +import React from 'react'; +import ReactDOM from 'react-dom'; +import VoiceControls from '../VoiceControls'; +import HelpChat from '../HelpChat'; + +function App() { + const [showHelp, setShowHelp] = React.useState(false); + + return ( + <> + console.log(cmd)} /> + + setShowHelp(false)} + currentPage="dashboard" + /> + + ); +} + +ReactDOM.render(, document.getElementById('root')); +EOF +``` + +4. **Build the bundle:** + +```bash +# Add to package.json scripts +npm set-script build "webpack --mode production" + +# Build +npm run build +``` + +5. **Update HTML template:** + +```bash +# services/dashboard/templates/index.html should include: +#
+# +``` + +--- + +## Optional Features Setup + +### 1. Enable GPU Acceleration for Whisper + +If you have an NVIDIA GPU: + +```bash +# Edit docker-compose.yml +nano docker-compose.yml + +# Add to hackgpt-api service: +# deploy: +# resources: +# reservations: +# devices: +# - driver: nvidia +# count: all +# capabilities: [gpu] + +# Restart +docker-compose up -d --build hackgpt-api +``` + +### 2. Configure n8n Webhook Integration + +```bash +# The webhook endpoint is already available at: +# POST http://localhost:8001/api/webhook/n8n + +# In n8n, create a webhook node pointing to: +# http://strikepackage-hackgpt-api:8001/api/webhook/n8n +``` + +### 3. Set Up Config Backups Directory + +```bash +# Create backup directory +docker exec -it strikepackage-hackgpt-api mkdir -p /workspace/config_backups + +# Or set custom location via environment variable +echo "CONFIG_BACKUP_DIR=/custom/path" >> .env +docker-compose restart +``` + +--- + +## Verification & Testing + +### Test Backend Features + +```bash +# 1. Test Nmap Parser +curl -X POST http://localhost:8001/api/nmap/parse \ + -H "Content-Type: application/json" \ + -d '{"format": "xml", "content": "
"}' + +# 2. Test Explanation API +curl -X POST http://localhost:8001/api/explain \ + -H "Content-Type: application/json" \ + -d '{"type": "error", "content": "Connection refused"}' + +# 3. Test Config Validation +curl -X POST http://localhost:8001/api/config/validate \ + -H "Content-Type: application/json" \ + -d '{"config_data": {"timeout": 30}, "config_type": "scan"}' + +# 4. Test LLM Chat (requires LLM service running) +curl -X POST http://localhost:8001/api/llm/chat \ + -H "Content-Type: application/json" \ + -d '{"message": "How do I scan a network?"}' +``` + +### Test Voice Control (Browser Required) + +1. Open: http://localhost:8080 +2. Click the microphone button (πŸŽ™οΈ) in bottom-right corner +3. Allow microphone permissions +4. Speak a command: "scan 192.168.1.1" +5. Check browser console for transcription result + +### Test Icons + +Open each icon URL in your browser: +- http://localhost:8080/static/windows.svg +- http://localhost:8080/static/linux.svg +- http://localhost:8080/static/mac.svg +- http://localhost:8080/static/server.svg +- http://localhost:8080/static/workstation.svg +- http://localhost:8080/static/network.svg +- http://localhost:8080/static/unknown.svg + +### Run a Complete Test Workflow + +```bash +# 1. Run an nmap scan +nmap -oX scan.xml -sV 192.168.1.0/24 + +# 2. Parse the results +curl -X POST http://localhost:8001/api/nmap/parse \ + -H "Content-Type: application/json" \ + -d "{\"format\": \"xml\", \"content\": \"$(cat scan.xml | sed 's/"/\\"/g')\"}" + +# 3. The response will show all discovered hosts with OS/device classification +``` + +--- + +## Troubleshooting + +### Issue: Voice transcription not working + +**Solution:** +```bash +# Check if Whisper is installed +docker exec -it strikepackage-hackgpt-api pip list | grep whisper + +# If not, install it +docker exec -it strikepackage-hackgpt-api pip install openai-whisper + +# Or configure OpenAI API key as fallback +echo "OPENAI_API_KEY=sk-your-key" >> .env +docker-compose restart +``` + +### Issue: "Module not found" errors + +**Solution:** +```bash +# Rebuild the services +docker-compose down +docker-compose up -d --build +``` + +### Issue: Icons not showing + +**Solution:** +```bash +# Verify icons exist +ls -la services/dashboard/static/*.svg + +# Check permissions +docker exec -it strikepackage-dashboard ls -la /app/static/*.svg + +# Restart dashboard +docker-compose restart dashboard +``` + +### Issue: LLM chat not responding + +**Solution:** +```bash +# Check LLM router is running +docker-compose ps | grep llm-router + +# Test LLM router directly +curl http://localhost:8000/health + +# Check Ollama or API keys are configured +docker exec -it strikepackage-llm-router env | grep API_KEY +``` + +### Issue: Config backups not saving + +**Solution:** +```bash +# Create the backup directory +docker exec -it strikepackage-hackgpt-api mkdir -p /workspace/config_backups + +# Check permissions +docker exec -it strikepackage-hackgpt-api ls -la /workspace + +# Test backup endpoint +curl -X POST http://localhost:8001/api/config/backup \ + -H "Content-Type: application/json" \ + -d '{"config_name": "test", "config_data": {"test": "value"}}' +``` + +### Issue: React components not loading + +**Solution:** +```bash +# If using Option B (React build): + +cd services/dashboard + +# Install dependencies +npm install + +# Build +npm run build + +# Check if bundle exists +ls -la static/dist/bundle.js + +# Restart dashboard +docker-compose restart dashboard +``` + +### Issue: Permission denied for microphone + +**Solution:** +- Voice control requires HTTPS in production +- For local testing, ensure you're accessing via `localhost` (not IP address) +- Click the lock icon in browser and enable microphone permissions + +--- + +## Summary + +### Minimum Installation (Backend Only) +```bash +docker-compose up -d +# All API endpoints work immediately! +``` + +### Recommended Installation (Backend + Simple Frontend) +```bash +docker-compose up -d +# Add the vanilla JS integration script to templates +# Voice control and help features work in browser +``` + +### Full Installation (Everything) +```bash +docker-compose up -d +docker exec -it strikepackage-hackgpt-api pip install openai-whisper TTS +cd services/dashboard && npm install && npm run build +# All features including React components +``` + +--- + +## What's Installed? + +After installation, you have access to: + +βœ… **22 new API endpoints** for nmap, voice, explanations, LLM help, config validation +βœ… **5 backend Python modules** with comprehensive functionality +βœ… **5 React component templates** ready for integration +βœ… **7 professional SVG icons** for device/OS visualization +βœ… **Voice control** (with optional local Whisper or cloud API) +βœ… **Network mapping** (nmap parser ready for visualization) +βœ… **LLM help system** (chat, autocomplete, explanations) +βœ… **Config management** (validation, backup, restore) +βœ… **Webhook integration** (n8n, alerts) + +--- + +## Next Steps + +1. **Review the documentation:** + - `FEATURES.md` - Complete feature reference + - `INTEGRATION_EXAMPLE.md` - Detailed integration examples + - `IMPLEMENTATION_SUMMARY.md` - Overview and statistics + +2. **Test the features:** + - Try the API endpoints with curl + - Test voice control in browser + - Run an nmap scan and parse results + +3. **Customize:** + - Add your own voice commands in `voice.py` + - Customize wizard steps in `explain.py` + - Integrate React components into your UI + +4. **Deploy:** + - Configure production API keys + - Enable HTTPS for voice features + - Set up backup directory with proper permissions + +--- + +For questions or issues, refer to the troubleshooting section or check the comprehensive documentation in `FEATURES.md`. + +Happy scanning! 🎯