Shodan Reconnaissance Elite

Leverage Shodan for internet-wide reconnaissance during authorized security assessments. This skill covers Shodan query syntax, device and service enumeration, vulnerability discovery, network mapping, and integration with penetration testing workflows using the Shodan API and CLI.

When to Use This Skill

Choose Shodan Reconnaissance Elite when you need to:

• Discover internet-facing assets belonging to a target organization
• Identify exposed services, default credentials, and known vulnerabilities
• Map an organization's external attack surface without active scanning
• Monitor for new exposures or changes in a target's internet presence

Consider alternatives when:

• You need internal network scanning (use Nmap or scanning framework skills)
• You need web application vulnerability testing (use Burp Suite or DAST tools)
• You need dark web or threat intelligence (use OSINT-specific tools)

Quick Start

Copy
pip install shodan
shodan init YOUR_API_KEY

Copy
import shodan

SHODAN_API_KEY = "YOUR_API_KEY"  # Use env variable in practice
api = shodan.Shodan(SHODAN_API_KEY)

# Search for a target organization
def search_organization(org_name, max_results=100):
    """Search Shodan for an organization's internet-facing assets."""
    try:
        results = api.search(f'org:"{org_name}"', limit=max_results)
        print(f"Results: {results['total']} total hosts")

        for result in results['matches']:
            ip = result['ip_str']
            port = result['port']
            org = result.get('org', 'N/A')
            product = result.get('product', 'N/A')
            vulns = result.get('vulns', [])

            print(f"\n{ip}:{port}")
            print(f"  Org: {org}")
            print(f"  Product: {product}")
            print(f"  OS: {result.get('os', 'N/A')}")
            if vulns:
                print(f"  Vulnerabilities: {', '.join(list(vulns)[:5])}")

        return results
    except shodan.APIError as e:
        print(f"Shodan API error: {e}")
        return None

# Look up a specific IP
def host_info(ip):
    """Get detailed information about a host."""
    try:
        host = api.host(ip)
        print(f"IP: {host['ip_str']}")
        print(f"Organization: {host.get('org', 'N/A')}")
        print(f"OS: {host.get('os', 'N/A')}")
        print(f"Open ports: {host['ports']}")

        for item in host['data']:
            print(f"\n  Port {item['port']}:")
            print(f"    Service: {item.get('product', 'unknown')}")
            print(f"    Banner: {item['data'][:200]}")

        if host.get('vulns'):
            print(f"\nVulnerabilities: {list(host['vulns'])}")

        return host
    except shodan.APIError as e:
        print(f"Error: {e}")
        return None

# search_organization("Acme Corporation")
# host_info("93.184.216.34")

Core Concepts

Shodan Query Filters

Filter	Description	Example
org	Organization name	org:"Google"
hostname	Hostname/domain	hostname:example.com
net	IP range/CIDR	net:192.168.0.0/16
port	Open port number	port:22
product	Software/product name	product:Apache
version	Software version	version:2.4.49
os	Operating system	os:"Windows Server 2019"
country	Country code	country:US
vuln	CVE vulnerability	vuln:CVE-2021-44228
ssl.cert.subject.cn	SSL certificate CN	ssl.cert.subject.cn:example.com
http.title	Web page title	http.title:"Dashboard"
has_screenshot	Has screenshot available	has_screenshot:true

Attack Surface Monitor

Copy
import shodan
import json
from datetime import datetime

class AttackSurfaceMonitor:
    """Monitor an organization's internet-facing attack surface."""

    def __init__(self, api_key, org_name):
        self.api = shodan.Shodan(api_key)
        self.org = org_name

    def full_enumeration(self):
        """Enumerate all internet-facing assets."""
        queries = [
            f'org:"{self.org}"',
            f'ssl.cert.subject.cn:"{self.org.lower().replace(" ", "")}.com"',
        ]

        all_hosts = {}
        for query in queries:
            try:
                results = self.api.search(query, limit=500)
                for match in results['matches']:
                    ip = match['ip_str']
                    if ip not in all_hosts:
                        all_hosts[ip] = {
                            'ip': ip,
                            'ports': [],
                            'services': [],
                            'vulns': set(),
                            'org': match.get('org', ''),
                        }
                    all_hosts[ip]['ports'].append(match['port'])
                    all_hosts[ip]['services'].append({
                        'port': match['port'],
                        'product': match.get('product', ''),
                        'version': match.get('version', ''),
                    })
                    all_hosts[ip]['vulns'].update(match.get('vulns', []))
            except shodan.APIError as e:
                print(f"Query failed: {e}")

        # Convert sets for JSON
        for host in all_hosts.values():
            host['vulns'] = list(host['vulns'])

        return all_hosts

    def risk_summary(self, hosts):
        """Generate risk summary from enumerated hosts."""
        total_hosts = len(hosts)
        total_vulns = sum(len(h['vulns']) for h in hosts.values())
        risky_ports = {21, 23, 445, 1433, 3306, 3389, 5432, 5900, 6379, 27017}
        exposed_risky = []

        for ip, data in hosts.items():
            exposed = risky_ports.intersection(data['ports'])
            if exposed:
                exposed_risky.append((ip, exposed))

        print(f"\n=== ATTACK SURFACE SUMMARY ===")
        print(f"Internet-facing hosts: {total_hosts}")
        print(f"Total known vulnerabilities: {total_vulns}")
        print(f"Hosts with risky ports exposed: {len(exposed_risky)}")

        if exposed_risky:
            print("\nRisky port exposures:")
            for ip, ports in exposed_risky:
                print(f"  {ip}: {ports}")

# monitor = AttackSurfaceMonitor("API_KEY", "Acme Corp")
# hosts = monitor.full_enumeration()
# monitor.risk_summary(hosts)

Configuration

Parameter	Description	Default
api_key	Shodan API key	Required
query_credits	Monthly query credit limit	Plan-dependent
scan_credits	Monthly on-demand scan credits	Plan-dependent
results_limit	Max results per query	100
monitor_interval	Alert monitoring frequency	"daily"
alert_severity	Minimum severity for alerts	"high"
output_format	Results format (json, csv, text)	"json"
proxy	HTTP proxy for API requests	None

Best Practices

1. Use Shodan for passive reconnaissance before active scanning — Shodan data is collected independently, so querying it doesn't touch the target. This provides attack surface visibility without triggering the target's IDS/IPS. Always start with passive recon.

2. Combine org, hostname, and SSL certificate queries — A single query type may miss assets. Organizations often have assets across multiple IP ranges, subsidiaries, and cloud providers. SSL certificate CN and subject alternative name queries catch assets that WHOIS-based org queries miss.

3. Set up Shodan Alerts for continuous monitoring — Use api.create_alert("My Alert", ip_range) to get notified when new services appear on your target's infrastructure. This catches shadow IT, misconfigured services, and temporary exposures that point-in-time scans miss.

4. Cross-reference Shodan findings with CVE databases — Shodan's vulns field maps to CVEs based on version detection. Verify these findings — version-based detection has false positives (the vulnerability may be patched without changing the version banner). Use the CVE data as a starting point for targeted testing.

5. Respect Shodan's rate limits and terms of service — Free API keys have limited queries per month. Cache results locally for repeated analysis. Don't use Shodan for unauthorized reconnaissance — the data is publicly collected, but using it to plan attacks without authorization is unethical and potentially illegal.

Common Issues

Shodan returns outdated data for some hosts — Shodan crawls the internet continuously but doesn't scan every host every day. Results may be days to weeks old. Check the last_update field in results. For current data, use Shodan's on-demand scanning feature (requires scan credits).

Organization search returns unrelated results — The org filter matches WHOIS organization names, which may be ISP names rather than the target company. Combine with net: filters for known IP ranges and hostname: for confirmed domains to reduce noise.

API key runs out of query credits — Free Shodan accounts have limited query credits. Use the CLI (shodan search) for quick lookups without code. For programmatic access, cache results aggressively and use filters to narrow queries before searching.