Censys v3
App Vendor: Censys
App Category: Data Enrichment & Threat Intelligence
Connector Version: 1.0.0
API Version: v3
About App
The Censys v3 app helps security teams gain visibility into internet-exposed assets using trusted global scan data. It provides structured insights into hosts, certificates, and web properties to support exposure management and threat investigation.
The Censys v3 app is configured with Cyware Orchestrate to perform the following actions:
Action Name | Description |
|---|---|
Aggregate Results for Search Query | This action retrieves aggregated data summaries for a Censys platform search query. To use this action, you must provide the organization id while configuring the app instance. |
Get Certificate Details | This action retrieves information about a single certificate, including its metadata and properties, using its SHA-256 fingerprint. |
Get Host Details | This action retrieves information about a single host identified by its IP address. |
Get Host Event History | This action retrieves the event history for a specific host, reflecting changes in service protocols and scan data over a defined period. |
Get Host History for a Certificate | This action retrieves the historical host observations associated with a specific certificate. To use this action, you must provide the organization ID while configuring the app instance. |
Get Scan Status | This action retrieves the current status of a live discovery or live rescan by its unique identifier. To use this action, you must provide the organization id while configuring the app instance. |
List Active Threats | This action retrieves a list of active threats observed by Censys by aggregating threat fingerprints across hosts and web properties. To use this action, you must provide the organization ID while configuring the app instance. |
Run Search Query | This action retrieves Censys v3 data by executing a search query across global host services using the Censys Query Language (CenQL). To use this action, you must provide the organization ID while configuring the app instance. |
Generic Action | This is a generic action used to make requests to any Censys v3 endpoint. |
Configuration Parameters
The following configuration parameters are required for the Censys v3 app to communicate with the Censys v3 enterprise application. The parameters can be configured by creating instances in the app.
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
API Key | Enter the Censys V3 API key generated from the Censys V3 console. | Password | Required | |
Verify | Choose your preference to verify SSL while making requests. It is recommended to set this option to yes. If no is passed, it may result in an incorrect connection establishment, potentially resulting in a broken connection. | Boolean | Optional | Allowed values: true and false Default value: true |
Timeout | Enter the timeout value in seconds. This is the number of seconds that requests will wait to establish a connection with Censys V3. | Integer | Optional | Allowed range: 15-120 Default value: 15 |
Organization ID | Enter the organization ID to associate API requests with a Censys organization. This is required for actions available only to starter or enterprise organizations. If not provided, the request uses free account permissions. | Text | Optional |
Action: Aggregate Results for Search Query
This action retrieves aggregated data summaries for a Censys platform search query. To use this action, you must provide the organization ID while configuring the app instance.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Field | Enter the field used to group search results while generating aggregated summaries. Example: host.services.port | Text | Required | |
Number of Buckets | Enter the number of buckets to split results into to control the granularity of the aggregation. Example: 100 | Integer | Required | |
Query | Enter the CenQL query string to define the dataset over which aggregation is performed. Example: host.services.protocol=ssh | Text | Required | |
Count by Level | Enter the document level to control how aggregation counts are calculated for nested fields. | Text | Optional | Allowed values: An empty string for the deepest level, a period (.) for the root level, or a nested path such as host.services. By default, counts are calculated at the deepest level. |
Filter by Query | Choose true if you want aggregation results to include only field values that strictly match the query constraints. | Boolean | Optional | The default value is false. |
Example Request
[
{
"field": "host.services.port",
"query": "host.services.protocol=SSH",
"number_of_buckets": "100"
}
]Action: Get Certificate Details
This action retrieves information about a single certificate, including its metadata and properties, using its SHA-256 fingerprint.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Certificate ID | Enter the SHA-256 certificate fingerprint to identify the specific record in the Censys v3 dataset. Example: 3daf2843a77b6f4e6af43cd9b6f6746053b8c928e056e8a724808db8905a94cf | Text | Required |
Example Request
[
{
"certificate_id": "000000006dbb05362ed7611d4c041d13654a8c44216d58351333dc4f353d92c2"
}
]Action: Get Host Details
This action retrieves information about a single host identified by its IP address.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Host ID | Enter the IP address of the host to retrieve specific asset information and metadata. Example: 8.8.8.8 | Text | Required |
Example Request
[
{
"host_id": "1.1.1.1"
}
]Action: Get Host Event History
This action retrieves the event history for a specific host, reflecting changes in service protocols and scan data over a defined period.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Host ID | Enter the IP address of the host to retrieve its event history. Example: 1.1.1.1 | Text | Required | |
Start Time | Enter the most recent timestamp in the time range (closest to the current time) to mark the upper boundary of the timeline. The value should be in RFC3339 format. Example: To retrieve events from January 1, 2025, to the start of January 2, 2025, enter 2025-01-02t00:00:00z. | Text | Required | |
End Time | Enter the earliest timestamp in the time range (furthest from the current time) to mark the lower boundary of the timeline. The value should be in RFC3339 format. Example: To retrieve events from January 1, 2025, to the start of January 2, 2025, enter 2025-01-01t00:00:00z. | Text | Required |
Example Request
[
{
"host_id": "45.200.55.190",
"end_time": "2024-12-10T00:00:00Z",
"start_time": "2024-12-10T00:00:00Z"
}
]Action: Get Host History for a Certificate
This action retrieves the historical host observations associated with a specific certificate. To use this action, you must provide the organization ID while configuring the app instance.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Certificate ID | Enter the SHA-256 hash of the certificate to retrieve its associated host observation history. Example: 55af8a301eb51abdaf7c31bec951638fe5a99d5d92117eca2be493026613fa46 | Text | Required | |
Start Time | Enter the ISO 8601 start time to only include observations that end at or after this time. Example: 2023-01-01t00:00:00z | Text | Optional | |
End time | Enter the ISO 8601 end time to only include observations that start at or before this time. Example: 2023-12-31t23:59:59z | Text | Optional | |
Port | Enter the port number to filter the host observations by a specific service port. Example: 443 | Integer | Optional | |
Protocol | Enter the transport protocol to filter the host observations by a specific protocol. Example: tcp | Text | Optional | |
Page Token | Enter the pagination token from a previous response to retrieve the next page of results. | Text | Optional | |
Page Size | Enter the number of results to retrieve on each page. | Integer | Optional | The maximum and default value is 100. |
Example Request
[
{
"certificate_id": "5d703a0062b7bbec02f3fcab7b1f139787c6d3d6ccf106af236b167d308bdb83"
}
]Action: Get Scan Status
This action retrieves the current status of a live discovery or live rescan by its unique identifier. To use this action, you must provide the organization ID while configuring the app instance.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Scan ID | Enter the unique UUID of the tracked scan to check its current progress. Example: 8a2af3d0-3f6f-40a2-832d-c2ef4271236e | Text | Required |
Example Request
[
{
"scan_id": "8a2af3d0-3f6f-40a2-832d-c2ef4271236e"
}
]Action: List Active Threats
This action retrieves a list of active threats observed by Censys by aggregating threat fingerprints across hosts and web properties. To use this action, you must provide the organization ID while configuring the app instance.
Action Input Parameters
No input parameters are required for this action.
Action: Run Search Query
This action retrieves Censys v3 data by executing a search query across global host services using the Censys Query Language (CenQL). To use this action, you must provide the organization ID while configuring the app instance.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Query | Enter the CenQL query string to define the criteria for searching host services. Example: host.services: (protocol=ssh and not port: 22) | Text | Required | |
Page Size | Enter the number of results to return on each page. Example: 1 | Integer | Optional | |
Page Token | Enter the page token returned from a previous request to retrieve the next page of search results. | Integer | Optional | |
Fields | Enter the specific fields to include in the response to limit the data received. Omitting port or protocol fields may result in matched_services being excluded from the response. Example: host.ip | List | Optional |
Example Request
[
{
"query": "host.ip:8.8.8.8"
}
]Action: Generic Action
This is a generic action used to make requests to any Censys v3 endpoint.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Method | Enter the HTTP method to make the request. | Text | Required | Allowed values: GET, POST, PUT, and DELETE |
Endpoint | Enter the endpoint to which you will make the request. Example: v3/threat-hunting/threats | Text | Required | |
Query Params | Enter the query parameters to make the request. Example: {'page_size': 100} | Key Value | Optional | |
Payload | Enter the payload JSON to pass to the API. Example: {"start_time": 2025-02-16t14:30:15z} | Any | Optional | |
Extra Fields | Enter the extra fields to pass to the API. | Key Value | Optional | Allowed keys: headers, payload_json, download, files, filename, retry_wait, retry_count, custom_output, and response_type |
Example Request
[
{
"method": "GET",
"endpoint": "v3/global/asset/host/8.8.8.8",
"extra_fields": {},
"query_params": {}
}
]