Cofense Vision

Cofense Vision is an email security solution that helps organizations detect and respond to phishing threats.

Cofense Vision is a powerful platform designed to automate phishing threat detection and response. It enables users to quarantine suspicious emails, conduct detailed searches, and retrieve search results efficiently. By integrating Cofense Vision with Swimlane Turbine, users can enhance their security operations with automated workflows, allowing for rapid identification and mitigation of phishing threats. This integration empowers security teams to streamline their processes, reduce manual effort, and improve response times to potential threats.

Prerequisites

Before you can use the Cofense Vision connector for Turbine, you'll need access to the Cofense Vision API. This requires the following:

OAuth2 client credentials authentication using the following parameters:

URL: The endpoint for accessing the Cofense Vision API.

Client Name: The name of the client used for authentication.

Client Password: The password associated with the client for secure access.

Capabilities

This connector provides the following capabilities:

Create a New Quarantine Job

Create New Search

Get All Searches

Get Search Results

Asset Setup

The following permissions are required to run each of the tasks:

Create a New Quarantine Job: QUARANTINE ADMIN, QUARANTINE_USER, or SYSTEM_ADMIN.

Create New Search: SEARCH_ADMIN, SEARCH USER, or SYSTEM_ADMIN.

Get All Searches: SEARCH_ADMIN, SEARCH USER, or SYSTEM_ADMIN.

Get Search Results: SEARCH_ADMIN, SEARCH USER, or SYSTEM_ADMIN.

Notes

This connector supports Cofense Vision API Version 5.

Additional Documentation

Cofense Vision Connector Documentation

Cofense Vision API Documentation

Configurations

Cofense Vision Client Credentials Authentication

Authenticates using client name and client password.

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
client_id	Account name for the client.	string	Required
client_secret	Password for the account name specified.	string	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

Create New Quarantine Job

Initiate a new quarantine job in Cofense Vision using specified email addresses for targeted action. Requires json_body with quarantineEmails.

Endpoint

URL: api/v5/quarantineJobs

Method: POST

Input

Argument Name	Type	Required	Description
quarantineEmails	array	Optional	Parameter for Create New Quarantine Job
quarantineEmails.recipientAddress	string	Optional	Parameter for Create New Quarantine Job
quarantineEmails.internetMessageId	string	Optional	Unique identifier

Input Example

{"json_body":{"quarantineEmails":[{"recipientAddress":"[email protected]","internetMessageId":"<BYAPR11MB2824EF099FE06D3740572 [email protected]>"},{"recipientAddress":"[email protected]","internetMessageId":"<BYAPR11MB2824A5994CF5BA9417724EEEDC8D0@BYAPR11MB2824.namprd11.prod.outlook.com>"}]}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	number	Unique identifier
createdBy	string	Output field: createdBy
createdDate	string	Date value
modifiedBy	string	Output field: modifiedBy
modifiedDate	string	Date value
stopRequested	boolean	Output field: stopRequested
emailcount	number	Count value
quarantineEmails	array	Output field: quarantineEmails
quarantineEmails.id	number	Unique identifier
quarantineEmails.recipientAddress	string	Output field: quarantineEmails.recipientAddress
quarantineEmails.internetMessageId	string	Unique identifier
quarantineEmails.ewsMessageId	object	Unique identifier
quarantineEmails.status	string	Status value
quarantineEmails.errorMessage	object	Response message
quarantineEmails.createdDate	string	Date value
quarantineEmails.quarantinedDate	object	Date value
quarantineEmails.originalFolderId	object	Unique identifier
quarantineJobRuns	array	Output field: quarantineJobRuns
quarantineJobRuns.id	number	Unique identifier
quarantineJobRuns.jobRunType	string	Type of the resource
quarantineJobRuns.status	string	Status value
quarantineJobRuns.startedDate	object	Date value
quarantineJobRuns.completedDate	object	Date value

Output Example

{"status_code":200,"response_headers":{"x-frame-options":"SAMEORIGIN","x-content-type-options":"nosniff","x-xss-protection":"1","referrer-policy":"no-referrer","strict-transport-security":"max-age=63072000; includeSubDomains;","content-security-policy":"default-src 'self';script-src 'self' 'unsafe-eval';frame-src 'self';child-src 's...","date":"Tue, 05 Mar 2024 06:06:52 GMT","cache-control":"private,max-age=0,no-cache,no-store,must-revalidate","pragma":"no-cache","content-type":"application/json...

Create New Search

Create a new search in Cofense Vision using specified criteria provided in the JSON body.

Endpoint

URL: api/v5/searches

Method: POST

Input

Argument Name	Type	Required	Description
subjects	array	Optional	The email subject must match one of the subjects in the list exactly, including spaces. Vision supports the use of one or more wildcard characters (*) in any position of a subject.
senders	array	Optional	The email sender must match one of the email addresses in the list. Vision supports the use of one or more wildcard characters (*) in any position of a sender email address.
attachmentNames	array	Optional	List of strings representing file names. The email must include at least one attachment matching one of the specified file names. Vision supports the use of one or more wildcard characters (*) in any position of an attachment file name.
attachmentHashCriteria	object	Optional	Parameter for Create New Search
attachmentHashCriteria.type	string	Optional	Type of the resource
attachmentHashCriteria.attachmentHashes	array	Optional	Parameter for Create New Search
attachmentHashCriteria.attachmentHashes.hashType	string	Optional	Either MD5 or SHA256.
attachmentHashCriteria.attachmentHashes.hashString	string	Optional	File hash of the attachment.
attachmentMimeTypes	array	Optional	List of mime types. This property returns emails with at least one attachment of one of the listed mime types.
domainCriteria	object	Optional	Parameter for Create New Search
domainCriteria.type	string	Optional	Type of the resource
domainCriteria.domains	array	Optional	Parameter for Create New Search
receivedAfterDate	string	Optional	Filters for emails that Vision processed on or after this date and time. The date and time must be in UTC in ISO 8601 format.
receivedBeforeDate	string	Optional	Filters for emails that Vision processed before or on this date and time. The date and time must be in UTC in ISO 8601 format.
url	string	Optional	Email content or attachment must contain the full URL exactly as specified, including http:// or https://. Vision supports the use of one or more wildcard characters (*) in any position of the URL.
internetMessageId	string	Optional	Unique identifier of the email, enclosed in angle brackets. This attribute is case sensitive.
headers	array	Optional	List of one or more additional criteria to search for in the email header.
headers.key	string	Optional	HTTP headers for the request
headers.values	array	Optional	HTTP headers for the request
partialIngest	boolean	Optional	Whether to search for partially ingested emails (true) or not search for partially ingested emails (false).
recipient	string	Optional	Email address of the recipient. Vision supports the use of one or more wildcard characters (*) in any position of a recipient email address.

Input Example

{"json_body":{"subjects":["Check this out","News of the day"],"senders":["[email protected]","[email protected]"],"attachmentNames":["foo.jpG","bAr.jpg"],"attachmentHashCriteria":{"type":"ALL","attachmentHashes":[{"hashType":"SHA256","hashString":"f814c32d07400260cda1c3dd8479c843bfa6062e1221bd85c04c5eee570ac413"}]},"attachmentMimeTypes":["text","image/jpg"],"domainCriteria":{"type":"ALL","domains":["example1.com","example2.com"]},"receivedAfterDate":"2023-08-01T00:00:00.000Z","receivedBeforeDate":"2023-08-02T00:00:00.000Z","url":"http://www.foo.com/bar","internetMessageId":"<[email protected]>","headers":[{"key":"Content-Type","values":["application/javascript","application/json"]},{"key":"X-Originating-IP","values":["127.0.0.1"]}],"partialIngest":true,"recipient":"[email protected]"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	number	Unique identifier
createdBy	string	Output field: createdBy
createdDate	string	Date value
modifiedBy	string	Output field: modifiedBy
modifiedDate	string	Date value
subjects	array	Output field: subjects
senders	array	Output field: senders
recipient	object	Output field: recipient
attachmentNames	array	Name of the resource
attachmentHashCriteria	object	Output field: attachmentHashCriteria
attachmentHashCriteria.type	string	Type of the resource
attachmentHashCriteria.attachmentHashes	array	Output field: attachmentHashCriteria.attachmentHashes
attachmentHashCriteria.attachmentHashes.hashType	string	Type of the resource
attachmentHashCriteria.attachmentHashes.hashString	string	Output field: attachmentHashCriteria.attachmentHashes.hashString
domainCriteria	object	Output field: domainCriteria
domainCriteria.type	string	Type of the resource
domainCriteria.domains	array	Output field: domainCriteria.domains
domainCriteria.whitelistURLs	array	URL endpoint for the request
domainCriteria.whitelistURLs.file_name	string	URL endpoint for the request
domainCriteria.whitelistURLs.file	string	URL endpoint for the request
attachmentMimeTypes	array	Type of the resource
receivedAfterDate	string	Date value
receivedBeforeDate	string	Date value

Output Example

Get All Searches

Retrieve a list of all searches conducted within Cofense Vision, including their details and statuses.

Endpoint

URL: api/v5/searches

Method: GET

Input

Argument Name	Type	Required	Description
parameters.page	number	Optional	Start page of the results. The value must be a positive integer or 0. Default: 0
parameters.size	number	Optional	Number of results per page. The value must be a positive integer up to 2000. Default: 20
parameters.sort	array	Optional	Name-value pair defining the order of search properties in the response. Multiple values are supported. Format: propertyName,sortOrder

Input Example

{"parameters":{"page":1,"size":100,"sort":["createdDate,desc"]}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
searches	array	Output field: searches
searches.id	number	Unique identifier
searches.createdBy	string	Output field: searches.createdBy
searches.createdDate	string	Date value
searches.modifiedBy	string	Output field: searches.modifiedBy
searches.modifiedDate	string	Date value
searches.subjects	array	Output field: searches.subjects
searches.subjects.file_name	string	Name of the resource
searches.subjects.file	string	Output field: searches.subjects.file
searches.senders	array	Output field: searches.senders
searches.senders.file_name	string	Name of the resource
searches.senders.file	string	Output field: searches.senders.file
searches.recipient	object	Output field: searches.recipient
searches.attachmentNames	array	Name of the resource
searches.attachmentNames.file_name	string	Name of the resource
searches.attachmentNames.file	string	Name of the resource
searches.attachmentHashCriteria	object	Output field: searches.attachmentHashCriteria
searches.attachmentHashCriteria.type	string	Type of the resource
searches.attachmentHashCriteria.attachmentHashes	array	Output field: searches.attachmentHashCriteria.attachmentHashes
searches.attachmentHashCriteria.attachmentHashes.file_name	string	Name of the resource
searches.attachmentHashCriteria.attachmentHashes.file	string	Output field: searches.attachmentHashCriteria.attachmentHashes.file
searches.domainCriteria	object	Output field: searches.domainCriteria
searches.domainCriteria.type	string	Type of the resource

Output Example

Get Search Results

Retrieve results of a previously initiated search in Cofense Vision using a unique identifier.

Endpoint

URL: api/v5/searches/{{id}}/results

Method: GET

Input

Argument Name	Type	Required	Description
parameters.page	number	Optional	Start page of the results. The value must be a positive integer or 0. Default: 0
parameters.size	number	Optional	Number of results per page. The value must be a positive integer up to 2000. Default: 20
parameters.sort	array	Optional	Name-value pair defining the order of search properties in the response. Multiple values are supported. Format: propertyName,sortOrder
path_parameters.id	number	Required	Parameters for the Get Search Results action

Input Example

{"parameters":{"page":1,"size":100,"sort":["createdDate,desc"]},"path_parameters":{"id":5}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
messages	array	Response message
messages.id	number	Unique identifier
messages.storageUri	string	Response message
messages.subject	string	Response message
messages.receivedOn	string	Response message
messages.sentOn	string	Response message
messages.deliveredOn	object	Response message
messages.processedOn	string	Response message
messages.md5	string	Response message
messages.sha1	object	Response message
messages.sha256	string	Response message
messages.internetMessageId	string	Unique identifier
messages.from	array	Response message
messages.from.id	number	Unique identifier
messages.from.personal	string	Response message
messages.from.address	string	Response message
messages.headers	array	HTTP headers for the request
messages.headers.id	number	HTTP headers for the request
messages.headers.name	string	HTTP headers for the request
messages.headers.value	string	HTTP headers for the request
messages.headers.seq	number	HTTP headers for the request
messages.recipients	array	Response message
messages.recipients.id	number	Unique identifier

Output Example

Response Headers

Header	Description	Example
cache-control	Directives for caching mechanisms	private,max-age=0,no-cache,no-store,must-revalidate
content-length	The length of the response body in bytes	538
content-security-policy	HTTP response header: content-security-policy	default-src 'self';script-src 'self' 'unsafe-eval';frame-src 'self';child-src 'self';worker-src 'self';media-src 'self';style-src 'self' 'unsafe-inline';img-src data: blob: 'self';frame-ancestors 'self';font-src 'self' data:;upgrade-insecure-requests;connect-src * data: blob: 'unsafe-inline';block-all-mixed-content;
content-type	The media type of the resource	application/json
date	The date and time at which the message was originated	Tue, 05 Mar 2024 06:06:52 GMT
pragma	HTTP response header: pragma	no-cache
referrer-policy	HTTP response header: referrer-policy	no-referrer
server	Information about the software used by the origin server	envoy
strict-transport-security	HTTP response header: strict-transport-security	max-age=63072000; includeSubDomains;
x-content-type-options	HTTP response header: x-content-type-options	nosniff
x-envoy-upstream-service-time	HTTP response header: x-envoy-upstream-service-time	28
x-frame-options	HTTP response header: x-frame-options	SAMEORIGIN
x-xss-protection	HTTP response header: x-xss-protection	1