Skip to main content

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.

    info

    The 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:

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

  2. Navigate to Integrations > Client API.

    watchTowr client API

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

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

note

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 ObjectRequiredMaps to Data Model
Cloud StorageYesCloud Resource
ContainerYesContainer Image
DomainYesSite
FindingYesVulnerability
Finding DefinitionYesVulnerability Definition
IPYesHost
IP RangeYesIP Range
Mobile ApplicationYesPackage
RepositoryYesCode Repository
SaaS PlatformYesSite
SubdomainYesSite
info

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 NameMaps to Attribute
businessUnitsLocal variable
created_atsourceCreatedDate
deleted_atLocal variable
iduid
namename
platformLocal variable
sourceLocal variable
statusstatus
typecategories
updated_atsourceLastModified
urlurl
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.

Container

Table 3: Container attribute mappings

Source Field NameMaps to Attribute
businessUnitsLocal variable
created_atsourceCreatedDate
deleted_atLocal variable
iduid
namename
ownerowner
platformLocal variable
sourceLocal variable
statusstatus
typecategories
updated_atsourceLastModified
urlurl
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.

Domain

Table 4: Domain attribute mappings

Source Field NameMaps to Attribute
businessUnitsLocal variable
created_atsourceCreatedDate
deleted_atLocal variable
iduid
liveLocal variable
namename
sourceLocal variable
statusstatus
typecategories
updated_atsourceLastModified
whoisDataLocal variable
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.

Finding

Table 5: Finding attribute mappings

Source Field NameMaps to Attribute
affected.data.idtargets
assigned_userLocal variable
ageLocal variable
created_atsourceCreatedDate
cve_idtype, cveIds, cveRecords
evidenceresults
finding_impactLocal variable
iduid
impactLocal variable
last_seenlastSeen
last_status_updated_atsourceLastModified
recommendationrecommendation
referencesreferences
retest.current_retest.completed_atLocal variable
retest.current_retest.requested_atLocal variable
retest.current_retest.requested_byLocal variable
retest.current_retest.retest_statusLocal variable
retest.current_retest.status_occurred_atLocal variable
retest.retest_remainingLocal variable
retest_historyLocal variable
severityseverity(calculate), sourceSeverity, severityScore
statusstatus(normalize), statusCategory, sourceStatus
tagstags
titlename
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.

Finding Definition

Table 6: Finding Definition attribute mappings

Source Field NameMaps to Attribute
assigned_userLocal variable
ageLocal variable
created_atsourceCreatedDate
cve_idtype, cveIds, cveRecords
cvssv3_metricscvssV3Calculate
cvssv3_scorecvssV3BaseScore
descriptiondescription
epss_scoreepssScore
finding_impactLocal variable
iduid
impactLocal variable
recommendationrecommendation
referencesreferences
retest.current_retest.completed_atLocal variable
retest.current_retest.requested_atLocal variable
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.

IP

Table 7: IP attribute mappings

Source Field NameMaps to Attribute
businessUnitsLocal variable
countryLocal variable
created_atsourceCreatedDate
deleted_atLocal variable
iduid
liveLocal variable
namename, ipAddresses, publicIpAddress, ipAddresses, privateIpAddresses
sourceLocal variable
statusstatus
typecategories
updated_atsourceLastModified
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.

IP Range

Table 8: IP Range attribute mappings

Source Field NameMaps to Attribute
asnLocal variable
businessUnitsLocal variable
countryLocal variable
created_atsourceCreatedDate
deleted_atLocal variable
descdescription
iduid
iprangeipAddresses, publicIpAddress, privateIpAddresses
sourceLocal variable
statusstatus
typecategories
updated_atsourceLastModified
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.

Mobile Application

Table 9: Mobile Application attribute mappings

Source Field NameMaps to Attribute
app_idLocal variable
businessUnitsLocal variable
created_atsourceCreatedDate
deleted_atLocal variable
iduid
namename
platformLocal variable
publisherpublisher
s3pathLocal variable
sourceLocal variable
statusstatus
typecategories
updated_atsourceLastModified
urlurl
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.

Repository

Table 10: Repository attribute mappings

Source Field NameMaps to Attribute
businessUnitsLocal variable
created_atsourceCreatedDate
deleted_atLocal variable
iduid
namename
ownerowner
providerLocal variable
sourceLocal variable
statusstatus
typecategories
updated_atsourceLastModified
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.

SaaS Platform

Table 11: SaaS Platform attribute mappings

Source Field NameMaps to Attribute
businessUnitsLocal variable
created_atsourceCreatedDate
deleted_atLocal variable
iduid
providerCloud provider
sourceLocal variable
statusstatus
typecategories
updated_atsourceLastModified
urlurl, name
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.

Subdomain

Table 12: Subdomain attribute mappings

Source Field NameMaps to Attribute
businessUnitsLocal variable
created_atsourceCreatedDate
deleted_atLocal variable
iduid
liveLocal variable
namename
sourcename, Local variable
statusstatus
typecategories
updated_atsourceLastModified
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 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 ObjectOptionAll Possible ValuesDescriptionExample
Cloud StoragestatusesIncorrect Identification, pending, Third Party, Tracked, Unregistered, verified, VerifiedOutOfScope, VerifiedReducedAttackA 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.
ContainerstatusesIncorrect Identification, pending, Third Party, Tracked, Unregistered, verified, VerifiedOutOfScope, VerifiedReducedAttackA 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.
DomainstatusesIncorrect Identification, pending, Third Party, Tracked, Unregistered, verified, VerifiedOutOfScope, VerifiedReducedAttackA 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.
FindingassetTypesapiDocumentation, cloudAsset, cloudStorage, container, dnsRecord, domain, ip, ipRange, mobileApp, packageManager, port, repository, saasPlatform, subdomainA 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.
severitiesinfo, low, medium, high, criticalA comma-separated list of finding severities. Retrieve findings with the specified severitiesKey: severities Value: medium,high,critical. This key and value combination only retrieves medium, high and critical findings.
statusesasset-no-longer-tracked, closed, confirmed, remediated, risk-accepted, unconfirmedA comma-separated list of finding statuses. Retrieve findings with the specified statusesKey: statuses Value: confirmed,risk-accepted. This key and value combination only retrieves confirmed and risk-accepted findings.
note

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 ObjectAPI Endpoints
Cloud StorageGET api/client/assets/cloudStorage/list
ContainerGET api/client/assets/container/list
DomainGET api/client/assets/domain/list
FindingGET api/client/findings/list
Finding DefinitionGET api/client/findings/list
IPGET api/client/assets/ip/list
IP RangeGET api/client/assets/ipRange/list
Mobile ApplicationGET api/client/assets/mobileApp/list
RepositoryGET api/client/assets/repository/list
SaaS PlatformGET api/client/assets/saasPlatform/list
SubdomainGET api/client/assets/subdomain/list
info

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