# Shodan

> Search Shodan, the search engine for Internet-connected devices: see what runs on an IP address, search and count exposed services by product, port, country or vulnerability, list a domain's subdomains and DNS records, request scans and manage Shodan Monitor network alerts. Eight actions are free and need no API key: InternetDB IP lookups, CVEDB vulnerability searches, subdomains and certificates from Certificate Transparency logs, and ping and DNS checks from around the world.

App · Compliance & Security · 25 actions. Web page: https://docs.lodol.com/docs/integrations/shodan

## Actions

### Count hosts

Count how many services match a Shodan search query, with an optional breakdown by country, organization, port or another property, without returning the results. Needs an API key; uses no query credits.

**Inputs**

- Query (`query`, text, required): A Shodan search query, written as on shodan.io. Filters narrow it: port:22, country:DE, org:"Example Corp", product:nginx, net:198.51.100.0/24 or vuln:CVE-2021-44228. Filters need a Membership.
- Breakdowns (`facets`, text): Properties to break the results down by, separated by commas, each with an optional number of top values: country, org:10, port, product or vuln.

**Outputs**

- `facets` (list): A breakdown of the results by each facet asked for
- `query` (text): The query counted
- `total` (number): How many results match

**Example output**

```json
{
  "facets": [
    {
      "facet": "org",
      "values": [
        {
          "count": 3012386,
          "value": "Amazon.com"
        },
        {
          "count": 1322102,
          "value": "Google Cloud"
        }
      ]
    }
  ],
  "query": "port:22",
  "total": 19590274
}
```

### Create network alert

Start monitoring IP addresses or networks with Shodan Monitor, and turn on the triggers to be notified about, like a newly opened port or a vulnerable service. Notifications go to the Shodan account's email. Needs an API key with a Membership (16 IP addresses) or a paid plan.

**Inputs**

- Name (`name`, text, required): A name for the alert, like Production network.
- IP addresses or networks (`networks`, list, required): The IP addresses, or networks in CIDR notation like 198.51.100.0/24, to monitor: a list, or entries separated by commas or new lines. A Membership monitors up to 16 IP addresses.
- Triggers (`triggers`, list): What to notify about, by email to the Shodan account. New service is the one Shodan recommends: it fires when something changes. Leave empty to turn triggers on later. One or more of: `new_service` (New service: a port that was not open before), `vulnerable` (Vulnerable: a verified vulnerability), `vulnerable_unverified` (Vulnerable (unverified): a likely vulnerability), `malware` (Malware: a compromised or malware-related service), `open_database` (Open database: a database without authentication), `ssl_expired` (SSL expired: an expired certificate), `end_of_life` (End of life: software past its end of life), `iot` (IoT: an Internet of Things device), `industrial_control_system` (Industrial control system), `internet_scanner` (Internet scanner: the device scans the Internet), and 4 more.
- Expires after days (`expires_in_days`, number): Stop monitoring after this many days. Leave empty to monitor until the alert is deleted. From 1 to 3650.

**Outputs**

- `alert_id` (text): The alert's ID
- `created_at` (text): When it was created (ISO 8601)
- `expires_at` (text): When it stops monitoring (ISO 8601); empty for never
- `ip_count` (number): How many IP addresses that is
- `name` (text): The alert's name
- `networks` (list): The addresses and networks it monitors
- `notifier_ids` (list): Where notifications go; default is the account's email
- `triggers` (list): The triggers turned on, like new_service

**Example output**

```json
{
  "alert_id": "OYPRB8IR9Z35AZPR",
  "created_at": "2021-01-27T03:44:22Z",
  "expires_at": null,
  "ip_count": 2,
  "name": "DNS Alert",
  "networks": [
    "8.8.8.8",
    "1.1.1.1"
  ],
  "notifier_ids": [
    "default"
  ],
  "triggers": [
    "new_service"
  ]
}
```

### Delete network alert

Delete a network alert, which stops monitoring its IP addresses and frees them for another alert. Needs an API key.

**Inputs**

- Alert ID (`alert_id`, text, required): The alert's ID, from Create network alert or List network alerts.

**Outputs**

- `alert_id` (text): The alert's ID
- `deleted` (true/false): True once it is deleted

**Example output**

```json
{
  "alert_id": "OYPRB8IR9Z35AZPR",
  "deleted": true
}
```

### Disable alert triggers

Turn off triggers for a network alert, to stop those notifications. The alert keeps monitoring. Needs an API key.

**Inputs**

- Alert ID (`alert_id`, text, required): The alert's ID, from Create network alert or List network alerts.
- Triggers (`triggers`, list, required): The triggers to change, like New service. One or more of: `new_service` (New service: a port that was not open before), `vulnerable` (Vulnerable: a verified vulnerability), `vulnerable_unverified` (Vulnerable (unverified): a likely vulnerability), `malware` (Malware: a compromised or malware-related service), `open_database` (Open database: a database without authentication), `ssl_expired` (SSL expired: an expired certificate), `end_of_life` (End of life: software past its end of life), `iot` (IoT: an Internet of Things device), `industrial_control_system` (Industrial control system), `internet_scanner` (Internet scanner: the device scans the Internet), and 4 more.

**Outputs**

- `alert_id` (text): The alert's ID
- `enabled` (true/false): True when they were turned on, false when off
- `triggers` (list): The triggers changed

**Example output**

```json
{
  "alert_id": "OYPRB8IR9Z35AZPR",
  "enabled": false,
  "triggers": [
    "vulnerable"
  ]
}
```

### Enable alert triggers

Turn on triggers for a network alert, to be notified when Shodan finds, for example, a new open port or a vulnerable service. Turning on one that is already on changes nothing. Needs an API key.

**Inputs**

- Alert ID (`alert_id`, text, required): The alert's ID, from Create network alert or List network alerts.
- Triggers (`triggers`, list, required): The triggers to change, like New service. One or more of: `new_service` (New service: a port that was not open before), `vulnerable` (Vulnerable: a verified vulnerability), `vulnerable_unverified` (Vulnerable (unverified): a likely vulnerability), `malware` (Malware: a compromised or malware-related service), `open_database` (Open database: a database without authentication), `ssl_expired` (SSL expired: an expired certificate), `end_of_life` (End of life: software past its end of life), `iot` (IoT: an Internet of Things device), `industrial_control_system` (Industrial control system), `internet_scanner` (Internet scanner: the device scans the Internet), and 4 more.

**Outputs**

- `alert_id` (text): The alert's ID
- `enabled` (true/false): True when they were turned on, false when off
- `triggers` (list): The triggers changed

**Example output**

```json
{
  "alert_id": "OYPRB8IR9Z35AZPR",
  "enabled": true,
  "triggers": [
    "new_service",
    "vulnerable"
  ]
}
```

### Find hostnames in certificate logs

Free, no API key needed. Find every host name under a domain that a publicly logged TLS certificate covers, from Shodan's mirror of the Certificate Transparency logs: a quick way to map a domain's subdomains.

**Inputs**

- Domain (`domain`, text, required): The domain, like example.com. A link or email address works too.

**Outputs**

- `count` (number): How many came back
- `domain` (text): The domain searched
- `hostnames` (list): Every host name under the domain that a logged certificate names, alphabetically

**Example output**

```json
{
  "count": 4,
  "domain": "shodan.io",
  "hostnames": [
    "book.shodan.io",
    "ctl.shodan.io",
    "shodan.io",
    "status.shodan.io"
  ]
}
```

### Find product CPEs

Free, no API key needed. List the CPE names Shodan's CVEDB knows for a product, one per version, like cpe:2.3:a:apache:log4j:2.14.1. Pass one to Search vulnerabilities to check that exact version. Free for non-commercial use.

**Inputs**

- Product (`product`, text, required): A product name as CPE names spell it, lowercase with underscores for spaces, like log4j, openssh or http_server.
- Maximum CPEs (`limit`, number): How many CPE names to return, up to 1,000. From 1 to 1000. Default: `100`.
- Offset (`offset`, number): How many to skip. For the next page, pass the next_offset the previous page returned. At least 0. Default: `0`.

**Outputs**

- `count` (number): How many came back
- `cpes` (list): CPE 2.3 names, one per version, like cpe:2.3:a:apache:log4j:2.14.1
- `has_more` (true/false): True when there are more on a later page
- `next_offset` (number): Pass as Offset to get the next page. Empty when there is no next page
- `product` (text): The product searched for

**Example output**

```json
{
  "count": 3,
  "cpes": [
    "cpe:2.3:a:apache:log4j:1.0.4",
    "cpe:2.3:a:apache:log4j:1.1.3",
    "cpe:2.3:a:apache:log4j:1.2"
  ],
  "has_more": true,
  "next_offset": 3,
  "product": "log4j"
}
```

### Get API plan and credits

Get the Shodan account's plan and what it has left this month: query credits, scan credits and monitored IP addresses. Needs an API key; works on every plan.

**Inputs**: None.

**Outputs**

- `monitored_ips` (number): How many IP addresses network alerts monitor
- `monitored_ips_limit` (number): How many IP addresses the plan can monitor; empty when unlimited
- `plan` (text): The plan's code, like oss (free) or dev (Membership)
- `plan_name` (text): The plan's name, like Free or Membership
- `query_credits_left` (number): Query credits left this month
- `query_credits_monthly` (number): Query credits the plan gives each month; empty when unlimited
- `scan_credits_left` (number): Scan credits left this month
- `scan_credits_monthly` (number): Scan credits the plan gives each month; empty when unlimited

**Example output**

```json
{
  "monitored_ips": 2,
  "monitored_ips_limit": 16,
  "plan": "dev",
  "plan_name": "Membership",
  "query_credits_left": 97,
  "query_credits_monthly": 100,
  "scan_credits_left": 100,
  "scan_credits_monthly": 100
}
```

### Get domain info

Get the subdomains and DNS records Shodan has seen for a domain, 100 records a page, optionally of one record type. Needs an API key with a Membership or a paid plan. Each page costs 1 query credit.

**Inputs**

- Domain (`domain`, text, required): The domain, like example.com. A link or email address works too.
- Record type (`record_type`, text): Only records of this type. One of: `all` (All types), `A` (A (IPv4 address)), `AAAA` (AAAA (IPv6 address)), `CNAME` (CNAME (alias)), `NS` (NS (name server)), `SOA` (SOA (zone authority)), `MX` (MX (mail server)), `TXT` (TXT (text)). Default: `all`.
- Include history (`include_history`, true/false): Also return what Shodan saw in the past, not only the latest. Default: `false`.
- Page (`page`, number): Which page of records, 100 a page. Each page costs 1 query credit. From 1 to 10000. Default: `1`.

**Outputs**

- `domain` (text): The domain
- `has_more` (true/false): True when there are more on a later page
- `page` (number): This page's number
- `records` (list): Up to 100 DNS records
- `subdomains` (list): Its subdomains, like www or mail
- `tags` (list): What Shodan noticed about the domain, like ipv6

**Example output**

```json
{
  "domain": "google.com",
  "has_more": true,
  "page": 1,
  "records": [
    {
      "hostname": "google.com",
      "last_seen": "2021-01-19T22:23:15Z",
      "subdomain": "",
      "type": "MX",
      "value": "aspmx.l.google.com"
    },
    {
      "hostname": "*.auth.corp.google.com",
      "last_seen": "2021-01-26T13:04:34Z",
      "subdomain": "*.auth.corp",
      "type": "CNAME",
      "value": "uberproxy.l.google.com"
    }
  ],
  "subdomains": [
    "*.auth.corp",
    "*.cloud.sandbox"
  ],
  "tags": [
    "ipv6"
  ]
}
```

### Get host details

Get everything Shodan knows about an IP address: who owns it, where it is, its open ports, and each service it runs with its software, TLS certificate, web page title and vulnerabilities. An address Shodan knows nothing about comes back with found false. Needs an API key with a Membership or a paid plan, and uses no query credits.

**Inputs**

- IP address (`ip_address`, text, required): The IPv4 or IPv6 address to look up.
- Include history (`include_history`, true/false): Also return what Shodan saw in the past, not only the latest. Default: `false`.
- Summary only (`summary_only`, true/false): Return only the open ports and general details, not each service. Faster, and smaller. Default: `false`.

**Outputs**

- `asn` (text): Its autonomous system, like AS15169
- `city` (text): The city
- `country_code` (text): Two-letter country code, like US
- `country_name` (text): The country's name
- `domains` (list): Domains those names belong to
- `found` (true/false): False when Shodan has no information on the address
- `hostnames` (list): Host names for the address
- `ip_address` (text): The address looked up
- `isp` (text): Its Internet service provider
- `last_update` (text): When Shodan last updated it (ISO 8601)
- `latitude` (number): Approximate latitude
- `longitude` (number): Approximate longitude
- `operating_system` (text): The operating system Shodan identified
- `organization` (text): The organization the address is assigned to
- `ports` (list): Every open port Shodan saw
- `region_code` (text): The region or state code
- `service_count` (number): How many services came back
- `services` (list): Each service it runs, by port
- `tags` (list): What kind of host it is, like cloud or vpn
- `vulnerability_ids` (list): CVE IDs of vulnerabilities across its services

**Example output**

```json
{
  "asn": "AS15169",
  "city": null,
  "country_code": "US",
  "country_name": "United States",
  "domains": [
    "dns.google"
  ],
  "found": true,
  "hostnames": [
    "dns.google"
  ],
  "ip_address": "8.8.8.8",
  "isp": "Google",
  "last_update": "2021-01-22T08:49:35Z",
  "latitude": 37.751,
  "longitude": -97.822,
  "operating_system": null,
  "organization": "Google",
  "ports": [
    53
  ],
  "region_code": null,
  "service_count": 1,
  "services": [
    {
      "banner": "\nRecursion: enabled",
      "collected_at": "2021-01-22T08:49:35Z",
      "cpes": [],
      "hostnames": [
        "dns.google"
      ],
      "http_server": null,
      "http_status": null,
      "http_title": null,
      "module": "dns-udp",
      "port": 53,
      "product": null,
      "ssl_expired": null,
      "ssl_expires_at": null,
      "ssl_issuer": null,
      "ssl_subject": null,
      "tags": [],
      "transport": "udp",
      "version": null,
      "vulnerabilities": []
    }
  ],
  "tags": [],
  "vulnerability_ids": []
}
```

### Get network alert

Get one network alert: what it monitors, which triggers are on and when it expires. Needs an API key.

**Inputs**

- Alert ID (`alert_id`, text, required): The alert's ID, from Create network alert or List network alerts.

**Outputs**

- `alert_id` (text): The alert's ID
- `created_at` (text): When it was created (ISO 8601)
- `expires_at` (text): When it stops monitoring (ISO 8601); empty for never
- `ip_count` (number): How many IP addresses that is
- `name` (text): The alert's name
- `networks` (list): The addresses and networks it monitors
- `notifier_ids` (list): Where notifications go; default is the account's email
- `triggers` (list): The triggers turned on, like new_service

**Example output**

```json
{
  "alert_id": "OYPRB8IR9Z35AZPR",
  "created_at": "2021-01-27T03:44:22Z",
  "expires_at": null,
  "ip_count": 2,
  "name": "DNS Alert",
  "networks": [
    "8.8.8.8",
    "1.1.1.1"
  ],
  "notifier_ids": [
    "default"
  ],
  "triggers": [
    "new_service"
  ]
}
```

### Get scan status

Check how far a scan has got: SUBMITTING, QUEUE, PROCESSING or DONE. Needs an API key.

**Inputs**

- Scan ID (`scan_id`, text, required): The ID Request a scan returned.

**Outputs**

- `created_at` (text): When it was requested (ISO 8601)
- `done` (true/false): True when the scan has finished
- `ip_count` (number): How many IP addresses it covers
- `scan_id` (text): The scan's ID
- `status` (text): SUBMITTING, QUEUE, PROCESSING or DONE

**Example output**

```json
{
  "created_at": "2021-01-26T08:17:43Z",
  "done": true,
  "ip_count": 1,
  "scan_id": "Mo8W7itcWumiy9Ay",
  "status": "DONE"
}
```

### Get vulnerability

Free, no API key needed. Get a vulnerability from Shodan's CVEDB by CVE or EUVD ID: its summary, CVSS scores, EPSS exploit prediction, whether CISA lists it as exploited in the wild, references and the affected software versions. An ID CVEDB doesn't have comes back with found false. Free for non-commercial use.

**Inputs**

- Vulnerability ID (`vulnerability_id`, text, required): A CVE ID like CVE-2021-44228, or an EU Vulnerability Database ID like EUVD-2024-16003. A link that contains one works too.

**Outputs**

- `affected_cpe_count` (number): How many CPE names are affected in all
- `affected_cpes` (list): The affected software versions as CPE 2.3 names (the first 500)
- `cve_id` (text): The CVE ID, like CVE-2021-44228
- `cvss` (number): The CVSS severity score, 0 to 10, from the newest CVSS version scored
- `cvss_v2` (number): The CVSS 2 score, if it was scored
- `cvss_v3` (number): The CVSS 3 score, if it was scored
- `cvss_v4` (number): The CVSS 4 score, if it was scored
- `cvss_version` (number): Which CVSS version that score is, like 3 or 4
- `epss` (number): The EPSS score: the chance, from 0 to 1, that it is exploited in the next 30 days
- `epss_percentile` (number): The share of all scored vulnerabilities with the same or a lower EPSS score, from 0 to 1
- `euvd_id` (text): Its ID in the EU Vulnerability Database, if it has one
- `found` (true/false): False when CVEDB has no record of that ID
- `known_exploited` (true/false): True when CISA lists it as known to be exploited in the wild (KEV)
- `proposed_action` (text): CISA's advice for known exploited vulnerabilities
- `published_at` (text): When it was published (ISO 8601)
- `ransomware_campaign` (text): Known when CISA knows it to be used in ransomware campaigns
- `references` (list): Links to advisories, patches and write-ups
- `summary` (text): What the vulnerability is and what it affects

**Example output**

```json
{
  "affected_cpe_count": 1593,
  "affected_cpes": [
    "cpe:2.3:a:apache:log4j:2.0",
    "cpe:2.3:a:apache:log4j:2.0.1"
  ],
  "cve_id": "CVE-2021-44228",
  "cvss": 10.0,
  "cvss_v2": 9.3,
  "cvss_v3": 10.0,
  "cvss_v4": null,
  "cvss_version": 3.0,
  "epss": 0.99999,
  "epss_percentile": 1.0,
  "euvd_id": "EUVD-2021-34768",
  "found": true,
  "known_exploited": true,
  "proposed_action": "Apache Log4j2 contains a vulnerability where JNDI features do not protect against attacker-controlled JNDI-related endpoints, allowing for remote code execution.",
  "published_at": "2021-12-10T10:15:09Z",
  "ransomware_campaign": "Known",
  "references": [
    "http://packetstormsecurity.com/files/165225/Apache-Log4j2-2.14.1-Remote-Code-Execution.html",
    "http://packetstormsecurity.com/files/165260/VMware-Security-Advisory-2021-0028.html"
  ],
  "summary": "Apache Log4j2 2.0-beta9 through 2.15.0 (excluding security releases 2.12.2, 2.12.3, and 2.3.1) JNDI features used in configuration, log messages, and parameters do not protect against attacker controlled LDAP and other JNDI related endpoints."
}
```

### List domain certificates

Free, no API key needed. List the TLS certificates issued for a domain, newest first, from Shodan's mirror of the Certificate Transparency logs: who issued each, when it expires and the names it covers. Use it to spot a certificate you didn't request, or one about to expire.

**Inputs**

- Domain (`domain`, text, required): The domain, like example.com. A link or email address works too.
- Only valid certificates (`valid_only`, true/false): Leave out certificates that have expired. Default: `false`.
- Maximum certificates (`limit`, number): How many certificates to return, up to 500. From 1 to 500. Default: `25`.

**Outputs**

- `certificates` (list): The certificates, newest first
- `count` (number): How many came back
- `domain` (text): The domain searched
- `has_more` (true/false): True when more matched than were returned
- `total` (number): How many matched in all

**Example output**

```json
{
  "certificates": [
    {
      "common_name": "shodan.io",
      "days_until_expiry": 76,
      "dns_names": [
        "shodan.io"
      ],
      "expired": false,
      "issuer": "YE2",
      "sha256": "ce6780ba7370ca76b5f24e88dcc1c5db214581bd0c21ec464c8e05274ebd7afa",
      "valid_from": "2026-09-17T11:21:42Z",
      "valid_until": "2026-12-16T11:21:41Z"
    }
  ],
  "count": 1,
  "domain": "shodan.io",
  "has_more": true,
  "total": 12
}
```

### List network alerts

List the account's network alerts, with what each monitors and which triggers are on. Needs an API key.

**Inputs**: None.

**Outputs**

- `alerts` (list): Every network alert on the account
- `count` (number): How many came back

**Example output**

```json
{
  "alerts": [
    {
      "alert_id": "OYPRB8IR9Z35AZPR",
      "created_at": "2021-01-27T03:44:22Z",
      "expires_at": null,
      "ip_count": 2,
      "name": "DNS Alert",
      "networks": [
        "8.8.8.8",
        "1.1.1.1"
      ],
      "notifier_ids": [
        "default"
      ],
      "triggers": [
        "new_service"
      ]
    }
  ],
  "count": 1
}
```

### List scans

List the scans this account has requested, with each one's status, 100 a page. Needs an API key.

**Inputs**

- Page (`page`, number): Which page of results, 100 a page. Page 1 is the first. From 1 to 10000. Default: `1`.

**Outputs**

- `count` (number): How many came back
- `has_more` (true/false): True when there are more on a later page
- `page` (number): This page's number
- `scans` (list): The scans on this page
- `total` (number): How many scans the account has

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "page": 1,
  "scans": [
    {
      "created_at": "2021-01-26T08:17:43Z",
      "done": true,
      "ip_count": 1,
      "scan_id": "Mo8W7itcWumiy9Ay",
      "status": "DONE"
    }
  ],
  "total": 19
}
```

### Look up DNS from around the world

Free, no API key needed. Look up a host name's DNS records from Shodan's Geonet servers in several cities around the world and compare the answers, to check that a DNS change has spread or that a site is served differently by region.

**Inputs**

- Host name (`hostname`, text, required): The host name to look up, like www.example.com.
- Record type (`record_type`, text): Which DNS records to look up. One of: `A` (A (IPv4 address)), `AAAA` (AAAA (IPv6 address)), `MX` (MX (mail server)), `NS` (NS (name server)), `TXT` (TXT (text)). Default: `A`.

**Outputs**

- `consistent` (true/false): True when every location got the same records
- `distinct_values` (list): Every value seen anywhere
- `hostname` (text): The name looked up
- `location_count` (number): How many locations looked it up
- `record_type` (text): The record type looked up, like A
- `results` (list): One result per location

**Example output**

```json
{
  "consistent": true,
  "distinct_values": [
    "104.18.12.238",
    "104.18.13.238"
  ],
  "hostname": "shodan.io",
  "location_count": 2,
  "record_type": "A",
  "results": [
    {
      "city": "Clifton",
      "country_code": "US",
      "values": [
        "104.18.12.238",
        "104.18.13.238"
      ]
    },
    {
      "city": "London",
      "country_code": "GB",
      "values": [
        "104.18.12.238",
        "104.18.13.238"
      ]
    }
  ]
}
```

### Look up IP address

Free, no API key needed. See what Shodan's weekly scan found at an IP address, from its InternetDB: open ports, host names, the software running (as CPE names), tags like cloud or vpn, and CVE IDs of known vulnerabilities. An address Shodan saw nothing at comes back with found false, not an error. Free for non-commercial use.

**Inputs**

- IP address (`ip_address`, text, required): The IPv4 or IPv6 address to look up.

**Outputs**

- `cpes` (list): The software Shodan identified, as CPE names, like cpe:/a:openbsd:openssh:7.4
- `found` (true/false): False when InternetDB has no record of the address: Shodan saw no open ports there
- `hostnames` (list): Host names for the address, from DNS and certificates
- `ip_address` (text): The address looked up
- `ports` (list): Open ports Shodan saw, like 22, 80 and 443
- `tags` (list): What kind of host it is, like cloud, vpn, self-signed or eol-os
- `vulnerability_ids` (list): CVE IDs of vulnerabilities the software may have, verified or not

**Example output**

```json
{
  "cpes": [
    "cpe:/a:cloudflare:cloudflare"
  ],
  "found": true,
  "hostnames": [
    "one.one.one.one"
  ],
  "ip_address": "1.1.1.1",
  "ports": [
    53,
    80,
    443,
    2052,
    2083,
    8080,
    8443
  ],
  "tags": [],
  "vulnerability_ids": []
}
```

### Ping from around the world

Free, no API key needed. Ping an IP address or host name from Shodan's Geonet servers in several cities around the world, to see whether it is up everywhere and how fast it answers from each place.

**Inputs**

- Host (`host`, text, required): An IP address or host name, like example.com.

**Outputs**

- `host` (text): The host pinged
- `location_count` (number): How many locations pinged it
- `reachable` (true/false): True when it answered from at least one location
- `reachable_from_count` (number): How many locations it answered
- `results` (list): One result per location

**Example output**

```json
{
  "host": "1.1.1.1",
  "location_count": 2,
  "reachable": true,
  "reachable_from_count": 2,
  "results": [
    {
      "average_ms": 2.27,
      "city": "Clifton",
      "country_code": "US",
      "ip_address": "1.1.1.1",
      "max_ms": 2.775,
      "min_ms": 1.406,
      "packets_received": 3,
      "packets_sent": 3,
      "reachable": true
    },
    {
      "average_ms": 1.886,
      "city": "Singapore",
      "country_code": "SG",
      "ip_address": "1.1.1.1",
      "max_ms": 2.723,
      "min_ms": 1.192,
      "packets_received": 3,
      "packets_sent": 3,
      "reachable": true
    }
  ]
}
```

### Request a scan

Ask Shodan to scan public IP addresses or networks now, rather than waiting for its regular crawl, for example after closing a port. Each IP address costs 1 scan credit. Needs an API key with a Membership or a paid plan. Check progress with Get scan status, then read the results with Get host details.

**Inputs**

- IP addresses or networks (`targets`, list, required): Public IP addresses, or networks in CIDR notation like 198.51.100.0/28, to scan: a list, or entries separated by commas or new lines. Each IP address costs 1 scan credit, so a /24 costs 256. Only scan addresses you are allowed to.

**Outputs**

- `ip_count` (number): How many IP addresses will be scanned
- `scan_credits_left` (number): Scan credits left this month
- `scan_id` (text): The scan's ID, for Get scan status
- `targets` (list): The addresses and networks sent

**Example output**

```json
{
  "ip_count": 1,
  "scan_credits_left": 99,
  "scan_id": "vwWO7P5N1rWF5jbh",
  "targets": [
    "1.1.1.1"
  ]
}
```

### Resolve hostnames

Look up the IP address of up to 100 host names at once. A name that doesn't resolve comes back with no address rather than stopping the rest. Needs an API key.

**Inputs**

- Host names (`hostnames`, list, required): Up to 100 host names, like example.com: a list from an earlier step, or names separated by commas or new lines.

**Outputs**

- `resolved_count` (number): How many resolved
- `results` (list): One result per host name, in the order given
- `unresolved_count` (number): How many did not

**Example output**

```json
{
  "resolved_count": 2,
  "results": [
    {
      "hostname": "google.com",
      "ip_address": "172.217.6.46"
    },
    {
      "hostname": "facebook.com",
      "ip_address": "157.240.22.35"
    }
  ],
  "unresolved_count": 0
}
```

### Reverse DNS lookup

Look up the host names of up to 100 IP addresses at once. An address with none comes back with an empty list rather than stopping the rest. Needs an API key.

**Inputs**

- IP addresses (`ip_addresses`, list, required): Up to 100 IP addresses: a list from an earlier step, or addresses separated by commas or new lines.

**Outputs**

- `found_count` (number): How many addresses had host names
- `results` (list): One result per address, in the order given

**Example output**

```json
{
  "found_count": 2,
  "results": [
    {
      "hostnames": [
        "dns.google"
      ],
      "ip_address": "8.8.8.8"
    },
    {
      "hostnames": [
        "one.one.one.one"
      ],
      "ip_address": "1.1.1.1"
    }
  ]
}
```

### Search hosts

Search Shodan for Internet-facing services, 100 a page, using the same queries as shodan.io: by product, port, country, organization, network or vulnerability. Optionally break the results down by country, port or another property. Needs an API key. A query with filters, or a page after the first, costs 1 query credit and needs a Membership.

**Inputs**

- Query (`query`, text, required): A Shodan search query, written as on shodan.io. Filters narrow it: port:22, country:DE, org:"Example Corp", product:nginx, net:198.51.100.0/24 or vuln:CVE-2021-44228. Filters need a Membership.
- Breakdowns (`facets`, text): Properties to break the results down by, separated by commas, each with an optional number of top values: country, org:10, port, product or vuln.
- Page (`page`, number): Which page of results, 100 a page. Every page after the first costs 1 query credit and needs a Membership. From 1 to 10000. Default: `1`.

**Outputs**

- `count` (number): How many came back
- `facets` (list): A breakdown of the results by each facet asked for
- `has_more` (true/false): True when there are more on a later page
- `matches` (list): Up to 100 services that match
- `page` (number): This page's number
- `query` (text): The query searched
- `total` (number): How many results match in all

**Example output**

```json
{
  "count": 1,
  "facets": [
    {
      "facet": "country",
      "values": [
        {
          "count": 7883733,
          "value": "US"
        }
      ]
    }
  ],
  "has_more": true,
  "matches": [
    {
      "asn": "AS7922",
      "banner": "HTTP/1.1 400 Bad Request\r\nServer: nginx\r\n",
      "city": "Denver",
      "collected_at": "2021-01-25T21:33:49Z",
      "country_code": "US",
      "country_name": "United States",
      "cpes": [
        "cpe:/a:igor_sysoev:nginx"
      ],
      "domains": [
        "webapplify.net"
      ],
      "hostnames": [
        "three.webapplify.net"
      ],
      "http_server": "nginx",
      "http_status": null,
      "http_title": "400 The plain HTTP request was sent to HTTPS port",
      "ip_address": "96.93.212.27",
      "isp": "Comcast Business",
      "module": "auto",
      "operating_system": null,
      "organization": "Comcast Business",
      "port": 443,
      "product": "nginx",
      "ssl_expired": null,
      "ssl_expires_at": null,
      "ssl_issuer": null,
      "ssl_subject": null,
      "tags": [],
      "transport": "tcp",
      "version": null,
      "vulnerabilities": []
    }
  ],
  "page": 1,
  "query": "product:nginx",
  "total": 23047224
}
```

### Search vulnerabilities

Free, no API key needed. Find vulnerabilities in Shodan's CVEDB by product (like log4j) or exact version (a CPE name), or the newest in anything. Narrow to ones known to be exploited, or to a publication date range, and sort by newest or by likelihood of exploitation (EPSS). Free for non-commercial use.

**Inputs**

- Product (`product`, text): A product name as CPE names spell it, lowercase with underscores for spaces, like log4j, openssh or http_server. Leave Product and CPE empty for the newest vulnerabilities in anything.
- CPE (`cpe`, text): One exact product version, as a CPE name like cpe:2.3:a:apache:log4j:2.14.1. Find product CPEs lists them, and a cpe:/ name from Look up IP address works too. Use this or Product, not both.
- Known exploited only (`known_exploited_only`, true/false): Only vulnerabilities CISA lists as known to be exploited in the wild (KEV). Default: `false`.
- Sort by (`sort_by`, text): Newest first, or most likely to be exploited first by EPSS score. One of: `newest` (Newest first), `epss` (Most likely to be exploited first (EPSS)). Default: `newest`.
- Published after (`published_after`, date): Only vulnerabilities published on or after this day.
- Published before (`published_before`, date): Only vulnerabilities published on or before this day.
- Maximum vulnerabilities (`limit`, number): How many vulnerabilities to return, up to 100. From 1 to 100. Default: `25`.
- Offset (`offset`, number): How many to skip. For the next page, pass the next_offset the previous page returned. At least 0. Default: `0`.

**Outputs**

- `count` (number): How many came back
- `has_more` (true/false): True when there are more on a later page
- `next_offset` (number): Pass as Offset to get the next page. Empty when there is no next page
- `vulnerabilities` (list): The vulnerabilities, newest first unless sorted by EPSS

**Example output**

```json
{
  "count": 1,
  "has_more": true,
  "next_offset": 1,
  "vulnerabilities": [
    {
      "affected_products": [
        {
          "product": "log4j",
          "vendor": "apache"
        }
      ],
      "cve_id": "CVE-2021-44228",
      "cvss": 10.0,
      "cvss_version": 3.0,
      "epss": 0.99999,
      "epss_percentile": 1.0,
      "euvd_id": "EUVD-2021-34768",
      "known_exploited": true,
      "proposed_action": "Apache Log4j2 contains a vulnerability where JNDI features do not protect against attacker-controlled JNDI-related endpoints, allowing for remote code execution.",
      "published_at": "2021-12-10T10:15:09Z",
      "ransomware_campaign": "Known",
      "references": [
        "http://packetstormsecurity.com/files/165225/Apache-Log4j2-2.14.1-Remote-Code-Execution.html",
        "http://packetstormsecurity.com/files/165260/VMware-Security-Advisory-2021-0028.html"
      ],
      "summary": "Apache Log4j2 2.0-beta9 through 2.15.0 (excluding security releases 2.12.2, 2.12.3, and 2.3.1) JNDI features used in configuration, log messages, and parameters do not protect against attacker controlled LDAP and other JNDI related endpoints."
    }
  ]
}
```

### Update alert networks

Replace the IP addresses and networks a network alert monitors with a new list. Its triggers stay as they are. Needs an API key.

**Inputs**

- Alert ID (`alert_id`, text, required): The alert's ID, from Create network alert or List network alerts.
- IP addresses or networks (`networks`, list, required): The IP addresses, or networks in CIDR notation like 198.51.100.0/24, to monitor: a list, or entries separated by commas or new lines. A Membership monitors up to 16 IP addresses.

**Outputs**

- `alert_id` (text): The alert's ID
- `created_at` (text): When it was created (ISO 8601)
- `expires_at` (text): When it stops monitoring (ISO 8601); empty for never
- `ip_count` (number): How many IP addresses that is
- `name` (text): The alert's name
- `networks` (list): The addresses and networks it monitors
- `notifier_ids` (list): Where notifications go; default is the account's email
- `triggers` (list): The triggers turned on, like new_service

**Example output**

```json
{
  "alert_id": "OYPRB8IR9Z35AZPR",
  "created_at": "2021-01-27T03:44:22Z",
  "expires_at": null,
  "ip_count": 2,
  "name": "DNS Alert",
  "networks": [
    "8.8.8.8",
    "1.1.1.1"
  ],
  "notifier_ids": [
    "default"
  ],
  "triggers": [
    "new_service"
  ]
}
```