BitSight

Security Rating Services

Overview

The BitSight Connector integrates with the BitSight Security Ratings platform to synchronize portfolio companies, monitored assets (hosts and sites), and security findings. It pulls data from the BitSight Ratings API to populate Brinqa with company risk posture, asset inventory, and violations discovered by BitSight across diligence, user behavior, and public disclosure risk vectors.

---

Data retrieved from BitSight

Connector Object	Required	Maps to Data Model
Company	Yes	Company
Ip Asset	Yes	Host
Domain Asset	Yes	Site
Finding	Yes	Violation
Finding Definition	Yes	Violation Definition

Model relationships

note

For detailed steps on how to view the data retrieved from BitSight in the Brinqa Platform, see How to view your data.

Setup

Connection settings

When setting up a data integration, select BitSight from the Connector dropdown and provide the following:

Setting	Required	Default	Description
API URL	Yes	https://api.bitsighttech.com/	BitSight API URL
API token	Yes	—	BitSight api token
Page size	No	100	Maximum number of records to get per API request
Parallel requests	No	min(processors, 4)	Maximum number of parallel API requests
Maximum retries	No	5	Maximum number of API request retries
Finding UID fields	No	empty (→ temporary_id)	Comma-separated list of fields to use for finding UID. temporary_id will be used if not specified.
Request timeout (seconds)	No	600	The maximum seconds allotted before a request will time out. Min: 60 seconds (1 minute), Max: 3600 seconds (1 hour).
SSL / TLS	No	false	Skip certificate verification

Authentication

The connector uses HTTP Basic authentication with a BitSight API token. The token is the username of the basic-auth credential with an empty password, Base64-encoded on every request.

Endpoint

Method	URL
GET	https://api.bitsighttech.com/ratings/v2/portfolio

The test() operation validates credentials by calling the portfolio endpoint with limit=1.

Request Headers

Header	Value
Authorization	Basic <base64(apiToken)>

Request Body

Basic authentication carries no request body. The credential is supplied entirely via the Authorization header, so the validation request is a plain GET with no payload.

Sample Response

The credential-validation call (GET /ratings/v2/portfolio?limit=1&offset=0) returns the paginated portfolio listing:

{
  "links": {
    "next": "https://api.bitsighttech.com/ratings/v2/portfolio?limit=1&offset=1",
    "previous": null
  },
  "count": 42,
  "results": [
    {
      "guid": "ea4ec2d7-951a-4e0b-a7d9-317301c0aa61",
      "name": "Accenture plc",
      "shortname": "Accenture plc",
      "network_size_v4": 428523,
      "rating": 810,
      "rating_date": "2020-11-07",
      "added_date": "2015-04-01",
      "industry": { "name": "Business Services", "slug": "business_services" },
      "sub_industry": { "name": "Management Consulting", "slug": "management_consulting" },
      "primary_domain": "accenture.com",
      "life_cycle": null,
      "relationship": null
    }
  ]
}

Response Fields

Field	Description
count	Total number of portfolio companies available
links.next	URL of the next page of results (null on the last page)
links.previous	URL of the previous page of results (null on the first page)
results	Array of portfolio company records consumed by the Company model

A 2xx status with a parseable body confirms the API token is valid. A non-2xx status is surfaced as a connection error with the message returned by the BitSight API.

Usage

All subsequent API requests include the same header:

Authorization: Basic <Base64(apiToken)>

Obtain the API token from the BitSight UI: Account Settings → API Tokens.

---

Sync Behavior

The connector supports incremental (delta) syncs. It maintains a sync token between runs and applies it as an incremental timestamp filter, so each run re-processes only the records that changed after the previous sync. The initial run retrieves the complete data set; later runs are incremental. The specific timestamp field applied to each object is documented under that object's Sync Duration Parameter.

How to obtain BitSight credentials

Generate a BitSight API token

For the BitSight connector to access the BitSight API, you must provide an API token. To generate a new API token, follow these steps:

1. Log in to your organization's BitSight portal as an administrator.

2. Navigate to Settings > Account.

3. Locate the User API Token section on the page.

4. Click Generate New Token.

   

5. In the Warning window, click Confirm.

   Your new API token displays. 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 a token, contact your BitSight administrator. For additional information, see BitSight documentation.

Data & mappings

Attribute mappings

Expand the sections below to view the mappings between the source and the Brinqa data model attributes:

Company

Source Field Name	SDM Attribute
Portfolio.added_date	SOURCE_CREATED_DATE
Portfolio.guid	UID
Portfolio.industry.name	INDUSTRY
Portfolio.life_cycle.name	LIFECYCLE
Portfolio.name	NAME
Portfolio.network_size_v4	NETWORK_SIZE
Portfolio.primary_domain	PRIMARY_DOMAIN
Portfolio.rating	RATING
Portfolio.rating_date	LAST_ASSESSED
Portfolio.relationship.name	RELATIONSHIP
Portfolio.shortname	SHORT_NAME
Portfolio.sub_industry.name	SUB_INDUSTRY
—	LAST_CAPTURED

Ip Asset

Source Field Name	SDM Attribute
AssetResource.app_grade	APP_GRADE
AssetResource.asset	UID
AssetResource.asset	NAME
AssetResource.asset_type	TYPE
AssetResource.country	COUNTRY
AssetResource.country_code	COUNTRY_CODE
AssetResource.hosted_by.guid	HOSTED_BY_ID
AssetResource.hosted_by.name	HOSTED_BY_NAME
AssetResource.identifier	IDENTIFIER
AssetResource.importance	SOURCE_SEVERITY_SCORE
AssetResource.importance_category	SEVERITY
AssetResource.importance_category	SOURCE_SEVERITY
AssetResource.importance_category	SEVERITY_SCORE
AssetResource.ip_addresses	IP_ADDRESSES
AssetResource.ip_addresses	PUBLIC_IP_ADDRESSES
AssetResource.ip_addresses	PRIVATE_IP_ADDRESSES
AssetResource.is_ip	IS_IP
AssetResource.latitude	LATITUDE
AssetResource.longitude	LONGITUDE
AssetResource.origin_subsidiary.guid	ORIGIN_SUBSIDIARY_ID
AssetResource.origin_subsidiary.name	ORIGIN_SUBSIDIARY_NAME
AssetResource.services	SERVICES
AssetResource.tags	TAGS
AttributeValues.ASSET_CATEGORY_HOST + AssetResource.asset_type	CATEGORIES
Portfolio.guid	COMPANY
—	LAST_CAPTURED

Domain Asset

Source Field Name	SDM Attribute
AssetResource.app_grade	APP_GRADE
AssetResource.asset	UID
AssetResource.asset	NAME
AssetResource.asset_type	TYPE
AssetResource.country	COUNTRY
AssetResource.country_code	COUNTRY_CODE
AssetResource.hosted_by.guid	HOSTED_BY_ID
AssetResource.hosted_by.name	HOSTED_BY_NAME
AssetResource.identifier	IDENTIFIER
AssetResource.importance	SOURCE_SEVERITY_SCORE
AssetResource.importance_category	SEVERITY
AssetResource.importance_category	SOURCE_SEVERITY
AssetResource.importance_category	SEVERITY_SCORE
AssetResource.ip_addresses	IP_ADDRESSES
AssetResource.ip_addresses	PUBLIC_IP_ADDRESSES
AssetResource.ip_addresses	PRIVATE_IP_ADDRESSES
AssetResource.is_ip	IS_IP
AssetResource.latitude	LATITUDE
AssetResource.longitude	LONGITUDE
AssetResource.origin_subsidiary.guid	ORIGIN_SUBSIDIARY_ID
AssetResource.origin_subsidiary.name	ORIGIN_SUBSIDIARY_NAME
AssetResource.services	SERVICES
AssetResource.tags	TAGS
AttributeValues.ASSET_CATEGORY_DOMAIN + AssetResource.asset_type	CATEGORIES
Portfolio.guid	COMPANY
—	LAST_CAPTURED

Finding

Source Field Name	SDM Attribute
derived from IPs	PUBLIC_IP_ADDRESSES
derived from IPs	PRIVATE_IP_ADDRESSES
FindingDetail.check_pass	CHECK_PASS
FindingDetail.country	COUNTRY
FindingDetail.cvss.base	CVSS_BASE_SCORES
FindingDetail.cvss.base (max)	CVSS_BASE_SCORE_MAX
FindingDetail.dest_port	PORT
FindingDetail.diligence_annotations	DILIGENCE_ANNOTATIONS
FindingDetail.diligence_annotations	RESULTS
FindingDetail.final_location	FINAL_LOCATION
FindingDetail.geo_ip_location	GEO_IP_LOCATION
FindingDetail.grade	GRADE
FindingDetail.observed_ips / attributed_observed_ips + ips_to_be_remediated (for ssl_certificates)	IP_ADDRESSES
FindingDetail.rollup_end_date	ROLLUP_END_DATE
FindingDetail.rollup_start_date	ROLLUP_START_DATE
FindingDetail.sample_timestamp	SAMPLE_TIMESTAMP
FindingDetail.searchable_details	SEARCHABLE_DETAILS
FindingResource.affects_rating	AFFECTS_RATING
FindingResource.assets[].asset + FindingResource.evidence_key	TARGETS
FindingResource.attributed_companies[].guid	ATTRIBUTED_COMPANIES_ID
FindingResource.attributed_companies[].name	ATTRIBUTED_COMPANIES_NAME
FindingResource.evidence_key	EVIDENCE_KEY
FindingResource.first_seen	FIRST_SEEN
FindingResource.last_seen	LAST_SEEN
FindingResource.remediated	REMEDIATED
FindingResource.remediated / StatusValues.ACTIVE	STATUS
FindingResource.risk_vector	RISK_VECTOR
FindingResource.risk_vector_label	RISK_VECTOR_LABEL
FindingResource.rolledup_observation_id	ROLLEDUP_ID
FindingResource.severity	SOURCE_SEVERITY_SCORE
FindingResource.severity_category	SOURCE_SEVERITY
FindingResource.severity_category	SEVERITY
FindingResource.severity_category	SEVERITY_SCORE
FindingResource.temporary_id or MD5 of configured findingUidFields	UID
MD5(FindingResource.risk_vector + severity)	TYPE
Portfolio.guid	COMPANY
—	STATUS_CATEGORY
—	LAST_CAPTURED

Finding Definition

Source Field Name	SDM Attribute
FindingDetail.diligence_annotations["message"]	DESCRIPTION
FindingDetail.remediations[]	RECOMMENDATION
FindingResource.risk_category	CATEGORIES
FindingResource.risk_category	RISK_CATEGORY
FindingResource.risk_vector_label	NAME
FindingResource.severity	SOURCE_SEVERITY_SCORE
FindingResource.severity_category	SEVERITY
FindingResource.severity_category	SOURCE_SEVERITY
FindingResource.severity_category	SEVERITY_CATEGORY
FindingResource.severity_category	SEVERITY_SCORE
FindingResource.tags	TAGS
MD5(FindingResource.risk_vector + severity)	UID
—	LAST_CAPTURED

Operations & API

Operations & API

Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).

Company

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: REST · Endpoint: GET /ratings/v2/portfolio
• Default filters: start_date (derived from since, formatted yyyy-MM-dd) when an incremental token is provided

Ip Asset

Operation options

Option	Type	Default	Description
portfolioIds	Comma-separated list of portfolio GUIDs to scope the sync to specific companies. Matching is case-insensitive. When unset, all portfolios are fetched.	—
TRANSACTION_ID	Identifier used to scope the per-sync SimpleKVStore<AssetResource> that dedupes assets across portfolios. Defaults to the connector framework's null-transaction id when absent.	—
findings_total_count	Filter assets by exact findings total count (passed as findings.total_count query parameter).	—
findings_total_count_gt	Filter assets with findings total count greater than the specified value (passed as findings.total_count_gt query parameter).	—
findings_total_count_lt	Filter assets with findings total count less than the specified value (passed as findings.total_count_lt query parameter).	—
findings_total_count_gte	Filter assets with findings total count greater than or equal to the specified value (passed as findings.total_count_gte query parameter).	—
findings_total_count_lte	Filter assets with findings total count less than or equal to the specified value (passed as findings.total_count_lte query parameter).	—

Delta sync

Supported.

API

• Type: REST · Endpoint: GET /ratings/v1/companies/{portfolioGuid}/assets
• Default filters: is_ip=true; start_date (derived from since, formatted yyyy-MM-dd) when an incremental token is provided

Domain Asset

Operation options

Option	Type	Default	Description
portfolioIds	Comma-separated list of portfolio GUIDs to scope the sync to specific companies. Matching is case-insensitive. When unset, all portfolios are fetched.	—
TRANSACTION_ID	Identifier used to scope the per-sync SimpleKVStore<AssetResource> that dedupes assets across portfolios. Defaults to the connector framework's null-transaction id when absent.	—
findings_total_count	Filter assets by exact findings total count (passed as findings.total_count query parameter).	—
findings_total_count_gt	Filter assets with findings total count greater than the specified value (passed as findings.total_count_gt query parameter).	—
findings_total_count_lt	Filter assets with findings total count less than the specified value (passed as findings.total_count_lt query parameter).	—
findings_total_count_gte	Filter assets with findings total count greater than or equal to the specified value (passed as findings.total_count_gte query parameter).	—
findings_total_count_lte	Filter assets with findings total count less than or equal to the specified value (passed as findings.total_count_lte query parameter).	—

Delta sync

Supported.

API

• Type: REST · Endpoint: GET /ratings/v1/companies/{portfolioGuid}/assets
• Default filters: is_ip=false; start_date (derived from since, formatted yyyy-MM-dd) when an incremental token is provided

Finding

Operation options

Option	Type	Default	Description
portfolioIds	Comma-separated list of portfolio GUIDs to scope the sync to specific companies. Matching is case-insensitive. When unset, all portfolios are fetched.	—
TRANSACTION_ID	Identifier used to scope the PersistentArray<StoredCompanyFinding> that caches the paginated findings payload so Finding and FindingDefinition syncs within the same transaction share one fetch. Defaults to the connector framework's null-transaction id when absent.	—
grade	Filter findings by grade (passed as details.grade query parameter). Available values: NEUTRAL, BAD, WARN, FAIR, GOOD, NONE.	—
affects_rating	Boolean filter for findings that affect the BitSight rating (passed as affects_rating query parameter).	—
remediated	Boolean filter for remediated findings (passed as remediated query parameter).	—
severity_category	String filter for findings by severity category (passed as severity_category query parameter). Available values: severe, material, moderate, minor	—
risk_category	Filter findings by risk category (passed as risk_category query parameter). Available values : Compromised Systems, Diligence, User Behavior.	—
risk_vector	Filter findings by risk vector (passed as risk_vector query parameter).	—

Delta sync

Supported.

API

• Type: REST · Endpoint: GET /ratings/v1/companies/{portfolioGuid}/findings
• Default filters: start_date (derived from since, formatted yyyy-MM-dd) when an incremental token is provided

note

UID generation for this model is further influenced by the findingUidFields connector configuration property (see Configuration). This is a configuration value, not an OperationOptions entry. When set, the UID is MD5(concatenated values of the configured JSON pointer fields from the finding resource); when unset or all resolved values are blank, the UID falls back to FindingResource.temporary_id.

Finding Definition

Operation options

Option	Type	Default	Description
portfolioIds	Comma-separated list of portfolio GUIDs to scope the sync to specific companies. Matching is case-insensitive. When unset, all portfolios are fetched.	—
TRANSACTION_ID	Identifier used to scope the PersistentArray<StoredCompanyFinding> that caches the paginated findings payload (shared with the Finding sync). Defaults to the connector framework's null-transaction id when absent.	—
grade	Filter findings by grade (passed as details.grade query parameter). Available values: NEUTRAL, BAD, WARN, FAIR, GOOD, NONE.	—
affects_rating	Boolean filter for findings that affect the BitSight rating (passed as affects_rating query parameter).	—
remediated	Boolean filter for remediated findings (passed as remediated query parameter).	—
severity_category	String filter for findings by severity category (passed as severity_category query parameter). Available values: severe, material, moderate, minor	—
risk_category	Filter findings by risk category (passed as risk_category query parameter). Available values : Compromised Systems, Diligence, User Behavior.	—
risk_vector	Filter findings by risk vector (passed as risk_vector query parameter).	—

Delta sync

Supported.

API

• Type: REST · Endpoint: GET /ratings/v1/companies/{portfolioGuid}/findings
• Default filters: start_date (derived from since, formatted yyyy-MM-dd) when an incremental token is provided

Changelog

Changelog

The BitSight connector has undergone the following changes:

Version	Description	Migration Steps
3.0.9	Improvements - Incremental sync parameter: Changed the incremental sync query parameter from start_date to last_seen_gte for more accurate incremental data retrieval. - Finding — REMEDIATED attribute: Added new REMEDIATED boolean attribute to the Finding model, mapped from FindingResource.remediated. Indicates whether a finding has been remediated in BitSight. When a finding is remediated, the STATUS is automatically set to "fixed" and STATUS_CATEGORY is derived accordingly. - Findings & Assets — local store for portfolios: Portfolio data is now saved locally during sync, allowing multiple model syncs within the same transaction to reuse already-fetched portfolio data without repeated API calls. The portfolioIds filter is now passed as the guid query parameter to the API for server-side filtering, replacing the previous client-side filter. - Finding & FindingDefinition — server-side filtering: Added six new operation options to BaseFindingModel that are passed as API query parameters, enabling server-side filtering of findings before ingestion: - grade — filter by grade (details.grade), Available values: NEUTRAL, BAD, WARN, FAIR, GOOD, NONE - affects_rating — filter by whether the finding affects the BitSight rating - remediated — filter by remediation status - severity_category — filter by severity category, Available values: severe, material, moderate, minor - risk_category — filter by risk category, Available values: Compromised Systems, Diligence, User Behavior - risk_vector — filter by risk vector - API endpoint constants: Extracted PORTFOLIOS_ENDPOINT, FINDINGS_ENDPOINT, and ASSETS_ENDPOINT into BitSightModel as public static final constants, replacing inline string concatenation across all models. - Ip Asset & Domain Asset — server-side filtering by findings count: Added five new operation options for filtering assets by findings total count: - findings_total_count — filter assets by exact findings count - findings_total_count_gt — filter assets with findings count greater than value - findings_total_count_lt — filter assets with findings count less than value - findings_total_count_gte — filter assets with findings count greater than or equal to value - findings_total_count_lte — filter assets with findings count less than or equal to value - Ip Asset & Domain Asset - reduced memory consumption: Refactored asset deduplication to use disk-backed key-value storage with lightweight string keys instead of storing full asset objects in memory. Significantly reduces memory usage during large asset syncs across multiple portfolios. Documentation - README: Documented the new REMEDIATED attribute, six finding filter operation options, and corrected the incremental sync parameter name from start_date to last_seen_gte.	N/A
3.0.8	Improvements - Dependency upgrades — Updated platform SDK and parent build dependencies to the latest releases for stability and security fixes.	N/A
3.0.7	Bug Fixes - Finding — RESULTS attribute: Fixed malformed JSON rendering in the UI. Removed <b> HTML tags from the label that caused garbled {{ "{" }}...{{ "}" }} display. Added a second serialization pass using writerWithDefaultPrettyPrinter() to produce human-readable, indented JSON (diligence markdown). - Finding — DILIGENCE_ANNOTATIONS attribute: Retained as compact raw JSON string (diligence raw) — no changes to this attribute. Improvements - InstantDeserializer: Removed custom InstantDeserializer class and replaced with the platform SDK's OptionalInstantDeserializer.	N/A
3.0.6	Improvements - Asset sync deduplication — During asset synchronization, assets are tracked in a per-transaction key-value store so the same asset appearing across multiple portfolios is processed and handed to the handler only once per run. This eliminates duplicate connector objects and reduces redundant downstream processing when portfolios share assets.	N/A
3.0.5	New Features - Configurable finding identifier — Added a Finding UID fields setting that lets you choose which finding fields are combined to build each finding's unique identifier. When left blank, the connector continues to use the BitSight temporary ID, preserving existing behavior. - Configurable request timeout — Added a Request timeout (seconds) setting so you can tune how long the connector waits for a BitSight API response (minimum 60 seconds, maximum 3600 seconds), improving reliability against slow responses in large environments. Improvements - Finding details — Added handling for additional finding detail fields and more resilient timeout and retry behavior during synchronization.	• Finding: The finding identifier is unchanged by default. If you configure custom Finding UID fields, existing findings will be re-keyed under the new identifiers — Action: re-sync the BitSight data source so findings are recreated under their new UIDs.
3.0.4	New Features - Rolled-up observation ID — Findings now include the BitSight rolled-up observation identifier, making it easier to correlate related observations. - Finding definition guidance — Finding definitions now populate a description (from diligence annotation messages) and remediation recommendations, giving more actionable context for each finding type. Improvements - Asset targeting — Improved how findings are associated with their related assets so coverage is more complete.	N/A
3.0.3	New Features - CVSS scoring detail — Findings now capture all CVSS base scores as a multi-valued attribute along with the maximum CVSS base score, instead of a single value, giving a fuller picture of finding severity. Improvements - Severity and date handling — Refined severity scoring on finding definitions and standardized date/timestamp handling across findings, companies, and assets for more consistent values.	• Finding: The single CVSS_BASE_SCORE attribute has been replaced by a multi-valued CVSS_BASE_SCORES attribute plus a new CVSS_BASE_SCORE_MAX attribute — Action: re-sync the BitSight data source so findings are repopulated with the new CVSS attributes.
3.0.2	New Features - Portfolio filtering — Added the ability to limit synchronization to specific BitSight portfolios by providing a comma-separated list of portfolio IDs, so you can scope a data source to only the portfolios you care about and reduce sync time.	N/A
3.0.1	Improvements - Asset severity scoring — Asset importance is now recorded as a distinct source severity score, and the calculated severity score is populated as a numeric value rather than a concatenated string, producing cleaner and more usable severity data.	• Finding Definition: The RISK_CATEGORY attribute type changed from a numeric value to text to correctly reflect BitSight risk category labels — Action: re-sync the BitSight data source so finding definitions are repopulated with the corrected attribute type.
3.0.0	Overview The BitSight connector integrates with BitSight to synchronize rated companies, their internet-facing domain and IP assets, and the security findings and finding definitions that drive BitSight security ratings. Category: Security Rating Services Models	N/A