---
title: Censys connector
description: Use the Censys connector to enrich hosts, web properties, and certificates, submit assets for rescanning, and run CensEye threat-hunting jobs using the Censys Platform API.
url: https://docs-v3-preview.elastic.dev/elastic/kibana/tree/main/reference/connectors-kibana/censys-action-type
products:
  - Kibana
applies_to:
  - Elastic Cloud Serverless: Preview
  - Elastic Stack: Planned
---

# Censys connector
The Censys connector communicates with the [Censys Platform API](https://docs.censys.com/reference/get-started) to enrich hosts, web properties, and certificates, submit assets for rescanning, and run CensEye threat-hunting jobs.
Every request issued by the connector is scoped to the configured Censys organization.

## Create connectors in Kibana

You can create connectors in **Stack Management > Connectors**.

### Connector configuration

Censys connectors have the following configuration properties:
<definitions>
  <definition term="API token">
    A Censys Platform personal access token for authentication.
  </definition>
  <definition term="Organization ID">
    The Censys organization ID.
  </definition>
</definitions>


## Test connectors

You can test connectors as you're creating or editing the connector in Kibana.

## Connector actions

The Censys connector has the following actions:
<definitions>
  <definition term="Get Host">
    Retrieve the full host record using its IP address. This is the credit-consuming deep-dive lookup.
    - **Host** (required): IPv4 or IPv6 address.
  </definition>
  <definition term="Get Host Enrichment">
    Retrieve a compact, SOC-optimized enrichment record for a host using its IP address. Returns a fixed subset of the latest-scan host data and is credit-free, making it suited to high-volume alert triage. Requires a Censys Core plan or higher.
    - **Host** (required): IPv4 or IPv6 address.
  </definition>
  <definition term="Get Web Property">
    Retrieve information about a web property using a specified hostname and port.
    - **Hostname** (required): The hostname, domain, or IP address (IPv4 or IPv6).
    - **Port** (required): Port number (1–65535).
  </definition>
  <definition term="Get Certificate">
    Retrieve information about a certificate by its SHA-256 fingerprint.
    - **Certificate** (required): 64-character SHA-256 hex string.
  </definition>
  <definition term="Get Host History">
    Retrieve the chronological scan timeline for a host over a time window.
    - **Host** (required): IPv4 or IPv6 address.
    - **Start Time** (required): RFC3339 timestamp for the start of the window (for example, `2025-01-01T00:00:00Z`).
    - **End Time** (required): RFC3339 timestamp for the end of the window. The end time must be later than the start time (for example, `2025-01-31T23:59:59Z`).
  </definition>
  <definition term="Rescan">
    Submit a host service or a web property for a fresh scan. Returns a scan ID.
    - **Type** (required): `service` to rescan a host service, or `webproperty` to rescan a web property.
    - For `service`:
      - **IP** (required): IPv4 or IPv6 address.
    - **Port** (required): port number (1–65535).
    - **Protocol** (required): application-layer protocol on the service (for example, `HTTP`, `SSH`, `TLS`).
    - **Transport Protocol** (required): one of `unknown`, `tcp`, `udp`, `icmp`, or `quic`.
    - For `webproperty`:
      - **Hostname** (required): hostname, domain, or IP address (IPv4 or IPv6).
    - **Port** (required): port number (1–65535).
  </definition>
  <definition term="Scan Status">
    Poll the status of a rescan submitted via Rescan.
    - **Scan ID** (required): The scan ID returned by Rescan.
  </definition>
  <definition term="CensEye Create Analysis Job">
    Submit a CensEye analysis job for a host, web property, or certificate. Set **Type** to the target kind and provide the matching identifier:
    - **Type** (required): `host`, `webproperty`, or `certificate`.
    - For `host`:
      - **Host** (required): IPv4 or IPv6 address.
    - For `webproperty`:
      - **Hostname** (required): hostname, domain, or IP address (IPv4 or IPv6).
    - **Port** (required): port number (1–65535).
    - For `certificate`:
      - **Certificate** (required): 64-character lowercase SHA-256 hex string.
  </definition>
  <definition term="CensEye Job Status">
    Poll the status of a CensEye job submitted via **CensEye Create Analysis Job**.
    - **Job ID** (required): The job ID returned by CensEye Create Analysis Job.
  </definition>
  <definition term="CensEye Job Result">
    Retrieve the results of a completed CensEye job.
    - **Job ID** (required): The job ID returned by **CensEye Create Analysis Job**.
  </definition>
</definitions>


## Workflow examples

Enrich an IP with the credit-free enrichment lookup, falling back to the full host record if the enrichment endpoint is unavailable:
```yaml
steps:
  - name: get_host_enrichment
    type: censys.getHostEnrichment
    connector-id: <connector-id>
    with:
      host: 8.8.8.8
    on-failure:
      continue: true

  - name: fallback_to_get_host
    type: if
    condition: '{{ steps.get_host_enrichment.error != blank }}'
    steps:
      - name: get_host
        type: censys.getHost
        connector-id: <connector-id>
        with:
          host: 8.8.8.8
```

Rescan a host service and re-fetch the host enrichment once the scan completes:
```yaml
steps:
  - name: submit_rescan
    type: censys.rescan
    connector-id: <connector-id>
    with:
      type: service
      ip: 8.8.8.8
      port: 443
      protocol: HTTP
      transportProtocol: tcp

  - name: wait_for_scan
    type: wait
    with:
      duration: 3s

  - name: check_scan_status
    type: censys.scanStatus
    connector-id: <connector-id>
    with:
      scanId: '{{ steps.submit_rescan.output.result.tracked_scan_id }}'

  - name: refresh_host
    type: censys.getHost
    connector-id: <connector-id>
    with:
      host: 8.8.8.8
```

Run a CensEye related-infrastructure job for a host and retrieve the pivots:
```yaml
steps:
  - name: create_censeye_job
    type: censys.censEyeCreateAnalysisJob
    connector-id: <connector-id>
    with:
      type: host
      host: 8.8.8.8

  - name: wait_for_job
    type: wait
    with:
      duration: 3s

  - name: check_job_status
    type: censys.censEyeJobStatus
    connector-id: <connector-id>
    with:
      jobId: '{{ steps.create_censeye_job.output.result.job_id }}'

  - name: get_job_results
    type: censys.censEyeJobResult
    connector-id: <connector-id>
    with:
      jobId: '{{ steps.create_censeye_job.output.result.job_id }}'
```


## Connector networking configuration

Use the [Action configuration settings](/elastic/kibana/tree/main/reference/configuration-reference/alerting-settings#action-settings) to customize connector networking configurations, such as proxies, certificates, or TLS settings.

## Get API credentials

To use the Censys connector you need a personal access token and organization ID. For more information, refer to [Get Started with Censys APIs](https://docs.censys.com/reference/get-started).
<note>
  If you belong to a Censys Starter or Enterprise organization, your admin must assign you the **API Access** role before you can use the API. Free users do not need this role.
</note>

1. Sign in to the [Censys Platform](https://platform.censys.io).
2. Click your **user icon** in the upper-right corner and select **API Access**.
3. Click **Create New Token**, enter a **Token Name** (and optional description), then click **Create**.
4. In the confirmation dialog, click **Copy to clipboard** and store the token securely. The token value is only shown once.
5. On the **Personal Access Tokens** page, ensure your organization account is selected. In the **Current Organization** box, click **Copy** to copy your **Organization ID**. Censys Starter, Search, and Enterprise organizations have an organization ID; Free accounts do not.
6. In Kibana, paste the token into the **API Token** field and the organization ID into the **Organization ID** field when configuring the connector.