Censys Integration with DefectDojo

Censys Integration with DefectDojo

Censys is an internet intelligence company whose platform continuously scans the public internet and records what it finds on each host: open ports, the services listening on them, certificates, and related metadata. Security teams use the Censys Platform to see their external exposure the way an outsider would, and to search for hosts by attributes such as IP range or autonomous system number (ASN). DefectDojo Pro connects to the Censys Platform global search API through an Upstream Connector that imports each host's exposed services as findings.

Censys Integration with DefectDojo

We connected Censys to DefectDojo because the most uncomfortable findings are the ones on hosts nobody thought were public. Censys sees our IP space from the outside, and the DefectDojo Pro connector turns that view into Records for each host and findings for each exposed service. Once those are in DefectDojo, an unexpected open service gets an owner, a severity, and an SLA like any other finding, instead of being something someone noticed once in a search console.

Why Censys Matters

Most vulnerability tools scan what you tell them about. Censys starts from what is actually reachable on the internet.

• It reports services on your address space whether or not they are in your inventory, which is how forgotten hosts and shadow IT get found.
• A search query scoped to your ASN or IP ranges turns a global dataset into a view of your own perimeter.
• Exposed services are often the first thing an attacker enumerates. Knowing about them before anyone else does is the point.
• On Censys Core (enterprise) tiers, per-host CVE and risk data is available, which adds vulnerability context to exposure data.

Advantages of This Integration

What running Censys data through DefectDojo Pro adds:

• External exposure as tracked work. Each exposed service becomes a finding that can be assigned, commented on, risk-accepted, or pushed to Jira or another Downstream Connector.
• One Record per host. Hosts discovered by your search query appear as Records you can map to the Assets that own them.
• Change over time. Each Sync runs a reimport against the existing Test, so newly exposed services appear as new findings and services that are no longer reported are marked inactive.
• Severity control. A Minimum Severity setting keeps lower-severity findings out of DefectDojo if your team only wants the significant ones.
• Context next to internal scans. When a host's Record maps to an Asset that also receives infrastructure scanner results, the outside view and the inside view sit together.

How This Integration Works

The Censys connector is a DefectDojo Pro feature, configured under Connect > Upstream.

1. Check your Censys tier. You need a Censys Platform account with API access. Search API access requires an organization, so a Starter tier or higher is needed; free-tier tokens have no organization ID and cannot use the search API. Per-host CVE and risk data is available only on Censys Core tiers, so on lower tiers findings represent exposed services rather than vulnerabilities.

2. Collect credentials. In the Censys Platform Console, create a Personal Access Token. Note your Organization ID, shown on the same settings page under "Current Organization".

3. Configure the connector. Enter https://api.platform.censys.io as the Location, the Personal Access Token as the API Key, and your Organization ID.

4. Scope the search. Enter a Search Query that limits the import to your own assets, for example a query on your autonomous system number (host.autonomous_system.asn) or on your address range (host.ip with a CIDR block). This is the most important setting on the connector: it decides which hosts DefectDojo treats as yours.

5. Filter and sync. Optionally set a Minimum Severity. Discover creates a Record for each matching host. Map Records to Assets (or enable Auto-Map), and Sync imports each host's exposed services as findings into a Test in the Global Connectors Engagement on the mapped Asset.

Data Granularity: What Gets Imported

The connector documentation describes the import at the level of hosts and services rather than individual fields.

If a value lands in the wrong DefectDojo field for your workflow, Connector Field Mappings can rearrange, combine, or normalize what the connector sends for this scan type.

Use Cases

Finding forgotten hosts: A team scopes the connector to its ASN and finds Records for hosts that are not in any internal inventory. Each one either gets mapped to an owning Asset or becomes a decommissioning task.

Watching for new exposure: Because Sync compares each run against the previous one, a service that suddenly appears on a public host shows up as a new finding. Teams can route new findings on critical Assets to a ticketing system for fast review.

Mergers and new address space: After acquiring a company, a team adds a second connector configuration scoped to the acquired company's IP ranges. Its hosts arrive as their own Records, which makes it easy to see the acquired perimeter separately before folding it into existing Assets.

Pairing with internal scanning: A host that shows an exposed service in Censys and a vulnerable package in an internal infrastructure scan is a clear priority. Mapping both to the same Asset puts that combination in one place.

Operational Tips

• Write the Search Query narrowly. A query that matches hosts you don't own will create Records and findings for someone else's infrastructure.
• Confirm your tier before setup. Free-tier tokens cannot use the search API, and without Core tier data your findings describe exposure rather than CVEs.
• Expect services on lower tiers to be findings without vulnerability IDs. Set SLAs and severity filters with that in mind.
• Map several hosts to one Asset when they front the same application or environment, so ownership and reporting follow the service rather than the IP address.
• Risk-accept services that are meant to be public, such as a web server on 443, with an expiration date so they come back for periodic review.
• Turn on the Connector Health Warning notification. If the token expires or the query stops returning hosts, you will hear about it rather than discovering an empty Test later.