CEcensys
Threat Hunting
Adversary Investigation

Get fingerprint observation history for a host

Changed on

Retrieve fingerprint observations for a host.<br><br>Use this endpoint to see which TLS certificate chains an IP has presented, on which ports, and when, so you can spot infrastructure changes, pivot to related hosts, identify certificate swaps, or tie a host to attacker-controlled certificates.<br><br>You may optionally include a time range by using start_time and end_time. If you do not specify a time frame, this endpoint will search the historical dataset that is available to your account.<br><br>You must provide an observation_type and can optionally filter by port and observation_value.<br><br>To use this endpoint, your organization must have access to the Adversary Investigation module.

get/v3/threat-hunting/host/{ip}/observations/fingerprints

Request

  • Base URL
    https://api.platform.censys.io
  • URL
    https://api.platform.censys.io/v3/threat-hunting/host/{ip}/observations/fingerprints
  • Auth
    HTTP bearer

Path parameters

ipstring ip required

The IP address of a host.

Example:8.8.8.8

Query parameters

organization_idstring uuid required

The ID of a Censys organization to associate the request with. See the Getting Started docs for more information.

Example:11111111-2222-3333-4444-555555555555
start_timestring

Start of date range (RFC3339 format, e.g., 2024-01-01T00:00:00Z). If not specified, defaults to the maximum query window back from the end time.

Example:2024-01-01T00:00:00Z
end_timestring

End of date range (RFC3339 format, e.g., 2024-01-31T23:59:59Z). If not specified, defaults to now. Cannot be in the future.

Example:2024-01-31T23:59:59Z
page_sizeinteger

Number of results per page (max 100)

Example:50
page_tokenstring

Pagination token from previous response

portinteger

Filter by port number

Example:443
transport_protocol'tcp' | 'udp' | 'icmp' | 'quic'

Filter by transport protocol when supported by the selected observation_type

Example:tcp
observation_valuestring

Filter by observation value for the selected observation_type

observation_type'tls_presented_chain_fingerprint_sha256' required

Fingerprint observation type to query.

order_bystring[] nullable

Order observations by these fields. Multiple values can be provided (e.g., ['port DESC', 'observation_value ASC']). transport_protocol ordering is only supported for observation types whose timelines expose that field; see the endpoint description for details.

Headers

X-Organization-IDstring uuid

The ID of a Censys organization to associate the request with. See the Getting Started docs for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.

Example:11111111-2222-3333-4444-555555555555

Response

A list of observation ranges

Changes