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