Bitsight
The Bitsight connector allows users to access detailed security performance insights and ratings for various organizations directly through the Swimlane platform.
Bitsight provides comprehensive security ratings and detailed insights into organizational security performance. With the Swimlane Turbine Bitsight connector, users can effortlessly retrieve detailed security issue insights for specified organizations, leveraging entity GUIDs to enhance threat analysis and risk management. This integration empowers end-users to prioritize risks effectively, streamline remediation efforts, and bolster their overall security posture without the need for complex coding.
Limitations
None to date.
Supported Versions
This Bitsight connector uses the Version 1 API.
Additional Docs
Configuration
Prerequisites
To effectively utilize the Bitsight connector for Swimlane Turbine, ensure you have the following:
- API Key Authentication with the necessary parameters:
- URL: Endpoint for the Bitsight API.
- API Token: Your unique identifier to authenticate with the Bitsight platform.
Authentication Methods
API Key Authentication:
- URL: The endpoint URL for the Bitsight API.
- API Token: Your unique identifier to authenticate with the Bitsight API.
Setup Instructions:
- Generating a Token: To generate a token, determine the token type and navigate to the User Preferences page: Settings β Account β User Preferences.
- Generating a User API Token
- In the User API Token section, select Generate New Token. Generate a new user token as needed, especially if you suspect your token has been compromised.
- Note: Generating a new user token will replace and invalidate the previous token.
- Generating a Company API Token Only admins and VRM admins can generate a company API token. Refer to user permissions for more details.
- In the Company API Token section, enter a description for the token in the New Token field, specifying its purpose.
- Select Generate, then copy the generated token and store it securely.
- The company API token is displayed only once for security purposes.
Capabilities
This Bitsight Connector provides the following capabilities:
- Companies Finding Details
Companies Finding Details
- Retrieve detailed findings for an organization in Bitsight, providing insights into specific security issues.
- Get an organizationβs finding details.
- This includes the finding details of risk types that affect or will affect security ratings; Compromised Systems, Diligence (except Domain Squatting), and User Behavior (File Sharing).
- This does not include Domain Squatting and Public Disclosures (Security Incidents and Other Disclosures), as their findings cannot be queried via the API.
Bitsight's documentation for this action can be found here.
Configurations
Bitsight API Key Authentication
Authenticates using an API Key
Configuration Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
url | A URL to the target host. | string | Required |
api_token | A unique API token used to access the Bitsight API securely. | string | Required |
verify_ssl | Verify SSL certificate | boolean | Optional |
http_proxy | A proxy to route requests through. | string | Optional |
Actions
Companies Finding Details
Retrieve detailed insights on security issues for a specified organization in Bitsight using the entity GUID.
Endpoint
- URL: /ratings/v1/companies/{{entity_guid}}/findings
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.entity_guid | string | Required | Unique Identifier for the Company. Identify the company to query. Portfolio companyβs unique identifier [entity_guid]. See GET Portfolio Details(https://help.bitsighttech.com/hc/en-us/articles/360055740193-GET-Portfolio-Details). |
parameters.fields | string | Optional | Comma-separated field names. Field names are the names of the fields in the response object. The order of the specific fields might not be reflected in the response. |
parameters.format | string | Optional | Set the format of the response data. Example - json. |
parameters.limit | number | Optional | Set the maximum number of results. The results might include fewer records (even zero), but not more. If not set, the default number of results can vary depending on the endpoint. |
parameters.offset | number | Optional | Set the starting point of the return. A 0 (zero) value starts the results from the first record in the result set. |
parameters.q | string | Optional | Perform a full-text search for matching records on all searchable fields. |
parameters.sort | string | Optional | Sort the response objects in alphabetical order. Field name. To sort in descending order, place a minus sign (-) immediately before the field name. Example - 'field_1,-field_2' first sorts by ascending field_1, and then by descending field_2. |
parameters.next | string | Optional | The link to navigate to the next page of the results. |
parameters.previous | string | Optional | The link to navigate to the previous page of the results. |
parameters.risk_category | string | Optional | To get details on specific risk categories, use the risk_category parameter along with the following comma-separated values Compromised Systems, Diligence, User Behavior. |
parameters.risk_vector | string | Optional | To get details on specific risk vectors, use the risk_vector parameter along with the following comma-separated values. |
parameters.affects_rating | boolean | Optional | Filter by findings that have an impact on the letter grade. true = Include only the findings that have an impact on the letter grade. |
parameters.affects_rating_details | string | Optional | Filter the result by the value of does_not_affect_rating_reason. Values may be used in combination. AFFECTS_RATING - Affects the risk vector grade. LIFETIME_EXPIRED - Does not affect the risk vector grade because the finding has reached the end of its lifetime. |
parameters.assets.asset | string | Optional | Filter by asset. Domain, IP Address. |
parameters.assets.category | string | Optional | Filter by asset importance. See asset importance(https://help.bitsighttech.com/hc/en-us/articles/360060231753-API-Fields-Asset-Importance). |
parameters.assets.combined_importance | string | Optional | Filter by combined asset importance. Comma-separated asset importance(https://help.bitsighttech.com/hc/en-us/articles/360060231753-API-Fields-Asset-Importance). |
parameters.assets.hosted_by | string | Optional | Filter by the hosting provider. Hosting providerβs unique identifier [entity_guid]. See GET Portfolio Details(https://help.bitsighttech.com/hc/en-us/articles/360055740193-GET-Portfolio-Details). |
parameters.attributed_companies.guid | array | Optional | Filter by companies in your Ratings Tree that are attributed to the finding. Comma-separated My Company or My Subsidiary unique identifiers [entity_guid]. See GET Portfolio Details(https://help.bitsighttech.com/hc/en-us/articles/360055740193-GET-Portfolio-Details). |
parameters.attributed_companies.name | array | Optional | Filter by companies in your Ratings Tree that are attributed to the finding. Comma-separated company names. |
parameters.details.cvss.base_gte | number | Optional | Include findings with vulnerabilities with a CVSS score greater than or equal to this value. Valid range - 1 to 10. |
parameters.details.cvss.base_lte | number | Optional | Include findings with vulnerabilities with a CVSS score less than or equal to this value. Valid range - 1 to 10. |
parameters.details.grade | string | Optional | Filter by Diligence finding grade or N/A for Compromised Systems and User Behavior findings. Incompatible with grade_lt and grade_gt. |
parameters.details.grade_gt | string | Optional | Include a range from the selected Diligence finding grade to GOOD. Incompatible with grade. |
parameters.details.grade_lt | string | Optional | Include a range from the selected Diligence finding grade to BAD. |
parameters.details.infection.family | string | Optional | Filter by infections. Comma-separated infection names. |
Input Example
{"parameters":{"fields":"affects_rating","format":"json","limit":100,"offset":100,"q":"","sort":"affects_rating","next":"","previous":"","risk_category":"Diligence","risk_vector":"open_ports","affects_rating":true,"affects_rating_details":"AFFECTS_RATING","assets.asset":"11.111.111.111","assets.category":"high","assets.combined_importance":"0.09","assets.hosted_by":"","attributed_companies.guid":[""],"attributed_companies.name":[""],"details.cvss.base_gte":1,"details.cvss.base_lte":1,"details.grade":"GOOD","details.grade_gt":"NEUTRAL","details.grade_lt":"GOOD","details.infection.family":"Gamarue","details.observed_ips_contains":"","details.vulnerabilities.severity":"minor","evidence_key":"11.111.111.111:23","expand":"tag_details","first_seen":"2025-02-04","first_seen_gt":"2025-02-04","first_seen_gte":"2025-02-04","first_seen_lt":"2025-02-04","first_seen_lte":"2025-02-04","guid":"4f99d64c-c3d8-4e08-b346-14f042e97116","last_remediation_status_date":"2025-02-04","last_remediation_status_date_gt":"2025-02-04","last_remediation_status_date_gte":"2025-02-04","last_remediation_status_date_lt":"2025-02-04","last_remediation_status_date_lte":"2025-02-04","last_remediation_status_label":"Open","last_seen":"2025-02-04","last_seen_gt":"2025-02-04","last_seen_gte":"2025-02-04","last_seen_lt":"2025-02-04","last_seen_lte":"2025-02-04","remediation_assignments":"4f99d64c-c3d8-4e08-b346-14f042e97116","risk_vector_label":"Open Ports","severity":3.9,"severity_gt":2.3,"severity_gte":3.4,"severity_lt":4.1,"severity_lte":5.1,"severity_category":2.5,"tags_contains":"saperix.com","unsampled":false,"vulnerabilities":"","count":1,"next_url":""},"path_parameters":{"entity_guid":"A9Jq47BBjea129322347d12e29c54b488752b3b71e"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
links | object | Output field: links |
links.previous | object | Output field: links.previous |
links.next | object | Output field: links.next |
count | number | Count value |
results | array | Result of the operation |
results.temporary_id | string | Unique identifier |
results.affects_rating | boolean | Result of the operation |
results.assets | array | Result of the operation |
results.assets.asset | string | Result of the operation |
results.assets.identifier | object | Unique identifier |
results.assets.category | string | Result of the operation |
results.assets.importance | number | Result of the operation |
results.assets.is_ip | boolean | Result of the operation |
results.assets.asset_type | string | Type of the resource |
results.assets.is_monitored | boolean | Result of the operation |
results.details | object | Result of the operation |
results.details.cvss | object | Result of the operation |
results.details.cvss.base | array | Result of the operation |
results.details.check_pass | string | Result of the operation |
results.details.evidence_key | string | Unique identifier |
results.details.first_seen | string | Result of the operation |
results.details.last_seen | string | Result of the operation |
results.details.related_findings | array | Result of the operation |
Output Example
{"links":{"previous":{},"next":{}},"count":123,"results":[{"temporary_id":"string","affects_rating":true,"assets":[],"details":{}}]}
Response Headers
Header | Description | Example |
|---|---|---|
Content-Type | The media type of the resource | application/json |
Date | The date and time at which the message was originated | Thu, 01 Jan 2024 00:00:00 GMT |