Shodan Integration with DefectDojo

Shodan Integration with DefectDojo

Shodan is a search engine for internet-connected devices. It continuously scans public IP space, records the banners and metadata that exposed services return, and makes the results searchable by hostname, network range, organization, product, and many other filters. Where it can, Shodan also associates known vulnerabilities (CVEs) with a host's services. It offers a web interface and a REST API, and the API is what the DefectDojo Pro Shodan connector uses.

Shodan Integration with DefectDojo

We connected Shodan to DefectDojo Pro because it shows us what the internet sees, which is not always what our own inventory says. The connector runs a Shodan search query that we scope to our own hosts, creates a Record for each matching host, and imports the CVEs Shodan has observed on that host's exposed services as findings. Once those Records map to Assets, an outdated web server on a forgotten IP shows up next to the rest of the findings for the team that owns it, with an SLA clock and a status history, and it drops out on a later sync once the service is fixed or taken offline.

Why Shodan Matters

Attackers look at your perimeter from the outside, often with exactly this kind of data.

• Shodan sees services that are reachable from the internet, including ones that were never registered in an internal inventory or scanner scope.
• It indexes by network range, hostname, and organization, so a single query can cover an entire external footprint.
• It reports CVEs per host, which turns a list of open ports into a list of specific problems.
• Shodan states that many of its CVEs are inferred from the software and version a service advertises rather than confirmed by testing, and that inferred results can include false positives. They are leads that need triage, which is where a vulnerability management workflow helps.

Advantages of This Integration

What we gained by syncing Shodan into DefectDojo Pro:

• External exposure on a schedule. Discover and Sync run every 6, 12, or 24 hours, so new exposure reaches DefectDojo without anyone running searches and exporting results.
• Scoped to what we own. The Search Query field restricts the import to our hosts, for example by hostname, network range, or organization name.
• One Record per host. Each matching host becomes a Record that maps to a DefectDojo Asset, either one per host or several hosts consolidated into one Asset.
• Prioritization context. Severity is derived from the CVSS score, with EPSS and CISA KEV context included where available, so a known exploited CVE on an exposed service stands out.
• A severity floor. The optional Minimum Severity setting keeps low-severity CVEs out until the team is ready for them.
• Lifecycle on every sync. Each Sync compares Shodan's latest data with existing findings. New CVEs are added, and findings that no longer appear are marked inactive.
• Triage tools for inferred findings. False positive marking, risk acceptance, notes, and assignment all apply, which matters for CVEs inferred from version banners.

How This Integration Works

Shodan is a DefectDojo Pro Upstream Connector. Connectors are not part of Community Edition, and this page covers only the connector.

1. Get an API key. Your Shodan API key is on your Shodan Account page. Host search with vulnerability data requires a Shodan membership or a paid API plan. The free tier cannot page through search results.

2. Add the connector. In the Pro UI, open Connect > Upstream, find Shodan under Available Connectors, and click Add Configuration. Enter:

• Location: https://api.shodan.io
• API Key: your Shodan API key.
• Search Query: a Shodan query scoped to your organization's assets, such as hostname:example.com, net:203.0.113.0/24, or org:"Example Inc". Only hosts matching the query are imported.
• Minimum Severity (optional): a floor below which findings are not imported.
• Label: a name that tells this configuration apart from others.

Then set the Discovery and Synchronization schedules, choose whether to enable Auto-Mapping, and submit.

3. Discover hosts. Discover runs the query and creates a Record for each matching host. With Auto-Mapping on, each Record is matched to an Asset with the same name or a new Asset is created. With it off, Records wait in the Unmapped list.

4. Sync CVEs. For every mapped Record, Sync imports the host's CVEs into an Engagement named Global Connectors under the mapped Asset, with a separate Test for this connector. Later syncs update that Test.

Data Granularity: What Gets Imported

The connector documentation describes the structure of what is imported rather than a field-by-field mapping, so the table sticks to what is documented.

If you need a different Title or a composite unique identifier, Connector Field Mappings under Connect > Field Mappings can rearrange values the connector already sends. They cannot add data the connector does not send.

Use Cases

Watching the external footprint: A security team scopes the query to its registered network ranges. Any host Shodan sees with a known CVE becomes a finding on an Asset, so a test server someone exposed over a weekend is visible on Monday.

Checking that scanner scope is complete: Shodan Records that do not match any existing Asset point at hosts the internal scanners may not cover. Mapping them deliberately, instead of auto-creating Assets, turns the Unmapped list into a review queue.

Prioritizing perimeter patching: Findings that carry CISA KEV context on internet-facing services go to the top of the queue, with SLAs that reflect their exposure.

Tracking subsidiaries or brands: Separate configurations with different Search Queries, such as one per domain, keep each brand's external exposure on its own Assets.

Operational Tips

• Keep the Search Query narrow and limited to infrastructure you own. Broad queries import hosts that are not yours and spend credits.
• Each page of search results consumes one Shodan query credit, so a query that matches many hosts uses more of your plan on every sync.
• Treat inferred CVEs as leads. Confirm the version on the host before assigning remediation, and mark false positives so they stay closed.
• Start with a Minimum Severity of High while the team works through the first import, then lower it.
• Use Ignored rather than Delete for host Records you do not want. Deleted Records return on the next Discover if they still match the query.
• Turn on the Connector Health Warning notification under Connections in your notification settings, so an expired plan or revoked key is reported instead of syncs quietly importing nothing.