Censys Attack Surface Management
The Censys ASM connector facilitates the integration of Censys' expansive attack surface management capabilities into the Swimlane Turbine platform.
Censys Attack Surface Management provides a powerful interface for security professionals to discover, monitor, and analyze their organization's attack surface. This connector enables Swimlane Turbine users to automate the retrieval of asset inventories, logbook entries, and risk event data, enhancing their security posture with up-to-date intelligence. By integrating with Censys, users can streamline continuous monitoring, risk assessment, and incident response workflows, ensuring a proactive defense against emerging threats.
Censys Attack Surface Management connector integrates with the Censys Attack Surface Management platform. It is used to manage and interact with the Censys API, providing capabilities such as data enrichment and threat intelligence.
Limitations
None to date.
Supported Versions
Censys Attack Surface Management connector supports the Censys Attack Surface Management API version specified in the connector.yaml.
Additional Docs
For more information, refer to the Censys API documentation.
Prerequisites
Before utilizing the Censys Attack Surface Management connector within Swimlane Turbine, ensure you have the following prerequisites:
- API Key Authentication with the following parameters:
- URL: The endpoint URL for the Censys ASM API.
- Censys API Key: Your personal API key provided by Censys to access their services.
Configuration
Authentication Methods
Censys Attack Surface Management connector supports the following authentication methods:
Setup Instructions:
This API uses JSON as the data exchange format. Standard HTTP status codes are used to indicate successes (200s), client errors (400s), and server errors (500s). All request body types, request query/path parameter types, and response types are described in this spec. All requests require a Censys-Api-Key header containing your team's API key.
- Navigate to the Censys Attack Surface Management platform.
- Obtain your Censys-Api-Key from the platform.
- Configure the connector with the obtained API Key in the apikey.yaml file.
Troubleshooting Tips:
- Ensure the API Key is correct and has the necessary permissions.
- Verify that the URL is correctly configured and accessible.
Capabilities
Censys Attack Surface Management Connector provides the following capabilities:
- Get Inventory
- Get Logbook
- Get Risk Events
- Get Risk Instances
Get Inventory
Retrieve the current inventory of assets from Censys Attack Surface Management for analysis and monitoring.
Get Logbook
Get logbook entries by querying this endpoint. Since the amount of logbook data may be significant, multiple calls to this endpoint could be required to collect all the data matching the filters you provide.
Note: the nextCursor will always be set, regardless if the event array is empty or doesn't have the maximum number of events.
Here's some pseudo code demonstrating how this might be accomplished:
initialCursor = getLogbookCursor({ filter: yourFilterObject })
response = getLogbookData({ cursor: initialCursor })
results = response.events
while (!response.endOfEvents) {
response = getLogbookData({ cursor: response.nextCursor })
results.addAll(response.events)
}All results for the given filters should now be in the results variable.
Get Risk Events
Get all risk events by querying this endpoint. There may be a significant number of entries, so pagination may be required to collect all of the information. The returned data is sorted by date, with the most recent events last. This, along with the pagination implementation, should allow for efficient querying of all risk events and monitoring for new events.
Example usage to get all risk events and then watch for new events:
GET https://app.censys.io/api/v2/risk-events?start=2022-04-04T00:00:00ZProcess the response and save the cursor returned in the next field for future use.
Until we receive a response with endOfEvents: true:
GET https://app.censys.io/api/v2/risk-events?cursor=<cursor>Process the response and save the cursor returned in the next field for future use.
Some time later - resume requesting events with the last used cursor.
You can also request that the content be presented in CSV form. To request CSV form, make a request with the Accept: text/csv header. NOTE: There will no longer be a cursor to resume with. Note that the CSV set of columns is somewhat dynamic depending particularly on what fields are encountered in the delta response object.
Results
Risk Events
Each event is represented by an object with details about the changes:
- id will contain a numeric ID uniquely identifying the risk event for the workspace.
- ts - RFC3339-encoded timestamp of the risk event.
- op - What sort of operation was performed: one of open, update, close.
- open - the item was created
- update - something about the item was changed
- close - the item was "closed" (generally only relevant for risk instances)
- src - Identifier for the source of the event: one of system, api, ui.
- srcID - Optional free-form identifier for the specific source. For src = ui this will typically be the name of the user that caused the change.
- reason - Optional free-form string describing why the change was made.
Delta Object
The delta object describes what sort of change was made - typically including details on what columns were updated or metadata changes were made.
Example delta fields:
- severity - Risk type or instance severity was changed to this value.
- userStatus - Risk instance was either muted (set to muted) or un-muted (set to empty). NOTE in CSV format - un-muted is impossible to differentiate from other changes due to null mapping to "".
- enabled - Risk type was enabled or disabled.
- metadata_added - Risk instances had this sequence of metadata items added (list of JSON objects).
- metadata_removed - Risk instances had this sequence of metadata items removed (list of JSON objects).
Get Risk Instances
Get all active risk instances in your attack surface. To replicate the results in the /search endpoint, you would use the query filter:
"and": [
["type.enabled", "=", true],
["status", "=", "open"],
["user_status", "=", null]
]Parameters
GET https://app.censys.io/api/v2/risk-instancesQuery Parameters:
- includeEvents=true - set to include risk type events
Results
The result is either a JSON object or a CSV. To request the CSV format - include the header Accept: text/csv in the request. The data will be formatted as a CSV with a header row to help process the data (since the column ordering is undefined). See the OpenAPI example data for what the JSON/CSV could look like.
The JSON object format will include the following two fields:
- total - the total number of risks
- risks - an array containing the risk data
Risk Instance Properties
Each risk instance will have the following properties listed:
- id - identifier for this specific risk instance
- typeID - risk type identifier
- context - context object describing where the risk was found
- displayName - human-readable display name
- severity - risk severity (critical/high/medium/low)
- status - "open" if the risk is observed, "closed" if the risk is no longer observed
- userStatus - "muted" if the risk is considered "accepted" and should be hidden from most UI
- firstComputedAt - RFC3339-encoded timestamp of when the risk was first observed in the workspace
- lastUpdatedAt - RFC3339-encoded timestamp of when the risk instance data was updated
- lastComputedAt - RFC3339-encoded timestamp of the most recent time the risk was observed
- categories - an array of risk categories. Risk categories are organized hierarchically, ex: ["Top Level", "Category", "Sub-Category"]. In the user-interface, the Category is what is presented.
- metadata - an array of custom risk metadata properties
- events - an array of associated Risk Events (only if includeEvents=true set)
- hostData - JSON object of the host data associated with the risk instance (only if includeHostData=true set). Returns data for the port the risk was found on. If host data cannot be reached, or the risk lacks an IP and port, a null value will be returned.
- matchContext - JSON object of additional details from the fingerprint match. This can include derived data from the host, or important information from the host used to make the match.
Match Context Details
BETA This data structure is currently subject to change.
The optional matchContext field is a JSON object that has two keys associated with a JSON dict:
- found: indicates a property of the service that we found to match the risk on and its value.
- want: indicates a property of a service that we would like to see on it.
For example, for a software end-of-life risk, we could have the following matchContext value:
{
"found": {
"services.software.version": "3.4.1"
},
"want": {
"service.software.version": "3.7.0"
}
}For a service-exposed risk, we could have the following:
{
"found": {
"service_name": "MYSQL"
}
}Risk Context
Host Risk Context
When a context contains the type: "host" then the risk is located on a host.
All host risks:
- ip - the IP address that the risk was found on
- name - the name used to lookup the host such as for SNI / Host header - may be "" if no name used
Service Risks:
- transport - the transport protocol used, ex: TCP, UDP, QUIC
- port - the port the service was found on
- service - the name of the service, ex: HTTP, HTTPS, SSH
Software Risks:
- cpe - the software CPE identifier, ex: cpe:2.3:a:_:php:7.1.33:_:_:_:_:_:_:_
Domain Risk Context
When a context contains the type: "domain" then the risk is located on a registered domain.
The name field of the context object contains the domain name.
Storage Bucket Risk Context
When a context contains the type: "bucket" then the risk is located on a cloud storage bucket.
The cri field of the context object contains Censys Resource Identifier for the storage bucket.
Examples include:
- cri:bucket:aws:s3:customer-test
- cri:bucket:gcp:gcs:customer-staging
- cri:bucket:azure:blob:myaccount:some-container
Risk Metadata Properties
Risk instances can have metadata attached to them.
Metadata items are treated as individual pieces of data that are linked to risk instances.
A metadata item is defined as having at least a src and potentially a srcID.
This pair of identifiers helps with managing system and API-provided metadata.
An example piece of useful metadata is one computed to attach cloud/cdn/classification data to risk instances:
{
"src": "system",
"srcID": "cloud-info",
"cdn": "CLOUDFLARE",
"classification": null,
"cloud": "CloudFlare Inc"
}Risk Instance Events
If the includeEvents=true flag was set, then each risk instance will include events associated with it in the events array field.
Each event is represented by an object with details about the changes:
- id will contain a numeric ID uniquely identifying the risk event for the workspace.
- ts - RFC3339-encoded timestamp of the risk event.
- op - What sort of operation was performed: one of open, update, close.
- open - the item was created
- update - something about the item was changed
- close - the item was "closed"
- src - Identifier for the source of the event: one of system, api, ui.
- srcID - Optional free-form identifier for the specific source. For src = ui this will typically be the name of the user that caused the change.
- reason - Optional free-form string describing why the change was made.
Risk Instance Host Data
If the includeHostData=true flag was set, then the risk instance will include the host data associated with it in the hostData field. The hostData will be a JSON object containing the Censys Search data for the host and port the risk was found on. If host data cannot be reached, or the risk lacks an IP and port, a null value will be returned.
For more information on the returned host data, see the Censys Search API documentation.
Delta Object
The delta object describes what sort of change was made - typically including details on what columns were updated or metadata changes were made.
Example delta fields:
- severity - Risk type or instance severity was changed to this value.
- userStatus - Risk instance was either muted (set to muted) or un-muted (set to empty). NOTE in CSV format - un-muted is impossible to differentiate from other changes due to null mapping to "".
- enabled - Risk type was enabled or disabled.
- metadata_added - Risk instances had this sequence of metadata items added (list of JSON objects).
- metadata_removed - Risk instances had this sequence of metadata items removed (list of JSON objects).
Configurations
Censys Attack Surface Management Authentication
Authenticates using an API Key.
Configuration Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
url | A URL to the target host. | string | Required |
Censys-Api-Key | Censys API Key. | string | Required |
verify_ssl | Verify SSL certificate. | boolean | Optional |
http_proxy | A proxy to route requests through. | string | Optional |
Actions
Get Inventory
Obtain the latest asset inventory from Censys Attack Surface Management for comprehensive analysis and continuous monitoring.
Endpoint
- URL: /api/inventory/v1
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.workspaces | array | Optional | Workspaces to search across. |
parameters.query | string | Optional | The raw Censys DSL query string. |
parameters.pageSize | number | Optional | How many hits to return. |
parameters.cursor | string | Optional | Workspaces to search across. |
parameters.sort | array | Optional | A list of fields to sort on. By default, these fields will be sorted in ASC order. To sort in DESC order, prepend a '-' to the field name, ie:- '-tags'. |
parameters.fields | array | Optional | A list of fields to include in response hits. If this field is empty, a default set of fields will be used. NOTE:- Some large fields (like HTTP bodies) are disallowed. |
Input Example
{"parameters":{"workspaces":["swimlaneas_swimlaneas_qaeqgdos"],"query":"query","pageSize":1,"cursor":"eyJmaWx0ZXIiOnt9LCJzdGFydCI6MX0=","sort":["-tags"],"fields":["tags"]}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
hits | array | Output field: hits |
nextCursor | string | Output field: nextCursor |
previousCursor | string | Output field: previousCursor |
queryDurationMillis | number | Output field: queryDurationMillis |
totalHits | number | Output field: totalHits |
Output Example
{"status_code":200,"response_headers":{"Date":"Mon, 25 Nov 2024 06:17:22 GMT","Content-Type":"application/json","Content-Encoding":"gzip","Connection":"keep-alive","strict-transport-security":"max-age=2592000; includeSubDomains; preload","CF-Cache-Status":"DYNAMIC","traceparent":"00-aa92bbf9fbce52fbf534d2d52d3721a9-bcb7c162a53f6519-01","Server":"cloudflare","CF-RAY":"8e7f83e73c6a1bdc-BOM"},"reason":"OK","json_body":{"hits":[{}],"nextCursor":"string","previousCursor":"string","queryDurationMillis...
Get Logbook
Gather logbook entries from Censys Attack Surface Management, potentially involving multiple calls to collect comprehensive data.
Endpoint
- URL: /api/v1/logbook
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.cursor | string | Optional | A logbook cursor generated by /api/v1/logbook-cursor. |
Input Example
{"parameters":{"cursor":"eyJmaWx0ZXIiOnt9LCJzdGFydCI6MX0="}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
events | array | Output field: events |
events.file_name | string | Name of the resource |
events.file | string | Output field: events.file |
nextCursor | string | Output field: nextCursor |
endOfEvents | boolean | Output field: endOfEvents |
Output Example
{"status_code":200,"response_headers":{"Date":"Tue, 05 Nov 2024 06:36:09 GMT","Content-Type":"application/json; charset=utf-8","Transfer-Encoding":"chunked","Connection":"keep-alive","vary":"Origin","access-control-allow-origin":"*","x-ratelimit-limit":"60000","x-ratelimit-remaining":"59999","x-ratelimit-reset":"Tue Nov 05 2024 06:37:08 GMT+0000 (Coordinated Universal Time)","censys-response-type":"ok","surrogate-control":"no-store","Cache-Control":"no-store, no-cache, must-revalidate, proxy-rev...
Get Risk Events
Pulls all risk events from Censys Attack Surface Management, offering pagination for extensive datasets.
Endpoint
- URL: /api/v2/risk-events
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.start | string | Optional | Start time (inclusive) of events to query for. RFC3339-formatted, ex- 2022-04-01T04:00:00Z. |
parameters.end | string | Optional | End time (inclusive) of events to query for. |
parameters.afterID | number | Optional | Risk event ID to query for events after. |
parameters.limit | number | Optional | Number of events to include in a page. 0 indicates use the default of 50,000. |
parameters.cursor | string | Optional | Cursor value to continue collecting events started in a previous request. |
Input Example
{"parameters":{"start":"2022-04-01T04:00:00Z","end":"2022-04-02T04:00:00Z","afterID":12345,"limit":50000,"cursor":"abc123"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
total | number | Output field: total |
next | string | Output field: next |
events | array | Output field: events |
events.id | number | Unique identifier |
events.ts | string | Output field: events.ts |
events.op | string | Output field: events.op |
events.src | string | Output field: events.src |
events.delta | object | Output field: events.delta |
events.delta.config | object | Output field: events.delta.config |
events.delta.config.cdn | object | Output field: events.delta.config.cdn |
events.delta.config.cdn.value | array | Value for the parameter |
events.delta.config.cloud | object | Output field: events.delta.config.cloud |
events.delta.config.cloud.value | array | Value for the parameter |
events.delta.config.classification | object | Output field: events.delta.config.classification |
events.delta.config.classification.value | array | Value for the parameter |
events.delta.enabled | object | Output field: events.delta.enabled |
events.riskType | string | Type of the resource |
endOfEvents | boolean | Output field: endOfEvents |
Output Example
{"status_code":200,"response_headers":{"Date":"Tue, 05 Nov 2024 06:40:50 GMT","Content-Type":"application/json; charset=utf-8","Transfer-Encoding":"chunked","Connection":"keep-alive","strict-transport-security":"max-age=2592000; includeSubDomains; preload","CF-Cache-Status":"DYNAMIC","Set-Cookie":"__cf_bm=jf8o1u9tfi6MRuydlO1IFMvPf7UitfcZP1YpiqM5xa8-1730788850-1.0.1.1-kU2yeGIzW...","Server":"cloudflare","CF-RAY":"8ddadacb096047c9-BOM","Content-Encoding":"gzip"},"reason":"OK","json_body":{"total":...
Get Risk Instances
Retrieve all active risk instances within your Censys Attack Surface Management attack surface.
Endpoint
- URL: /api/v2/risk-instances
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.includeEvents | boolean | Optional | If the includeEvents=true flag was set, then each risk instance will include events associated with it in the events array field. |
parameters.includeHostData | boolean | Optional | If the includeHostData=true flag was set, then the risk instance will include the host data associated with it in the hostData field. The hostData will be a JSON object containing the Censys Search data for the host and port the risk was found on. If host data cannot be reached, or the risk lacks an ip and port, a null value will be returned. |
Input Example
{"parameters":{"includeEvents":true,"includeHostData":true}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
total | number | Output field: total |
risks | array | Output field: risks |
risks.file_name | string | Name of the resource |
risks.file | string | Output field: risks.file |
Output Example
{"status_code":200,"response_headers":{"Date":"Tue, 05 Nov 2024 06:37:51 GMT","Content-Type":"application/json; charset=utf-8","Content-Length":"22","Connection":"keep-alive","strict-transport-security":"max-age=2592000; includeSubDomains; preload","CF-Cache-Status":"DYNAMIC","Set-Cookie":"__cf_bm=amomJNNBSAUU5hZ2spTI5TM81wgb6SEgVU4D_ne0np4-1730788671-1.0.1.1-CLGXuIz33...","Server":"cloudflare","CF-RAY":"8ddad665cdf947c9-BOM"},"reason":"OK","json_body":{"total":0,"risks":[]}}
Get Risk Instances By ID
Retrieve all active risk instances associated with a given ID from your Censys Attack Surface Management attack surface.
Endpoint
- URL: /api/v2/risk-instances/{{id}}
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.includeEvents | boolean | Optional | If the includeEvents=true flag was set, then each risk instance will include events associated with it in the events array field. |
parameters.includeHostData | boolean | Optional | If the includeHostData=true flag was set, then the risk instance will include the host data associated with it in the hostData field. The hostData will be a JSON object containing the Censys Search data for the host and port the risk was found on. If host data cannot be reached, or the risk lacks an ip and port, a null value will be returned. |
path_parameters.id | number | Required | The ID of the risk instance to retrieve. |
Input Example
{"parameters":{"includeEvents":true,"includeHostData":true},"path_parameters":{"id":100}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
id | number | Unique identifier |
typeID | string | Unique identifier |
context | object | Output field: context |
context.name | string | Name of the resource |
context.port | number | Output field: context.port |
context.type | string | Type of the resource |
displayName | string | Name of the resource |
severity | string | Output field: severity |
status | string | Status value |
firstComputedAt | string | Output field: firstComputedAt |
lastUpdatedAt | string | Output field: lastUpdatedAt |
lastComputedAt | string | Output field: lastComputedAt |
confidence | string | Unique identifier |
categories | array | Output field: categories |
categories.0 | string | Output field: categories.0 |
categories.1 | string | Output field: categories.1 |
categories.2 | string | Output field: categories.2 |
metadata | array | Response data |
metadata.cloud | string | Response data |
metadata.src | string | Response data |
metadata.srcID | string | Response data |
events | array | Output field: events |
events.id | number | Unique identifier |
Output Example
{"status_code":200,"response_headers":{"cf-cache-status":"DYNAMIC","cf-ray":"9aaa1ae5bae79367-MAA","content-encoding":"gzip","content-type":"application/json; charset=utf-8","date":"Mon08 Dec 2025 06:11:23 GMT","server":"cloudflare","strict-transport-security":"max-age=2592000; includeSubDomains; preload","via":"1.1 google"},"reason":"OK","json_body":{"id":80,"typeID":"no-trusted-path-certificate","context":{"name":"mr-2889.pr.corp.censys.io","port":443,"type":"webentity"},"displayName":"No Trus...
Response Headers
Header | Description | Example |
|---|---|---|
access-control-allow-origin | HTTP response header: access-control-allow-origin | * |
Cache-Control | Directives for caching mechanisms | no-store, no-cache, must-revalidate, proxy-revalidate |
censys-response-type | HTTP response header: censys-response-type | ok |
cf-cache-status | HTTP response header: cf-cache-status | DYNAMIC |
CF-RAY | HTTP response header: CF-RAY | 8e7f83e73c6a1bdc-BOM |
Connection | HTTP response header: Connection | keep-alive |
Content-Encoding | HTTP response header: Content-Encoding | gzip |
Content-Length | The length of the response body in bytes | 22 |
Content-Type | The media type of the resource | application/json; charset=utf-8 |
Date | The date and time at which the message was originated | Tue, 05 Nov 2024 06:36:09 GMT |
expires | The date/time after which the response is considered stale | 0 |
pragma | HTTP response header: pragma | no-cache |
Server | Information about the software used by the origin server | cloudflare |
Set-Cookie | HTTP response header: Set-Cookie | __cf_bm=amomJNNBSAUU5hZ2spTI5TM81wgb6SEgVU4D_ne0np4-1730788671-1.0.1.1-CLGXuIz33UQh2bUMbVngUbj0A1y4nfBGs1cEUfbg.6.PR.B9azRiTFGzsTICsPd_Dhb3r73C1upx7OXs0l6qcQ; path=/; expires=Tue, 05-Nov-24 07:07:51 GMT; domain=.censys.io; HttpOnly; Secure; SameSite=None |
strict-transport-security | HTTP response header: strict-transport-security | max-age=2592000; includeSubDomains; preload |
surrogate-control | HTTP response header: surrogate-control | no-store |
traceparent | HTTP response header: traceparent | 00-aa92bbf9fbce52fbf534d2d52d3721a9-bcb7c162a53f6519-01 |
Transfer-Encoding | HTTP response header: Transfer-Encoding | chunked |
vary | HTTP response header: vary | Origin |
via | HTTP response header: via | 1.1 google |
x-frame-options | HTTP response header: x-frame-options | SAMEORIGIN |
x-ratelimit-limit | The number of requests allowed in the current rate limit window | 60000 |
x-ratelimit-remaining | The number of requests remaining in the current rate limit window | 59999 |
x-ratelimit-reset | The time at which the current rate limit window resets | Tue Nov 05 2024 06:37:08 GMT+0000 (Coordinated Universal Time) |