watchTowr
watchTowr is an external attack surface management tool that scans your assets and generates findings against those assets. You can bring cloud storage, container, domain, IP, IP range, mobile application, SaaS platform, subdomain, and other security data from watchTowr into Brinqa to construct a comprehensive view of your attack surface, thus strengthening your cybersecurity posture.
This document details the information you must provide for the connector to authenticate with watchTowr and how to obtain that information from watchTowr. 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 watchTowr from the Connector drop-down list. You must provide the following information to authenticate watchTowr with Brinqa:
-
API URL: Your organization's watchTowr portal URL. The default format is
https://<organization-name>.watchtowr.com/. -
API key: The access key associated with the watchTowr account, which must have permissions to log in to the API server and return data.
infoThe watchTowr user must have at least the User role assigned to them in order to retrieve data from the watchTowr API. For additional information on roles, see watchTowr documentation.
Obtain a watchTowr API key
For the watchTowr connector to access the watchTowr API, you must provide an API key. To obtain an API key, follow these steps:
-
Log in to your organization's watchTowr portal as an administrator.
-
Navigate to Integrations > Client API.
-
Click Regenerate New API Token.
Your new API key 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.
-
In the API Whitelist Management section, you have two options:
-
Turn off whitelisting: Toggle API Whitelist Management to Off to disable IP whitelisting completely, allowing any IP address to access the watchTowr Client API.
-
Enable whitelisting: If you prefer to restrict access to specific IP addresses or ranges, please contact your Brinqa Support specialists so that they can assist you with the list of IP addresses or IP ranges for whitelisting.
-
If you do not have the permissions to create an API key, contact your watchTowr administrator. For additional information, see watchTowr documentation.
Additional settings
The watchTowr connector contains additional options for specific configuration:
-
Page size: The maximum number of records to get per API request. The default setting is 30. It is not recommended to go over 30.
-
Parallel requests: The maximum number of parallel API requests. The default setting is 4.
Types of data to retrieve
The watchTowr connector can retrieve the following types of data from the watchTowr API:
Table 1: Data retrieved from watchTowr
| Connector Object | Required | Maps to Data Model |
|---|---|---|
| Cloud Storage | Yes | Cloud Resource |
| Container | Yes | Container Image |
| Domain | Yes | Site |
| Finding | Yes | Vulnerability |
| Finding Definition | Yes | Vulnerability Definition |
| IP | Yes | Host |
| IP Range | Yes | IP Range |
| Mobile Application | Yes | Package |
| Repository | Yes | Code Repository |
| SaaS Platform | Yes | Site |
| Subdomain | Yes | Site |
For detailed steps on how to view the data retrieved from watchTowr 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.
Cloud Storage
Table 2: Cloud Storage attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| businessUnits | Local variable |
| created_at | sourceCreatedDate |
| deleted_at | Local variable |
| id | uid |
| name | name |
| platform | Local variable |
| source | Local variable |
| status | status |
| type | categories |
| updated_at | sourceLastModified |
| url | url |
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.
Container
Table 3: Container attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| businessUnits | Local variable |
| created_at | sourceCreatedDate |
| deleted_at | Local variable |
| id | uid |
| name | name |
| owner | owner |
| platform | Local variable |
| source | Local variable |
| status | status |
| type | categories |
| updated_at | sourceLastModified |
| url | url |
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 4: Domain attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| businessUnits | Local variable |
| created_at | sourceCreatedDate |
| deleted_at | Local variable |
| id | uid |
| live | Local variable |
| name | name |
| source | Local variable |
| status | status |
| type | categories |
| updated_at | sourceLastModified |
| whoisData | 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.
Finding
Table 5: Finding attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| affected.data.id | targets |
| assigned_user | Local variable |
| age | Local variable |
| created_at | sourceCreatedDate |
| cve_id | type, cveIds, cveRecords |
| evidence | results |
| finding_impact | Local variable |
| id | uid |
| impact | Local variable |
| last_seen | lastSeen |
| last_status_updated_at | sourceLastModified |
| recommendation | recommendation |
| references | references |
| retest.current_retest.completed_at | Local variable |
| retest.current_retest.requested_at | Local variable |
| retest.current_retest.requested_by | Local variable |
| retest.current_retest.retest_status | Local variable |
| retest.current_retest.status_occurred_at | Local variable |
| retest.retest_remaining | Local variable |
| retest_history | Local variable |
| severity | severity(calculate), sourceSeverity, severityScore |
| status | status(normalize), statusCategory, sourceStatus |
| tags | tags |
| title | name |
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.
Finding Definition
Table 6: Finding Definition attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| assigned_user | Local variable |
| age | Local variable |
| created_at | sourceCreatedDate |
| cve_id | type, cveIds, cveRecords |
| cvssv3_metrics | cvssV3Calculate |
| cvssv3_score | cvssV3BaseScore |
| description | description |
| epss_score | epssScore |
| finding_impact | Local variable |
| id | uid |
| impact | Local variable |
| recommendation | recommendation |
| references | references |
| retest.current_retest.completed_at | Local variable |
| retest.current_retest.requested_at | 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.
IP
Table 7: IP attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| businessUnits | Local variable |
| country | Local variable |
| created_at | sourceCreatedDate |
| deleted_at | Local variable |
| id | uid |
| live | Local variable |
| name | name, ipAddresses, publicIpAddress, ipAddresses, privateIpAddresses |
| source | Local variable |
| status | status |
| type | categories |
| updated_at | sourceLastModified |
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.
IP Range
Table 8: IP Range attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| asn | Local variable |
| businessUnits | Local variable |
| country | Local variable |
| created_at | sourceCreatedDate |
| deleted_at | Local variable |
| desc | description |
| id | uid |
| iprange | ipAddresses, publicIpAddress, privateIpAddresses |
| source | Local variable |
| status | status |
| type | categories |
| updated_at | sourceLastModified |
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.
Mobile Application
Table 9: Mobile Application attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| app_id | Local variable |
| businessUnits | Local variable |
| created_at | sourceCreatedDate |
| deleted_at | Local variable |
| id | uid |
| name | name |
| platform | Local variable |
| publisher | publisher |
| s3path | Local variable |
| source | Local variable |
| status | status |
| type | categories |
| updated_at | sourceLastModified |
| url | url |
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.
Repository
Table 10: Repository attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| businessUnits | Local variable |
| created_at | sourceCreatedDate |
| deleted_at | Local variable |
| id | uid |
| name | name |
| owner | owner |
| provider | Local variable |
| source | Local variable |
| status | status |
| type | categories |
| updated_at | sourceLastModified |
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.
SaaS Platform
Table 11: SaaS Platform attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| businessUnits | Local variable |
| created_at | sourceCreatedDate |
| deleted_at | Local variable |
| id | uid |
| provider | Cloud provider |
| source | Local variable |
| status | status |
| type | categories |
| updated_at | sourceLastModified |
| url | url, name |
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.
Subdomain
Table 12: Subdomain attribute mappings
| Source Field Name | Maps to Attribute |
|---|---|
| businessUnits | Local variable |
| created_at | sourceCreatedDate |
| deleted_at | Local variable |
| id | uid |
| live | Local variable |
| name | name |
| source | name, Local variable |
| status | status |
| type | categories |
| updated_at | sourceLastModified |
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 watchTowr connector supports the following operation options. See connector operation options for information about how to apply them.
Table 13: watchTowr connector operation options
| Connector Object | Option | All Possible Values | Description | Example |
|---|---|---|---|---|
| Cloud Storage | statuses | Incorrect Identification, pending, Third Party, Tracked, Unregistered, verified, VerifiedOutOfScope, VerifiedReducedAttack | A comma-separated list of cloud storage statuses. Retrieve cloud storage assets with the specified statuses. | Key: statuses Value: verified,Tracked. This key and value combination only retrieves verified and tracked cloud storages. |
| Container | statuses | Incorrect Identification, pending, Third Party, Tracked, Unregistered, verified, VerifiedOutOfScope, VerifiedReducedAttack | A comma-separated list of container statuses. Retrieve containers with the specified statuses. | Key: statuses Value: verified,Third Party. This key and value combination only retrieves verified and third party containers. |
| Domain | statuses | Incorrect Identification, pending, Third Party, Tracked, Unregistered, verified, VerifiedOutOfScope, VerifiedReducedAttack | A comma-separated list of domain statuses. Retrieve domains with the specified statuses. | Key: statuses Value: verified,Unreqistered. This key and value combination only retrieves verified and unregistered domains. |
| Finding | assetTypes | apiDocumentation, cloudAsset, cloudStorage, container, dnsRecord, domain, ip, ipRange, mobileApp, packageManager, port, repository, saasPlatform, subdomain | A comma-separated list of asset types. Retrieve findings from the specified asset types. | Key: assetTypes Value: mobileApp,saasPlatform. This key and value combination only retrieves findings from mobile apps and SaaS platforms. |
| severities | info, low, medium, high, critical | A comma-separated list of finding severities. Retrieve findings with the specified severities | Key: severities Value: medium,high,critical. This key and value combination only retrieves medium, high and critical findings. | |
| statuses | asset-no-longer-tracked, closed, confirmed, remediated, risk-accepted, unconfirmed | A comma-separated list of finding statuses. Retrieve findings with the specified statuses | Key: statuses Value: confirmed,risk-accepted. This key and value combination only retrieves confirmed and risk-accepted findings. |
The option keys and values are case-sensitive as they are shown in this documentation.
APIs
The watchTowr connector uses the watchTowr Platform Client API. Specifically, it uses the following endpoints:
Table 14: watchTowr API Endpoints
| Connector Object | API Endpoints |
|---|---|
| Cloud Storage | GET api/client/assets/cloudStorage/list |
| Container | GET api/client/assets/container/list |
| Domain | GET api/client/assets/domain/list |
| Finding | GET api/client/findings/list |
| Finding Definition | GET api/client/findings/list |
| IP | GET api/client/assets/ip/list |
| IP Range | GET api/client/assets/ipRange/list |
| Mobile Application | GET api/client/assets/mobileApp/list |
| Repository | GET api/client/assets/repository/list |
| SaaS Platform | GET api/client/assets/saasPlatform/list |
| Subdomain | GET api/client/assets/subdomain/list |
To view watchTowr Platform Client API documentation, log in to your watchTowr portal and navigate to Integrations > Client API > API Documentation.
Changelog
The watchTowr connector has undergone the following changes:
3.0.1
- Fixed an issue where the watchTowr connector sync was failing.
3.0.0
- Initial Integration+ release.