Censys
Censys is an external attack surface management tool that scans your assets for potential risks. You can bring certificate, domain, host, storage, and risk information from Censys into Brinqa to construct a unified view of your attack surface and strengthen your cybersecurity posture.
This document details the information you must provide for the connector to authenticate with Censys and how to obtain that information from Censys. See create a data integration for step-by-step instructions on setting up the integration.
Required connection settings
When setting up a data integration, select Censys from the Connector drop-down. If you cannot find the connector in the drop-down, make sure that you have installed it first. You must provide the following information to authenticate Censys with Brinqa:
-
API URL: The Censys API URL. The default URL is
https://app.censys.io. -
API key: The API key associated with the Censys account, which must have permissions to log in to the API server and return data.
-
Workspace ID: The Censys workspace ID. You can use commas to separate multiple workspace IDs. For additional information on workspaces, see Censys documentation.
Generate a Censys API key
For the Censys connector to use the Censys API, you must provide an API key. To generate an API key, follow these steps:
-
Log in to your organization's Censys account.
-
Click the API tab.
Your API ID and Secret display. Copy the Secret value. Although you can return to this page to view the token, you should handle it with care by ensuring that it is stored in a secure location.
If you do not have permissions to generate an API key, contact your Censys administrator. For additional information, see Censys documentation about workspaces and API keys.
Additional settings
The Censys connector contains an additional option for specific configuration:
- Page size: The maximum number of records to get per API request. The default setting is 100. It is not recommended to go over 100.
Types of data to retrieve
The Censys connector can retrieve the following types of data from the Censys API:
Table 1: Data retrieved from Censys
| Connector Object | Required | Maps to Data Model |
|---|---|---|
| Certificate | Yes | Certificate |
| Domain | Yes | Site |
| Host | Yes | Host |
| Risk Event | No | Not mapped |
| Risk Instance | Yes | Vulnerability |
| Risk Type | Yes | Vulnerability Definition |
| Storage Bucket | Yes | Cloud Resource |
The Censys connector does not currently support operation options for the types of data it retrieves.
For detailed steps on how to view the data retrieved from Censys in the Brinqa Platform, see How to view your data.
Attribute mappings
Expand the sections below to view the mappings between the source and the Brinqa data model attributes.
Certificate
Table 2: Certificate attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| ASSOCIATION_DATE | sourceCreatedDate |
| BROWSER_TRUST | Local variable |
| EXPIRATION_DATE | terminationDate |
| IN_USE | Local variable |
| IS_VALID | Local variable |
| ISSUER | owner |
| KEY_TYPE | Local variable |
| NAMES_ON_CERT | dnsNames |
| OWNERSHIP_STATUS | Local variable |
| SELF_SIGNED | Local variable |
| SHA_256 | Local variable |
| SYS_ID | uid |
| TAGS | tags |
Local variable indicates that the field is processed within a specific context, such as a particular workflow or calculation. Unlike other attributes, local variables aren't mapped to the unified data models. They only exist on the source data model.
Domain
Table 3: Domain attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| ASSOCIATION_DATE | sourceCreatedDate |
| DOMAIN | name |
| EXPIRATION_DATE | terminatedDate |
| MAIL_SERVERS | Local variable |
| NAME_SERVERS | Local variable |
| REGISTRAR | registry, Local variable |
| SYS_ID | uid |
| TAGS | tags |
Local variable indicates that the field is processed within a specific context, such as a particular workflow or calculation. Unlike other attributes, local variables aren't mapped to the unified data models. They only exist on the source data model.
Host
Table 4: Host attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| ASN | Local variable |
| ASSOCIATION_DATE | sourceCreatedDate |
| CLOUD | cloudProvider |
| COUNTRY_CODE | Local variable |
| IP_ADDRESS | ipAddresses |
| LATITUDE | Local variable |
| LONGITUDE | Local variable |
| NAMES | dnsNames |
| PORTS | Local variable |
| PROVINCE | Local variable |
| SYS_ID | uid |
| TAGS | tags |
Local variable indicates that the field is processed within a specific context, such as a particular workflow or calculation. Unlike other attributes, local variables aren't mapped to the unified data models. They only exist on the source data model.
Risk Instance
Table 5: Risk Instance attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| categories | categories |
| context.ip | ipAddresses, publicIpAddresses, privateIpAddresses |
| context.name | Local variable |
| context.port | port |
| context.service | service |
| context.transport | protocol |
| context.type | type |
| displayName | name |
| events.id | targets, Local variable |
| firstComputedAt | firstFound |
| id | uid |
| lastComputedAt | lastSeen |
| lastUpdatedAt | sourceLastModified |
| metadata | Local variable |
| severity | severity, sourceSeverity, severityScore |
| status | status, sourceStatus |
| typeID | targets |
Local variable indicates that the field is processed within a specific context, such as a particular workflow or calculation. Unlike other attributes, local variables aren't mapped to the unified data models. They only exist on the source data model.
Risk Type
Table 6: Risk Type attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| activeRiskCount | Local variable |
| addedAt | sourceCreatedDate |
| categories | categories |
| config | Local variable |
| contextType | Local variable |
| description | description |
| enabled | Local variable |
| events.id | targets, Local variable |
| id | uid |
| lastUpdatedAt | sourceLastModified |
| name | name |
| recommendedSeverity | Local variable |
| references | references |
| remediations | recommendation |
| riskCount | Local variable |
| severity | severity, sourceSeverity, severityScore |
| subjectType | Local variable |
Local variable indicates that the field is processed within a specific context, such as a particular workflow or calculation. Unlike other attributes, local variables aren't mapped to the unified data models. They only exist on the source data model.
Storage Bucket
Table 7: Storage Bucket attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| _details | Local variable |
| association_date | firstSeen |
| source | Local variable |
| storage_bucket.account_id | cloudAccountId |
| storage_bucket.editable_settings | Local variable |
| storage_bucket.name | name |
| storage_bucket.provider | cloudProvider |
| storage_bucket.readable_objects | Local variable |
| storage_bucket.scanned_at | lastScanned |
| storage_bucket.uri | url |
| storage_bucket.writable_objects | Local variable |
| tags | tags |
| type | type |
Local variable indicates that the field is processed within a specific context, such as a particular workflow or calculation. Unlike other attributes, local variables aren't mapped to the unified data models. They only exist on the source data model.
APIs
The Censys connector uses the Censys REST API v1 and v2. Specifically, it uses the following endpoints:
Table 8: Censys API Endpoints
| Connector Object | API Endpoints |
|---|---|
| Certificate | GET /api/inventory/v1 |
| Domain | GET /api/inventory/v1 |
| Host | GET /api/inventory/v1 |
| Risk Event | GET /api/v2/risk-events |
| Risk Instance | GET /api/v2/risk-instances |
| Risk Type | GET /api/v2/risk-types |
| Storage Bucket | GET /api/inventory/v1 |
Changelog
The Censys connector has undergone the following changes:
3.0.1
- Fixed an issue where tags for hosts were not populating.
3.0.0
- Initial Integration+ release.