SecurityScorecard
Security Rating Services- Overview
- Setup
- Data & mappings
- Operations & API
- Changelog
The SecurityScorecard Connector integrates with the SecurityScorecard platform to synchronize portfolio companies, security issues (findings), and issue type definitions. It pulls data from the SecurityScorecard API to populate Brinqa with company risk ratings, security findings across multiple factors, and issue type metadata for classification.
Data retrieved from SecurityScorecard
| Connector Object | Required | Maps to Data Model |
|---|---|---|
| Company | Yes | Site |
| Issue | Yes | Violation |
| Issue Type | Yes | Violation Definition |
Model relationships
For detailed steps on how to view the data retrieved from SecurityScorecard in the Brinqa Platform, see How to view your data.
Connection settings
When setting up a data integration, select SecurityScorecard from the Connector dropdown and provide the following:
| Setting | Required | Default | Description |
|---|---|---|---|
| API URL | No | https://api.securityscorecard.io | SecurityScorecard API URL |
| API key | Yes | — | SecurityScorecard account API key |
| Portfolio ID | No | — | Optional - Limit sync to a specific portfolio - Leave empty to sync all portfolios |
Authentication
The connector authenticates with the SecurityScorecard API using an API key sent as a token in the Authorization header. The API key is generated from a SecurityScorecard account and supplied to the connector as a confidential configuration property.
There is no separate token-exchange request; the configured API key is attached to every API request.
Authorization Header
| Header | Value |
|---|---|
Authorization | Token {apiKey} |
Validation Endpoint
The connection is validated by issuing a request to the portfolios endpoint.
| Method | URL |
|---|---|
| GET | {url}/portfolios |
Request Headers
| Header | Value |
|---|---|
Authorization | Token {apiKey} |
Accept | application/json |
Sample Response
{
"entries": [
{
"id": "60c78cc8a4f3a30013b0cc11",
"name": "My Portfolio",
"privacy": "shared",
"read_only": false
}
]
}
Response Fields
| Field | Description |
|---|---|
entries[].id | Portfolio identifier used to enumerate companies. |
entries[].name | Portfolio display name. |
entries[].privacy | Portfolio privacy setting. |
entries[].read_only | Whether the portfolio is read-only. |
The same Authorization: Token {apiKey} header is sent on every subsequent request (portfolios, companies, company factors, issues, and issue-type metadata).
How to obtain SecurityScorecard credentials
Generate a SecurityScorecard API key
For the SecurityScorecard connector to retrieve data from the SecurityScorecard REST API, you must provide an API key. To do so, follow these steps:
-
Log in to your organization's SecurityScorecard portal as an administrator.
-
Click your profile photo in the top-right corner and in the dropdown, click My Settings.
-
Click API and then click Generate New API Token.
-
Click Confirm.
Your new API key displays. You can't view the key again after this. Copy and save it to a secure location.
Note: If you do not have permissions to generate a key, contact your SecurityScorecard administrator. For additional information, see SecurityScorecard documentation.
(Optional) Create a SecurityScorecard Bot user
In addition to using an API key tied to an existing user, you can also create a "Bot User" (also known as a service account) in SecurityScorecard. This account is specifically designed to access the SecurityScorecard API and retrieve data. For additional information, see SecurityScorecard documentation.
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 |
|---|---|
CompanyFactorResource.score | {factor.name} |
CompanyResource.domain | UID |
CompanyResource.domain | DOMAIN |
CompanyResource.grade | GRADE |
CompanyResource.industry | INDUSTRY |
CompanyResource.last30days_score_change | LAST_30_DAYS_SCORE_CHANGE |
CompanyResource.name | NAME |
CompanyResource.score | SCORE |
CompanyResource.size | SIZE |
| System timestamp | LAST_CAPTURED |
Issue
| Source Field Name | SDM Attribute |
|---|---|
CompanyResource.domain | TARGETS |
| Derived from status | STATUS_CATEGORY |
| Hardcoded "active" | PROVIDER_STATUS |
| Issue type key | TYPE |
IssueResource.analysis | ANALYSIS |
IssueResource.analysis_description | ANALYSIS_DESCRIPTION |
IssueResource.assets | ASSETS |
IssueResource.banner | BANNER |
IssueResource.browser | BROWSER |
IssueResource.cookie_name | COOKIE_NAME |
IssueResource.description | DESCRIPTION |
IssueResource.domain | DOMAIN |
IssueResource.dst_ip | DESTINATION_IP |
IssueResource.evidence | EVIDENCE |
IssueResource.final_url | FINAL_URL |
IssueResource.first_seen_time | FIRST_SEEN |
IssueResource.full_name | NAME |
IssueResource.hostname | HOSTNAMES |
IssueResource.initial_url | INITIAL_URL |
IssueResource.ip_address | IP_ADDRESSES |
IssueResource.ip_address | PUBLIC_IP_ADDRESSES |
IssueResource.ip_address | PRIVATE_IP_ADDRESSES |
IssueResource.issue_id | UID |
IssueResource.last_seen_time | LAST_SEEN |
IssueResource.malware_detection_methods | MALWARE_DETECTION_METHODS |
IssueResource.malware_family | MALWARE_FAMILY |
IssueResource.ports | PORTS |
IssueResource.product_latest_version | PRODUCT_LATEST_VERSION |
IssueResource.product_manufacturer | PRODUCT_MANUFACTURER |
IssueResource.product_name | PRODUCT_NAME |
IssueResource.product_state_ref | PRODUCT_STATE_REFERENCE |
IssueResource.product_state_status | PRODUCT_STATE_STATUS |
IssueResource.product_type | PRODUCT_TYPE |
IssueResource.product_version | PRODUCT_VERSION |
IssueResource.raw_cookie | RAW_COOKIE |
IssueResource.scheme | SCHEME |
IssueResource.services | SERVICES |
IssueResource.src_ip | SOURCE_IP |
IssueResource.state_effective_date | STATE_EFFECTIVE_DATE |
IssueResource.state_ref | STATE_REFERENCE |
IssueResource.target | TARGET |
IssueResource.url | URL |
IssueResource.url | REFERENCES |
IssueResource.user_agent | USER_AGENT |
IssueResource.vulnerability_description | VULNERABILITY_DESCRIPTION |
IssueResource.vulnerability_id | VULNERABILITY_ID |
IssueResource.vulnerability_publish_date | VULNERABILITY_PUBLISH_DATE |
IssueResource.vulnerability_url | VULNERABILITY_URL |
IssueResource.year | YEAR |
| Normalized status | SOURCE_STATUS |
| Normalized status | STATUS |
| System timestamp | LAST_CAPTURED |
Issue Type
| Source Field Name | SDM Attribute |
|---|---|
| Derived from normalized severity | SEVERITY_SCORE |
IssueTypeResource.factor | TAGS |
IssueTypeResource.key | UID |
IssueTypeResource.key | CATEGORIES |
IssueTypeResource.long_description | DESCRIPTION |
IssueTypeResource.recommendation | RECOMMENDATION |
IssueTypeResource.severity | SOURCE_SEVERITY |
IssueTypeResource.short_description | SUMMARY |
IssueTypeResource.title | NAME |
IssueTypeResource.title | TITLE |
Normalized from IssueTypeResource.severity | SEVERITY |
| System timestamp | LAST_CAPTURED |
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
The connector README does not document sync behavior for this object.
API
- Type: REST endpoint · Endpoint:
GET /portfolios/{portfolioId}/companies
Issue
Operation options
This object does not support any operation options.
Delta sync
The connector README does not document sync behavior for this object.
API
- Type: REST endpoint · Endpoint:
GET /companies/{domain}/issues/{issueType}
Issue Type
Operation options
This object does not support any operation options.
Delta sync
The connector README does not document sync behavior for this object.
API
- Type: REST endpoint · Endpoint:
GET /metadata/issue-types
Changelog
The SecurityScorecard connector has undergone the following changes:
| Version | Description | Migration Steps |
|---|---|---|
| 3.0.2 | New Features - Added optional Portfolio ID configuration property to limit sync to a specific portfolio scorecard instead of pulling all portfolios. Improvements - Added graceful error handling for Company and Issue sync: if a scorecard or company returns a permission error (e.g., HTTP 403 for private custom scorecards that are not shared), the connector logs a warning and proceeds with the remaining companies/portfolios instead of failing the entire sync. - Added standard LAST_CAPTURED attribute to all models to record sync capture time. - Added TAGS attribute to the Issue Type model. - Refined Issue Type model mappings: mapped the issue type's human-readable title to both NAME and TITLE, and the factor category to TAGS. - Standardized custom attribute reflection by adopting the getCustomAttributeInfos() helper pattern across all models. - Upgraded connectors-model version to 1.6.19. | N/A |
| 3.0.1 | Improvements - Connector-sourced attribute values now take precedence over non-connector data channels (manual edits, bulk imports, UI input) when the platform consolidates records, so SecurityScorecard data is no longer overridden by lower-priority sources. Bug Fixes - Corrected the Issue model's "Year" attribute to be stored as text (was a number), matching the value returned by the SecurityScorecard API. | • Issue: the "Year" attribute changed from a number to text. Re-sync the SecurityScorecard connector to repopulate issues with the corrected type. |
| 3.0.0 | Overview The SecurityScorecard connector integrates with SecurityScorecard to synchronize rated companies, the security issues identified against them, and the catalog of issue types used to classify those findings. Category: Security Rating Services Models | N/A |