# Shodan Attack Surface Mapper — Ports, Services & CVEs (`gochujang/shodan-surface-mapper`) Actor

Map the attack surface of IP addresses and domains using Shodan. Returns open ports, running services, service banners, known CVEs, geolocation, ASN, and ISP. Requires a free Shodan API key (register at shodan.io).

- **URL**: https://apify.com/gochujang/shodan-surface-mapper.md
- **Developed by:** [Hojun Lee](https://apify.com/gochujang) (community)
- **Categories:** Developer tools
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 item processeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Shodan Attack Surface Mapper — Open Ports, Services, CVEs, Geolocation

Map the external attack surface of any IP address or domain using the [Shodan](https://shodan.io) API. Returns open ports, running services, service banners, known CVEs, geolocation, ASN, and ISP — all from a single Actor run.

**Requires a free Shodan API key** — register at [shodan.io](https://account.shodan.io). The free tier supports direct IP lookups with no credit card required.

***

### Use Cases

- **Penetration testing recon** — quickly enumerate open ports and services on targets before an engagement
- **External attack surface management (EASM)** — continuously monitor what your organization exposes to the internet
- **Vendor / third-party risk assessment** — audit a vendor's internet-facing infrastructure for misconfigurations
- **Cloud misconfiguration detection** — find inadvertently exposed RDP, SSH, database, or admin ports
- **CVE triage** — identify hosts running software with known CVEs before your security team does
- **Research and threat intelligence** — bulk-enrich IP lists with service, location, and vulnerability context

***

### Input

| Field | Type | Required | Description |
|---|---|---|---|
| `shodanApiKey` | string (secret) | Yes | Your Shodan API key. Get free at [shodan.io](https://account.shodan.io) |
| `ips` | array of string | No\* | IPv4 or IPv6 addresses to look up |
| `domains` | array of string | No\* | Domain names to resolve then look up |
| `includeVulns` | boolean | No | Include known CVE IDs (default: `true`) |
| `includeBanners` | boolean | No | Include raw service banners, first 200 chars (default: `false`) |

\* At least one IP or domain is required.

#### Example input (JSON)

```json
{
  "shodanApiKey": "YOUR_SHODAN_API_KEY",
  "ips": ["8.8.8.8", "1.1.1.1"],
  "domains": ["scanme.nmap.org"],
  "includeVulns": true,
  "includeBanners": false
}
```

***

### Output

Each scanned host produces one result item. A final `_type: "summary"` item aggregates the run.

#### Host result (found)

```json
{
  "ip": "45.33.32.156",
  "found": true,
  "hostnames": ["scanme.nmap.org"],
  "domains": ["nmap.org"],
  "country_name": "United States",
  "city": "Fremont",
  "org": "Linode",
  "isp": "Linode, LLC",
  "asn": "AS63949",
  "open_ports": [22, 80, 9929, 31337],
  "port_count": 4,
  "services": [
    {
      "port": 22,
      "protocol": "ssh",
      "product": "OpenSSH",
      "version": "6.6.1p1",
      "cpe": ["cpe:/a:openbsd:openssh:6.6.1p1"],
      "transport": "tcp"
    },
    {
      "port": 80,
      "protocol": "http",
      "product": "Apache httpd",
      "version": "2.4.7",
      "cpe": ["cpe:/a:apache:http_server:2.4.7"],
      "transport": "tcp"
    }
  ],
  "vulns": ["CVE-2014-0160", "CVE-2015-3253"],
  "vuln_count": 2,
  "tags": [],
  "last_update": "2024-11-15T08:21:00.000000",
  "scanned_at": "2025-09-01T12:00:00.000000Z"
}
```

#### Host result (not found)

```json
{
  "ip": "192.168.1.1",
  "found": false,
  "scanned_at": "2025-09-01T12:00:00.000000Z"
}
```

#### Summary item

```json
{
  "_type": "summary",
  "total_hosts": 3,
  "hosts_found": 2,
  "hosts_not_found": 1,
  "total_open_ports": 12,
  "common_ports_breakdown": [
    {"port": 443, "count": 2},
    {"port": 80, "count": 2},
    {"port": 22, "count": 1}
  ],
  "hosts_with_vulns": 1,
  "unique_countries": ["Germany", "United States"],
  "completed_at": "2025-09-01T12:00:05.000000Z"
}
```

***

### Pricing

| Event | Price |
|---|---|
| Actor start | $0.001 |
| Per IP/host scanned | $0.005 |

Scanning 100 hosts costs approximately **$0.50 + compute time**.

***

### Comparison to Alternatives

| Tool | Cost | What you get |
|---|---|---|
| Shodan Enterprise API | $899+/yr | Full search, real-time scans, alerts |
| Censys Enterprise | $15,000+/yr | Certificate transparency + Shodan-style scan |
| **This Actor** | $0.005/host | Shodan free-tier host lookups, structured output, Apify integration |

This Actor is ideal for teams that need structured, enriched host data without a Shodan Enterprise subscription.

***

### Free Tier Limitations

- **No search queries** — only direct IP lookups (`/shodan/host/{ip}`)
- **No real-time scanning** — data reflects Shodan's last crawl of that IP
- **Rate limited** — 1 request/second; the Actor automatically throttles to comply
- **No HTTPS certificate data** or historical port data (paid features)

#### Upgrade path for paid Shodan accounts

If you have a Shodan paid plan (from $49/mo), you can also use Shodan's search API (`/shodan/host/search`) to find all hosts matching a query — e.g., all Apache servers in Germany with port 3389 open. Contact us or open a GitHub issue to request this extension.

***

### Tips

- Use `domains` input to automatically resolve hostnames to IPs before scanning — useful when you know domain names but not IPs.
- Enable `includeBanners` only when you need raw service fingerprinting data — it can significantly increase output size.
- Combine with the [Smart Money Wallet Tracker](https://apify.com/gochujang/smart-money-wallet-tracker) or other infrastructure actors for comprehensive recon workflows.
- Results are based on Shodan's last crawl — for fresh data you need a Shodan paid scan credit.

**Keywords:** Shodan, attack surface, port scanning, OSINT, security audit, CVE, SSL, network reconnaissance, cybersecurity

***

### Related actors

- [SSL Certificate Monitor](https://apify.com/gochujang/ssl-certificate-monitor) — Certificate details and expiry monitoring for the exposed services found here
- [CVE Vulnerability Tracker](https://apify.com/gochujang/cve-vulnerability-tracker) — CVE intelligence to research vulnerabilities flagged by this actor
- [Domain Breach Checker](https://apify.com/gochujang/domain-breach-checker) — Data breach history for domains whose attack surface is mapped here

### Feedback

If this actor powers your security research, a review helps others find it: [Leave a review on Apify Store](https://apify.com/gochujang/shodan-surface-mapper#reviews)

# Actor input Schema

## `shodanApiKey` (type: `string`):

Your Shodan API key. Get a free key at https://account.shodan.io — free tier supports direct IP lookups.

## `ips` (type: `array`):

List of IPv4 or IPv6 addresses to look up in Shodan.

## `domains` (type: `array`):

List of domain names to resolve to IPs and then look up in Shodan (e.g. example.com, api.example.com).

## `includeVulns` (type: `boolean`):

When enabled, includes known CVE identifiers reported by Shodan for each host.

## `includeBanners` (type: `boolean`):

When enabled, includes the raw service banners (first 200 chars) for each open port. Can be large for hosts with many open ports.

## Actor input object example

```json
{
  "ips": [],
  "domains": [],
  "includeVulns": true,
  "includeBanners": false
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("gochujang/shodan-surface-mapper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("gochujang/shodan-surface-mapper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call gochujang/shodan-surface-mapper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,gochujang/shodan-surface-mapper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/5lc6T9tZjfFOdF73h/builds/Yhb4whKXcAhAV660z/openapi.json