1. Censys
  2. Censys Search
  3. Getting Started with Censys Search 2.0

Other Articles In This Section

In this article:

Search 2.0 API Quick Start

  • Updated

The quickest way to get started with the Censys Search 2.0 API is to visit our API docs, where you can try out all of the API calls right from the page.

API page showing the 'try it out' feature in action

This tutorial introduces key concepts and walks you through select examples of the API’s core functionality.

Connecting to the API

Search API endpoints are hosted at https://search.censys.io/api/

Authentication

Every call to the API requires authentication with HTTP basic auth using the API ID and secret shown on the My Account page.

Account page showing location of API ID and secret

This page also lists the rate limits that apply to your account.

v2 Responses

Every v2 endpoint response includes:

  1. Status

  2. Result

Example Response

The example below shows a response from the host aggregate endpoint. The response contains the HTTP status and the result. In the result, two fields echo the request, and the actual breakdown of TLS version usage.

{
  "code": 200, // Status
  "status": "OK", // Status
  "result": {
    "query": "services.tls: *",  // Used to select hosts for evaluation
    "field": "services.tls.version_selected", // The host field whose values are become the buckets
    "total": 239226493,   // Total number of hosts whose TLS values were tallied
    "buckets": [
      {
        "key": "TLSv1_2",
        "count": 108934487
      },
      {
        "key": "TLSv1_1",
        "count": 690044
      },
      {
        "key": "TLSv1_0",
        "count": 4855982
      },
      {
        "key": "SSLv3",
        "count": 92406
      }
    ],
    "total_omitted": 0, // The number of hosts omitted from the aggregation
    "potential_deviation": 0
  }
}

Host Endpoints

Hosts are identified by an IP address. Virtual hosts are identified by an IP address and name, joined by a plus sign (+).

You can use the API to search for hosts, compare hosts, view a single host in its current state or at a historical point in time, retrieve a chronology of host events, obtain a list of current names the host responded to in scan, and more.

The endpoints introduced below highlight the use and usefulness of the API, but are not exhaustive by any means.

A sampling of endpoints that take the HTTP GET method:

  • Search (/v2/hosts/search) — Search for hosts using the Censys Search Language.

  • Aggregate (/v2/hosts/aggregate) — Generate a report about the frequency of values seen for a specified field across all hosts matching a search.

  • View (v2/hosts/{id}) — View a host as it is known to Censys currently or at a historical point in time.

  • Diff (v2/hosts/{ip}/diff) — List the transformations that would turn one host into another.

  • Events (/v2/hosts/{id}/events) — List events documenting observed changes in the host’s data over time.

  • Names (/v2/hosts/{id}/names) — List the names that the host responded to during a scan.

Search Hosts

Search hosts by submitting a query written in the Censys Search Language. This endpoint returns a paginated result with a preview of the hosts whose attributes match the submitted query.

Host Fields Returned in Result

  • ip - The IP address of the host

  • name - The name of the host (if present)

  • location - An object containing fields related to the host’s geographical location

  • autonomous_system - An object containing fields related to the autonomous system that the host is reachable at

  • last_updated_at - A time stamp of the representation of the host as it was known to Censys when it was indexed for searching

Service Fields Returned in Result

These fields are present in a services array, which provides a preview of every service on the matching host, and in a matched_services array, which provides the same preview of only the services that matched some part of the provided search criteria:

  • port - The port number that the service is running on

  • service_name - The name of the service. Usually an L7 protocol

  • extended_service_name - The name of the service, including the TLS indicator, if the service completed a TLS handshake when scanned

  • transport_protocol - The name of the L4 protocol used to reach the service on.

Full details about the matching hosts must be fetched individually using the View endpoint.

Method and Path

GET /v2/hosts/search

URL Parameters

None

Query Parameters

Query parameters should be added to the path after a leading question mark (?), separated by an ampersand (&).

Parameter Required? Type Description Example

q

optional

string

The query to be executed, written in the Censys Search Language

q=services.http.response.headers.server: nginx

per_page

optional

integer

The number of results to be returned (max: 100, default: 50)

per_page=1

cursor

optional

string

The base-64-encoded string of the next or prev page cursor returned in the API response

cursor=eyJBZnRlciI6WyIxLjAuMTAzLjkiLCJcdTAwM2NuaWxcdTAwM2UiXSwiUmV2ZXJzZSI6ZmFsc2UsIlNlZWQiOjB9

Example Search Request

Search for (the next page of) hosts with an HTTP service reporting "nginx" in the server header.

GET \https://search.censys.io/api/v2/hosts/search?q=services.http.response.headers.server%3A%20nginx&per_page=1&cursor=eyJBZnRlciI6WyIxLjAuMTAzLjkiLCJcdTAwM2NuaWxcdTAwM2UiXSwiUmV2ZXJzZSI6ZmFsc2UsIlNlZWQiOjB9=

Example Success Response

The search executed successfully and found 19,788,926 hosts matching the query. One result is printed out, as specified by the per_page parameter.

{
  "code": 200,
  "status": "OK",
  "result": {
    "query": "services.http.response.headers.server: nginx",
    "total": 19788926,
    "duration": 103,
    "hits": [
      {
        "ip": "1.0.112.130",
        "services": [
          {
            "port": 5006,
            "service_name": "HTTP",
            "certificate": "760daa3d7a9bdd8d18b552300537cf8fadf72ba59196154bf902c3e3ab5d1e94",
            "transport_protocol": "TCP"
          },
          {
            "port": 49924,
            "service_name": "HTTP",
            "certificate": "760daa3d7a9bdd8d18b552300537cf8fadf72ba59196154bf902c3e3ab5d1e94",
            "transport_protocol": "TCP"
          },
          {
            "port": 58355,
            "service_name": "HTTP",
            "transport_protocol": "TCP"
          },
          {
            "port": 58357,
            "service_name": "HTTP",
            "transport_protocol": "TCP"
          }
        ],
        "location": {
          "continent": "Asia",
          "country": "Japan",
          "country_code": "JP",
          "city": "Shimonoseki",
          "postal_code": "750-0011",
          "timezone": "Asia/Tokyo",
          "province": "Yamaguchi",
          "coordinates": {
            "latitude": 33.9564,
            "longitude": 130.939
          },
          "registered_country": "Japan",
          "registered_country_code": "JP"
        },
        "autonomous_system": {
          "asn": 18144,
          "description": "AS-ENECOM Energia Communications,Inc.",
          "bgp_prefix": "1.0.64.0/18",
          "name": "AS-ENECOM Energia Communications,Inc.",
          "country_code": "JP"
        },
        "last_updated_at": "2022-11-07T12:37:29.030Z",
        "dns": {
          "reverse_dns": {
            "names": [
              "130.112.0.1.megaegg.ne.jp"
            ]
          }
        },
        "matched_services": [
          {
            "port": 58355,
            "service_name": "HTTP",
            "transport_protocol": "TCP"
          },
          {
            "port": 58357,
            "service_name": "HTTP",
            "transport_protocol": "TCP"
          }
        ]
      }
    ],
    "links": {
      "next": "eyJBZnRlciI6WyIxLjAuMTEyLjEzMCIsIlx1MDAzY25pbFx1MDAzZSJdLCJSZXZlcnNlIjpmYWxzZSwiU2VlZCI6MH0=",
      "prev": "eyJBZnRlciI6WyIxLjAuMTEyLjEzMCIsIlx1MDAzY25pbFx1MDAzZSJdLCJSZXZlcnNlIjp0cnVlLCJTZWVkIjowfQ=="
    }
  }
}

View a Host

View a host as it is known to Censys now or at a historical point in time. Nanosecond precision (9 decimal places) is supported.

This endpoint is frequently used in conjunction with the Search endpoint, which returns a list of hosts that match a query.

Method and Path

GET /v2/hosts/{ip}

URL Parameters

Parameter Required? Type Description Example

id

required

string

The IP address of the host or the IP address/name of the virtual host

1.12.253.129, 1.12.253.120+example.com

Query Parameters

Query parameters should be added to the path after a leading question mark ?, separated by an ampersand (&).

Parameter Required? Type Description Example

at_time

optional

string

A historical timestamp formatted according to RFC-3339

at_time=2021-10-27T04:32:35.015Z

Example View Request

View host 160.13.89.64 as it was known to Censys on October 10, 2022 at 11:19:00.000 PM UTC.

`GET https://search.censys.io/api/v2/hosts/160.13.89.64?at_time=2022-10-19T11%3A19%3A00.000Z `

Example Success Response

The host record was successfully retrieved, showing a single unknown service running on port 7070 using TLS 1.2 encryption and presenting a self-signed certificate.

{
  "code": 200,
  "status": "OK",
  "result": {
    "ip": "160.13.89.64",
    "services": [
      {
        "service_name": "UNKNOWN",
        "extended_service_name": "UNKNOWN",
        "port": 7070,
        "observed_at": "2022-10-09T16:36:02.609189134Z",
        "perspective_id": "PERSPECTIVE_NTT",
        "source_ip": "167.248.133.44",
        "_decoded": "banner_grab",
        "_encoding": {
          "banner": "DISPLAY_UTF8",
          "certificate": "DISPLAY_HEX"
        },
        "banner": "",
        "banner_grab": {
          "transport": "TCP"
        },
        "banner_hashes": [
          "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        ],
        "certificate": "7264f98ffc0f3f1e3cf1d8cc96c666b78ff1167224db00cb07445d914e3accca",
        "tls": {
          "version_selected": "TLSv1_2",
          "cipher_selected": "TLS_RSA_WITH_AES_128_GCM_SHA256",
          "certificates": {
            "_encoding": {
              "leaf_fp_sha_256": "DISPLAY_HEX"
            },
            "leaf_fp_sha_256": "7264f98ffc0f3f1e3cf1d8cc96c666b78ff1167224db00cb07445d914e3accca",
            "leaf_data": {
              "subject_dn": "CN=AnyDesk Client",
              "issuer_dn": "CN=AnyDesk Client",
              "pubkey_bit_size": 2048,
              "pubkey_algorithm": "RSA",
              "tbs_fingerprint": "ce2452106b7c354414f2cb146aa503614c21858e22589c47f52945532da8269d",
              "fingerprint": "7264f98ffc0f3f1e3cf1d8cc96c666b78ff1167224db00cb07445d914e3accca",
              "issuer": {
                "common_name": [
                  "AnyDesk Client"
                ]
              },
              "subject": {
                "common_name": [
                  "AnyDesk Client"
                ]
              },
              "public_key": {
                "key_algorithm": "RSA",
                "rsa": {
                  "_encoding": {
                    "modulus": "DISPLAY_BASE64",
                    "exponent": "DISPLAY_BASE64"
                  },
                  "modulus": "upGsJCnXOgesLlW0jDuolFwFDc0VCQp5xwX0PlXrT8PtZPOdHOQpAo+kBZRCHPY9eFGRHQeplj/0cEEb9YSzXjlrV2fztbBkz1v6J18PW69MgFMLiwAJzlcYIGPvZoztMtckftHeYt3LTJK9Um7ITWn0BLUCH0VYOdKRCstnUhzrjHvIbct5uaSfIxoFObGakrlbXTgP5G/+r9HP/Cd1+boiq7a+73UjI51uRIFF2RAPOsayG2cpcK5M3XJhpY/vBUABVXx+qzaqy0dgyxDC0vmJAYcLiUtL/BbFnbVMkoyyp92UoWxoT6EjkAO+NAyLVbpx7NnmwjRV9tBG6O+kjQ==",
                  "exponent": "AAEAAQ==",
                  "length": 256
                },
                "fingerprint": "9f45934d82bbc75787675d939a802e40631637f8d04c855ac0150a3d9026f379"
              },
              "signature": {
                "self_signed": true,
                "signature_algorithm": "SHA256-RSA"
              }
            }
          },
          "_encoding": {
            "ja3s": "DISPLAY_HEX"
          },
          "ja3s": "ccd5709d4a9027ec272e98b9924c36f7"
        },
        "transport_fingerprint": {
          "raw": "65535,128,true,MNWNNS,1414,false,false"
        },
        "transport_protocol": "TCP",
        "truncated": false
      }
    ],
    "location": {
      "continent": "Asia",
      "country": "Japan",
      "country_code": "JP",
      "city": "Shibuya",
      "postal_code": "150-6011",
      "timezone": "Asia/Tokyo",
      "province": "Tokyo",
      "coordinates": {
        "latitude": 35.6654,
        "longitude": 139.6977
      },
      "registered_country": "Japan",
      "registered_country_code": "JP"
    },
    "location_updated_at": "2022-10-09T16:36:05.839715Z",
    "autonomous_system": {
      "asn": 2497,
      "description": "IIJ Internet Initiative Japan Inc.",
      "bgp_prefix": "160.13.0.0/16",
      "name": "IIJ Internet Initiative Japan Inc.",
      "country_code": "JP"
    },
    "autonomous_system_updated_at": "2022-10-09T16:36:05.839494Z",
    "dns": {},
    "last_updated_at": "2022-10-09T16:36:05.857Z"
  }
}

Certificates

Certificates are identified by a SHA-256 digest of their content (referred to as a fingerprint or fp). Search for and view certificates using v1 endpoints. Tag, comment on, and obtain a list of hosts presenting a certificate on v2 endpoints.

The endpoints introduced below highlight the use and usefulness of the API, but are not exhaustive by any means.

These endpoints use a mixture of methods (POST, GET) and paths (v1/v2):

  • "Hosts by Cert" (v2/certificates/{fp}/hosts) — Lists the hosts that are currently presenting a certificate.

  • Search (v1/search/certificates) — Search for hosts using the Censys Search Language.

  • Report (v1/report/certificates) — Generate a report about the values for a specified field across all certs matching a search.

  • View (v1/view/certificates/{fp}) — View a host as it is known to Censys currently or at a historical point in time.

List Hosts Presenting a Certificate

See a list of hosts that are currently presenting a certificate during a TLS handshake.

Method and Path

GET /v2/certificates/{fp}/hosts

URL Parameters

Parameter Required? Type Description Example

fp

required

string

The SHA-256 fingerprint of the cert

fce621c0dc1c666d03d660472f636ce91e66e96460545f0da7eb1a24873e2f70

Query Parameters

None.

Example View Hosts by Cert Request

Return of a lists of hosts presenting certificate 6acc71db36da0cce367d80dafd9f6b1a679a9df9f32e7ab0be795fa5ee153e01.

GET /v2/certificates/6acc71db36da0cce367d80dafd9f6b1a679a9df9f32e7ab0be795fa5ee153e01/hosts

Example Response

The one host, identified by its IP address, that is presenting the certificate and the time that it was presented.

{
  "code": 200,
  "status": "OK",
  "result": {
    "fingerprint": "6acc71db36da0cce367d80dafd9f6b1a679a9df9f32e7ab0be795fa5ee153e01",
    "hosts": [
      {
        "observed_at": "2021-11-02T09:43:48.446082119Z",
        "ip": "52.14.77.60"
      }
    ],
    "links": {
      "next": ""
    }
  }
}

Search Certificates

Search certificates by submitting a query written in the legacy query syntax. This endpoint returns a paginated result with the certificate fields specified in the search request.

Method and URL

POST v1/search/certificates

URL Parameters

None

Query Parameters

None

Data Parameters

Data parameters should be posted as a JSON request document.

Parameter Required? Type Description Example

query

required

string

The query to be executed

"query": "parsed.names: censys.io and parsed.signature.self_signed: true and metadata.seen_in_scan: true"

page

optional

integer

The page of the result set to be returned

"page": 1

fields

optional

array[string]

The fields you would like returned in the result with keys written out in "dot notation"

"fields": [ "parsed.fingerprint_sha256" ]

flatten

optional

boolean

Format of the returned results. Default is flattened.

"flatten: "true"

Example Search Request

Return SHA-256 fingerprints of self-signed certificates whose names section contains "censys.io" that have ever been seen during a Censys scan

POST /v1/search/certificates

Body

{
  "query": "parsed.names: censys.io and parsed.signature.self_signed: true and metadata.seen_in_scan: true",
  "page": 1,
  "fields": [
    "parsed.fingerprint_sha256"
  ],
  "flatten": true
}

Example Response

The response includes the first of 50 pages of the fingerprints whose certificates matched the query.

{
  "status": "ok",
  "metadata": {
    "query": "parsed.names: censys.io and parsed.signature.self_signed: true and metadata.seen_in_scan: true",
    "count": 4974,
    "backend_time": 37,
    "page": 1,
    "pages": 50
  },
  "results": [
    {
      "parsed.fingerprint_sha256": "6acc71db36da0cce367d80dafd9f6b1a679a9df9f32e7ab0be795fa5ee153e01"
    },
    {
      "parsed.fingerprint_sha256": "983efe28bf271a8cc5c482f92a762146dedbbcbaec76f11558c6cee2aeb3954b"
    },
    {
      "parsed.fingerprint_sha256": "e0dd3fb5cf70c3efac9fbbf5f05d2726e90d18193ed7e2a099dde2f9a906ea87"
    },
...
  ]
}

View a Certificate

View individual certificate records, which include the raw bytes, parsed fields, certificate transparency data, browser trust, and metadata about Censys’s discovery of the certificate and maintenance of its record.

Method and URL

GET v1/view/certificates/{fp}

URL Parameters

Parameter Required? Type Description Example

fp

required

string

The SHA-256 fingerprint of the cert

fce621c0dc1c666d03d660472f636ce91e66e96460545f0da7eb1a24873e2f70

Query Parameters

None

Example View Request

View the Censys record of the certificate fce621c0dc1c666d03d660472f636ce91e66e96460545f0da7eb1a24873e2f70.

GET https://search.censys.io/api/v1/view/certificates/fce621c0dc1c666d03d660472f636ce91e66e96460545f0da7eb1a24873e2f70

Example Response

The certificate record was successfully retrieved.

{
  "validation_timestamp": "2015-10-07T01:18:48+00:00",
  "updated_at": "2015-10-06T20:18:50",
  "raw": "MIIDQ\...G9rw=",
  "validation.nss.valid": false,
  "parsed": {
    "fingerprint_sha1": "3704a663ed5db89f85c5377852d678b299389775",
    "subject_dn": "CN=ns1.google.com, emailAddress=ssl@ns1.google.com",
    "issuer": {
      "common_name": [
        "ns1.google.com"
      ]
    },
    "signature": {
      "self_signed": true,
      "valid": false,
      "value": "Leve...dvA==",
      "signature_algorithm": {
        "oid": "1.2.840.113549.1.1.11",
        "name": "SHA256WithRSA"
      }
    },
    "validity": {
      "start": "2015-09-10T06:49:19Z",
      "end": "2016-09-09T06:49:19Z"
    },
    "issuer_dn": "CN=ns1.google.com, emailAddress=ssl@ns1.google.com",
    "fingerprint_sha256":
20
"fce621c0dc1c666d03d660472f636ce91e66e96460545f0da7eb1a24873e2f70",
    "version": 3,
    "extensions": {
      "authority_key_id": "dc3e2e3f49b126782f2dd4444c3cb5970be85979",
      "basic_constraints": {
        "is_ca": false
      },
      "subject_key_id": "3D4uP0mxJngvLdRETDy1lwvoWXk=",
      "certificate_policies": [
      ]
    },
    "signature_algorithm": {
      "oid": "1.2.840.113549.1.1.11",
      "name": "SHA256WithRSA"
    },
    "serial_number": "1952809538",
    "fingerprint_md5": "37ec912bf30802fd4ab3592f8713ef6f",
    "subject_key_info": {
      "key_algorithm": {
        "oid": "",
        "name": "RSA"
      },
      "rsa_public_key": {
        "length": 2048,
        "modulus": "vYjm5...PfLw==",
        "exponent": 65537
      }
    },
    "subject": {
      "common_name": [
        "ns1.google.com"
      ]
    }
  },
}

Related articles

Comments

0 comments

Article is closed for comments.