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.

   

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Initial Integration+ release.