This skill should be used when the user asks to "search for exposed devices on the internet," "perform Shodan reconnaissance," "find vulnerable services using Shodan," "scan IP ranges with Shodan," or "discover IoT devices and open ports." It provides comprehensive guidance for using Shodan's search engine, CLI, and API for penetration testing reconnaissance.
Add this skill
npx mdskills install sickn33/shodan-reconnaissanceComprehensive pentesting reconnaissance guide with extensive CLI examples and search patterns
1---2name: Shodan Reconnaissance and Pentesting3description: This skill should be used when the user asks to "search for exposed devices on the internet," "perform Shodan reconnaissance," "find vulnerable services using Shodan," "scan IP ranges with Shodan," or "discover IoT devices and open ports." It provides comprehensive guidance for using Shodan's search engine, CLI, and API for penetration testing reconnaissance.4metadata:5 author: zebbern6 version: "1.1"7---89# Shodan Reconnaissance and Pentesting1011## Purpose1213Provide 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.1415## Inputs / Prerequisites1617- **Shodan Account**: Free or paid account at shodan.io18- **API Key**: Obtained from Shodan account dashboard19- **Target Information**: IP addresses, domains, or network ranges to investigate20- **Shodan CLI**: Python-based command-line tool installed21- **Authorization**: Written permission for reconnaissance on target networks2223## Outputs / Deliverables2425- **Asset Inventory**: List of discovered hosts, ports, and services26- **Vulnerability Report**: Identified CVEs and exposed vulnerable services27- **Banner Data**: Service banners revealing software versions28- **Network Mapping**: Geographic and organizational distribution of assets29- **Screenshot Gallery**: Visual reconnaissance of exposed interfaces30- **Exported Data**: JSON/CSV files for further analysis3132## Core Workflow3334### 1. Setup and Configuration3536#### Install Shodan CLI37```bash38# Using pip39pip install shodan4041# Or easy_install42easy_install shodan4344# On BlackArch/Arch Linux45sudo pacman -S python-shodan46```4748#### Initialize API Key49```bash50# Set your API key51shodan init YOUR_API_KEY5253# Verify setup54shodan info55# Output: Query credits available: 10056# Scan credits available: 10057```5859#### Check Account Status60```bash61# View credits and plan info62shodan info6364# Check your external IP65shodan myip6667# Check CLI version68shodan version69```7071### 2. Basic Host Reconnaissance7273#### Query Single Host74```bash75# Get all information about an IP76shodan host 1.1.1.17778# Example output:79# 1.1.1.180# Hostnames: one.one.one.one81# Country: Australia82# Organization: Mountain View Communications83# Number of open ports: 384# Ports:85# 53/udp86# 80/tcp87# 443/tcp88```8990#### Check if Host is Honeypot91```bash92# Get honeypot probability score93shodan honeyscore 192.168.1.1009495# Output: Not a honeypot96# Score: 0.397```9899### 3. Search Queries100101#### Basic Search (Free)102```bash103# Simple keyword search (no credits consumed)104shodan search apache105106# Specify output fields107shodan search --fields ip_str,port,os smb108```109110#### Filtered Search (1 Credit)111```bash112# Product-specific search113shodan search product:mongodb114115# Search with multiple filters116shodan search product:nginx country:US city:"New York"117```118119#### Count Results120```bash121# Get result count without consuming credits122shodan count openssh123# Output: 23128124125shodan count openssh 7126# Output: 219127```128129#### Download Results130```bash131# Download 1000 results (default)132shodan download results.json.gz "apache country:US"133134# Download specific number of results135shodan download --limit 5000 results.json.gz "nginx"136137# Download all available results138shodan download --limit -1 all_results.json.gz "query"139```140141#### Parse Downloaded Data142```bash143# Extract specific fields from downloaded data144shodan parse --fields ip_str,port,hostnames results.json.gz145146# Filter by specific criteria147shodan parse --fields location.country_code3,ip_str -f port:22 results.json.gz148149# Export to CSV format150shodan parse --fields ip_str,port,org --separator , results.json.gz > results.csv151```152153### 4. Search Filters Reference154155#### Network Filters156```157ip:1.2.3.4 # Specific IP address158net:192.168.0.0/24 # Network range (CIDR)159hostname:example.com # Hostname contains160port:22 # Specific port161asn:AS15169 # Autonomous System Number162```163164#### Geographic Filters165```166country:US # Two-letter country code167country:"United States" # Full country name168city:"San Francisco" # City name169state:CA # State/region170postal:94102 # Postal/ZIP code171geo:37.7,-122.4 # Lat/long coordinates172```173174#### Organization Filters175```176org:"Google" # Organization name177isp:"Comcast" # ISP name178```179180#### Service/Product Filters181```182product:nginx # Software product183version:1.14.0 # Software version184os:"Windows Server 2019" # Operating system185http.title:"Dashboard" # HTTP page title186http.html:"login" # HTML content187http.status:200 # HTTP status code188ssl.cert.subject.cn:*.example.com # SSL certificate189ssl:true # Has SSL enabled190```191192#### Vulnerability Filters193```194vuln:CVE-2019-0708 # Specific CVE195has_vuln:true # Has any vulnerability196```197198#### Screenshot Filters199```200has_screenshot:true # Has screenshot available201screenshot.label:webcam # Screenshot type202```203204### 5. On-Demand Scanning205206#### Submit Scan207```bash208# Scan single IP (1 credit per IP)209shodan scan submit 192.168.1.100210211# Scan with verbose output (shows scan ID)212shodan scan submit --verbose 192.168.1.100213214# Scan and save results215shodan scan submit --filename scan_results.json.gz 192.168.1.100216```217218#### Monitor Scan Status219```bash220# List recent scans221shodan scan list222223# Check specific scan status224shodan scan status SCAN_ID225226# Download scan results later227shodan download --limit -1 results.json.gz scan:SCAN_ID228```229230#### Available Scan Protocols231```bash232# List available protocols/modules233shodan scan protocols234```235236### 6. Statistics and Analysis237238#### Get Search Statistics239```bash240# Default statistics (top 10 countries, orgs)241shodan stats nginx242243# Custom facets244shodan stats --facets domain,port,asn --limit 5 nginx245246# Save to CSV247shodan stats --facets country,org -O stats.csv apache248```249250### 7. Network Monitoring251252#### Setup Alerts (Web Interface)253```2541. Navigate to Monitor Dashboard2552. Add IP, range, or domain to monitor2563. Configure notification service (email, Slack, webhook)2574. Select trigger events (new service, vulnerability, etc.)2585. View dashboard for exposed services259```260261### 8. REST API Usage262263#### Direct API Calls264```bash265# Get API info266curl -s "https://api.shodan.io/api-info?key=YOUR_KEY" | jq267268# Host lookup269curl -s "https://api.shodan.io/shodan/host/1.1.1.1?key=YOUR_KEY" | jq270271# Search query272curl -s "https://api.shodan.io/shodan/host/search?key=YOUR_KEY&query=apache" | jq273```274275#### Python Library276```python277import shodan278279api = shodan.Shodan('YOUR_API_KEY')280281# Search282results = api.search('apache')283print(f'Results found: {results["total"]}')284for result in results['matches']:285 print(f'IP: {result["ip_str"]}')286287# Host lookup288host = api.host('1.1.1.1')289print(f'IP: {host["ip_str"]}')290print(f'Organization: {host.get("org", "n/a")}')291for item in host['data']:292 print(f'Port: {item["port"]}')293```294295## Quick Reference296297### Essential CLI Commands298299| Command | Description | Credits |300|---------|-------------|---------|301| `shodan init KEY` | Initialize API key | 0 |302| `shodan info` | Show account info | 0 |303| `shodan myip` | Show your IP | 0 |304| `shodan host IP` | Host details | 0 |305| `shodan count QUERY` | Result count | 0 |306| `shodan search QUERY` | Basic search | 0* |307| `shodan download FILE QUERY` | Save results | 1/100 results |308| `shodan parse FILE` | Extract data | 0 |309| `shodan stats QUERY` | Statistics | 1 |310| `shodan scan submit IP` | On-demand scan | 1/IP |311| `shodan honeyscore IP` | Honeypot check | 0 |312313*Filters consume 1 credit per query314315### Common Search Queries316317| Purpose | Query |318|---------|-------|319| Find webcams | `webcam has_screenshot:true` |320| MongoDB databases | `product:mongodb` |321| Redis servers | `product:redis` |322| Elasticsearch | `product:elastic port:9200` |323| Default passwords | `"default password"` |324| Vulnerable RDP | `port:3389 vuln:CVE-2019-0708` |325| Industrial systems | `port:502 modbus` |326| Cisco devices | `product:cisco` |327| Open VNC | `port:5900 authentication disabled` |328| Exposed FTP | `port:21 anonymous` |329| WordPress sites | `http.component:wordpress` |330| Printers | `"HP-ChaiSOE" port:80` |331| Cameras (RTSP) | `port:554 has_screenshot:true` |332| Jenkins servers | `X-Jenkins port:8080` |333| Docker APIs | `port:2375 product:docker` |334335### Useful Filter Combinations336337| Scenario | Query |338|---------|-------|339| Target org recon | `org:"Company Name"` |340| Domain enumeration | `hostname:example.com` |341| Network range scan | `net:192.168.0.0/24` |342| SSL cert search | `ssl.cert.subject.cn:*.target.com` |343| Vulnerable servers | `vuln:CVE-2021-44228 country:US` |344| Exposed admin panels | `http.title:"admin" port:443` |345| Database exposure | `port:3306,5432,27017,6379` |346347### Credit System348349| Action | Credit Type | Cost |350|--------|-------------|------|351| Basic search | Query | 0 (no filters) |352| Filtered search | Query | 1 |353| Download 100 results | Query | 1 |354| Generate report | Query | 1 |355| Scan 1 IP | Scan | 1 |356| Network monitoring | Monitored IPs | Depends on plan |357358## Constraints and Limitations359360### Operational Boundaries361- Rate limited to 1 request per second362- Scan results not immediate (asynchronous)363- Cannot re-scan same IP within 24 hours (non-Enterprise)364- Free accounts have limited credits365- Some data requires paid subscription366367### Data Freshness368- Shodan crawls continuously but data may be days/weeks old369- On-demand scans provide current data but cost credits370- Historical data available with paid plans371372### Legal Requirements373- Only perform reconnaissance on authorized targets374- Passive reconnaissance generally legal but verify jurisdiction375- Active scanning (scan submit) requires authorization376- Document all reconnaissance activities377378## Examples379380### Example 1: Organization Reconnaissance381```bash382# Find all hosts belonging to target organization383shodan search 'org:"Target Company"'384385# Get statistics on their infrastructure386shodan stats --facets port,product,country 'org:"Target Company"'387388# Download detailed data389shodan download target_data.json.gz 'org:"Target Company"'390391# Parse for specific info392shodan parse --fields ip_str,port,product target_data.json.gz393```394395### Example 2: Vulnerable Service Discovery396```bash397# Find hosts vulnerable to BlueKeep (RDP CVE)398shodan search 'vuln:CVE-2019-0708 country:US'399400# Find exposed Elasticsearch with no auth401shodan search 'product:elastic port:9200 -authentication'402403# Find Log4j vulnerable systems404shodan search 'vuln:CVE-2021-44228'405```406407### Example 3: IoT Device Discovery408```bash409# Find exposed webcams410shodan search 'webcam has_screenshot:true country:US'411412# Find industrial control systems413shodan search 'port:502 product:modbus'414415# Find exposed printers416shodan search '"HP-ChaiSOE" port:80'417418# Find smart home devices419shodan search 'product:nest'420```421422### Example 4: SSL/TLS Certificate Analysis423```bash424# Find hosts with specific SSL cert425shodan search 'ssl.cert.subject.cn:*.example.com'426427# Find expired certificates428shodan search 'ssl.cert.expired:true org:"Company"'429430# Find self-signed certificates431shodan search 'ssl.cert.issuer.cn:self-signed'432```433434### Example 5: Python Automation Script435```python436#!/usr/bin/env python3437import shodan438import json439440API_KEY = 'YOUR_API_KEY'441api = shodan.Shodan(API_KEY)442443def recon_organization(org_name):444 """Perform reconnaissance on an organization"""445 try:446 # Search for organization447 query = f'org:"{org_name}"'448 results = api.search(query)449450 print(f"[*] Found {results['total']} hosts for {org_name}")451452 # Collect unique IPs and ports453 hosts = {}454 for result in results['matches']:455 ip = result['ip_str']456 port = result['port']457 product = result.get('product', 'unknown')458459 if ip not in hosts:460 hosts[ip] = []461 hosts[ip].append({'port': port, 'product': product})462463 # Output findings464 for ip, services in hosts.items():465 print(f"\n[+] {ip}")466 for svc in services:467 print(f" - {svc['port']}/tcp ({svc['product']})")468469 return hosts470471 except shodan.APIError as e:472 print(f"Error: {e}")473 return None474475if __name__ == '__main__':476 recon_organization("Target Company")477```478479### Example 6: Network Range Assessment480```bash481# Scan a /24 network range482shodan search 'net:192.168.1.0/24'483484# Get port distribution485shodan stats --facets port 'net:192.168.1.0/24'486487# Find specific vulnerabilities in range488shodan search 'net:192.168.1.0/24 vuln:CVE-2021-44228'489490# Export all data for range491shodan download network_scan.json.gz 'net:192.168.1.0/24'492```493494## Troubleshooting495496| Issue | Cause | Solution |497|-------|-------|----------|498| No API Key Configured | Key not initialized | Run `shodan init YOUR_API_KEY` then verify with `shodan info` |499| Query Credits Exhausted | Monthly credits consumed | Use credit-free queries (no filters), wait for reset, or upgrade |500| Host Recently Crawled | Cannot re-scan IP within 24h | Use `shodan host IP` for existing data, or wait 24 hours |501| Rate Limit Exceeded | >1 request/second | Add `time.sleep(1)` between API requests |502| Empty Search Results | Too specific or syntax error | Use quotes for phrases: `'org:"Company Name"'`; broaden criteria |503| Downloaded File Won't Parse | Corrupted or wrong format | Verify with `gunzip -t file.gz`, re-download with `--limit` |504
Full transparency — inspect the skill content before installing.