--- title: Twinwave slug: connectors/twinwave docTags: createdAt: 2026-06-09T16:29:52.533Z --- 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 |