Knowbe4 Phisher

The KnowBe4 PhishER connector allows for seamless integration with the PhishER platform, enabling automated phishing threat management and analysis.

KnowBe4 PhishER is a comprehensive phishing response platform that enables security teams to prioritize, analyze, and respond to threats. This connector allows Swimlane Turbine users to automate the management of phishing incidents by integrating with PhishER's capabilities. Users can add comments, tags, download email files, and update message statuses directly within Swimlane Turbine, streamlining the incident response process. The integration enhances operational efficiency, reduces response times, and improves threat categorization within the security operations workflow.

Prerequisites

To utilize the KnowBe4 PhishER connector within Swimlane Turbine, ensure you have the following prerequisites:

HTTP Bearer Authentication with the following parameters:

URL: The endpoint URL for the PhishER API.

Product API Token: Your unique token to authenticate with the PhishER API.

Capabilities

This connector provides the following capabilities:

Add Comment to Multiple Messages

Add Comment

Add Tags

Get All Messages

Get Message by ID

Download EML using RawUrl

Update Message

Update Multiple Messages

Notes

PhishER API Documentation

Configurations

HTTP Bearer Authentication

Authenticates using bearer token such as a JWT, etc.

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
token		string	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

Add Comment

Appends a user-defined comment to a specific PhishER message identified by its 'id'.

Endpoint

URL: /graphql

Method: POST

Input

Argument Name	Type	Required	Description
id	string	Required	Unique identifier
comment	string	Required	Parameter for Add Comment

Input Example

{"id":"4fa977fb-eea6-4b5d-bdd4-ad8176765342","comment":"Test Comment"}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	object	Response data
data.phisherCommentCreate	object	Response data
data.phisherCommentCreate.errors	object	Response data
data.phisherCommentCreate.node	object	Response data
data.phisherCommentCreate.node.body	string	Response data
data.phisherCommentCreate.node.createdAt	string	Response data

Output Example

{"status_code":200,"response_headers":{"Content-Type":"application/json; charset=utf-8","Content-Length":"115","Connection":"keep-alive","Date":"Mon, 20 Nov 2023 19:15:57 GMT","X-Frame-Options":"SAMEORIGIN","X-XSS-Protection":"1; mode=block","X-Content-Type-Options":"nosniff","X-Download-Options":"noopen","X-Permitted-Cross-Domain-Policies":"none","Referrer-Policy":"strict-origin-when-cross-origin","Vary":"Accept, Origin","ETag":"W/\"c46a067f44b199493b5e908c1ebbded7\"","Cache-Control":"max-age=0...

Add Comment to Multiple Messages

Adds a specified comment to all KnowBe4 PhishER messages that match the provided query, using 'query' and 'comment' inputs.

Endpoint

URL: /graphql

Method: POST

Input

Argument Name	Type	Required	Description
query	string	Required	Parameter for Add Comment to Multiple Messages
comment	string	Required	Parameter for Add Comment to Multiple Messages

Input Example

{"query":"query","comment":"Test Comment"}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	object	Response data
data.phisherCommentsCreate	object	Response data
data.phisherCommentsCreate.errors	object	Response data
data.phisherCommentsCreate.totalCount	number	Response data

Output Example

Add Tags

Adds specified tags to a PhishER message by its unique ID to improve categorization and response handling.

Endpoint

URL: /graphql

Method: POST

Input

Argument Name	Type	Required	Description
id	string	Required	Unique identifier
tags	array	Required	Parameter for Add Tags

Input Example

{"id":"12345678-1234-1234-1234-123456789abc","tags":["string"]}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	object	Response data
data.phisherTagsCreate	object	Response data
data.phisherTagsCreate.errors	object	Response data
data.phisherTagsCreate.nodes	object	Response data
data.phisherTagsCreate.nodes.name	string	Response data
data.phisherTagsCreate.nodes.type	string	Response data

Output Example

{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Thu, 2 May 2024 20:37:23 GMT"},"reason":"OK","json_body":{"data":{"phisherTagsCreate":{}}}}

Download EML using RawUrl

Retrieve an email file from a specified URL using the KnowBe4 PhishER connector; 'rawurl' parameter is required.

Endpoint

Method: GET

Input

Argument Name	Type	Required	Description
rawurl	string	Required	Raw URL

Input Example

{"rawurl":"string"}

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 All Messages

Returns a paginated list of messages from KnowBe4 PhishER using a specified Lucene query.

Endpoint

URL: /graphql

Method: POST

Input

Argument Name	Type	Required	Description
query	string	Optional	The Lucene query to search against.
all	boolean	Optional	Flag to request all items at once.
page	number	Optional	The page number you want to fetch.
per	number	Optional	Number of items in each page. Minimum 25 items/page.

Input Example

{"query":"","all":true,"page":1,"per":25}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	object	Response data
data.phisherMessages	object	Response data
data.phisherMessages.nodes	array	Response data
data.phisherMessages.nodes.actionStatus	string	Response data
data.phisherMessages.nodes.attachments	array	Response data
data.phisherMessages.nodes.attachments.actualContentType	string	Response data
data.phisherMessages.nodes.attachments.filename	string	Response data
data.phisherMessages.nodes.attachments.md5	string	Response data
data.phisherMessages.nodes.attachments.reportedContentType	string	Response data
data.phisherMessages.nodes.attachments.s3Key	string	Response data
data.phisherMessages.nodes.attachments.sha1	string	Response data
data.phisherMessages.nodes.attachments.sha256	string	Response data
data.phisherMessages.nodes.attachments.size	number	Response data
data.phisherMessages.nodes.attachments.ssdeep	string	Response data
data.phisherMessages.nodes.attachments.virustotal	object	Response data
data.phisherMessages.nodes.category	string	Response data
data.phisherMessages.nodes.comments	array	Response data
data.phisherMessages.nodes.comments.file_name	string	Response data
data.phisherMessages.nodes.comments.file	string	Response data
data.phisherMessages.nodes.events	array	Response data
data.phisherMessages.nodes.events.causer	string	Response data
data.phisherMessages.nodes.events.createdAt	string	Response data
data.phisherMessages.nodes.events.eventType	string	Response data

Output Example

{"data":{"phisherMessages":{"nodes":[],"pagination":{}}}}

Get Message by ID

Retrieves a specific PhishER message by the unique identifier, facilitating targeted analysis of phishing incidents.

Endpoint

URL: /graphql

Method: POST

Input

Argument Name	Type	Required	Description
id	string	Required	Unique identifier

Input Example

{"id":"4fa977fb-eea6-4b5d-bdd4-ad8176765342"}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	object	Response data
data.phisherMessage	object	Response data
data.phisherMessage.actionStatus	string	Response data
data.phisherMessage.attachments	array	Response data
data.phisherMessage.attachments.actualContentType	string	Response data
data.phisherMessage.attachments.filename	string	Response data
data.phisherMessage.attachments.md5	string	Response data
data.phisherMessage.attachments.reportedContentType	string	Response data
data.phisherMessage.attachments.s3Key	string	Response data
data.phisherMessage.attachments.sha1	string	Response data
data.phisherMessage.attachments.sha256	string	Response data
data.phisherMessage.attachments.size	number	Response data
data.phisherMessage.attachments.ssdeep	string	Response data
data.phisherMessage.attachments.virustotal	object	Response data
data.phisherMessage.attachments.virustotal.permalink	object	Response data
data.phisherMessage.attachments.virustotal.positives	object	Response data
data.phisherMessage.attachments.virustotal.scanned	object	Response data
data.phisherMessage.attachments.virustotal.sha256	object	Response data
data.phisherMessage.category	string	Response data
data.phisherMessage.comments	array	Response data
data.phisherMessage.comments.file_name	string	Response data
data.phisherMessage.comments.file	string	Response data
data.phisherMessage.events	array	Response data

Output Example

{"data":{"phisherMessage":{"actionStatus":"active","attachments":[],"category":"string","comments":[],"events":[],"from":"string","headers":[],"id":"12345678-1234-1234-1234-123456789abc","links":[],"phishmlReport":{},"pipelineStatus":"active","rawUrl":"string","reportedBy":"string","rules":[],"severity":"string"}}}

Update Message

Applies payload data to update a specific PhishER message using the provided ID.

Endpoint

URL: /graphql

Method: POST

Input

Argument Name	Type	Required	Description
id	string	Required	Unique identifier
payload	object	Required	Parameter for Update Message
payload.category	string	Optional	Parameter for Update Message
payload.status	string	Optional	Status value
payload.severity	string	Optional	Parameter for Update Message

Input Example

{"id":"4fa977fb-eea6-4b5d-bdd4-ad8176765342","payload":{"category":"UNKNOWN","status":"RECEIVED","severity":"UNKNOWN_SEVERITY"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	object	Response data
data.phisherMessageUpdate	object	Response data
data.phisherMessageUpdate.errors	object	Response data
data.phisherMessageUpdate.node	object	Response data
data.phisherMessageUpdate.node.actionStatus	string	Response data
data.phisherMessageUpdate.node.attachments	array	Response data
data.phisherMessageUpdate.node.attachments.actualContentType	string	Response data
data.phisherMessageUpdate.node.attachments.filename	string	Response data
data.phisherMessageUpdate.node.attachments.md5	string	Response data
data.phisherMessageUpdate.node.attachments.reportedContentType	string	Response data
data.phisherMessageUpdate.node.attachments.s3Key	string	Response data
data.phisherMessageUpdate.node.attachments.sha1	string	Response data
data.phisherMessageUpdate.node.attachments.sha256	string	Response data
data.phisherMessageUpdate.node.attachments.size	number	Response data
data.phisherMessageUpdate.node.attachments.ssdeep	string	Response data
data.phisherMessageUpdate.node.attachments.virustotal	object	Response data
data.phisherMessageUpdate.node.category	string	Response data
data.phisherMessageUpdate.node.comments	array	Response data
data.phisherMessageUpdate.node.comments.body	string	Response data
data.phisherMessageUpdate.node.comments.createdAt	string	Response data
data.phisherMessageUpdate.node.events	array	Response data
data.phisherMessageUpdate.node.events.causer	object	Response data
data.phisherMessageUpdate.node.events.createdAt	string	Response data

Output Example

{"data":{"phisherMessageUpdate":{"errors":{},"node":{}}}}

Update Multiple Messages

Updates multiple PhishER messages at once using a Lucene Query and payload, improving message management efficiency.

Endpoint

URL: /graphql

Method: POST

Input

Argument Name	Type	Required	Description
query	string	Required	Parameter for Update Multiple Messages
payload	object	Required	Parameter for Update Multiple Messages
payload.category	string	Optional	Parameter for Update Multiple Messages
payload.status	string	Optional	Status value
payload.severity	string	Optional	Parameter for Update Multiple Messages

Input Example

{"query":"","payload":{"category":"UNKNOWN","status":"RESOLVED","severity":"HIGH"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	object	Response data
data.phisherMessagesUpdate	object	Response data
data.phisherMessagesUpdate.errors	object	Response data
data.phisherMessagesUpdate.updated	number	Response data

Output Example

Response Headers

Header	Description	Example
Cache-Control	Directives for caching mechanisms	max-age=0, private, must-revalidate
Connection	HTTP response header: Connection	keep-alive
Content-Encoding	HTTP response header: Content-Encoding	gzip
Content-Length	The length of the response body in bytes	115
Content-Security-Policy	HTTP response header: Content-Security-Policy
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Mon, 20 Nov 2023 20:03:31 GMT
ETag	An identifier for a specific version of a resource	W/"c46a067f44b199493b5e908c1ebbded7"
Referrer-Policy	HTTP response header: Referrer-Policy	strict-origin-when-cross-origin
Strict-Transport-Security	HTTP response header: Strict-Transport-Security	max-age=63113904; includeSubDomains; preload
Transfer-Encoding	HTTP response header: Transfer-Encoding	chunked
Vary	HTTP response header: Vary	Accept, Origin
Via	HTTP response header: Via	1.1 4173c7a8e447342f9200b2668a0cba0a.cloudfront.net (CloudFront)
X-Amz-Cf-Id	HTTP response header: X-Amz-Cf-Id	l_MUPjfdQtUpGZ-HZebQE-gJ8ovWhz0eAQr3k8X14HNHK39LzJ4X9w==
X-Amz-Cf-Pop	HTTP response header: X-Amz-Cf-Pop	HYD57-P3
X-Cache	HTTP response header: X-Cache	Miss from cloudfront
X-Content-Type-Options	HTTP response header: X-Content-Type-Options	nosniff
X-Download-Options	HTTP response header: X-Download-Options	noopen
X-Frame-Options	HTTP response header: X-Frame-Options	SAMEORIGIN
X-Permitted-Cross-Domain-Policies	HTTP response header: X-Permitted-Cross-Domain-Policies	none
X-Request-Id	A unique identifier for the request	97d91d18-b4cf-4151-9dfb-5408f22ca03d
X-Runtime	HTTP response header: X-Runtime	0.147532
X-XSS-Protection	HTTP response header: X-XSS-Protection	1; mode=block