Shodan

View as Markdown

Community Platform

runZero pulls your externally facing assets and services from Shodan through the Shodan API for better visibility of your internet footprint and cyber hygiene.

Getting started

To set up the Shodan integration:

  1. Add your Shodan API key to runZero.
  2. Choose whether to run the integration as a scan probe or a connector task.
  3. Activate the integration to sync your data into runZero.

Requirements

  • A Shodan account with a license that fits your needs.

Step 1: Add the Shodan credential to runZero

  1. Go to the new credential page in runZero and name the credential, for example Shodan.
  2. Choose Shodan Search API key from the list of credential types.
  3. Enter your Shodan Search API key. The key is on the Account page of the Shodan portal, where you can also reset it.
  4. To share this credential with other organizations, select Make this a global credential. Otherwise, you can grant access per organization.
  5. Save the credential.

Step 2: Choose how to configure the Shodan integration

You can run the Shodan integration as a scan probe or a connector task. A scan probe gathers Shodan data during a scan task. A connector task runs on its own, from the cloud or from one of your Explorers, and performs only the integration sync.

Step 3: Set up and activate the Shodan integration to sync data

With the credential saved, set up a connection or a scan probe to sync your data from Shodan.

Step 3a: Configure the Shodan integration as a connector task

A connection needs a schedule and a site. The schedule sets when the sync runs, and the site is where runZero creates any new Shodan-only assets.

  1. Activate a connection to Shodan. You can also reach every third-party connection from the integrations page, your inventory, or the tasks page.
  2. Choose the credential you added earlier. If it isn’t listed, check that it has access to your current organization.
  3. Either enter a Shodan search in Shodan’s search syntax, or let runZero generate a search for the public IP addresses of all live assets.
  4. Optionally, use the “Ignore Shodan tags” input to enter a comma-separated list of tags to exclude from Shodan assets.
  5. Enter a name for the task, like Shodan sync.
  6. Schedule the sync to run once or on a recurring schedule, starting at the date and time you set.
  7. Under Task configuration, choose the site for your assets.
  8. To leave out assets runZero hasn’t scanned, switch the Exclude unknown assets toggle to Yes. The import includes them by default.
  9. Activate the connection. The sync runs on your schedule, and the tasks page shows when the next sync will run.

Step 3b: Configure the Shodan integration as a scan probe

  1. Create a new scan task, or pick a future or recurring one from your Tasks page.
  2. Add or update the scan parameters as needed.
  3. On the Probes and SNMP tab, choose any other probes to include, set the Shodan toggle to Yes, and adjust the default options if needed. As with a connector task, you can enter a Shodan search string directly or choose assets mode to have runZero generate a search for the public IP addresses of all live assets.
  4. On the Credentials tab, set the Shodan toggle to Yes for the credential you want to use.
  5. Click Initialize scan to save the task. It runs immediately or at its scheduled time.

Step 4: View Shodan assets and services

After a successful sync, your Shodan assets appear in your inventory with a Shodan icon in the Source column.

The integration also gathers service details. Go to Inventory > Services to view the service data from Shodan.

To filter by Shodan assets or services, run these queries:

Open an asset or service to see the attributes runZero pulled from the Shodan Search API.

Troubleshooting

If you’re having trouble with the integration, start with these questions and answers.

Why is the Shodan integration unable to connect?

  1. Check whether the Shodan integration is returning any data.
    • Query the inventory rather than the task details to review all the data available from this integration.
    • In some cases, an integration’s configuration limits how much data reaches the runZero console.
  2. Some integrations require specific actions that are easy to overlook. If you miss a step during setup, the integration may not work correctly. Review this page and follow the steps exactly.
  3. If the Shodan integration can’t connect, check the task log for errors. Common errors include:
    • 500: server error, unable to connect to the endpoint
    • 404: hitting an unknown endpoint on the server
    • 403: not authorized, likely a credential issue
Updated