Shodan

Community Platform

runZero integrates with Shodan by importing data from the Shodan API. This integration allows you to sync data about your externally-facing assets and services from Shodan to provide better visibility of your internet footprint and cyber hygiene.

Getting started

To set up the Shodan integration, you’ll need to:

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

Requirements

Before you can set up the Shodan integration:

  • Verify that you have runZero Enterprise.
  • Make sure you have a Shodan account with the correct license to meet your needs.

Step 1: Add the Shodan credential to runZero

  1. Go to the new credential page in runZero. Provide a name for the credential, like Shodan.
  2. Choose Shodan Search API key from the list of credential types.
  3. Provide your Shodan Search API key - To view your API key, go to your Account page in the Shodan portal. Your API key is available on that page and can be reset if needed.
  4. If you want other organizations to be able to use this credential, select the Make this a global credential option. Otherwise, you can configure access on a per-organization basis.
  5. Save the credential. You’re now ready to set up and activate the connection to bring in data from Shodan.

Step 2: Choose how to configure the Shodan integration

The Shodan integration can be configured as either a scan probe or a connector task. Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync.

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

After you add your Shodan credential, you’ll need to 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 requires you to specify a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new Shodan-only assets are created.

  1. Activate a connection to Shodan. You can access all available third-party connections from the integrations page, your inventory, or the tasks page.
  2. Choose the credential you added earlier. If you don’t see the credential listed, make sure the credential has access to the organization you are currently in.
  3. You can choose whether to specify a Shodan search using Shodan’s search syntax, or to have runZero generate a search for all of the public IP addresses of live assets.
  4. Enter a name for the task, like Shodan sync.
  5. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start at the date and time you have set.
  6. Under Task configuration, choose the site you want to add your assets to.
  7. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the Exclude unknown assets toggle to Yes. By default, the integration will include assets that have not been scanned by runZero.
  8. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the tasks page to see when the next sync will occur.

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

  1. Create a new scan task or select a future or recurring scan task from your Tasks page.
  2. Add or update the scan parameters based on any additional requirements.
  3. On the Probes and SNMP tab, choose which additional probes to include, set the Shodan toggle to Yes, and change any of the default options if needed. As with running the integration as a connector task, you can choose to specify a Shodan search string directly, or choose assets mode to have runZero generate a search query to look for all public IP addresses of live assets.
  4. On the Credentials tab, set the Shodan toggle for the credential you wish to use to Yes.
  5. Click Initialize scan to save the scan task and have it run immediately or at the scheduled time.

Step 4: View Shodan assets and services

After a successful sync, you can go to your inventory to view your Shodan assets. These assets will have a Shodan icon listed in the Source column.

The Shodan integration gathers details about services in addition to enriching asset inventory data. Go to Inventory > Services to view the service data provided by Shodan.

To filter by Shodan assets or services, consider running the following queries:

Click into each asset or service to see its individual attributes. runZero will show you the attributes returned by the Shodan Search API.

Troubleshooting

If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting.

Why is the Shodan integration unable to connect?

  1. Are you getting any data from the Shodan integration?
    • Make sure to query the inventory rather than look at the task details to review all the data available from this integration.
    • In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console.
  2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the intergration, it may not work correctly. Please review this documentation and follow the steps exactly.
  3. If the Shodan integration is unable to connect be sure to check the task log for errors. Some 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