TwinWave

the twinwave connector enables automated interactions with the twinwave platform, facilitating the submission and analysis of urls and files for threat detection and response twinwave is a cutting edge threat analysis platform that specializes in the deep inspection of complex threats with the twinwave connector for swimlane turbine, users can automate the retrieval of forensic data, manage analysis jobs, and download detailed reports this integration empowers security teams to enhance their threat detection and response capabilities by leveraging twinwave's comprehensive analysis engines the connector simplifies complex workflows, allowing users to focus on strategic security tasks while swimlane turbine handles the automation of routine processes this connector integrates twinwave's rest api with swimlane turbine prerequisites to effectively utilize the twinwave connector within the swimlane turbine platform, ensure you have the following prerequisites api key authentication url the endpoint url for the twinwave api api key your personal authentication key to access the twinwave api capabilities this connector provides the following capabilities downlaod submitted resource get an artifact get engines list get a job's normalized forensics get a job summary get a task's normalized forensics get a task's raw forensics resubmit job retrieve a pdf report search across job resources and forensics submit file for scanning submit url for scanning poll for done jobs note priority parameter should be between 1 and 255 count parameter should not be more than 100 configurations twinwave api key authentication authenticates using an api key configuration parameters parameter description type required url a url to the target host string required x api key api key string required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions download submitted resource downloads a password protected zip archive of the submitted resource from twinwave using job id and sha256 decrypt with password 'infected' endpoint url /v1/jobs/{{job id}}/resources/{{sha256}} method get input argument name type required description path parameters job id string required previous job id of the task path parameters sha256 string required sha 256 for the job's resource input example {"path parameters" {"job id" "b638a944 21fb 4ff0 b1c5 29221991a533","sha256" "sha 256"}} output parameter type description file object attachments file file string output field file file file file name string name of the resource output example {"file" {"file" "string","file name" "example name"}} get artifact retrieves a specified artifact from twinwave using the provided artifact path parameter endpoint url /v1/jobs/artifacts/{{artifact path}} method get input argument name type required description path parameters artifact path string required path from the forensic items image and savedartifacts input example {"path parameters" {"artifact path" "artifact path"}} output parameter type description file object attachments file file string output field file file file file name string name of the resource output example {"file" {"file" "string","file name" "example name"}} get engines list retrieve a list of available analysis engines from twinwave endpoint url /v1/engines method get output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"reason" "ok","response headers" {},"json body" {}} get job normalized forensics retrieve consolidated forensics for a specific job across all resources and engines in twinwave, requiring the job id endpoint url /v1/jobs/{{job id}}/forensics method get input argument name type required description path parameters job id string required previous job id to get normalized forensics input example {"path parameters" {"job id" "b638a944 21fb 4ff0 b1c5 29221991a533"}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"reason" "ok","response headers" {},"json body" {}} get job summary retrieve a comprehensive summary for a specified job in twinwave using the unique job id endpoint url /v1/jobs/{{job id}} method get input argument name type required description path parameters job id string required previous job id to get summary input example {"path parameters" {"job id" "b638a944 21fb 4ff0 b1c5 29221991a533"}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"reason" "ok","response headers" {},"json body" {}} get task normalized forensics retrieves normalized forensic data for a given job and task id within twinwave, detailing analysis from a specific resource and engine run endpoint url /v1/jobs/{{job id}}/tasks/{{task id}}/forensics method get input argument name type required description path parameters job id string required previous job id of the task path parameters task id string required task id to get normalized forensics input example {"path parameters" {"job id" "b638a944 21fb 4ff0 b1c5 29221991a533","task id" "b638a944 21fb 4ff0 b1c5 29221991a533"}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"reason" "ok","response headers" {},"json body" {}} get task raw forensics retrieve raw forensic data for a specific task in twinwave using the provided job and task identifiers endpoint url /v1/jobs/{{job id}}/tasks/{{task id}}/rawforensics method get input argument name type required description path parameters job id string required previous job id of the task path parameters task id string required task id to get raw forensics input example {"path parameters" {"job id" "b638a944 21fb 4ff0 b1c5 29221991a533","task id" "b638a944 21fb 4ff0 b1c5 29221991a533"}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"reason" "ok","response headers" {},"json body" {}} poll for done jobs continuously polls twinwave for completed jobs and ingests the results into the system endpoint url /v1/jobs/poll method get input argument name type required description parameters token string optional an opaque string that is used to advance the poll session parameters since number optional the unix timestamp specifying where in time to start the polling session ignored when token is provided parameters source string optional filter jobs by submission source ignored when token is provided parameters api key id string optional filter jobs by api key id ignored when token is provided parameters username string optional filter jobs by username ignored when token is provided parameters taskdetails boolean optional control whether full task details are returned or not ignored when token is provided parameters batch size number optional the maximum number of jobs to return per call ignored when token is provided input example {"parameters" {"token" "1234567890","since" 9831200000000,"source" "api","api key id" "1234567890","username" "john doe","taskdetails"\ true,"batch size" 10}} output parameter type description status code number http status code of the response reason string response reason phrase jobs array output field jobs jobs id string unique identifier jobs tenantid string unique identifier jobs accountid string unique identifier jobs username string name of the resource jobs submission object output field jobs submission jobs submission md5 string output field jobs submission md5 jobs submission sha256 string output field jobs submission sha256 jobs submission name string name of the resource jobs resources array output field jobs resources jobs resources id string unique identifier jobs resources jobid string unique identifier jobs resources type string type of the resource jobs resources name string name of the resource jobs resources location string output field jobs resources location jobs resources filemetadata object response data jobs resources filemetadata md5 string response data jobs resources filemetadata sha256 string response data jobs resources filemetadata size number response data jobs resources filemetadata mimetype string response data jobs resources filemetadata filetype string response data jobs resources parentid string unique identifier jobs resources tasks array output field jobs resources tasks output example {"status code" 200,"reason" "ok","jobs" \[{"id" "1234567890","tenantid" "1234567890","accountid" "1234567890","username" "john doe","submission" {},"resources" \[],"resourcecount" 10,"priority" 10,"labels" \[],"verdict" "malware","state" "pending","score" 0,"displayscore" 0,"tasks" \[],"createdat" "2025 01 01t00 00 00z"}]} resubmit job resubmits an existing job in twinwave using the specified job id provided in the path parameters endpoint url /v1/jobs/{{job id}}/reanalyze method post input argument name type required description path parameters job id string required previous job id to be re submitted as a new job input example {"path parameters" {"job id" "b638a944 21fb 4ff0 b1c5 29221991a533"}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"reason" "ok","response headers" {},"json body" {}} retrieve a pdf report retrieve a pdf report for a specified job by providing the unique job id in twinwave endpoint url /v1/jobs/{{job id}}/pdfreport method get input argument name type required description path parameters job id string required previous job id to get summary input example {"path parameters" {"job id" "b638a944 21fb 4ff0 b1c5 29221991a533"}} output parameter type description file object attachments file file string output field file file file file name string name of the resource output example {"file" {"file" "string","file name" "example name"}} search job resources and forensics performs a search across job resources and forensics within twinwave to identify relevant data points endpoint url /v1/jobs/searchv2 method get input argument name type required description parameters mode string optional parameters for the search job resources and forensics action parameters term string optional specify the string to search for in the specified field parameters field string optional specify in which field to look for the matching term accepted values detection name, detection desc, domain, filename, filetype, hostname, ip, md5, mimetype, sha256, tag, url parameters type string optional specify whether the term must be an exact match, a case insensitive substring match, startswith match, endswith match, or a tokenized search accepted values exact, substring, startswith, endswith, tokenized parameters count number optional specify number of results to be returned max value 100 parameters shared only boolean optional specify true to only search across jobs (and their resources) which have been shared parameters verdict string optional verdict accepted value malware, phish, spam parameters start time string optional specify the start time in iso format to search jobs starting from the specified time this value is inclusive parameters end time string optional specify the end time in iso format to search jobs before the specified time this value is exclusive parameters page number optional the page for which you want results default 1 parameters score min number optional only return jobs with a score greater than or equal to the value in (between 0 and 1 0) defaults to 0 parameters score max number optional only return jobs with a score less than or equal to the value in (between 0 and 1 0) defaults to 0 parameters api key id string optional only return jobs submitted using the given api key id parameters submitted by string optional specify a username or part of a username input example {"parameters" {"mode" "mode","term" " exe","field" "filetype","type" "endswith","count" 10,"shared only"\ false,"verdict" "malware","start time" "2023 03 01t07 00 00 000z","end time" "2023 03 01t07 00 00 000z","page" 1,"score min" 0 5,"score max" 0 5,"api key id" "sswe2435","submitted by" "alice"}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"reason" "ok","response headers" {},"json body" {}} submit file for scanning submits a new file to twinwave for scanning and analysis, requiring the 'files' input for operation endpoint url /v1/jobs/files method post input argument name type required description data body object optional response data data body priority number optional response data data body profile string optional response data data body engines array optional response data data body parameters archive document password string optional parameters for the submit file for scanning action data body parameters decode rewritten urls boolean optional parameters for the submit file for scanning action data body parameters user agent string optional parameters for the submit file for scanning action data body parameters wa exit region string optional parameters for the submit file for scanning action files array required parameter for submit file for scanning files file name string required name of the resource files file string required parameter for submit file for scanning input example {"data body" {"priority" 10,"profile" "profile name","engines" \["engines"],"parameters" {"archive document password" "fdkejk432","decode rewritten urls"\ false,"user agent" "alias\ default","wa exit region" "us residential"}}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"reason" "ok","response headers" {},"json body" {}} submit url for scanning submits a url to twinwave for scanning and analysis, requiring the 'url' parameter in the json body endpoint url /v1/jobs/urls method post input argument name type required description url string optional the target url to visit and analyze priority number optional the job's priority relative to other jobs jobs with a lower priority value are processed before those with a higher value valid priority values are between 1 and 255 default priority 10 profile string optional an optional profile name that defines the analysis behavior to be used during the analysis for this job if no profile name is submitted the system will use the default profile engines array optional list of engines to be used during the analysis if you'd like to use the default engines for your account, omit this parameter parameters archive document password string optional a password for extracting files from passwordprotected archive files or for decrypting documents parameters decode rewritten urls boolean optional controls whether rewritten urls from a number of vendors (proofpoint, menlo security, etc ) are automatically decoded parameters user agent string optional specify a custom user agent for web analyzer to use omit to use the default you can specify a raw user agent string, or supply one of the common user agent aliases to get canned user agents for common devices parameters wa exit region string optional specify a custom geoip based exit region for web analyzer runs valid values are us residential , us , asia , europe input example {"json body" {"url" "example com","priority" 10,"profile" "profile name","engines" \["engines"],"parameters" {"archive document password" "fdkejk432","decode rewritten urls"\ false,"user agent" "alias\ default","wa exit region" "us residential"}}} output parameter type description status code number http status code of the response reason string response reason phrase output example {"status code" 200,"reason" "ok","response headers" {},"json body" {}} 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