opencode-skills-collection 4.0.52 → 4.0.54

package/bundled-skills/shodan-reconnaissance/references/detailed-guide.md

@@ -0,0 +1,366 @@
+# Shodan Reconnaissance and Pentesting - Detailed Guide
+
+> This file contains the detailed procedure and reference material extracted from `SKILL.md` for focused loading. The root skill defines activation, examples, safety constraints, and limitations.
+
+## Purpose
+
+Provide systematic methodologies for leveraging Shodan as a reconnaissance tool during penetration testing engagements. This skill covers the Shodan web interface, command-line interface (CLI), REST API, search filters, on-demand scanning, and network monitoring capabilities for discovering exposed services, vulnerable systems, and IoT devices.
+
+
+## Inputs / Prerequisites
+
+- **Shodan Account**: Free or paid account at shodan.io
+- **API Key**: Obtained from Shodan account dashboard
+- **Target Information**: IP addresses, domains, or network ranges to investigate
+- **Shodan CLI**: Python-based command-line tool installed
+- **Authorization**: Written permission for reconnaissance on target networks
+
+
+## Outputs / Deliverables
+
+- **Asset Inventory**: List of discovered hosts, ports, and services
+- **Vulnerability Report**: Identified CVEs and exposed vulnerable services
+- **Banner Data**: Service banners revealing software versions
+- **Network Mapping**: Geographic and organizational distribution of assets
+- **Screenshot Gallery**: Visual reconnaissance of exposed interfaces
+- **Exported Data**: JSON/CSV files for further analysis
+
+
+## Core Workflow
+
+### 1. Setup and Configuration
+
+#### Install Shodan CLI
+```bash
+# Using pip
+pip install shodan
+
+# Or easy_install
+easy_install shodan
+
+# On BlackArch/Arch Linux
+sudo pacman -S python-shodan
+```
+
+#### Initialize API Key
+```bash
+# Set your API key
+shodan init YOUR_API_KEY
+
+# Verify setup
+shodan info
+# Output: Query credits available: 100
+#         Scan credits available: 100
+```
+
+#### Check Account Status
+```bash
+# View credits and plan info
+shodan info
+
+# Check your external IP
+shodan myip
+
+# Check CLI version
+shodan version
+```
+
+### 2. Basic Host Reconnaissance
+
+#### Query Single Host
+```bash
+# Get all information about an IP
+shodan host 1.1.1.1
+
+# Example output:
+# 1.1.1.1
+# Hostnames: one.one.one.one
+# Country: Australia
+# Organization: Mountain View Communications
+# Number of open ports: 3
+# Ports:
+#   53/udp
+#   80/tcp
+#   443/tcp
+```
+
+#### Check if Host is Honeypot
+```bash
+# Get honeypot probability score
+shodan honeyscore 192.168.1.100
+
+# Output: Not a honeypot
+#         Score: 0.3
+```
+
+### 3. Search Queries
+
+#### Basic Search (Free)
+```bash
+# Simple keyword search (no credits consumed)
+shodan search apache
+
+# Specify output fields
+shodan search --fields ip_str,port,os smb
+```
+
+#### Filtered Search (1 Credit)
+```bash
+# Product-specific search
+shodan search product:mongodb
+
+# Search with multiple filters
+shodan search product:nginx country:US city:"New York"
+```
+
+#### Count Results
+```bash
+# Get result count without consuming credits
+shodan count openssh
+# Output: 23128
+
+shodan count openssh 7
+# Output: 219
+```
+
+#### Download Results
+```bash
+# Download 1000 results (default)
+shodan download results.json.gz "apache country:US"
+
+# Download specific number of results
+shodan download --limit 5000 results.json.gz "nginx"
+
+# Download all available results
+shodan download --limit -1 all_results.json.gz "query"
+```
+
+#### Parse Downloaded Data
+```bash
+# Extract specific fields from downloaded data
+shodan parse --fields ip_str,port,hostnames results.json.gz
+
+# Filter by specific criteria
+shodan parse --fields location.country_code3,ip_str -f port:22 results.json.gz
+
+# Export to CSV format
+shodan parse --fields ip_str,port,org --separator , results.json.gz > results.csv
+```
+
+### 4. Search Filters Reference
+
+#### Network Filters
+```
+ip:1.2.3.4                  # Specific IP address
+net:192.168.0.0/24          # Network range (CIDR)
+hostname:example.com        # Hostname contains
+port:22                     # Specific port
+asn:AS15169                 # Autonomous System Number
+```
+
+#### Geographic Filters
+```
+country:US                  # Two-letter country code
+country:"United States"     # Full country name
+city:"San Francisco"        # City name
+state:CA                    # State/region
+postal:94102                # Postal/ZIP code
+geo:37.7,-122.4             # Lat/long coordinates
+```
+
+#### Organization Filters
+```
+org:"Google"                # Organization name
+isp:"Comcast"               # ISP name
+```
+
+#### Service/Product Filters
+```
+product:nginx               # Software product
+version:1.14.0              # Software version
+os:"Windows Server 2019"    # Operating system
+http.title:"Dashboard"      # HTTP page title
+http.html:"login"           # HTML content
+http.status:200             # HTTP status code
+ssl.cert.subject.cn:*.example.com  # SSL certificate
+ssl:true                    # Has SSL enabled
+```
+
+#### Vulnerability Filters
+```
+vuln:CVE-2019-0708          # Specific CVE
+has_vuln:true               # Has any vulnerability
+```
+
+#### Screenshot Filters
+```
+has_screenshot:true         # Has screenshot available
+screenshot.label:webcam     # Screenshot type
+```
+
+### 5. On-Demand Scanning
+
+#### Submit Scan
+```bash
+# Scan single IP (1 credit per IP)
+shodan scan submit 192.168.1.100
+
+# Scan with verbose output (shows scan ID)
+shodan scan submit --verbose 192.168.1.100
+
+# Scan and save results
+shodan scan submit --filename scan_results.json.gz 192.168.1.100
+```
+
+#### Monitor Scan Status
+```bash
+# List recent scans
+shodan scan list
+
+# Check specific scan status
+shodan scan status SCAN_ID
+
+# Download scan results later
+shodan download --limit -1 results.json.gz scan:SCAN_ID
+```
+
+#### Available Scan Protocols
+```bash
+# List available protocols/modules
+shodan scan protocols
+```
+
+### 6. Statistics and Analysis
+
+#### Get Search Statistics
+```bash
+# Default statistics (top 10 countries, orgs)
+shodan stats nginx
+
+# Custom facets
+shodan stats --facets domain,port,asn --limit 5 nginx
+
+# Save to CSV
+shodan stats --facets country,org -O stats.csv apache
+```
+
+### 7. Network Monitoring
+
+#### Setup Alerts (Web Interface)
+```
+1. Navigate to Monitor Dashboard
+2. Add IP, range, or domain to monitor
+3. Configure notification service (email, Slack, webhook)
+4. Select trigger events (new service, vulnerability, etc.)
+5. View dashboard for exposed services
+```
+
+### 8. REST API Usage
+
+#### Direct API Calls
+```bash
+# Get API info
+curl -s "https://api.shodan.io/api-info?key=YOUR_KEY" | jq
+
+# Host lookup
+curl -s "https://api.shodan.io/shodan/host/1.1.1.1?key=YOUR_KEY" | jq
+
+# Search query
+curl -s "https://api.shodan.io/shodan/host/search?key=YOUR_KEY&query=apache" | jq
+```
+
+#### Python Library
+```python
+import shodan
+
+api = shodan.Shodan('YOUR_API_KEY')
+
+# Search
+results = api.search('apache')
+print(f'Results found: {results["total"]}')
+for result in results['matches']:
+    print(f'IP: {result["ip_str"]}')
+
+# Host lookup
+host = api.host('1.1.1.1')
+print(f'IP: {host["ip_str"]}')
+print(f'Organization: {host.get("org", "n/a")}')
+for item in host['data']:
+    print(f'Port: {item["port"]}')
+```
+
+
+## Quick Reference
+
+### Essential CLI Commands
+
+| Command | Description | Credits |
+|---------|-------------|---------|
+| `shodan init KEY` | Initialize API key | 0 |
+| `shodan info` | Show account info | 0 |
+| `shodan myip` | Show your IP | 0 |
+| `shodan host IP` | Host details | 0 |
+| `shodan count QUERY` | Result count | 0 |
+| `shodan search QUERY` | Basic search | 0* |
+| `shodan download FILE QUERY` | Save results | 1/100 results |
+| `shodan parse FILE` | Extract data | 0 |
+| `shodan stats QUERY` | Statistics | 1 |
+| `shodan scan submit IP` | On-demand scan | 1/IP |
+| `shodan honeyscore IP` | Honeypot check | 0 |
+
+*Filters consume 1 credit per query
+
+### Common Search Queries
+
+| Purpose | Query |
+|---------|-------|
+| Find webcams | `webcam has_screenshot:true` |
+| MongoDB databases | `product:mongodb` |
+| Redis servers | `product:redis` |
+| Elasticsearch | `product:elastic port:9200` |
+| Default passwords | `"default password"` |
+| Vulnerable RDP | `port:3389 vuln:CVE-2019-0708` |
+| Industrial systems | `port:502 modbus` |
+| Cisco devices | `product:cisco` |
+| Open VNC | `port:5900 authentication disabled` |
+| Exposed FTP | `port:21 anonymous` |
+| WordPress sites | `http.component:wordpress` |
+| Printers | `"HP-ChaiSOE" port:80` |
+| Cameras (RTSP) | `port:554 has_screenshot:true` |
+| Jenkins servers | `X-Jenkins port:8080` |
+| Docker APIs | `port:2375 product:docker` |
+
+### Useful Filter Combinations
+
+| Scenario | Query |
+|---------|-------|
+| Target org recon | `org:"Company Name"` |
+| Domain enumeration | `hostname:example.com` |
+| Network range scan | `net:192.168.0.0/24` |
+| SSL cert search | `ssl.cert.subject.cn:*.target.com` |
+| Vulnerable servers | `vuln:CVE-2021-44228 country:US` |
+| Exposed admin panels | `http.title:"admin" port:443` |
+| Database exposure | `port:3306,5432,27017,6379` |
+
+### Credit System
+
+| Action | Credit Type | Cost |
+|--------|-------------|------|
+| Basic search | Query | 0 (no filters) |
+| Filtered search | Query | 1 |
+| Download 100 results | Query | 1 |
+| Generate report | Query | 1 |
+| Scan 1 IP | Scan | 1 |
+| Network monitoring | Monitored IPs | Depends on plan |
+
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| No API Key Configured | Key not initialized | Run `shodan init YOUR_API_KEY` then verify with `shodan info` |
+| Query Credits Exhausted | Monthly credits consumed | Use credit-free queries (no filters), wait for reset, or upgrade |
+| Host Recently Crawled | Cannot re-scan IP within 24h | Use `shodan host IP` for existing data, or wait 24 hours |
+| Rate Limit Exceeded | >1 request/second | Add `time.sleep(1)` between API requests |
+| Empty Search Results | Too specific or syntax error | Use quotes for phrases: `'org:"Company Name"'`; broaden criteria |
+| Downloaded File Won't Parse | Corrupted or wrong format | Verify with `gunzip -t file.gz`, re-download with `--limit` |