Censys

Overview

The Censys integration connects the Praetorian Guard Platform (PGP) with Censys Search, importing internet-facing assets, host data, and certificate information into your attack surface inventory. Censys continuously scans the global IPv4 address space and popular ports to build a comprehensive map of internet-connected devices and services — PGP leverages this data to discover assets associated with your organization that may not be visible through internal tooling alone.

This integration is designed for organizations that want to enrich their attack surface with external intelligence from Censys. By combining Censys's internet-wide scanning data with PGP's continuous threat exposure management, you gain visibility into exposed hosts, services, and certificates that belong to your organization, including shadow IT and forgotten infrastructure that traditional asset inventories miss.

What the Integration Does

When connected, PGP performs a read-only import from the Censys Search API:

  • Hosts as Assets: Internet-facing hosts discovered by Censys that match your organization's seeds (domains, IP ranges, ASNs) are imported as PGP assets. Each host includes metadata such as IP address, open ports, running services, operating system, and last observed timestamp.
  • Certificates as Assets: TLS/SSL certificates associated with your domains are imported, including certificate details such as subject, issuer, validity period, SANs (Subject Alternative Names), and fingerprint. Expired or misconfigured certificates are flagged.
  • Services and Ports: For each discovered host, the running services (HTTP, HTTPS, SSH, FTP, etc.) and their port numbers are captured as metadata, providing a detailed picture of what is exposed on the internet.
  • Domain Discovery: Censys data is used to discover subdomains and related domains tied to your organization, which are imported as seeds to feed PGP's discovery pipeline.

    • Data flows one direction only — from Censys into PGP. The integration never writes back to Censys or modifies any data in the Censys platform.

    Prerequisites

    Before setting up the integration, you need a Censys Search API credential:

  • Create an account at [censys.io](https://censys.io) if you do not already have one
  • Log in and navigate to Account > API
  • Locate your API credentials:
  • API ID: Your unique API identifier
  • API Secret: Your API secret key
  • Ensure your Censys plan includes API access with sufficient query quota for your asset count

    • The API credentials provide read-only access to Censys Search data. No additional permissions configuration is required beyond having an active account with API access.

    Setup

  • Go to Integrations, then Attack Surface Management, then Censys in the Guard Platform
  • Enter your Censys API credentials in the setup form
  • Click Connect — PGP will validate your credentials by testing API access before saving
    • FieldDescriptionRequired
    API IDYour Censys API identifier from the Account > API pageYes
    API SecretYour Censys API secret keyYes

    If validation fails, verify that your API credentials are correct and that your Censys account has an active plan with API access.

    What Data Is Synced

    Hosts

    Internet-facing hosts matching your organization's seeds are imported with:

  • Asset name: IP address or hostname of the discovered host
  • Asset type: Host
  • Metadata: IP address, autonomous system (ASN), operating system, last observed timestamp, geographic location, and cloud provider (if applicable)

    • Services

    Services running on discovered hosts are captured as metadata:

    Censys DataPGP Mapping
    Open port + service nameService metadata on host asset
    HTTP response detailsService metadata (status code, headers, title)
    TLS configurationService metadata (protocol version, cipher suite)
    Banner dataService metadata on host asset

    Certificates

    TLS/SSL certificates associated with your domains are imported:

  • Certificate subject: The common name and organization from the certificate
  • SANs: All Subject Alternative Names listed on the certificate
  • Validity: Not-before and not-after dates
  • Issuer: The certificate authority that issued the certificate
  • Fingerprint: SHA-256 fingerprint for unique identification

    • Discovered Domains

    Subdomains and related domains found through Censys data are imported as seeds:

  • Domain name: The discovered subdomain or related domain
  • Source: Tagged as discovered via Censys
  • Discovery method: Reverse DNS, certificate SAN, or HTTP response analysis

    • API Endpoints Used

    EndpointMethodPurpose
    /api/v2/hosts/searchGETSearch for hosts matching organization seeds
    /api/v2/hosts/{ip}GETFetch detailed host data including services
    /api/v2/certificates/searchGETSearch for certificates matching organization domains
    /api/v2/certificates/{fingerprint}GETFetch detailed certificate metadata
    /api/v1/accountGETValidate API credentials and check quota

    Base URL: https://search.censys.io

    All requests are authenticated using HTTP Basic Auth with the API ID and API Secret over HTTPS.

    Troubleshooting

    IssueCauseFix
    Validation fails on connectAPI ID or API Secret is incorrectVerify credentials on the Censys Account > API page
    No assets appearingNo seeds configured in PGP that match Censys dataAdd your organization's domains, IP ranges, or ASNs as seeds in PGP before syncing
    Rate limit errorsQuery volume exceeds your Censys plan quotaUpgrade your Censys plan or reduce the number of seeds being queried
    Missing certificatesCertificates not yet indexed by CensysCensys indexes certificates as they are observed — recently deployed certificates may take time to appear
    Stale host dataCensys scan cycle has not yet refreshed the hostCensys rescans the internet periodically — host data reflects the most recent scan
    Partial resultsAPI pagination limits reachedPGP handles pagination automatically — if results are consistently partial, contact support

    Security and Data Handling

  • Read-only access: The integration only reads data from Censys Search. It never writes, modifies, or deletes any data in Censys.
  • Credential handling: Your Censys API ID and API Secret are stored as encrypted credentials within PGP and are never exposed in logs or the UI after initial entry.
  • Authentication: Credentials are transmitted via HTTP Basic Auth over HTTPS for every API call.
  • Data filtering: Imported assets and seeds pass through PGP standard filtering rules, allowing you to control which discovered hosts and certificates are included in your attack surface.