OctapusPrime is a headless pentesting appliance designed to run on a small ARM‐based board (e.g., Neo Pi running DietPi or Debian). It combines a comprehensive suite of proven CLI tools with an advanced IFTTT (If-This-Then-That) scenario builder featuring intelligent conditional execution, dynamic variable extraction, and real-time automation.
Enhanced Features:
- 40+ Security Tools organized by category (Network Discovery, Web Testing, Vulnerability Scanning, etc.)
- Advanced IFTTT Scenario Builder with conditional logic and variable extraction
- Dynamic Variable System with regex-based data extraction and substitution
- Enhanced Web Interface with real-time scenario execution monitoring
- Example Scenarios Library with pre-built penetration testing workflows
- Physical GPIO trigger (push-button + LED) for remote scan execution
- Professional dark-mode interface with octopus-themed design
With OctapusPrime, you can create sophisticated adaptive penetration testing workflows that intelligently respond to scan results and automatically adjust their behavior based on discovered services, open ports, and extracted data.
landing page with navigation to all features and modern octopus-themed design
Access to 40+ categorized security tools with real-time execution monitoring
Visual workflow creation with conditional logic, variable extraction, and intelligent automation
GPIO configuration, network settings, and platform-specific hardware setup
Watch tool execution in real-time with variable extraction and conditional logic decisions
- OctapusPrime One‐Touch Pentest Suite
-
Comprehensive 40+ Security Tools Suite
- Network Discovery: Nmap, Masscan, Zmap, Amass, Subfinder
- Web Application Testing: Gobuster, FFuF, Feroxbuster, Nikto, WhatWeb, SQLMap, Nuclei
- Vulnerability Scanning: Nuclei, Trivy, TestSSL
- Credential Attacks: Hydra, John the Ripper, Hashcat
- Information Gathering: TheHarvester, Amass, Subfinder, Shodan
- Enumeration: Enum4linux, NBTScan, LDAP Search, SNMP Check, SMB Client
- Specialized Tools: EyeWitness, GitLeaks, and more
-
Advanced IFTTT Scenario Builder
- Conditional Logic: IF-THEN execution based on previous step results
- Variable Extraction: Regex-based data capture from tool outputs
- Dynamic Substitution: Real-time variable replacement in arguments
- Example Scenarios: Pre-built workflows for common penetration testing methodologies
- Scenario Management: Save, load, and share complex testing workflows
- Validation System: Real-time argument and variable validation
Create intelligent workflows that adapt based on scan results
- Enhanced Web Interface
- Modern Dark Theme: Professional security-focused design
- Tool Categories: Organized tool selection with descriptions
- Real-time Execution: Live progress monitoring and log streaming
- Variable Picker: Visual variable selection and management
- Keyboard Shortcuts: Productivity enhancements for power users
- Responsive Design: Works on desktop, tablet, and mobile devices
Comprehensive tool dashboard with categorized security tools
- Professional Backend Architecture
- Thread-safe Execution: Parallel tool execution with proper resource management
- WebSocket Communication: Real-time bidirectional communication
- RESTful API: Complete API for automation and integration
- Error Handling: Comprehensive error recovery and reporting
- Logging System: Detailed execution logs and debugging information
Watch execution progress with real-time variable extraction and logging
┌──────────────┐ ┌───────────────────────┐ ┌──────────────────┐
│ Physical │ │ │ │ 40+ CLI Tools │
│ Button │── GPIO ─▶│ Enhanced Controller │── Thread ▶│ Network Discovery│
│ (GPIO 17) │ │ & IFTTT Engine │ │ Web Testing │
└──────────────┘ │ │ │ Vuln Scanning │
│ Variable Extraction │ │ Credential Attacks│
│ Conditional Logic │ │ Info Gathering │
└─────────┬─────────────┘ │ Enumeration │
│ └──────────────────┘
│ WebSocket + REST API
▼
┌───────────────────────┐ ┌─────────────────────┐
│ Enhanced Server │◀───┐ │ Enhanced Web UI │
│ (Flask + SocketIO) │ │ │ ┌─────────────────┐ │
│ Scenario Builder │ │ │ │ IFTTT Builder │ │
│ Variable System │ │ │ │ Variable System │ │
│ Example Library │ │ │ └─────────────────┘ │
│ Real-time Execution │ │ │ ┌─────────────────┐ │
│ /api/run_scenario │ └──▶ │ Live Monitoring │ │
│ /load_scenario │ │ │ Progress Tracking│ │
│ /list_scenarios │ │ └─────────────────┘ │
└───────────────────────┘ └─────────────────────┘
-
Enhanced Scenario Builder
- IFTTT conditional logic system
- Variable extraction with regex patterns
- Tool templates and argument validation
- Example scenario library
-
Variable System
- Dynamic parameter substitution
- Regex-based data extraction
- Built-in and custom variables
- Real-time variable validation
-
Advanced Tool Integration
- 40+ categorized security tools
- Tool-specific templates and examples
- Intelligent argument completion
- Performance optimization
Before installing OctapusPrime, ensure your system meets the following requirements:
- DietPi (Debian-based), Debian 12, Ubuntu 22.04/24.04, or Kali Linux
- Root/sudo privileges for package installation and systemd configuration
- At least 4GB RAM recommended for large scans
- 20GB+ storage for tools and scan results
Core System Packages:
sudo apt update && sudo apt upgrade -y
sudo apt install -y \
python3 \
python3-pip \
python3-venv \
python3-dev \
git \
curl \
wget \
build-essential \
libssl-dev \
libffi-dev \
software-properties-common \
apt-transport-https \
ca-certificates \
gnupg \
lsb-release# For Raspberry Pi/compatible boards
sudo apt install -y python3-rpi.gpio python3-gpiozero
# Alternative GPIO libraries
sudo apt install -y python3-lgpiocurl -s https://install.zerotier.com | sudo bash
sudo zerotier-cli join <YOUR_NETWORK_ID>Will be installed in virtual environment during setup:
# Core requirements (from requirements.txt)
Flask
Flask-SocketIO
eventlet
python-socketio
python-engineio
aiohttp
gpiozero
lgpio
requests- Static IP or discoverable hostname recommended
- Port 8080 accessible for web interface
- GPIO pins 17 (button) and 27 (LED) available if using hardware features
- Internet access for tool updates and vulnerability databases
# Update system and install core packages
sudo apt update && sudo apt upgrade -y
# Install essential build tools and libraries
sudo apt install -y \
python3 python3-pip python3-venv python3-dev \
git curl wget build-essential \
libssl-dev libffi-dev libxml2-dev libxslt1-dev \
zlib1g-dev libjpeg-dev libpng-dev \
software-properties-common apt-transport-https \
ca-certificates gnupg lsb-releaseNetwork Discovery & Scanning:
# Core network tools
sudo apt install -y nmap masscan zmap
# Advanced discovery tools
sudo apt install -y amass subfinder theharvester
# DNS enumeration
sudo apt install -y dnsutils dnsenum fierceWeb Application Testing:
# Directory/file enumeration
sudo apt install -y gobuster dirb dirsearch
# Web fuzzers
sudo apt install -y ffuf feroxbuster
# Web vulnerability scanners
sudo apt install -y nikto whatweb sqlmap
# Template-based scanner
go install -v github.com/projectdiscovery/nuclei/v2/cmd/nuclei@latestVulnerability & SSL Testing:
# SSL/TLS testing
sudo apt install -y testssl.sh sslscan
# Container vulnerability scanning
sudo apt install -y trivy
# General vulnerability scanning
sudo apt install -y openvas-scannerCredential Attacks:
# Brute force tools
sudo apt install -y hydra medusa patator
# Password cracking
sudo apt install -y john hashcatInformation Gathering:
# OSINT tools
sudo apt install -y theharvester maltego-teeth
# Social engineering
sudo apt install -y set
# Shodan CLI
pip3 install shodanEnumeration Tools:
# SMB/NetBIOS enumeration
sudo apt install -y enum4linux nbtscan smbclient
# LDAP enumeration
sudo apt install -y ldap-utils
# SNMP enumeration
sudo apt install -y snmp snmp-mibs-downloader
# Database tools
sudo apt install -y postgresql-client mysql-clientGo-based Tools:
# Install Go if not present
sudo apt install -y golang-go
# Install Go-based security tools
go install -v github.com/projectdiscovery/nuclei/v2/cmd/nuclei@latest
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest
go install -v github.com/projectdiscovery/naabu/v2/cmd/naabu@latest
go install -v github.com/tomnomnom/gf@latest
go install -v github.com/tomnomnom/waybackurls@latest
# Add Go bin to PATH
echo 'export PATH=$PATH:~/go/bin' >> ~/.bashrc
source ~/.bashrcPython-based Tools:
# Install additional Python tools
pip3 install --user \
shodan \
truffleHog \
gitpython \
requests \
beautifulsoup4 \
selenium \
pycryptodome
# EyeWitness dependencies
sudo apt install -y chromium-browser
git clone https://github.com/FortyNorthSecurity/EyeWitness.git /opt/EyeWitness
cd /opt/EyeWitness/Python/setup
sudo ./setup.shAdditional Specialized Tools:
# GitLeaks for secret detection
sudo wget -O /usr/local/bin/gitleaks \
https://github.com/zricethezav/gitleaks/releases/latest/download/gitleaks_linux_amd64
sudo chmod +x /usr/local/bin/gitleaks
# Feroxbuster (if not in repos)
curl -sL https://raw.githubusercontent.com/epi052/feroxbuster/master/install-nix.sh | bash
# Ensure all tools are in PATH
sudo ln -sf ~/go/bin/* /usr/local/bin/ 2>/dev/null || trueTool Verification:
# Verify installation of key tools
echo "Verifying tool installation..."
for tool in nmap masscan gobuster ffuf nikto sqlmap hydra john hashcat \
amass subfinder nuclei testssl.sh trivy gitleaks feroxbuster \
enum4linux nbtscan theharvester whatweb; do
if command -v $tool >/dev/null 2>&1; then
echo "✓ $tool installed"
else
echo "✗ $tool missing"
fi
done# Clone the repository
git clone https://github.com/slayingripper/OctapusPrime.git
cd OctapusPrime
# Create necessary directories
mkdir -p scenarios logs outputs
# Set appropriate permissions
chmod +x bin/octapus_controller.py
chmod +x bin/webapp/server.py
# Verify directory structure
ls -la
# Should show: bin/, scenarios/, logs/, README.md, requirements.txt, etc.# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate
# Upgrade pip and install dependencies
pip install --upgrade pip
pip install -r requirements.txt
# Install additional packages for enhanced features
pip install \
jsonschema \
python-dateutil \
psutil \
netifaces
# If using GPIO features
pip install RPi.GPIO gpiozero lgpio
# Verify installation
python3 -c "
import flask, flask_socketio, requests
print('✓ Core dependencies installed successfully')
"# Create systemd service files
sudo tee /etc/systemd/system/octapus-controller.service > /dev/null <<EOF
[Unit]
Description=OctapusPrime Controller Service
After=network.target
[Service]
Type=simple
User=root
WorkingDirectory=$(pwd)
Environment=PATH=$(pwd)/venv/bin
ExecStart=$(pwd)/venv/bin/python bin/octapus_controller.py
Restart=always
RestartSec=3
[Install]
WantedBy=multi-user.target
EOF
sudo tee /etc/systemd/system/octapus-web.service > /dev/null <<EOF
[Unit]
Description=OctapusPrime Web Service
After=network.target
[Service]
Type=simple
User=root
WorkingDirectory=$(pwd)
Environment=PATH=$(pwd)/venv/bin
ExecStart=$(pwd)/venv/bin/python bin/webapp/server.py
Restart=always
RestartSec=3
[Install]
WantedBy=multi-user.target
EOF
# Reload systemd and enable services
sudo systemctl daemon-reload
sudo systemctl enable octapus-controller.service
sudo systemctl enable octapus-web.service
# Start services
sudo systemctl start octapus-controller.service
sudo systemctl start octapus-web.service
# Check status
sudo systemctl status octapus-controller.service
sudo systemctl status octapus-web.serviceAlternative: Running Without Systemd Services
For development, testing, or temporary usage, you can run OctapusPrime directly without installing systemd services:
# Activate virtual environment
source venv/bin/activate
# Run web server directly (will start on http://localhost:8080)
python3 bin/webapp/server.py
# In another terminal, run the GPIO controller (optional)
source venv/bin/activate
python3 bin/octapus_controller.pyBenefits of direct execution:
- Quick Testing: Immediate startup without service configuration
- Development Mode: Easy debugging with direct console output
- Temporary Usage: No permanent system changes
- Custom Configuration: Easy to modify startup parameters
Note: Running directly will only be active while your terminal session is open. For production deployments, systemd services are recommended for automatic startup and proper daemon management.
- Access Builder: Navigate to
/scenariofrom the main interface - Create Scenarios: Use the visual IFTTT builder to create complex workflows
- Add Steps: Select tools from categorized dropdown menus
- Configure Logic: Set IF-THEN conditions for adaptive execution
- Extract Variables: Use regex patterns to capture data from tool outputs
- Save & Load: Manage reusable scenario libraries
Build intelligent workflows with conditional logic and variable extraction
Condition Types:
- Always Execute: Runs unconditionally
- Previous Step Contains: Execute if output contains specific text
- Previous Step Matches Regex: Execute if output matches regex pattern
- Variable Exists: Execute if a variable has been set
- Variable Equals: Execute if variable equals specific value
- Previous Step Success/Failure: Execute based on exit status
Example Workflow:
Step 1: Nmap port scan (Always)
→ Extract web_ports: (\d+)/tcp\s+open\s+http
Step 2: Gobuster directory scan (IF web_ports exists)
→ Use discovered ports for targeted scanning
Step 3: Nuclei vulnerability scan (IF directories found)
→ Focus on discovered web applications
Built-in Variables:
{target}: Primary scan target{network}: Network range{timestamp}: Current timestamp{scan_id}: Unique scan identifier
Custom Variables:
- Extract using regex patterns from tool output
- Use in subsequent tool arguments
- Real-time substitution and validation
- Hardware Setup: Connect momentary button to GPIO 17, GPIO 23 ,LED to GPIO 27
- Default Scan: Press button to trigger preconfigured scan sequence
- Machanger: Press the button to located at the GPIO 23 to easily change the MAC address
- LED Feedback: Visual indication of scan progress and completion
Configure GPIO pins and hardware settings for physical button integration
- Landing Page: Navigate to
http://[device-ip]:8080 - Enhanced Dashboard: Access full tool suite and scenario builder
- Real-time Monitoring: Watch execution progress and extract variables
- 40+ Categorized Tools: Organized by function and use case
- IFTTT Scenario Builder: Visual workflow creation
- Variable Management: Dynamic parameter system
- Example Scenarios: Pre-built penetration testing workflows
- Real-time Execution: Live progress monitoring and log streaming
- Tool Templates: Pre-configured argument sets for common tasks
- Variable Picker: Visual variable selection and management
- Condition Builder: Drag-and-drop IF-THEN logic creation
- Regex Helper: Pattern testing and validation tools
- Keyboard Shortcuts: Power-user productivity features
- Real-time Display: Tool outputs stream live to web interface
- Variable Extraction: Watch variables being captured from outputs
- Conditional Execution: See IF-THEN logic decisions in real-time
- Historical Logs: Access previous scan results and extracted data
Monitor execution progress with real-time logging and variable extraction
OctapusPrime/
├── bin/
│ ├── octapus_controller.py # Enhanced GPIO controller
│ └── webapp/
│ ├── server.py # Flask server with scenario API
│ ├── static/
│ │ ├── css/ # Enhanced styling
│ │ └── js/ # IFTTT logic and variable system
│ └── frontend/
│ ├── landing.html # Octopus-themed landing page
│ ├── index.html # Tool dashboard
│ ├── scenario.html # IFTTT scenario builder
│ └── help.html # Comprehensive documentation
├── scenarios/ # Saved IFTTT scenarios (JSON)
│ ├── examples/ # Pre-built example scenarios
│ └── user/ # User-created scenarios
├── logs/ # Execution logs and outputs
├── outputs/ # Tool-specific output files
├── templates/ # Tool argument templates
├── systemd/ # Enhanced service configurations
├── docs/ # Additional documentation
├── GIFS/ # Demo GIFs and screenshots
├── venv/ # Python virtual environment
├── requirements.txt # Python dependencies
└── README.md # This comprehensive guide
Network Discovery & Scanning (5 tools):
nmap- Network exploration and security auditingmasscan- High-speed Internet-scale port scannerzmap- Fast single-packet Internet scanneramass- Attack surface mapping and asset discoverysubfinder- Passive subdomain discovery tool
Web Application Testing (7 tools):
gobuster- Directory/file/DNS busting toolffuf- Fast web fuzzerferoxbuster- Recursive content discoverynikto- Web vulnerability scannerwhatweb- Web technology fingerprintingsqlmap- SQL injection exploitation toolnuclei- Fast vulnerability scanner with templates
Vulnerability & SSL Testing (3 tools):
nuclei- Template-based vulnerability scannertrivy- Container and dependency vulnerability scannertestssl.sh- SSL/TLS security assessment tool
Credential & Authentication (3 tools):
hydra- Network service brute-forcerjohn- Password hash cracking toolhashcat- Advanced password recovery tool
Information Gathering (3 tools):
theharvester- Email and domain intelligence gatheringamass- Comprehensive asset discoveryshodan- Internet-connected device search engine
Enumeration (5 tools):
enum4linux- SMB enumeration for Linux/Windowsnbtscan- NetBIOS name scanningldapsearch- LDAP directory enumerationsnmp-check- SNMP service enumerationsmbclient- SMB share access and enumeration
Specialized Tools (6 tools):
eyewitness- Web application screenshot toolgitleaks- Git repository secret detectiondirsearch- Web path scannerdirb- Web content scannerwpscan- WordPress vulnerability scannerferoxbuster- Fast content discovery tool
- Update Tool Database: Add new tool to categorized tool list in JavaScript
- Create Templates: Define argument templates and examples
- Add Descriptions: Include tool descriptions and usage examples
- Test Integration: Verify tool execution and output parsing
- Tool not found: Verify installation and PATH configuration
- Permission errors: Check user permissions for tool execution
- GPIO access denied: Ensure proper GPIO permissions or run as root
- WebSocket connection fails: Verify network configuration and firewall settings
- Scenario validation errors: Check variable syntax and tool arguments
- Concurrent Execution: Adjust thread limits for system capabilities
- Memory Management: Monitor resource usage during large scans
- Network Optimization: Configure rate limiting for network-intensive tools
- Storage Management: Implement log rotation and output cleanup
# Check service logs
sudo journalctl -u octapus-web.service -f
sudo journalctl -u octapus-controller.service -f
# Test individual components
source venv/bin/activate
python3 bin/webapp/server.py # Test web server
python3 bin/octapus_controller.py # Test controller
# Debug scenario execution
curl -X POST http://localhost:8080/api/run_scenario \
-H "Content-Type: application/json" \
-d '{"name": "test", "steps": [{"tool": "nmap", "args": ["-sV", "127.0.0.1"]}]}'
# Verify tool installations
which nmap gobuster sqlmap hydra nuclei
# Test WebSocket connection
python3 -c "
import socketio
sio = socketio.Client()
sio.connect('http://localhost:8080')
print('WebSocket connection successful')
"
# Docker Build
sudo docker compose build
sudo docker run --network host -it almalinux:9OctapusPrime welcomes contributions to expand the security tool ecosystem:
Areas for Contribution:
- New Tool Integration: Add support for additional security tools
- Scenario Templates: Create pre-built workflows for specific testing scenarios
- UI/UX Improvements: Enhance the web interface and user experience
- Performance Optimization: Improve execution speed and resource usage
- Documentation: Expand guides, tutorials, and tool references
- Bug Fixes: Address issues and improve stability
Development Process:
- Fork the repository
- Create feature branch
- Follow existing code style
- Include comprehensive tests
- Update documentation
- Submit pull request
This project is licensed under the MIT License - see the LICENSE file for details.
IMPORTANT LEGAL NOTICE:
OctapusPrime is designed for authorized security testing and educational purposes only. This tool should only be used against systems you own or have explicit written permission to test.
Prohibited Uses:
- Unauthorized access to computer systems
- Testing systems without proper authorization
- Any illegal or malicious activities
User Responsibilities:
- Obtain proper authorization before testing
- Comply with applicable laws and regulations
- Use responsibly and ethically
- Respect privacy and data protection laws
No Warranty: The developers provide this software "as is" without any warranties. Users assume all responsibility and liability for the use of this software.
By using OctapusPrime, you agree to use it legally and ethically in accordance with all applicable laws and regulations.