| name | shodan-reconnaissance |
| description | Shodan query strategies for internet-wide host intelligence, asset discovery, vulnerability correlation, and attack surface mapping. Use when enriching BBOT results with Shodan data, hunting for exposed services, or correlating CVEs with discovered infrastructure. |
Shodan Reconnaissance
Purpose
Use Shodan to complement BBOT reconnaissance with internet-wide scan intelligence. Shodan provides passive host data, banner analysis, CVE correlation, and historical records that BBOT's active scanning may miss.
For evaluation tasks, the Shodan MCP can be pointed at a task-local mock service
by setting SHODAN_API_URL while still providing any non-empty
SHODAN_API_KEY. When SHODAN_API_URL is unset, the MCP uses the official
Shodan API client.
Integration with BBOT Graph
The primary workflow is: BBOT discovers assets → Shodan enriches them.
- Query the Neo4j graph for discovered IPs and domains
- Use Shodan to enrich with service details, CVEs, and historical data
- Feed Shodan findings back into analysis
Enrichment Patterns
Enrich all discovered IPs:
MATCH (ip:IP_ADDRESS) RETURN ip.address
Then for each IP: shodan_host_info(ip="x.x.x.x")
Find org-wide exposure:
shodan_host_search(query='org:"Target Corp"')
Cross-reference results against known IPs in the graph.
Discover assets BBOT missed:
shodan_host_search(query='ssl.cert.subject.cn:target.com')
shodan_host_search(query='hostname:target.com')
Compare with MATCH (d:DNS_NAME) RETURN d.name to find gaps.
Query Strategies
Asset Discovery
| Goal | Query |
|---|
| All hosts for an org | org:"Target Corp" |
| Hosts by hostname | hostname:target.com |
| Hosts by SSL cert | ssl.cert.subject.cn:target.com |
| Hosts by IP range | net:10.0.0.0/24 |
| Hosts by ASN | asn:AS12345 |
| Cloud-hosted assets | org:"Amazon" hostname:target.com |
Service Hunting
| Goal | Query |
|---|
| Web servers | hostname:target.com port:80,443 |
| Remote desktop | port:3389 org:"Target Corp" |
| SSH servers | port:22 org:"Target Corp" |
| Databases | port:3306,5432,27017,6379 org:"Target Corp" |
| Elasticsearch | port:9200 org:"Target Corp" |
| Docker APIs | port:2375,2376 org:"Target Corp" |
| Kubernetes | port:6443,10250 org:"Target Corp" |
Vulnerability Hunting
| Goal | Query |
|---|
| Hosts with known CVEs | vuln:CVE-2021-44228 org:"Target Corp" |
| Outdated SSL | ssl.version:sslv2 hostname:target.com |
| Expired certs | ssl.cert.expired:true hostname:target.com |
| Self-signed certs | ssl.cert.issuer.cn:target.com hostname:target.com |
| Default credentials | "default password" org:"Target Corp" |
| Specific product vulns | product:"Apache" version:"2.4.49" |
Technology Fingerprinting
| Goal | Query |
|---|
| Specific product | product:"nginx" org:"Target Corp" |
| HTTP title match | http.title:"Dashboard" org:"Target Corp" |
| Specific server header | "Server: Apache/2.4.49" |
| WAF detection | http.waf:"Cloudflare" hostname:target.com |
| CMS detection | http.component:"WordPress" hostname:target.com |
Workflow: Full ASM Enrichment
Step 1: Check Credits
Always start here to avoid hitting limits.
shodan_api_info()
Step 2: Scope Assessment
Use shodan_count (free, no credits) before committing to full searches.
shodan_count(query='org:"Target Corp"')
shodan_count(query='hostname:target.com')
shodan_count(query='ssl.cert.subject.cn:target.com')
Step 3: Broad Discovery
Run full searches on the most productive queries.
shodan_host_search(query='org:"Target Corp"', facets='port,product,country')
Facets give you instant distribution analysis without paging through results.
Step 4: Targeted Enrichment
For high-value IPs found by BBOT, get full details.
shodan_host_info(ip="x.x.x.x", history=True)
Historical data reveals services that were recently taken down or changed.
Step 5: Exploit Correlation
For any CVEs found on hosts, check exploit availability.
shodan_exploits_search(query="CVE-2024-XXXXX")
Step 6: DNS Cross-Reference
Validate and expand DNS data.
shodan_dns_lookup(hostnames=["api.target.com", "dev.target.com"])
shodan_dns_reverse(ips=["x.x.x.x", "y.y.y.y"])
Facet Analysis
Facets are the most powerful Shodan feature for ASM. They aggregate across all results without pagination.
Key facets:
port — Service distributionproduct — Technology distributioncountry — Geographic distributionorg — Hosting provider distributionos — Operating system distributionvuln — CVE distribution (requires paid plan)ssl.version — SSL/TLS version distributionhttp.title — Web page title distribution
Example: Full surface profile in one query:
shodan_host_search(
query='org:"Target Corp"',
facets='port,product,country,os,vuln,ssl.version'
)
Credit Management
| Operation | Credit Cost |
|---|
shodan_count | Free |
shodan_host_search | 1 query credit per page |
shodan_host_info | Free (IP lookups are free) |
shodan_dns_lookup | Free |
shodan_dns_reverse | Free |
shodan_exploits_search | Free |
Strategy: Use count + facets first, host_info for specific IPs (free), and reserve host_search for when you need the full match list.
