### Example Host Search Request Source: https://docs.censys.com/docs/ls-api This example demonstrates a GET request to search for hosts with specific HTTP server headers and requests particular fields in the response. ```http GET https://search.censys.io/api/v2/hosts/search?q=services.http.response.headers.server%3A%20nginx%3F%2A&per_page=1&virtual_hosts=EXCLUDE&fields=services.port%2Cservices.service_name%2Cservices.software.uniform_resource_identifier ``` -------------------------------- ### Example Response for Hosts by Cert Source: https://docs.censys.com/docs/ls-api An example response detailing the hosts presenting a certificate, including their IP address and observation time. ```json { "code": 200, "status": "OK", "result": { "fingerprint": "6acc71db36da0cce367d80dafd9f6b1a679a9df9f32e7ab0be795fa5ee153e01", "hosts": [ { "observed_at": "2021-11-02T09:43:48.446082119Z", "ip": "52.14.77.60" } ], "links": { "next": "" } } } ``` -------------------------------- ### Example Host View Request Source: https://docs.censys.com/docs/ls-api This example demonstrates how to view a specific host's data at a particular point in time using the Censys API. ```http GET https://search.censys.io/api/v2/hosts/160.13.89.64?at_time=2022-10-19T11%3A19%3A00.000Z ``` -------------------------------- ### Certificate Data Tokenization with Regex Source: https://docs.censys.com/docs/censys-query-language Shows how to use regex for searching certificate data when the default tokenization is not suitable. This example matches certificates with common names starting with a specific prefix. ```censys-query-language cert.parsed.subject.common_name=~`^abcdefg-1234567` ``` -------------------------------- ### Field-Value Query Example Source: https://docs.censys.com/docs/censys-query-language Targets a specific field on a record with a comparison operator. This example searches for hosts located in 'Ann Arbor'. ```CenQL host.location.city="Ann Arbor" ``` -------------------------------- ### Example 200 Response for Snapshot Files (Truncated) Source: https://docs.censys.com/docs/ls-download-censys-universal-internet-dataset This is a truncated example JSON response showing the files within a specific snapshot. It includes download paths and metadata for each file. ```json { "series": { "id": "universal-internet-dataset-v2-ipv4", "name": "Universal Internet DataSet of IPv4 Hosts" }, "id": "20231107", "timestamp": "202301107T000000", "task_id": null, "metadata": null, "total_size": 704279348958, "files": { "ipv4-000000000000.avro": { "compressed_size": 71374181, "download_path": "https://file-host-02.censys.io/snapshots/universal-internet-dataset-v2-ipv4/20230416/ipv4-000000000000.avro", "compressed_md5_fingerprint": "a65be1938e1be56132ff48ac460384d9", "file_type": null, "compression_type": null } } } ``` -------------------------------- ### Request Full Certificates Snapshot Details URL Source: https://docs.censys.com/docs/ls-download-certs-2-data Make a GET request to the details URL obtained from the previous step to get specific file information for the snapshot. ```http GET https://search.censys.io/api/v1/data/certificates-v2-full/2023-03-01T12:50:16.804634Z ``` -------------------------------- ### Example 200 Response for Dataset File List (Truncated) Source: https://docs.censys.com/docs/ls-download-certs-2-data This is a truncated example of a successful response when requesting the details of a specific incremental dataset. It lists the files within the dataset, including their compressed size and download path. ```json "series": { "id": "certificates-v2-incremental", "name": "Incremental Updates to X.509 Certificates" }, "id": "2023-03-07T12:50:11.773781Z", "timestamp": "20230307T125012", "task_id": null, "metadata": null, "total_size": 24252152323, "files": { "certificates-000000000000.avro": { "compressed_size": 34138, "download_path": "https://file-host-02.censys.io/snapshots/certificates-v2-incremental/2023-03-07T12:50:11.773781Z/certificates-000000000000.avro", "compressed_md5_fingerprint": "2f69439ebada1bc20bc6391a2ffa484f", "file_type": null, "compression_type": null }, ... } } ``` -------------------------------- ### Example 200 Response for Snapshot ID Source: https://docs.censys.com/docs/ls-download-censys-universal-internet-dataset This is an example JSON response when successfully retrieving snapshot information. It includes the latest snapshot ID and details URL. ```json { "id": "universal-internet-dataset-v2-ipv4", "name": "Universal Internet DataSet of IPv4 Hosts", "description": "Deep Scans of more than 3,500 popular ports featuring Automatic Protocol Detection across hosts in the IPv4 address space. Schema version 2.", "results": { "latest": { "id": "20231107", "timestamp": "20231107T000000", "details_url": "https://search.censys.io/api/v1/data/universal-internet-dataset-v2-ipv4/20230416" }, "historical": [...] } } ``` -------------------------------- ### Example 200 Response for Dataset Series Source: https://docs.censys.com/docs/ls-download-certs-2-data This is an example of a successful response when requesting the incremental dataset series. It includes the series ID, name, description, and details about the latest and historical results. ```json "id": "certificates-v2-incremental", "name": "Incremental Updates to X.509 Certificates", "description": "Parsed X.509 certificates as incremental updates to the last full series snapshot. Schema version 2.", "results": { "latest": { "id": "2023-03-07T12:50:11.773781Z", "timestamp": "20230307T125012", "details_url": "https://search.censys.io/api/v1/data/certificates-v2-incremental/2023-03-07T12:50:11.773781Z" }, "historical": [], } } ``` -------------------------------- ### GCP Standalone Project Scope Example Source: https://docs.censys.com/docs/asm-gcp-cloud-connector Example JSON body for configuring a standalone GCP Project scope for the Hosted Cloud Connector. Includes Project ID, project ID for service account creation, and optional service type exclusions. ```json { "gcp": { "project_id": "YOUR_PROJECT_ID", "exclude_service_types": [ "compute" ] } } ``` -------------------------------- ### Install cencli with Homebrew Source: https://docs.censys.com/docs/platform-cli macOS and Linux users can install cencli using Homebrew. This command also automatically generates shell completion scripts. ```bash brew install censys/tap/cencli ``` -------------------------------- ### Example Slack Webhook Message Format Source: https://docs.censys.com/docs/platform-collections-configure-webhooks-for-slack This example shows how to format a Slack message using variables from a Censys webhook. It combines event details for both human readability and system integration. ```text New Webhook Event {}asset_type - {}asset_id was {}event_verb {}event_type to the collection {}collection_name at {}timestamp. ``` -------------------------------- ### GCP Organization Scope Example Source: https://docs.censys.com/docs/asm-gcp-cloud-connector Example JSON body for configuring a GCP Organization scope for the Hosted Cloud Connector. Includes Organization ID, project ID for service account creation, and optional service type exclusions. ```json { "gcp": { "organization_id": "YOUR_ORGANIZATION_ID", "project_id": "YOUR_PROJECT_ID", "exclude_service_types": [ "compute" ] } } ``` -------------------------------- ### Webhook Request Body Example Source: https://docs.censys.com/docs/platform-collections-webhooks An example of a webhook request body for an 'add' event, indicating a new certificate was added to a collection. It includes asset details, collection information, and the query used. ```json { "asset_id": "f9f055ac237c123b9a7a8644832319ad41d399c9f714f52bc6a02c4a875cfb27", "asset_type": "cert", "collection_id": "364133a0-53ae-4f51-82d0-17c25aed92e3", "collection_name": "Certificates belonging to Vandelay Industries", "event_type": "add", "evidence": "cert f9f055ac237c123b9a7a8644832319ad41d399c9f714f52bc6a02c4a875cfb27 was added to collection 364133a0-53ae-4f51-82d0-17c25aed92e3 on 2025-02-03T20:03:01Z based on the collection query.", "org_id": "00000000-0000-0000-0000-000000000000", "query": "cert.parsed.subject.organization: "Vandelay Industries"", "timestamp": "2025-02-03T20:03:01Z", "url": "https://platform.censys.io/collections/364133a0-53ae-4f51-82d0-17c25aed92e3?org=00000000-0000-0000-0000-000000000000" } ``` -------------------------------- ### Example API Response Structure Source: https://docs.censys.com/docs/ls-api Illustrates the structure of a typical response from the host aggregate endpoint, including status and result details. ```json { "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": 290406670, // Total number of services whose TLS values were tallied "buckets": [ { "key": "TLSv1_2", "count": 77335713 }, { "key": "TLSv1_3", "count": 53386055 }, { "key": "TLSv1_0", "count": 2937331 }, { "key": "TLSv1_1", "count": 615279 } ], "total_omitted": 0, // The number of services omitted from the aggregation "potential_deviation": 0 } } ``` -------------------------------- ### Example Search for Pulse Secure Software Source: https://docs.censys.com/docs/ls-introductory-use-cases Demonstrates a practical search query to find hosts running Pulse Secure software, utilizing CPE formatting. ```bash https://search.censys.io/search?resource=hosts&q=services.software.uniform_resource_identifier%3A+%60cpe%3A2.3%3Ao%3Apulse_secure%3Apulse_connect_secure%3A*%3A*%3A*%3A*%3A*%3A*%3A*%3A*%60 ``` -------------------------------- ### View Certificate Record Request Source: https://docs.censys.com/docs/ls-api This example shows how to make a GET request to the Censys API to retrieve a specific certificate record using its SHA-256 fingerprint. ```http GET https://search.censys.io/api/v1/view/certificates/fce621c0dc1c666d03d660472f636ce91e66e96460545f0da7eb1a24873e2f70 ``` -------------------------------- ### Query Censys History with Duration and Start Time Source: https://docs.censys.com/docs/platform-cli Combine `--start` and `--duration` flags to define a time window relative to a specific start time. Supported duration units include hours (h), days (d), weeks (w), and years (y). ```bash censys history 8.8.8.8 --start 2025-01-01T00:00:00Z --duration 30d ``` -------------------------------- ### Legacy Search Host Data Model Example Source: https://docs.censys.com/docs/dataset-differences-legacy-search-censys-platform Illustrates the structure of a host record in the Legacy Search data model, showing combined service information within a 'services' array. ```json { "ip": "8.8.8.8", "services": [ { "port":80, "service":"http", "http":{ "title": "Hello World!" } ], "location":{ "city": "Ann Arbor", ... }, ... } ``` -------------------------------- ### Example Search within a CIDR Block for Self-Signed Certificates Source: https://docs.censys.com/docs/ls-introductory-use-cases Illustrates how to search for hosts within a given CIDR block that have self-signed certificates, useful for security posture assessment. ```bash https://search.censys.io/search?resource=hosts&q=ip%3A+3.128.0.0%2F9+and+services.tls.certificates.leaf_data.signature.self_signed%3A+true ``` -------------------------------- ### Example Filter Aggregate Request Source: https://docs.censys.com/docs/asm-inventory-aggregation-api A request body example for a filter aggregation, used to count services with specific software risks within a workspace. ```json { "workspaces": [ "your-workspace-id" ], "query": "host.name: * and host.services.software.risks:*", "aggregation": { "nested": { "path": "host.services" }, "sub_aggregation": { "filter": { "query": "software.risks:*" } } } } ``` -------------------------------- ### View host records from an input file Source: https://docs.censys.com/docs/platform-cli Uses the --input-file flag to specify a file containing a list of assets to view. ```bash censys view -i hosts.txt ``` -------------------------------- ### Example Rare Term Aggregate Request Source: https://docs.censys.com/docs/asm-inventory-aggregation-api A request body example for a rare term aggregation, used to find provinces with a limited number of high-risk hosts. ```json { "workspaces": [ "{{workspace_id}}" ], "query": "host.services.risks.severity:{critical, high}", "aggregation": { "rareTerm": { "field": "host.location.province", "maxCount": 10 } } } ``` -------------------------------- ### Web Property Record Structure Example Source: https://docs.censys.com/docs/platform-web-property-dataset This JSON excerpt illustrates the basic structure of an empty web property record, showing the fields and nested objects typically found. ```json { "web": { "port": "", "scan_timed": "", "hostname": "", "labels": [], "endpoints": [ { "endpoint_type": "", "path": "", "banner": "", "banner_hash_sha256": "", "banner_hex": "", "transport_protocol": "", "": {} } ] }, "misconfigs": [], "exposures": [], "vulns": [], "software": [], "hardware": [], "operating_system": [], "tls": [] } ``` -------------------------------- ### Query Censys History with Start Time Source: https://docs.censys.com/docs/platform-cli Use the `--start` flag to define the beginning of the time window for historical data retrieval. The time must be in RFC3339 format. ```bash censys history 8.8.8.8 --start 2025-10-01T00:00:00Z ``` -------------------------------- ### View host record with short output format Source: https://docs.censys.com/docs/platform-cli Uses the --output format flag to specify the 'short' output format for results. ```bash censys view 8.8.8.8 -O short ``` -------------------------------- ### Export First 50 Hosts Matching Query Source: https://docs.censys.com/docs/ls-export-results Use this snippet to print the first 50 hosts matching a specific query to the screen. Ensure the Censys CLI tool is installed and configured. ```python from censys.search import CensysHosts h = CensysHosts() query = h.search ("services.service_name: HTTP", per_page=50, pages=1) print(query.view_all()) ``` -------------------------------- ### Get Snapshot ID Source: https://docs.censys.com/docs/ls-download-censys-universal-internet-dataset Retrieve the latest or historical snapshot ID for a given dataset series by making a GET request to the series endpoint. This is the first step in downloading the dataset. ```APIDOC ## GET /api/v1/data/{dataset_series} ### Description Retrieves information about a specific dataset series, including the latest snapshot ID and historical data details. ### Method GET ### Endpoint `/api/v1/data/universal-internet-dataset-v2-ipv4` `/api/v1/data/universal-internet-dataset-v2-ipv6` `/api/v1/data/universal-internet-dataset-v2-ipv4-virtual-hosts` `/api/v1/data/universal-internet-dataset-v2-ipv6-virtual-hosts` ### Parameters #### Query Parameters None #### Request Body None ### Response #### Success Response (200) - **id** (string) - The identifier for the dataset series. - **name** (string) - The human-readable name of the dataset series. - **description** (string) - A description of the dataset series. - **results** (object) - Contains information about the latest and historical snapshots. - **latest** (object) - **id** (string) - The ID of the latest snapshot. - **timestamp** (string) - The timestamp of the latest snapshot. - **details_url** (string) - The URL to retrieve details about the latest snapshot. - **historical** (array) - An array of historical snapshot details. ### Request Example ```bash curl -g -X 'GET' \ 'https://search.censys.io/api/v1/data/universal-internet-dataset-v2-ipv4' \ -H 'Accept: application/json' \ --user "$CENSYS_API_ID:$CENSYS_API_SECRET" ``` ### Response Example ```json { "id": "universal-internet-dataset-v2-ipv4", "name": "Universal Internet DataSet of IPv4 Hosts", "description": "Deep Scans of more than 3,500 popular ports featuring Automatic Protocol Detection across hosts in the IPv4 address space. Schema version 2.", "results": { "latest": { "id": "20231107", "timestamp": "20231107T000000", "details_url": "https://search.censys.io/api/v1/data/universal-internet-dataset-v2-ipv4/20230416" }, "historical": [] } } ``` ``` -------------------------------- ### Censys Platform Host Data Model Example Source: https://docs.censys.com/docs/dataset-differences-legacy-search-censys-platform An example of a host record in the Censys Platform data model. This structure includes host-level information derived from service scan data. ```json { "dns": { // DNS Names and Forward DNS Data }, "ip": , "service_count": , "truncated": , "location": { // Location details such as continent, country, country_code, city, postal_code, timezone, and co-ordinates }, "routing": { // Routing information such as ASN,BGP Prefix, BGP name and country }, "services": [ { "port": , "protocol": , "transport_protocol": , "misconfigs": [], "exposures": [], "vulns": [], "software": [], "hardware": [], "operating_systems": [], "threats": [], "labels": [], "ip": , "scan_time": "2024-10-20T20:07:50.000Z", "banner": "", "banner_hash_sha256": "", "": { // Details about service repeated for each identified service } } ], "whois": { // WhoIS data about host includes name, CIDRs, organization, contacts }, "labels": [] } ``` -------------------------------- ### Example Search Response Source: https://docs.censys.com/docs/ls-api This JSON object represents a paginated response from a certificate search query, showing metadata and a list of matching certificate fingerprints. ```json { "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" }, ... ] } ``` -------------------------------- ### Full Certificates Snapshot File Details Source: https://docs.censys.com/docs/ls-download-certs-2-data This response provides detailed information about a specific file within the certificate snapshot, including its compressed size and download path. ```json "series": { "id": "certificates-v2-full", "name": "Full Set of X.509 Certificates" }, "id": "2023-03-01T12:50:16.804634Z", "timestamp": "20230301T125017", "task_id": null, "metadata": null, "total_size": 12336264834346, "files": { "certificates-000000000000.avro": { "compressed_size": 73423483, "download_path": "https://file-host-02.censys.io/snap shots/certificates-v2-full/2023-03-01T12:50:16.804634Z/certificates-000000000000.avro", "compressed_md5_fingerprint":"c399b93f9cb1e6c5b697955b718c96e", "file_type": null, "compression_type": null } } } ``` -------------------------------- ### View a specific web property record Source: https://docs.censys.com/docs/platform-cli Fetches information about a web property using its hostname and port. ```bash censys view platform.censys.io:80 ``` -------------------------------- ### Search for Hosts with Specific Software (CPE) Source: https://docs.censys.com/docs/ls-introductory-use-cases Identify hosts running a particular software version using Common Platform Enumeration (CPE) identifiers. This is crucial for vulnerability management. ```bash services.software.uniform_resource_identifier: {CPE-formatted software URI} ``` -------------------------------- ### Request Specific Incremental Dataset Details Source: https://docs.censys.com/docs/ls-download-certs-2-data After obtaining the `details_url` from the dataset series response, use this GET request to get a list of files that comprise a specific incremental dataset result. This is crucial for identifying the files to download. ```bash GET \https://search.censys.io/api/v1/data/certificates-v2-incremental/2023-03-07T12:50:11.773781Z ``` -------------------------------- ### Hosts with Certificates Added in the Last Calendar Year in CenQL Source: https://docs.censys.com/docs/use-relative-time-in-queries Query for hosts with certificates added within the current calendar year. It defines the range from the start of the current year to the start of the next year, rounded to the nearest day. ```CenQL host.services.cert.added_at > "now/y" and host.services.cert.added_at < "now+1y/y" ``` -------------------------------- ### Search for Hosts Running Nginx with Specific HTML Title Source: https://docs.censys.com/docs/censys-query-language Combine software product search with HTML title content. This example finds hosts running nginx with a specific title in their HTML. ```censys-query-language host.services: (software.product = "nginx" and endpoints.http.html_title = "Welcome to nginx!") ```