COBRA is a comprehensive IoT penetration testing framework designed to automate the discovery, analysis, and reporting of vulnerabilities in IoT devices and networks. Built with Python, it provides both command-line and API interfaces for security professionals.

• Nmap Integration: Real network scanning with Nmap
• Device Discovery: Automatic detection of IoT devices
• Port Analysis: Comprehensive port and service enumeration
• Shodan Integration: Enrichment with external threat intelligence

• Protocol-Specific Scanners: MQTT, CoAP, RTSP, and more
• CVE Database: Integration with NVD for real-time vulnerability data
• Risk Scoring: Automated CVSS-based risk assessment
• Custom Vulnerability Detection: Framework for adding new scanners

• HTML Reports: Beautiful, interactive reports with Bootstrap
• Visualizations: Charts and graphs for vulnerability distribution
• Executive Summaries: High-level risk overview
• Technical Details: Comprehensive technical findings

• REST API: Full API for integration and automation
• Modular Architecture: Easy to extend with new scanners
• Configuration Management: Centralized configuration system
• JSON Storage: Simple file-based storage system

• Python 3.8+
• Nmap (for network scanning)
• Internet connection (for Shodan API and NVD updates)

Single command installation:

# Clone the repository
git clone https://github.com/servais1983/cobra-iot-pentest.git
cd cobra-iot-pentest

# Complete automatic installation
chmod +x install.sh && ./install.sh

That's it! The script automatically:

• Creates virtual environment
• Installs dependencies
• Generates configuration
• Tests installation

For users who prefer a simpler approach without database complexity:

# Use the simple scanner (JSON-based)
python simple_cobra.py scan 192.168.1.0/24

# List recent scans
python simple_cobra.py list

# View scan details
python simple_cobra.py show <scan_id>

After installation:

# Option 1: Interactive startup script (recommended)
chmod +x start.sh && ./start.sh

# Option 2: Manual usage
source venv/bin/activate
python -m src.cobra

# Option 3: Quick test
python scripts/quick_test.py

If you prefer manual installation:

# 1. Create virtual environment
python3 -m venv venv
source venv/bin/activate

# 2. Install dependencies
pip install -r requirements-minimal.txt

# 3. Configure
cp config/cobra.example.yaml config/cobra.yaml

# 4. Test
python scripts/quick_test.py

1. Copy the example configuration:

   cp config/cobra.example.yaml config/cobra.yaml

2. Edit the configuration file:

   # config/cobra.yaml
   api_keys:
     shodan: "your-shodan-api-key"  # Optional but recommended
     openai: "your-openai-api-key"  # Optional for AI features
   
   scanning:
     nmap_args: "-sV -O -T4"
     default_ports: "1-1024,1883,5683,8080,8883"

Shodan provides external threat intelligence to enrich your scan results with:

• Device manufacturer information
• Known vulnerabilities
• Geographic location data
• Service banners and versions

How to get your Shodan API key:

1. Visit Shodan: Go to https://account.shodan.io/register
2. Create Account: Sign up for a free account
3. Get API Key: Navigate to your account dashboard
4. Copy Key: Copy your API key from the dashboard

Configure in COBRA:

# config/cobra.yaml
api_keys:
  shodan: "YOUR_SHODAN_API_KEY_HERE"

# Network scan (Simple version)
python simple_cobra.py scan 192.168.1.0/24

# List recent scans
python simple_cobra.py list

# View scan details
python simple_cobra.py show <scan_id>

cobra-iot-pentest/
├── install.sh              # Main installation script
├── start.sh                # Interactive startup script
├── simple_cobra.py         # Simple scanner (JSON-based)
├── requirements-minimal.txt # Essential dependencies
├── requirements.txt        # All dependencies
├── config/
│   ├── cobra.example.yaml  # Example configuration
│   └── cobra.yaml         # Active configuration
├── src/cobra/             # Main source code
├── scripts/               # Utility scripts
├── scan_results/          # JSON scan results
├── logs/                  # Log files
└── reports/               # Generated reports

• Anonymous Login Detection: Tests for unauthenticated access
• Wildcard Subscription: Checks for open topic subscriptions
• Message Interception: Captures and analyzes MQTT traffic

• CoAP Scanner: Constrained Application Protocol
• RTSP Scanner: Real-Time Streaming Protocol
• Modbus Scanner: Industrial control systems
• Zigbee Scanner: Wireless sensor networks

• Legal Compliance: Only scan networks you own or have permission to test
• Rate Limiting: Respect API rate limits (Shodan, NVD)
• Data Privacy: Sensitive data is stored locally by default
• Network Impact: Scans may impact network performance

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

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

• Documentation: Check the docs/ directory
• Issues: Report bugs via GitHub Issues
• Troubleshooting: See TROUBLESHOOTING.md

• CoAP Scanner: Constrained Application Protocol support
• RTSP Scanner: Camera and streaming device analysis
• Modbus Scanner: Industrial control system testing
• Web Dashboard: Real-time monitoring interface
• Alert System: Automated vulnerability notifications
• PDF Reports: Export reports to PDF format
• Docker Support: Containerized deployment
• CI/CD Pipeline: Automated testing and deployment

• Nmap: Network discovery and port scanning
• Shodan: External threat intelligence
• NVD: National Vulnerability Database
• Flask: Web framework
• Bootstrap: UI framework for reports

Disclaimer: This tool is for authorized security testing only. Always obtain proper permissions before scanning any network or device.