watchTowr
External Attack Surface Management- Overview
- Setup
- Data & mappings
- Operations & API
- Changelog
The watchTowr connector integrates with the watchTowr Attack Surface Management and Continuous Automated Red Teaming platform. It synchronizes the assets watchTowr discovers across your external attack surface — cloud storage, container images, domains, subdomains, IP addresses, IP ranges, mobile applications, code repositories, and SaaS platforms — together with the security findings raised against those assets and the underlying finding definitions (vulnerability definitions, including CVSS and EPSS scoring).
Data is retrieved from the watchTowr client API over HTTPS using paginated list endpoints. Asset and finding endpoints support incremental synchronization by filtering on the record's last-updated timestamp.
Data retrieved from watchTowr
| Connector Object | Required | Maps to Data Model |
|---|---|---|
| Cloud Resource | Yes | Cloud Resource |
| Container Image | Yes | Container Image |
| Domain | Yes | Site |
| Sub Domain | Yes | Site |
| Ip | Yes | Host |
| IP Range | Yes | IP Range |
| Mobile app | Yes | Package |
| Code Repository | Yes | Code Repository |
| Saas Platform | Yes | Site |
| Finding | Yes | Vulnerability |
| Finding Definition | Yes | Vulnerability Definition |
Model relationships
For detailed steps on how to view the data retrieved from watchTowr in the Brinqa Platform, see How to view your data.
Connection settings
When setting up a data integration, select watchTowr from the Connector dropdown and provide the following:
| Setting | Required | Default | Description |
|---|---|---|---|
| API URL | Yes | — | watchTowr security API URL |
| API key | Yes | — | watchTowr security API key |
| Page size | No | 30 | Maximum number of records to get per API request |
| Parallel requests | No | min(4, available processors) | Maximum number of parallel API requests |
Authentication
The connector authenticates with a long-lived API key that is sent as a Bearer token on every request.
The API key is supplied as connector configuration. On each request the connector sets:
Authorization: Bearer <apiKey>
There is no separate token-exchange/login step — the configured API key is used directly. Connectivity is validated against a lightweight list endpoint.
Test / Connectivity Endpoint
| Method | URL |
|---|---|
| GET | {url}/api/client/certificates/list?page=1&pageSize=1 |
Request Headers
| Header | Value |
|---|---|
Authorization | Bearer <apiKey> |
User-Agent | BrinqaWatchtowrConnector/<version> |
Accept | application/json |
Sample Response
{
"data": [
{
"id": 1,
"name": "example.com",
"status": "verified"
}
]
}
Response Fields
| Field | Description |
|---|---|
data | Array of records for the requested resource. The connector reads from the data node; a 2xx status confirms the credential is valid and the platform is reachable. |
A successful (2xx) response confirms the API key is valid; the same Authorization: Bearer <apiKey> header is reused on all subsequent asset and finding requests.
How to obtain watchTowr credentials
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.
-
Note: If you do not have the permissions to create an API key, contact your watchTowr administrator. For additional information, see watchTowr documentation.
Attribute mappings
Expand the sections below to view the mappings between the source and the Brinqa data model attributes:
Cloud Resource
| Source Field Name | SDM Attribute |
|---|---|
AssetResource.platform | PLATFORM |
AssetResource.url | URL |
Container Image
| Source Field Name | SDM Attribute |
|---|---|
AssetResource.owner | OWNER |
AssetResource.platform | PLATFORM |
AssetResource.url | URL |
Domain
| Source Field Name | SDM Attribute |
|---|---|
AssetResource.live | LIVE |
AssetResource.whoisData[].raw | WHO_IS |
Sub Domain
| Source Field Name | SDM Attribute |
|---|---|
AssetResource.live | LIVE |
Ip
| Source Field Name | SDM Attribute |
|---|---|
AssetResource.country | COUNTRY |
AssetResource.live | LIVE |
AssetResource.name | IP_ADDRESSES |
AssetResource.name (local) | PRIVATE_IP_ADDRESSES |
AssetResource.name (non-local) | PUBLIC_IP_ADDRESSES |
IP Range
| Source Field Name | SDM Attribute |
|---|---|
AssetResource.asn | ASN |
AssetResource.country | COUNTRY |
AssetResource.desc | DESCRIPTION |
AssetResource.iprange | IP_RANGE |
Mobile app
| Source Field Name | SDM Attribute |
|---|---|
AssetResource.app_id | APP_ID |
AssetResource.platform | PLATFORM |
AssetResource.publisher | PUBLISHER |
AssetResource.s3path | S3PATH |
AssetResource.url | URL |
Code Repository
| Source Field Name | SDM Attribute |
|---|---|
AssetResource.owner | OWNER |
AssetResource.provider | PROVIDER |
Saas Platform
| Source Field Name | SDM Attribute |
|---|---|
AssetResource.provider | CLOUD_PROVIDER |
AssetResource.url | URL |
AssetResource.url | NAME |
Finding
| Source Field Name | SDM Attribute |
|---|---|
| derived from normalized status | STATUS_CATEGORY |
FindingResource.affected.data.id | TARGETS |
FindingResource.age | AGE |
FindingResource.assigned_user.name | ASSIGNED_USER_NAME |
FindingResource.created_at | SOURCE_CREATED_DATE |
FindingResource.evidence | RESULTS |
FindingResource.finding_impact | FINDING_IMPACT |
FindingResource.id | UID |
FindingResource.id | NAME |
FindingResource.impact | IMPACT |
FindingResource.last_seen | LAST_SEEN |
FindingResource.last_status_updated_at | SOURCE_LAST_MODIFIED |
FindingResource.retest.current_retest.completed_at | CURRENT_RETEST_COMPLETED_AT |
FindingResource.retest.current_retest.requested_at | CURRENT_RETEST_REQUESTED_AT |
FindingResource.retest.current_retest.requested_by | CURRENT_RETEST_REQUESTED_BY |
FindingResource.retest.current_retest.retest_status | CURRENT_RETEST_STATUS |
FindingResource.retest.current_retest.status_occurred_at | CURRENT_RETEST_STATUS_OCCURRED_AT |
FindingResource.retest.retest_remaining | RETEST_REMAINING |
FindingResource.status | SOURCE_STATUS |
FindingResource.tags[].id + name | TAGS |
FindingResource.title | TYPE |
normalized FindingResource.status | STATUS |
Finding Definition
| Source Field Name | SDM Attribute |
|---|---|
| calculated from CVSS v3 vector | CVSS_V3_BASE_SCORE |
| calculated from CVSS v3 vector | CVSS_V3_TEMPORAL_SCORE |
| derived from normalized severity | SEVERITY_SCORE |
FindingResource.cve_id | CVE_IDS |
FindingResource.cve_id | CVE_RECORDS |
FindingResource.cvssv3_metrics | CVSS_V3_VECTOR |
FindingResource.description | DESCRIPTION |
FindingResource.epss_score | EPSS_SCORE |
FindingResource.recommendation | RECOMMENDATION |
FindingResource.references | REFERENCES |
FindingResource.severity | SOURCE_SEVERITY |
FindingResource.title | UID |
FindingResource.title | NAME |
normalized FindingResource.severity | SEVERITY |
| parsed from CVSS v3 vector | CVSS_V3_AV |
| parsed from CVSS v3 vector | CVSS_V3_AC |
| parsed from CVSS v3 vector | CVSS_V3_PR |
| parsed from CVSS v3 vector | CVSS_V3_UI |
| parsed from CVSS v3 vector | CVSS_V3_CI |
| parsed from CVSS v3 vector | CVSS_V3_II |
| parsed from CVSS v3 vector | CVSS_V3_AI |
| parsed from CVSS v3 vector | CVSS_V3_E |
| parsed from CVSS v3 vector | CVSS_V3_RL |
| parsed from CVSS v3 vector | CVSS_V3_RC |
| parsed from CVSS v3 vector | CVSS_V3_SEVERITY |
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).
Cloud Resource
Operation options
This object does not support any operation options.
Delta sync
Supported.
API
- Type: REST endpoint · Endpoint:
GET api/client/assets/cloudStorage/list
Container Image
Operation options
This object does not support any operation options.
Delta sync
Supported.
API
- Type: REST endpoint · Endpoint:
GET api/client/assets/container/list
Domain
Operation options
This object does not support any operation options.
Delta sync
Supported.
API
- Type: REST endpoint · Endpoint:
GET api/client/assets/domain/list
Sub Domain
Operation options
This object does not support any operation options.
Delta sync
Supported.
API
- Type: REST endpoint · Endpoint:
GET api/client/assets/subdomain/list
Ip
Operation options
This object does not support any operation options.
Delta sync
Supported.
API
- Type: REST endpoint · Endpoint:
GET api/client/assets/ip/list
IP Range
Operation options
This object does not support any operation options.
Delta sync
Supported.
API
- Type: REST endpoint · Endpoint:
GET api/client/assets/ipRange/list
Mobile app
Operation options
This object does not support any operation options.
Delta sync
Supported.
API
- Type: REST endpoint · Endpoint:
GET api/client/assets/mobileApp/list
Code Repository
Operation options
This object does not support any operation options.
Delta sync
Supported.
API
- Type: REST endpoint · Endpoint:
GET api/client/assets/repository/list
Saas Platform
Operation options
This object does not support any operation options.
Delta sync
Supported.
API
- Type: REST endpoint · Endpoint:
GET api/client/assets/saasPlatform/list
Finding
Operation options
This object does not support any operation options.
Delta sync
Supported.
API
- Type: REST endpoint · Endpoint:
GET api/client/findings/list
Finding Definition
Operation options
This object does not support any operation options.
Delta sync
Supported.
API
- Type: REST endpoint · Endpoint:
GET api/client/findings/list
Changelog
The watchTowr connector has undergone the following changes:
| Version | Description | Migration Steps |
|---|---|---|
| 3.0.6 | 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 watchTowr data is no longer overridden by lower-priority sources. Bug Fixes - Corrected the Finding model's "Current retest status occurred at" attribute to be stored as a proper timestamp (was text), matching the value returned by the watchTowr API. | • Finding: the "Current retest status occurred at" attribute changed from text to a timestamp. Re-sync the watchTowr connector to repopulate findings with the corrected type. |
| 3.0.5 | Improvements Dependency Upgrades - Upgraded internal framework and model libraries to the latest stable versions for improved reliability, security patches, and alignment with the rest of the connector platform. | N/A |
| 3.0.4 | Improvements - Outbound requests to watchTowr now include a connector-specific User-Agent that identifies the connector and its version, making connector traffic easier to attribute and troubleshoot on the watchTowr side. Dependency Upgrades - Upgraded internal framework and model libraries to the latest stable versions for improved reliability, security patches, and alignment with the rest of the connector platform. | N/A |
| 3.0.3 | Bug Fixes - Resolved a sync failure that could occur when the watchTowr API returned a domain's name servers as either a single value or a list. Asset collection now tolerates both shapes without erroring. | N/A |
| 3.0.2 | Bug Fixes - Improved resilience when parsing WHOIS data returned by the watchTowr API, preventing potential sync errors caused by an inconsistently shaped field that the connector does not use. | N/A |
| 3.0.1 | New Features - Initial release of the watchTowr connector. Synchronizes watchTowr Attack Surface Management data into the platform, covering a broad range of asset types — domains and subdomains, IP addresses and IP ranges, cloud resources, code repositories, container images, mobile apps, and SaaS platforms — along with their security findings and finding definitions. | N/A |