WatchTowr API

the watchtowr api connector allows for streamlined management of security threats by providing actions to interact with notes, hunts, findings, and assets watchtowr is a cutting edge security platform that specializes in identifying and managing digital risks across various assets the watchtowr api connector for swimlane turbine enables users to automate the retrieval of detailed information on findings, hunts, and suspicious domains, as well as manage notes and statuses for assets within the watchtowr ecosystem by integrating with swimlane turbine, security teams can enhance their threat intelligence and incident response capabilities, streamline security operations, and maintain a proactive security posture by leveraging real time data and actionable insights from watchtowr limitations none to date supported versions this connector supports the latest version of watchtowr api prerequisites to utilize the watchtowr api connector within swimlane, ensure you have the following prerequisites http bearer token authentication with the following parameters url endpoint for the watchtowr api token a valid bearer token to authenticate api requests capabilities this connector provides the following capabilities create note update note get hunt details list hunts list hunt findings get finding details list finding statuses update finding status reset finding list assets list suspicious domains get suspicious domain details create note create a note for a specific api documentation asset watchtowr's documentation for this action can be found here https //apidocs watchtowr io/apis/adversary sight openapi/api documentation/add asset apidocumentation note update note update a note of a specific api documentation asset watchtowr's documentation for this action can be found here https //apidocs watchtowr io/apis/adversary sight openapi/api documentation/update asset apidocumentation note get hunt details get the details of a specific hunt watchtowr's documentation for this action can be found here https //apidocs watchtowr io/apis/intelligence openapi/hunts/show the detail hunt list hunts list all available hunt assets, ordered by creation date watchtowr's documentation for this action can be found here https //apidocs watchtowr io/apis/intelligence openapi/hunts/get client hunts list hunt findings list all findings for a specific hunt watchtowr's documentation for this action can be found here https //apidocs watchtowr io/apis/intelligence openapi/hunts/get list finding by hunt get finding details get the details of a specific finding watchtowr's documentation for this action can be found here https //apidocs watchtowr io/apis/continuous assurance openapi/findings/get finding details list finding statuses list all available statuses for findings watchtowr's documentation for this action can be found here https //apidocs watchtowr io/apis/continuous assurance openapi/findings/get available finding statuses update finding status update the status of a specific finding watchtowr's documentation for this action can be found here https //apidocs watchtowr io/apis/continuous assurance openapi/findings/update finding status reset finding initiate a retest for a specific finding watchtowr's documentation for this action can be found here https //apidocs watchtowr io/apis/continuous assurance openapi/findings/start specific finding retest list assets get a list of assets for a specific hunt watchtowr's documentation for this action can be found here https //apidocs watchtowr io/apis/intelligence openapi/hunts/get list asset by hunt list suspicious domains list all discovered suspicious domain assets, ordered by discovery date watchtowr's documentation for this action can be found here https //apidocs watchtowr io/apis/intelligence openapi/suspicious domains/get list suspicious domain get suspicious domain details get the details of a specific suspicious domain watchtowr's documentation for this action can be found here https //apidocs watchtowr io/apis/intelligence openapi/suspicious domains/get suspicious domain details configurations http bearer authentication watchtowr api authentication using bearer token configuration parameters parameter description type required url a url to the target host string required token the bearer token to authenticate with string required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions create note creates a note for a specified api documentation asset using the provided 'id' and 'note' content endpoint url /api/client/assets/apidocumentation/show/{{id}}/note method post input argument name type required description path parameters id number required the asset id of the api documentation asset to create a new note for note string optional content of the note title string optional title of the note input example {"json body" {"note" "passed to the engineering team review on 01/07/2024","title" "initial review 01/01/2024"},"path parameters" {"id" 1234}} output parameter type description status code number http status code of the response reason string response reason phrase data object response data data id number response data data note string response data data note type string response data data note id number response data data title string response data data author object response data data author id number response data data author name string response data data last modified string response data output example {"status code" 200,"reason" "ok","json body" {"data" {"id" 1,"note" "passed to the engineering team review on 01/07/2024","note type" "domain","note id" 2,"title" "initial review 01/01/2024","author" {},"last modified" "2022 02 13t02 10 00 000000z"}}} get finding details retrieve detailed information for a specific finding in watchtowr api using the unique identifier endpoint url /api/client/findings/show/{{id}} method get input argument name type required description path parameters id number required the id of the finding to retrieve input example {"path parameters" {"id" 1234}} output parameter type description status code number http status code of the response reason string response reason phrase data object response data data id number response data data title string response data data description string response data data impact string response data data finding impact string response data data tags array response data data tags id number response data data tags name string response data data evidence string response data data recommendation string response data data severity string response data data cvssv3 score number response data data cvssv3 metrics string response data data status string response data data created at string response data data affected object response data data cve id string response data data epss score number response data data retest object response data data retest retest remaining number response data data retest current retest object response data data retest current retest requested by string response data output example {"status code" 200,"reason" "ok","json body" {"data" {"id" 1,"title" "valid credentials discovered in business system","description" "through watchtowr's credential stuffing capabilities, a valid set of credentials ","impact" "depending on the system, if leveraged by an attacker it may be possible to \n\n g ","finding impact" "prioritised findings","tags" \[],"evidence" "url https //example com/adfs/ls\n\nvalid credentials discovered \nusername user\np ","recommendation" "as a priority, get hunt details retrieve detailed information for a specific hunt identified by its unique id in the watchtowr api endpoint url /api/client/hunts/show/{{id}} method get input argument name type required description path parameters id number required parameters for the get hunt details action input example {"path parameters" {"id" 1234}} output parameter type description status code number http status code of the response reason string response reason phrase data object response data data id number response data data priority string response data data type string response data data created at string response data data updated at string response data data total findings number response data data total assets number response data data hunt request type string response data data rapid exposure mechanism string response data data title string response data data description string response data data hypothesis string response data data references array response data data completed at string response data data completed by string response data data requested by string response data data status string response data output example {"status code" 200,"reason" "ok","json body" {"data" {"id" 1,"priority" "high","type" "bespoke","created at" "2023 06 28t02 22 36 000z","updated at" "2023 06 28t02 22 36 000z","total findings" 1,"total assets" 10,"hunt request type" "others","rapid exposure mechanism" "impactlesspoc","title" "hunt for itw exploited command injection in palo alto networks globalprotect gat ","description" "\\"watchtowr performed a proactive hunt to determine if there are any instances of ","hypothesis" "\\"a se get suspicious domain details retrieve detailed information about a specific suspicious domain using its unique identifier endpoint url /api/client/suspicious domain/show/{{id}} method get input argument name type required description path parameters id number required the id of the suspicious domain to retrieve input example {"path parameters" {"id" 1234}} output parameter type description status code number http status code of the response reason string response reason phrase data object response data data id number response data data name string response data data discovery reason string response data data status string response data data whoisdata array response data data whoisdata id number response data data whoisdata data object response data data whoisdata data org string response data data whoisdata data city string response data data whoisdata data name string response data data whoisdata data state string response data data whoisdata data dnssec string response data data whoisdata data emails array response data data whoisdata data status array response data data whoisdata data address string response data data whoisdata data country string response data data whoisdata data zipcode string response data data whoisdata data registrar string response data data whoisdata data domain name string response data data whoisdata data name servers array response data data whoisdata data referral url string response data data whoisdata data whois server string response data output example {"status code" 200,"reason" "ok","json body" {"data" {"id" 1,"name" "example com","discovery reason" "example reason","status" "legitimate","whoisdata" \[],"created at" "2022 02 22 22 00 00"}}} list assets retrieve a list of assets associated with a specific hunt id from the watchtowr api endpoint url /api/client/hunts/show/{{id}}/assets method get input argument name type required description parameters page number optional the page number for paginated results parameters pagesize number optional the number of items to be included on each page of paginated results path parameters id number required hunt id of the hunt to retrieve assets from input example {"parameters" {"page" 1,"pagesize" 20},"path parameters" {"id" 1234}} output parameter type description status code number http status code of the response reason string response reason phrase data array response data data type string response data data source string response data data status string response data data created at string response data data id string response data data country object response data data platform object response data data provider object response data data url string response data data name string response data data businessunits array response data data businessunits file name string response data data businessunits file string response data data discovery reason object response data data owner object response data data live boolean response data data sub type string response data data super type string response data data metadata object response data meta object output field meta meta pagination object output field meta pagination meta pagination total number output field meta pagination total output example {"status code" 200,"reason" "ok","json body" {"data" \[{"type" "repository","source" "initial data","status" "verified","created at" "2021 11 22t22 17 12 000z","id" "1","country"\ null,"platform"\ null,"provider" "test provider","url"\ null,"name" "test name","businessunits" \[],"discovery reason" "discovery reason test data","owner" "test owner","live"\ null,"sub type"\ null,"super type"\ null,"metadata" {}},{"type" "repository","source" "module github enumeration v0 1","status" "verified","created at" list finding statuses retrieve a list of all available statuses for findings within the watchtowr api endpoint url /api/client/findings/statuses method get output parameter type description status code number http status code of the response reason string response reason phrase data array response data data 0 string response data data 1 string response data data 2 string response data data 3 string response data data 4 string response data data 5 string response data output example {"status code" 200,"reason" "ok","json body" {"data" \[\[]]}} list findings retrieve a list of all discovered findings from watchtowr api, sorted by the date they were identified endpoint url /api/client/findings/list method get input argument name type required description parameters page number optional the page number for paginated results parameters pagesize number optional the number of items to be included on each page of paginated results parameters created from string optional filter findings created after a given date and time parameters created to string optional filter findings created before a given date and time parameters updated from string optional filter findings updated after a given date and time parameters updated to string optional filter findings updated before a given date and time parameters statuses string optional filter findings by a list of comma separated statuses they're tagged with parameters businessunitids string optional filter findings by a list of comma separated business unit ids that they're related to parameters findingimpactthreshold string optional filter findings by a finding impact threshold parameters findingtitle string optional search findings by title contents parameters severities string optional filter findings by a list of comma separated severities they're tagged with parameters assettitle string optional search by findings by affected asset parameters assettypes string optional filter findings by a comma separated list of affected asset types parameters tags string optional filter findings by a comma separated list of tags parameters onlyvalidatedexploitable boolean optional filter to only show findings validated as exploitable parameters onlyunacknowledged boolean optional filter to only show unacknowledged findings parameters exploitationrisklevel string optional filter findings by a comma separated list of exploitation risk levels input example {"parameters" {"page" 1,"pagesize" 10,"created from" "2022 02 22 22 00 00","created to" "2022 02 23 22 00 00","updated from" "2022 02 22 22 00 00","updated to" "2022 02 23 22 00 00","statuses" "confirmed,unconfirmed,remediated,risk accepted,closed,asset no longer tracked","businessunitids" "1,2,3","findingimpactthreshold" "medium","findingtitle" "critical vulnerability in your network","severities" "critical,high,medium,low"}} output parameter type description status code number http status code of the response reason string response reason phrase data array response data data id number response data data title string response data data created at string response data data cvssv3 score number response data data cvssv3 metrics string response data data description string response data data impact string response data data finding impact string response data data tags array response data data tags id number response data data tags name string response data data evidence string response data data recommendation string response data data references string response data data severity string response data data status string response data data affected object response data data affected data object response data data affected data type string response data data affected data source string response data data affected data status string response data data affected data created at string response data output example {"status code" 200,"reason" "ok","json body" {"data" \[{"id" 2917,"title" "valid credentials discovered in business system","created at" "2023 11 24t07 56 51 000z","cvssv3 score" 8 6,"cvssv3 metrics" "cvss 3 1/av\ n/ac\ l/pr\ n/ui\ n/s\ u/c\ h/i\ h/a\ n/e\ f/rl\ w/rc\ c","description" "through watchtowr's credential stuffing capabilities, a valid set of credentials have been identified to work to authenticate to a legitimately exposed business system \n\nthese credentials have been confirmed as valid again list hunt findings retrieve a list of all findings associated with a specific hunt identified by its unique id in the watchtowr api endpoint url /api/client/hunts/show/{{id}}/findings method get input argument name type required description parameters page number optional the page number for paginated results parameters pagesize number optional the number of items to be included on each page of paginated results path parameters id number required the id of the hunt to retrieve findings from input example {"parameters" {"page" 1,"pagesize" 20},"path parameters" {"id" 1234}} output parameter type description status code number http status code of the response reason string response reason phrase data array response data data id number response data data title string response data data description string response data data impact string response data data finding impact string response data data tags array response data data tags id number response data data tags name string response data data evidence string response data data recommendation string response data data severity string response data data cvssv3 score number response data data cvssv3 metrics string response data data status string response data data created at string response data data affected object response data data cve id string response data data epss score number response data data retest object response data data retest retest remaining number response data data retest current retest object response data data retest current retest requested by string response data output example {"status code" 200,"reason" "ok","json body" {"data" \[{}],"meta" {"pagination" {}}}} list hunts retrieve a list of all available hunt assets from watchtowr api, sorted by their creation date endpoint url /api/client/hunts/list method get input argument name type required description parameters page number optional the page number for paginated results parameters pagesize number optional the number of items to be included on each page of paginated results parameters statuses string optional filter hunts by hunt status parameters huntsearch string optional search for hunts by text in hunt name parameters types string optional filter hunts by hunt types parameters created from string optional filter hunts created after a given date and time parameters created to string optional filter hunts created before a given date and time parameters updated from string optional filter hunts updated after a given date and time parameters updated to string optional filter hunts updated before a given date and time parameters priorities string optional filter hunts updated before a given date and time parameters resourcefilter string optional filter hunts that have associated assets or findings parameters onlyresolved boolean optional filter to only show resolved hunts parameters isunacknowledged boolean optional filter to only show hunts that are not acknowledged input example {"parameters" {"page" 1,"pagesize" 50,"statuses" "received,in progress,completed,not covered","huntsearch" "remote code execution","types" "bespoke,proactive","created from" "2022 02 22 22 00 00","created to" "2022 02 23 22 00 00","updated from" "2022 02 22 22 00 00","updated to" "2022 02 23 22 00 00","priorities" "high,medium,low","resourcefilter" "hasassetsorfindings","onlyresolved"\ false,"isunacknowledged"\ true}} output parameter type description status code number http status code of the response reason string response reason phrase data array response data data id number response data data priority string response data data type string response data data created at string response data data updated at string response data data total findings number response data data total assets number response data data hunt request type string response data data rapid exposure mechanism string response data data title string response data data status string response data meta object output field meta meta pagination object output field meta pagination meta pagination total number output field meta pagination total meta pagination count number count value meta pagination per page number output field meta pagination per page meta pagination current page number output field meta pagination current page meta pagination total pages number output field meta pagination total pages meta pagination links object output field meta pagination links meta pagination links previous string output field meta pagination links previous meta pagination links next string output field meta pagination links next output example {"status code" 200,"reason" "ok","json body" {"data" \[{}],"meta" {"pagination" {}}}} list suspicious domains retrieve a list of all suspicious domain assets detected by watchtowr api, sorted by the date they were discovered endpoint url /api/client/suspicious domain/list method get input argument name type required description parameters page number optional the page number for paginated results parameters pagesize number optional the number of items to be included on each page of paginated results parameters created from string optional filter suspicious domains created after a given date and time parameters created to string optional filter suspicious domains created before a given date and time parameters updated from string optional filter suspicious domains updated after a given date and time parameters updated to string optional filter suspicious domains updated before a given date and time parameters search string optional search suspicious domains by text within the domain parameters discovery reason string optional search suspicious domains by discovery reason parameters whoissearch string optional search suspicious domains by contents of whois data parameters statuses string optional filter suspicious domains by a list of comma separated statuses that asset is tagged with input example {"parameters" {"page" 1,"pagesize" 50,"created from" "2022 02 22 22 00 00","created to" "2022 02 23 22 00 00","updated from" "2022 02 22 22 00 00","updated to" "2022 02 23 22 00 00","search" "watchtowr com","discovery reason" "suspicious words","whoissearch" "name server malicious ns com","statuses" "pending,malicious,legitimate,benign"}} output parameter type description status code number http status code of the response reason string response reason phrase data array response data data id number response data data name string response data data discovery reason string response data data status string response data data whoisdata array response data data whoisdata id number response data data whoisdata data object response data data whoisdata data org string response data data whoisdata data city string response data data whoisdata data name string response data data whoisdata data state string response data data whoisdata data dnssec string response data data whoisdata data emails array response data data whoisdata data status array response data data whoisdata data address string response data data whoisdata data country string response data data whoisdata data zipcode string response data data whoisdata data registrar string response data data whoisdata data domain name string response data data whoisdata data name servers array response data data whoisdata data referral url string response data data whoisdata data whois server string response data output example {"status code" 200,"reason" "ok","json body" {"data" \[{}],"meta" {"pagination" {}}}} retest finding initiates a retest for a specific finding identified by the 'finding id' in watchtowr api endpoint url /api/client/findings/retest/{{finding id}} method post input argument name type required description path parameters finding id number required the id of the finding to retest input example {"path parameters" {"finding id" 1234}} output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier title string output field title description string output field description impact string output field impact finding impact string output field finding impact tags array output field tags tags id number unique identifier tags name string name of the resource evidence string unique identifier recommendation string output field recommendation severity string output field severity cvssv3 score number score value cvssv3 metrics string output field cvssv3 metrics status string status value created at string output field created at affected object output field affected cve id string unique identifier epss score number score value retest object output field retest retest retest remaining number output field retest retest remaining retest current retest object output field retest current retest retest current retest requested by string output field retest current retest requested by retest current retest requested at string output field retest current retest requested at output example {"status code" 200,"reason" "ok","json body" {"id" 1,"title" "valid credentials discovered in business system","description" "through watchtowr's credential stuffing capabilities, a valid set of credentials ","impact" "depending on the system, if leveraged by an attacker it may be possible to \n\n g ","finding impact" "prioritised findings","tags" \[{}],"evidence" "url https //example com/adfs/ls\n\nvalid credentials discovered \nusername user\np ","recommendation" "as a priority, it is update finding status updates the status of a specific finding in watchtowr api using the provided 'id' and 'status' endpoint url /api/client/findings/status/{{id}} method post input argument name type required description path parameters id number required the id of the finding to update status string optional the new status for the finding statusreason string optional the reason for the status change input example {"json body" {"status" "confirmed","statusreason" "reason for change"},"path parameters" {"id" 1234}} output parameter type description status code number http status code of the response reason string response reason phrase data object response data data id number response data data title string response data data description string response data data impact string response data data finding impact string response data data tags array response data data tags id number response data data tags name string response data data evidence string response data data recommendation string response data data severity string response data data cvssv3 score number response data data cvssv3 metrics string response data data status string response data data created at string response data data affected object response data data cve id string response data data epss score number response data data retest object response data data retest retest remaining number response data data retest current retest object response data data retest current retest requested by string response data output example {"status code" 200,"reason" "ok","json body" {"data" {"id" 1,"title" "valid credentials discovered in business system","description" "through watchtowr's credential stuffing capabilities, a valid set of credentials ","impact" "depending on the system, if leveraged by an attacker it may be possible to \n\n g ","finding impact" "prioritised findings","tags" \[],"evidence" "url https //example com/adfs/ls\n\nvalid credentials discovered \nusername user\np ","recommendation" "as a priority, update note updates a specific note identified by asset and note ids in the watchtowr api, requiring the updated note content endpoint url /api/client/assets/apidocumentation/show/{{id}}/note/{{noteid}} method put input argument name type required description path parameters id number required the asset id of an api documentation asset with a note to update path parameters noteid number required the id of the note to update note string optional parameter for update note title string optional parameter for update note input example {"json body" {"note" "passed to the engineering team review on 01/07/2024","title" "initial review 01/01/2024"},"path parameters" {"id" 123,"noteid" 456}} output parameter type description status code number http status code of the response reason string response reason phrase data object response data data id number response data data note string response data data note type string response data data note id number response data data title string response data data author object response data data author id number response data data author name string response data data last modified string response data output example {"status code" 200,"reason" "ok","json body" {"data" {"id" 1,"note" "passed to the engineering team review on 01/07/2024","note type" "domain","note id" 2,"title" "initial review 01/01/2024","author" {},"last modified" "2022 02 13t02 10 00 000000z"}}} 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