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:

1. Log in to your organization's Censys account.

2. 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.

note

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 additional options 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.

• Maximum retries: The maximum number of times that the integration attempts to connect to the Censys API before giving up and reporting a failure. The default setting is 5.

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

info

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

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

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

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

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

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

info

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.

Operation options

The Censys connector supports the following operation options. See connector operation options for information about how to apply them.

Table 8: Censys connector operation options

Connector Object	Option	All Possible values	Description	Example
Risk Instance	includeEvents	true, false	Limit retrieved risk instances by whether to include associated event data.	Key: includeEvents Value: true. This key and value combination includes event data in the retrieved risk instances.
	includeHostData	true, false	Limit retrieved risk instances by whether to include associated host data.	Key: includeHostData Value: true. This key and value combination includes host data in the retrieved risk instances.

note

The option keys and values are case-sensitive as they are shown in this documentation.

APIs

The Censys connector uses the Censys REST API v1 and v2. Specifically, it uses the following endpoints:

Table 9: 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:

Table 10: Censys connector changelog

Version	Description
3.0.4	Updated the Censys logo to the current branding.
3.0.3	- Fixed an issue where the Risk Instance object sync was failing. - Added a new additional setting to help manage API throttling and optimize API call handling: Maximum retries. - Added two new operation options to the Risk Instance object to control whether event and host data is retrieved: includeEvents and includeHostData.
3.0.2	Fixed an issue where the Certificate and Storage Bucket object syncs were failing.
3.0.1	Fixed an issue where tags for hosts were not populating.
3.0.0	Initial Integration+ release.