shodan-reconnaissance git:20260611.414f191A

Immutable. This exact content is served forever at /api/v1/blob/c5dfc76121d51c64.

---
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.**

1. Query the Neo4j graph for discovered IPs and domains
2. Use Shodan to enrich with service details, CVEs, and historical data
3. Feed Shodan findings back into analysis

### Enrichment Patterns

**Enrich all discovered IPs:**
```cypher
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 distribution
- `product` — Technology distribution
- `country` — Geographic distribution
- `org` — Hosting provider distribution
- `os` — Operating system distribution
- `vuln` — CVE distribution (requires paid plan)
- `ssl.version` — SSL/TLS version distribution
- `http.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.