SKILL.md
GitHubShodan Reconnaissance Skill
Query Shodan for exposed services, target enrichment, and attack surface discovery.
Parse the user's input to determine the action:
$shodan search "org:Acme port:443"→ run a Shodan search query$shodan target 203.0.113.1→ enrich a specific IP$shodan target example.com→ enrich a domain (DNS + per-IP lookup)$shodan dorking "Acme Corp"→ build advanced Shodan dorks for a target$shodan monitor "Acme Corp"→ exposure report for an organization$shodan cve CVE-2024-3400→ find hosts vulnerable to a specific CVE$shodan cve CVE-2024-3400 "Acme Corp"→ CVE search scoped to an org
Prerequisites
- API key: Set
SHODAN_API_KEYenvironment variable- Free tier: limited searches, good for IP lookups
- Membership ($49 one-time): unlocks search filters, bulk lookups
- Small Business+: monitor, alerts, on-demand scanning
- CLI: Install with
pip install shodanoruv add shodan - Verify access:
shodan info(shows query/scan credits remaining)
If the API key is not set, inform the user and show how to set it:
export SHODAN_API_KEY="your-key-here"
# Or add to ~/.zshrc for persistence
echo 'export SHODAN_API_KEY="your-key-here"' >> ~/.zshrc
Actions
search — Run a Shodan query
Build the query from the user's input
Execute:
shodan search --fields ip_str,port,org,hostnames,product,version,os "<query>" --limit 100Parse and format results into a table:
IP Port Service Version Org Hostnames ───────────────────────────────────────────────────────────────────────────── 203.0.113.1 443 nginx 1.25.3 Target Corp www.target.com 203.0.113.2 22 OpenSSH 8.9p1 Target Corp ssh.target.comHighlight interesting findings:
- Critical: Known vulnerable versions, default credentials services, exposed admin panels
- Interesting: Uncommon ports, development/staging services, database ports, ICS/SCADA
- Note: Self-signed certs, expired certs, outdated software
Group results by service type when there are many results
target — Enrich a specific IP or domain
For IPs:
shodan host <ip>For domains:
shodan domain <domain>then lookup each IP foundCollect and present:
Host Summary:
- IP, ASN, organization, ISP, country/city
- Open ports and services (with versions)
- Hostnames and reverse DNS
- Last scan date
- Known vulnerabilities (CVEs) Shodan has flagged
- SSL/TLS certificate details (issuer, expiry, SANs)
- Technologies detected
Domain Summary (if domain provided):
- DNS records (A, AAAA, MX, NS, TXT, CNAME)
- Subdomains discovered
- Per-IP breakdown of services
Flag anything juicy:
- Ports that shouldn't be public (3389, 5900, 27017, 6379, 9200, 5432, 3306, 445)
- Services with known CVEs
- Expired or self-signed SSL certs
- Development/staging environments exposed
- Default pages or install wizards
dorking — Build advanced Shodan queries
Based on what the user describes, build targeted Shodan dorks.
Query building reference:
# Organization targeting
org:"Target Corp"
org:"Target Corp" port:443
# Network range
net:203.0.113.0/24
net:203.0.113.0/24 port:22
# Service-specific
product:"Apache httpd" version:"2.4.49" # Path traversal CVE-2021-41773
product:"Microsoft Exchange" port:443 # Exchange servers
product:"OpenSSH" version:"7.6" # Older SSH
"Server: Apache/2.4.49" # Raw banner match
# Exposed services (shouldn't be public)
org:"Target" port:3389 # RDP
org:"Target" port:445 # SMB
org:"Target" port:27017 # MongoDB
org:"Target" port:6379 # Redis
org:"Target" port:9200 # Elasticsearch
org:"Target" port:5432 # PostgreSQL
org:"Target" port:3306 # MySQL
org:"Target" port:11211 # Memcached
org:"Target" "port:2379" # etcd
# Web technologies
org:"Target" http.title:"Dashboard"
org:"Target" http.title:"Login"
org:"Target" http.title:"Index of /" # Directory listing
org:"Target" http.component:"WordPress"
org:"Target" http.component:"Jira"
org:"Target" http.component:"Jenkins"
org:"Target" http.component:"Grafana"
org:"Target" http.favicon.hash: # Favicon hash matching
# SSL/TLS
org:"Target" ssl.cert.expired:true
org:"Target" ssl.cert.issuer.cn:"Let's Encrypt"
ssl.cert.subject.cn:"target.com" # Find all IPs for a cert
# Vulnerable services
vuln:CVE-2021-44228 # Log4Shell
vuln:CVE-2023-22515 # Confluence
vuln:CVE-2024-3400 # PAN-OS
# ICS/SCADA (if in scope)
org:"Target" tag:ics
org:"Target" port:502 # Modbus
org:"Target" port:44818 # EtherNet/IP
# Cloud metadata
org:"Amazon" http.title:"Target"
"X-Powered-By" org:"Target"
# Country/city filtering
org:"Target" country:"US" city:"New York"
# Screenshot available
org:"Target" has_screenshot:true
# Honeypot detection
org:"Target" tag:honeypot
Present 5-10 relevant queries for the scenario with explanations of what each finds and why it matters.
monitor — Check exposure for an organization
Run multiple targeted queries for the org:
shodan search 'org:"<org_name>"' --fields ip_str,port,product,version --limit 500Build an exposure report:
Attack Surface Summary:
- Total IPs discovered
- Total open ports
- Unique services and versions
Exposed Services by Risk:
Risk Service Count Details Critical RDP (3389) 3 Direct RDP exposure to internet Critical MongoDB (27017) 1 No auth likely High SSH (22) 15 Check for password auth High Expired SSL 4 Trust issues, possible neglect Info HTTPS (443) 42 Normal Version Intelligence:
- Outdated software detected (with CVE references)
- End-of-life products
Recommendations:
- Prioritized list of what to investigate or report
If the user asks, save the full report as markdown
cve — Find hosts vulnerable to a specific CVE
- Search:
shodan search "vuln:<cve_id>"(or if targeting an org:shodan search "vuln:<cve_id> org:\"<org>\"") - If Shodan doesn't index that CVE, fall back to service/version matching:
- Look up affected product/versions for the CVE
- Build a query matching those versions
- Present results with:
- Affected hosts and their details
- CVE description and severity
- Whether exploitation requires authentication or special conditions
- Suggested next steps (verify, exploit, report)
Python API Fallback
If the Shodan CLI isn't available or for complex queries, use the Python API:
import shodan
import os
api = shodan.Shodan(os.environ["SHODAN_API_KEY"])
# Search
results = api.search("org:\"Target Corp\" port:443")
for result in results["matches"]:
print(f"{result['ip_str']}:{result['port']} - {result.get('product', 'unknown')}")
# Host lookup
host = api.host("203.0.113.1")
print(f"Ports: {host['ports']}")
print(f"Vulns: {host.get('vulns', [])}")
# DNS lookup
dns = api.dns.domain_info("target.com")
Output Formatting
- Default: Rich tables to terminal with color-coded severity
- With
--output <file>: Markdown report file with full details - Always include the Shodan query used so the user can repeat or modify it
- Note the scan date — Shodan data can be days/weeks old