KnowBe4 PhishER

Overview

PhishER is an email threat management platform to orchestrate your threat response and manage the high volume of potentially malicious email messages reported by your users. With the automatic prioritization of emails, PhishER helps your InfoSec and Security Operations team cut through the inbox noise and respond to the most dangerous threats more quickly.

D3 SOAR is providing REST operations to function with KnowBe4 PhishER.

For example, you can use KnowBe4 PhishER to reduce the Phish-prone percentage, improve rapport between employees and the IT security team with the help of the Phish Alert Button, and make the IT security team’s job easier when it comes to detecting and addressing phishing emails.

KnowBe4 PhishER is available for use in:

D3 SOAR	V15.0.13.0+
Category	Email Security
Deployment Options	Option II, Option IV

Known Limitations

Usage of KnowBe4's Event APIs is limited to 1,000 requests per day plus the number of licensed users on your account. The APIs may only be accessed four times per second. Please note that the API limits will start around five (5) minutes to twenty-four (24) hours from the first API request.

Please refer to Rate Limiting for detailed information.

Connection

To connect to KnowBe4 PhishER from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Server URL (domain level)	The server URL of the KnowBe4 API.	https://ca.knowbe4.com/
API Token	The Product API Token to authenticate the API connection.	eyJh****************MNoA

Reader Note

The scenario outlined in this user guide assumes that you already have the following prerequisites:

A KnowBe4 account
A user account with admin access to the KnowBe4 account.

Permission Requirements

Each endpoint in the KnowBe4 PhishER API requires a certain permission scope. All commands will only require the "Limited" permission for Rooms, Inbox, Rules, Actions, PhishRIP, Blockist and Settings to run in D3 SOAR. For more information about configuring security roles, see PhishER Settings – Knowledge Base.

As KnowBe4 PhishER is using role-based access control (RBAC), the API access token is generated based on a specific user account and the application. Therefore, the command permissions are inherited from the user account’s role. Users need to configure their user profile from the KnowBe4 PhishER console for each command in this integration.

Configuring KnowBe4 PhishER to Work with D3 SOAR

Log in to the KnowBe4 console with your account email and password. Once logged in, click your account email on the top right corner, and select Account Settings from the drop-down menu.
From the left side menu of the Account Settings page, click on API under Account Integrations. Select API Token under Product API.
On the Product API Tokens page, click + Create New API Token.
To create a new API token, provide a name for the token and then select "PhishER" as the product. Next, specify the token expiration date and user, and make sure that the API is enabled. Finally, click Create Token to complete the process.
The new token will be created and listed on the Product API Tokens page. Copy and store the token in a secure location to establish the integration connection in D3 SOAR.

Creating a New User

Log in to your KnowBe4 console with admin credentials.
On the landing page, select the USERS from the top navigation menu.
Click Add Users, and select Create Single User from the drop-down menu.
Enter the required information, and click Create User.
Click Add Admin Access to grant admin privileges to the created user.
Assign a role to that user. Please refer to Permission Requirements for more information.
On the Manage Users page, select the Edit button corresponding to the user that was created.
Scroll down to the PhishER section and click Enable. Finally, select Update User to save your changes.

Configuring D3 SOAR to Work with KnowBe4 PhishER

Log in to D3 SOAR.
Find the KnowBe4 PhishER integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type KnowBe4 PhishER in the search box to find the integration, then click it to select it.
4. Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to KnowBe4 PhishER.
1. Connection Name: The desired name for the connection.
2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): Add your desired description for the connection.
6. Configure User Permissions: Defines which users have access to the connection.
7. Active: Check the tick box to ensure the connection is available for use.
8. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input your domain level Server URL.
  Note: The appropriate base URL depends on the location of your KnowBe4 account server.
  For the US server (training.knowbe4.com), use training.knowbe4.com/graphql.
  For the EU server (eu.knowbe4.com), use eu.knowbe4.com/graphql.
  For the CA server (ca.knowbe4.com), use ca.knowbe4.com/graphql.
  For the UK server (uk.knowbe4.com), use uk.knowbe4.com/graphql.
  For the DE server (de.knowbe4.com), use de.knowbe4.com/graphql.
  2. Copy the API Token from the KnowBe4 PhishER platform (Refer to step 7 of Configuring KnowBe4 PhishER to Work with D3 SOAR).
9. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
10. Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.
  To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
Test the connection.
1. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

KnowBe4 PhishER includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the KnowBe4 PhishER API, please refer to the KnowBe4 PhishER API reference.

Reader Note

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring KnowBe4 PhishER to Work with D3 SOAR for details.

Bulk Create Tags

Adds a collection of tags to the specified PhishER message based on the defined query condition.

Input

Input Parameter	Required/Optional	Description	Example
Query	Optional	The query condition to filter the PhishER messages to add tags. If this parameter is not defined, the specified tags will be added to all messages. For more information about the Lucene Query Syntax, see How to Use Lucene Query Syntax – Knowledge Base.	subject: phishing AND -category:clean
Tags	Required	The tags to add to the specified PhishER messages.	[ "suspectSpamTag", "PhishTag" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "data": {
        "phisherTagsBulkCreate": {
            "errors": null,
            "totalCount": 1
        }
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "TotalCount": "\"1\""
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

data	{'phisherTagsBulkCreate': {'errors': None, 'totalCount': 1}}

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Bulk Create Tags failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the KnowBe4 PhishER portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Unauthorized.

Error Sample Data

Bulk Create Tags failed.

Status Code: 401.

Message: Message: Unauthorized.

Bulk Delete Tags

Deletes a collection of tags to the specified PhishER message based on the defined query condition.

Input

Input Parameter	Required/Optional	Description	Example
Query	Optional	The query condition to filter the PhishER messages to remove tags. If this parameter is not defined, the specified tags will be added to all messages. For more information about the Lucene Query Syntax, see How to Use Lucene Query Syntax – Knowledge Base.	subject: phishing AND -category:clean
Tags	Required	The tags to remove from the specified PhishER messages. If this parameter is not defined, no tags will be removed. Only existing tags can be removed.	[ "suspectSpamTag", "PhishTag_NoExist" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "data": {
        "phisherTagsBulkDelete": {
            "errors": null,
            "totalCount": 1
        }
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "TotalCount": "\"1\""
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

data	{'phisherTagsBulkDelete': {'errors': None, 'totalCount': 1}}

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Bulk Delete Tags failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the KnowBe4 PhishER portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Unauthorized.

Error Sample Data

Bulk Delete Tags failed.

Status Code: 401.

Message: Unauthorized.

Create Comment

Adds a comment to a PhishER message.

Reader Note

The parameter Message IDs is required to run this command.

You should already have your desired Message ID on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired Message ID. Message IDs can be found in the returned raw data at the path $.data.phisherMessages.nodes.id.

Input

Input Parameter	Required/Optional	Description	Example
Message ID	Required	The ID of the PhishER message to add a comment. Message IDs can be obtained using the Fetch Event command.	*----**
Comment	Required	The comment text to add to the specified message.	Test Comment 725B

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "data": {
        "phisherCommentCreate": {
            "errors": null,
            "node": {
                "body": "Test Comment 725B",
                "createdAt": "2022-07-25T17:06:47Z"
            }
        }
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Comment": "\"\\\"Test Comment 725B\\\"\"",
    "CreatedTime": "\"\\\"2022-07-25T17:06:47Z\\\"\""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

data	{'phisherCommentCreate': {'errors': None, 'node': {'body': 'Test Comment 725B', 'createdAt': '2022-07-25T17:06:47Z'}}}

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Create Comment failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the KnowBe4 PhishER portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Message ID not found.

Error Sample Data

Create Comment failed.

Status Code: 404.

Message: Message ID not found.

Create Comments

Adds comments to all PhishER messages matching the query condition.

Input

Input Parameter	Required/Optional	Description	Example
Query	Optional	The query condition to filter the PhishER messages to add comments. If this parameter is not defined, the specified tags will be added to all messages. For more information about the Lucene Query Syntax, see How to Use Lucene Query Syntax – Knowledge Base.	subject: phishing AND -category:clean
Comment	Required	The comment text to add to the specified messages. If this parameter is not defined, no comments will be added.	This is a suspected phishing email.

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "data": {
        "phisherCommentsCreate": {
            "errors": [],
            "totalCount": 1
        }
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "TotalCount": "\"1\""
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

data	{'phisherCommentsCreate': {'errors': [], 'totalCount': 1}}

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Create Comment failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the KnowBe4 PhishER portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Message ID not found.

Error Sample Data

Create Comment failed.

Status Code: 404.

Message: Message ID not found.

Create Tags

Adds a collection of tags to the specified PhishER message.

Reader Note

The parameter Message IDs is required to run this command.

You should already have your desired Message ID on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired Message ID. Message IDs can be found in the returned raw data at the path $.data.phisherMessages.nodes.id.

Input

Input Parameter	Required/Optional	Description	Example
Message ID	Required	The ID of the PhishER message to add tags. Message IDs can be obtained using the Fetch Event command.	*----**
Tags	Required	The tags to add to the specified PhishER message.	[ "SuspectSpam725", "medium_severity" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "data": {
        "phisherTagsCreate": {
            "errors": null,
            "nodes": [
                {
                    "name": "SUSPECTSPAM725",
                    "type": "STANDARD"
                },
                {
                    "name": "MEDIUM_SEVERITY",
                    "type": "STANDARD"
                }
            ]
        }
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Tags": "\"[ \\\"SUSPECTSPAM725\\\", \\\"MEDIUM_SEVERITY\\\" ]\""
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

data	{'phisherTagsCreate': {'errors': None, 'nodes': [{'name': 'SUSPECTSPAM725', 'type': 'STANDARD'}, {'name': 'MEDIUM_SEVERITY', 'type': 'STANDARD'}]}}

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Delete Tags failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the KnowBe4 PhishER portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Message id not found.

Error Sample Data

Delete Tags failed.

Status Code: 404.

Message: Message id not found.

Delete Tags

Deletes a collection of tags on the specified PhishER message.

Reader Note

The parameter Message IDs is required to run this command.

You should already have your desired Message ID on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired Message ID. Message IDs can be found in the returned raw data at the path $.data.phisherMessages.nodes.id.

Input

Input Parameter	Required/Optional	Description	Example
Message ID	Required	The ID of the PhishER message to remove tags. Message IDs can be obtained using the Fetch Event command.	*----**
Tags	Optional	The tags to remove from the specified PhishER message. If this parameter is not defined, no tags will be removed.	[ "medium_severity" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "data": {
        "phisherTagsDelete": {
            "errors": null,
            "nodes": [
                {
                    "name": "SUSPECTSPAM725",
                    "type": "STANDARD"
                }
            ]
        }
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "RemainedTags": "\"[ \\\"SUSPECTSPAM725\\\" ]\""
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

data	{'phisherTagsDelete': {'errors': None, 'nodes': [{'name': 'SUSPECTSPAM725', 'type': 'STANDARD'}]}}

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Delete Tags failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the KnowBe4 PhishER portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Message id not found.

Error Sample Data

Delete Tags failed.

Status Code: 404.

Message: Message id not found.

Fetch Event

Returns a list of messages reported by users based on your specified search conditions. The most recently reported messages are displayed first.

Note for Time-related parameters

The input format of time-related parameters may vary based on your account settings. As a result, the sample data provided in our commands is different from what you see. To set your preferred time format, follow these steps:

Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose your desired date and time format.

After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Optional	The start time of the time range to fetch events in UTC time format. The time range corresponds to the selected time field for the Query Time Type parameter. Note: The start time can only be specified at a daily granularity.	2023-04-01 00:00
End Time	Optional	The end time of the time range to fetch events in UTC time format. The time range corresponds to the selected time field for the Query Time Type parameter. Note: The end time can only be specified at a daily granularity.	2023-04-02 00:00
Query Time Type	Optional	The time field (i.e. Reported Date or Sent Date) to query with the Start Time and End Time parameters. If this parameter is not defined, the default setting is Reported Date. Reported Date: The date that the phisher message was reported. Sent Date: The date that the message was sent to the reporter.	Reported Date
Number of Event(s) Fetched	Optional	The maximum number of messages to return. If this parameter is not defined, all messages matching the search conditions will be returned.	10
Category	Optional	The category to filter returned messages. The available categories are Unknown, Clean, Spam and Threat. To filter by multiple categories, separate them with a comma.	[ "Spam", "Unknown" ]
Status	Optional	The status to filter returned messages. The available statuses are Received, In_Review and Resolved. If this parameter is not defined, messages will not be filtered by status. To filter by multiple statuses, separate them with a comma.	[ "Received", "In_Review" ]
Priority	Optional	The priority level to filter returned messages. The available priority levels are Unknown_Severity, Low, Medium, High and Critical. If this parameter is not defined, messages will not be filtered by priority. To filter by multiple priority levels, separate them with a comma.	[ "Unknown_Severity", "Low" ]
Search Condition	Optional	The query condition to filter the returned PhishER messages. Any fields in the query that already exist as a command parameter will be ignored. For more information about the Lucene Query Syntax, see How to Use Lucene Query Syntax – Knowledge Base.	from: (test* OR user*)

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "data": {
        "phisherMessages": {
            "nodes": [
                {
                    "actionStatus": "IN_REVIEW",
                    "attachments": [],
                    "category": "UNKNOWN",
                    "comments": [
                        {
                            "body": "Test NEW Comments 724",
                            "createdAt": "2022-07-24T20:23:59Z"
                        }
                    ],
                    "headers": [
                        {
                            "header": "Delivered-To",
                            "data": "test@example.com"
                        },
                        {
                            "header": "Received",
                            "data": "by ***** with SMTP id *****; Wed, 4 May 2022 17:39:09 -0700 (PDT)"
                        },
                        {
                            "header": "X-Received",
                            "data": "by ***** with SMTP id *****-*****.*****; Wed, 04 May 2022 17:39:09 -0700 (PDT)"
                        }
                    ],
                    "events": [
                        {
                            "causer": null,
                            "createdAt": "2022-07-24T19:45:15Z",
                            "eventType": "CREATED",
                            "events": null,
                            "id": "***-***-***-***-***",
                            "triggerer": null
                        },
                        {
                            "causer": "Phish ML",
                            "createdAt": "2022-07-24T19:45:25Z",
                            "eventType": "OTHER",
                            "events": {
                                "clean": 0,
                                "spam": 99.95,
                                "threat": 0.06
                            },
                            "id": "***-***-***-***-***",
                            "triggerer": null
                        },
                        {
                            "causer": null,
                            "createdAt": "2022-07-24T19:45:25Z",
                            "eventType": "OTHER",
                            "events": {
                                "changes": [
                                    {
                                        "from": "processing",
                                        "name": "pipeline_status",
                                        "to": "processed"
                                    }
                                ]
                            },
                            "id": "***-***-***-***-***",
                            "triggerer": null
                        },
                        {
                            "causer": null,
                            "createdAt": "2022-07-24T20:28:14Z",
                            "eventType": "OTHER",
                            "events": {
                                "changes": [
                                    {
                                        "from": "unknown_severity",
                                        "name": "severity",
                                        "to": "low"
                                    }
                                ]
                            },
                            "id": "***-***-***-***-***",
                            "triggerer": null
                        },
                        {
                            "causer": null,
                            "createdAt": "2022-07-24T20:28:27Z",
                            "eventType": "OTHER",
                            "events": {
                                "changes": [
                                    {
                                        "from": "received",
                                        "name": "action_status",
                                        "to": "in_review"
                                    }
                                ]
                            },
                            "id": "***-***-***-***-***",
                            "triggerer": null
                        },
                        {
                            "causer": "Tony Fu",
                            "createdAt": "2022-07-25T01:13:10Z",
                            "eventType": "OTHER",
                            "events": {
                                "changes": [
                                    {
                                        "from": "false",
                                        "name": "viewed",
                                        "to": "true"
                                    }
                                ]
                            },
                            "id": "***-***-***-***-***",
                            "triggerer": null
                        }
                    ],
                    "id": "21c5c20d-d55b-415a-830b-627b0f9ef988",
                    "links": [],
                    "phishmlReport": {
                        "confidenceClean": 0.0000100000033853576,
                        "confidenceSpam": 0.999451458454132,
                        "confidenceThreat": 0.000568497227504849
                    },
                    "pipelineStatus": "PROCESSED",
                    "rawUrl": "https://phisher-parts-production-ca-*****.amazonaws.com/***-***-***-***-***/2022-07-24/*****/*****?response-content-disposition=attachment%3B%20filename%3D%22%22%3B%20filename%2A%3DUTF-8%27%27&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=***%***%2Fca-central-1%2Fs3%2Faws4_request&X-Amz-Date=20220725T024550Z&X-Amz-Expires=86400&X-Amz-Security-Token=*****",
                    "reportedBy": "test@example.com",
                    "rules": [],
                    "severity": "LOW",
                    "subject": "5;37",
                    "from": "test@example.com",
                    "tags": []
                },
                {
                    "actionStatus": "IN_REVIEW",
                    "attachments": [
                        {
                            "actualContentType": "text/csv",
                            "filename": "1000 CC Records.csv",
                            "md5": "*****",
                            "reportedContentType": "text/csv",
                            "s3Key": "*****/*****",
                            "sha1": "*****",
                            "sha256": "*****",
                            "size": 86976,
                            "ssdeep": "***//***",
                            "virustotal": null
                        },
                        {
                            "actualContentType": "text/csv",
                            "filename": "1000 CC Records.csv",
                            "md5": "*****",
                            "reportedContentType": "text/csv",
                            "s3Key": "***/***",
                            "sha1": "*****",
                            "sha256": "*****",
                            "size": 91838,
                            "ssdeep": "1536:N/***/***/***/***:***+***/***/***",
                            "virustotal": null
                        }
                    ],
                    "category": "UNKNOWN",
                    "comments": [
                        {
                            "body": "Test NEW Comments 724",
                            "createdAt": "2022-07-24T20:23:59Z"
                        }
                    ],
                    "headers": [
                        {
                            "header": "Delivered-To",
                            "data": "test@example.com"
                        },
                        {
                            "header": "Received",
                            "data": "by 2***** with SMTP id *****; Fri, 24 Jun 2022 11:44:52 -0700 (PDT)"
                        },
                        {
                            "header": "X-Received",
                            "data": "by 2***** with SMTP id fp7-*****.*****; Fri, 24 Jun 2022 11:44:51 -0700 (PDT)"
                        }
                    ],
                    "events": [
                        {
                            "causer": null,
                            "createdAt": "2022-07-24T19:44:01Z",
                            "eventType": "CREATED",
                            "events": null,
                            "id": "***-***-***-***-***",
                            "triggerer": null
                        },
                        {
                            "causer": "Phish ML",
                            "createdAt": "2022-07-24T19:44:07Z",
                            "eventType": "OTHER",
                            "events": {
                                "clean": 0.14,
                                "spam": 6.11,
                                "threat": 93.76
                            },
                            "id": "***-***-***-***-***",
                            "triggerer": null
                        },
                        {
                            "causer": null,
                            "createdAt": "2022-07-24T19:44:07Z",
                            "eventType": "OTHER",
                            "events": {
                                "changes": [
                                    {
                                        "from": "processing",
                                        "name": "pipeline_status",
                                        "to": "processed"
                                    }
                                ]
                            },
                            "id": "***-***-***-***-***",
                            "triggerer": null
                        },
                        {
                            "causer": null,
                            "createdAt": "2022-07-24T20:28:14Z",
                            "eventType": "OTHER",
                            "events": {
                                "changes": [
                                    {
                                        "from": "unknown_severity",
                                        "name": "severity",
                                        "to": "low"
                                    }
                                ]
                            },
                            "id": "***-***-***-***-***",
                            "triggerer": null
                        },
                        {
                            "causer": null,
                            "createdAt": "2022-07-24T20:28:27Z",
                            "eventType": "OTHER",
                            "events": {
                                "changes": [
                                    {
                                        "from": "received",
                                        "name": "action_status",
                                        "to": "in_review"
                                    }
                                ]
                            },
                            "id": "***-***-***-***-***",
                            "triggerer": null
                        },
                        {
                            "causer": "Tony Fu",
                            "createdAt": "2022-07-25T01:13:16Z",
                            "eventType": "OTHER",
                            "events": {
                                "changes": [
                                    {
                                        "from": "false",
                                        "name": "viewed",
                                        "to": "true"
                                    }
                                ]
                            },
                            "id": "***-***-***-***-***",
                            "triggerer": null
                        }
                    ],
                    "id": "***-***-***-***-***",
                    "links": [
                        {
                            "dispositions": [
                                "NONE"
                            ],
                            "firstSeen": "2022-03-07T22:39:57Z",
                            "id": "***-***-***-***-***",
                            "lastSeen": "2022-07-24T19:44:02Z",
                            "scheme": "http",
                            "target": "http://www.d3security.com",
                            "url": "www.d3security.com",
                            "virustotal": null
                        },
                        {
                            "dispositions": [
                                "NONE"
                            ],
                            "firstSeen": "2022-03-07T22:39:57Z",
                            "id": "***-***-***-***-***",
                            "lastSeen": "2022-07-24T19:44:02Z",
                            "scheme": "http",
                            "target": "http://info.***.com/***/D3Security_Email%***.png",
                            "url": null,
                            "virustotal": null
                        }
                    ],
                    "phishmlReport": {
                        "confidenceClean": 0.00137163139879704,
                        "confidenceSpam": 0.0610864050686359,
                        "confidenceThreat": 0.937572002410889
                    },
                    "pipelineStatus": "PROCESSED",
                    "rawUrl": "https://***",
                    "reportedBy": "test@example.com",
                    "rules": [],
                    "severity": "LOW",
                    "subject": "test message 624b",
                    "from": "test@example.com",
                    "tags": []
                }
            ],
            "pagination": {
                "page": 1,
                "pages": 1,
                "per": 1000,
                "totalCount": 2
            }
        }
    }
}

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

D3 customizes the Context Data by extracting the data from path $.data.phisherMessages.nodes in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
    {
        "actionStatus": "IN_REVIEW",
        "attachments": [],
        "category": "UNKNOWN",
        "comments": [
            {
                "body": "Test NEW Comments 724",
                "createdAt": "2022-07-24T20:23:59Z"
            }
        ],
        "headers": [
            {
                "header": "Delivered-To",
                "data": "test@example.com"
            },
            {
                "header": "Received",
                "data": "by ***** with SMTP id *****; Wed, 4 May 2022 17:39:09 -0700 (PDT)"
            },
            {
                "header": "X-Received",
                "data": "by ***** with SMTP id *****-*****.*****; Wed, 04 May 2022 17:39:09 -0700 (PDT)"
            }
        ],
        "events": [
            {
                "causer": null,
                "createdAt": "2022-07-24T19:45:15Z",
                "eventType": "CREATED",
                "events": null,
                "id": "***-***-***-***-***",
                "triggerer": null
            },
            {
                "causer": "Phish ML",
                "createdAt": "2022-07-24T19:45:25Z",
                "eventType": "OTHER",
                "events": {
                    "clean": 0,
                    "spam": 99.95,
                    "threat": 0.06
                },
                "id": "***-***-***-***-***",
                "triggerer": null
            },
            {
                "causer": null,
                "createdAt": "2022-07-24T19:45:25Z",
                "eventType": "OTHER",
                "events": {
                    "changes": [
                        {
                            "from": "processing",
                            "name": "pipeline_status",
                            "to": "processed"
                        }
                    ]
                },
                "id": "***-***-***-***-***",
                "triggerer": null
            },
            {
                "causer": null,
                "createdAt": "2022-07-24T20:28:14Z",
                "eventType": "OTHER",
                "events": {
                    "changes": [
                        {
                            "from": "unknown_severity",
                            "name": "severity",
                            "to": "low"
                        }
                    ]
                },
                "id": "***-***-***-***-***",
                "triggerer": null
            },
            {
                "causer": null,
                "createdAt": "2022-07-24T20:28:27Z",
                "eventType": "OTHER",
                "events": {
                    "changes": [
                        {
                            "from": "received",
                            "name": "action_status",
                            "to": "in_review"
                        }
                    ]
                },
                "id": "***-***-***-***-***",
                "triggerer": null
            },
            {
                "causer": "Tony Fu",
                "createdAt": "2022-07-25T01:13:10Z",
                "eventType": "OTHER",
                "events": {
                    "changes": [
                        {
                            "from": "false",
                            "name": "viewed",
                            "to": "true"
                        }
                    ]
                },
                "id": "***-***-***-***-***",
                "triggerer": null
            }
        ],
        "id": "21c5c20d-d55b-415a-830b-627b0f9ef988",
        "links": [],
        "phishmlReport": {
            "confidenceClean": 0.0000100000033853576,
            "confidenceSpam": 0.999451458454132,
            "confidenceThreat": 0.000568497227504849
        },
        "pipelineStatus": "PROCESSED",
        "rawUrl": "https://phisher-parts-production-ca-*****.amazonaws.com/***-***-***-***-***/2022-07-24/*****/*****?response-content-disposition=attachment%3B%20filename%3D%22%22%3B%20filename%2A%3DUTF-8%27%27&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=***%***%2Fca-central-1%2Fs3%2Faws4_request&X-Amz-Date=20220725T024550Z&X-Amz-Expires=86400&X-Amz-Security-Token=*****",
        "reportedBy": "test@example.com",
        "rules": [],
        "severity": "LOW",
        "subject": "5;37",
        "from": "test@example.com",
        "tags": []
    },
    {
        "actionStatus": "IN_REVIEW",
        "attachments": [
            {
                "actualContentType": "text/csv",
                "filename": "1000 CC Records.csv",
                "md5": "*****",
                "reportedContentType": "text/csv",
                "s3Key": "*****/*****",
                "sha1": "*****",
                "sha256": "*****",
                "size": 86976,
                "ssdeep": "***//***",
                "virustotal": null
            },
            {
                "actualContentType": "text/csv",
                "filename": "1000 CC Records.csv",
                "md5": "*****",
                "reportedContentType": "text/csv",
                "s3Key": "***/***",
                "sha1": "*****",
                "sha256": "*****",
                "size": 91838,
                "ssdeep": "1536:N/***/***/***/***:***+***/***/***",
                "virustotal": null
            }
        ],
        "category": "UNKNOWN",
        "comments": [
            {
                "body": "Test NEW Comments 724",
                "createdAt": "2022-07-24T20:23:59Z"
            }
        ],
        "headers": [
            {
                "header": "Delivered-To",
                "data": "test@example.com"
            },
            {
                "header": "Received",
                "data": "by 2***** with SMTP id *****; Fri, 24 Jun 2022 11:44:52 -0700 (PDT)"
            },
            {
                "header": "X-Received",
                "data": "by 2***** with SMTP id fp7-*****.*****; Fri, 24 Jun 2022 11:44:51 -0700 (PDT)"
            }
        ],
        "events": [
            {
                "causer": null,
                "createdAt": "2022-07-24T19:44:01Z",
                "eventType": "CREATED",
                "events": null,
                "id": "***-***-***-***-***",
                "triggerer": null
            },
            {
                "causer": "Phish ML",
                "createdAt": "2022-07-24T19:44:07Z",
                "eventType": "OTHER",
                "events": {
                    "clean": 0.14,
                    "spam": 6.11,
                    "threat": 93.76
                },
                "id": "***-***-***-***-***",
                "triggerer": null
            },
            {
                "causer": null,
                "createdAt": "2022-07-24T19:44:07Z",
                "eventType": "OTHER",
                "events": {
                    "changes": [
                        {
                            "from": "processing",
                            "name": "pipeline_status",
                            "to": "processed"
                        }
                    ]
                },
                "id": "***-***-***-***-***",
                "triggerer": null
            },
            {
                "causer": null,
                "createdAt": "2022-07-24T20:28:14Z",
                "eventType": "OTHER",
                "events": {
                    "changes": [
                        {
                            "from": "unknown_severity",
                            "name": "severity",
                            "to": "low"
                        }
                    ]
                },
                "id": "***-***-***-***-***",
                "triggerer": null
            },
            {
                "causer": null,
                "createdAt": "2022-07-24T20:28:27Z",
                "eventType": "OTHER",
                "events": {
                    "changes": [
                        {
                            "from": "received",
                            "name": "action_status",
                            "to": "in_review"
                        }
                    ]
                },
                "id": "***-***-***-***-***",
                "triggerer": null
            },
            {
                "causer": "Tony Fu",
                "createdAt": "2022-07-25T01:13:16Z",
                "eventType": "OTHER",
                "events": {
                    "changes": [
                        {
                            "from": "false",
                            "name": "viewed",
                            "to": "true"
                        }
                    ]
                },
                "id": "***-***-***-***-***",
                "triggerer": null
            }
        ],
        "id": "***-***-***-***-***",
        "links": [
            {
                "dispositions": [
                    "NONE"
                ],
                "firstSeen": "2022-03-07T22:39:57Z",
                "id": "***-***-***-***-***",
                "lastSeen": "2022-07-24T19:44:02Z",
                "scheme": "http",
                "target": "http://www.d3security.com",
                "url": "www.d3security.com",
                "virustotal": null
            },
            {
                "dispositions": [
                    "NONE"
                ],
                "firstSeen": "2022-03-07T22:39:57Z",
                "id": "***-***-***-***-***",
                "lastSeen": "2022-07-24T19:44:02Z",
                "scheme": "http",
                "target": "http://info.***.com/***/D3Security_Email%***.png",
                "url": null,
                "virustotal": null
            }
        ],
        "phishmlReport": {
            "confidenceClean": 0.00137163139879704,
            "confidenceSpam": 0.0610864050686359,
            "confidenceThreat": 0.937572002410889
        },
        "pipelineStatus": "PROCESSED",
        "rawUrl": "https://***",
        "reportedBy": "test@example.com",
        "rules": [],
        "severity": "LOW",
        "subject": "test message 624b",
        "from": "test@example.com",
        "tags": []
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "MessageIDs": "\"[ \\\"4cc4b200-cc15-4061-8213-c41bbc6d4f81\\\" ]\""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error HandlingFetch Event Field Mapping

Please note that Fetch Event commands require Event Field Mapping. Field mapping plays a key role in the data normalization process part of the event pipeline. Field mapping converts the original data fields from the different providers to D3 system fields which are standardized by the D3 data model. You can edit the provided mapping or customize new mappings to suit your needs. Please refer to Event and Incident Intake Field Mapping for more details.

If you require a custom field mapping, click +Add Field to add a custom field mapping. You may also remove built-in field mappings by clicking x. Please note that two underscore characters will automatically prefix the defined Field Name as the System Name for a custom field mapping. Additionally, if an input Field Name contains any spaces, they will automatically be replaced with underscores for the corresponding System Name.

As a system integration, the KnowBe4 PhishER integration has some pre-configured field mappings for default field mapping below:

Default Event Source

The Default Event Source is the default set of field mapping that is applied when this fetch event command is executed. For out-of-the-box integrations, you will find a set of field mapping provided by the system. It contains field mappings for common fields from fetched events including Unique Event Key, Sender and Email subject (e.g., .id, .from and .subject). The default event source also provides field mapping for the fields specific to email security such as Severity, Email Type and Status.

Main Event JSON Path: $.data.phisherMessages.nodes

The Main Event JSON Path determines the root path where the system starts parsing raw response data into D3 event data. The JSON path begins with $, representing the root element. The path is formed by appending a sequence of child elements to $, each separated by a dot (.). Square brackets with nested quotation marks ([‘...’]) should be used to separate child elements in JSON arrays.

For example, the root node of a JSON Path is $.data.phisherMessages.nodes. The child node denoting the Unique Event Key field would be .id. Putting it together, the JSON Path expression to extract the Unique Event Key is $.data.phisherMessages.nodes.id.

Field Name	Source Field
Clean Confidence	.phishmlReport.confidenceClean
Reported_By	.reportedBy
Sent Time	headers[?(@.header=='Date')].data
Spam_Confidence	.phishmlReport.confidenceSpam
Threat Confidence	.phishmlReport.confidenceThreat
Unique Event Key	.id
Event Type	.category
Start Time	.events[0].createdAt
Sender	.from
Severity	.severity
Status	.actionStatus
Email subject	.subject
Tag	.tag

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Fetch Event failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the KnowBe4 PhishER portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Fetch Event failed: Mal-formatted data found in API response.

Error Sample Data

Fetch Event failed.

Status Code: 401.

Message: Fetch Event failed: Mal-formatted data found in API response.

Get Messages

Retrieves PhishER messages of the given message IDs.

Reader Note

The parameter Message IDs is required to run this command.

You should already have your desired Message ID on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired Message ID. Message IDs can be found in the returned raw data at the path $.data.phisherMessages.nodes.id.

Input

Input Parameter	Required/Optional	Description	Example
Message IDs	Required	The IDs of the PhishER messages to retrieve. Message IDs can be obtained using the Fetch Event command.	[ "*----**" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "data": {
            "phisherMessage": {
                "actionStatus": "RESOLVED",
                "attachments": [],
                "category": "SPAM",
                "comments": [
                    {
                        "body": "Test Comment 725C",
                        "createdAt": "2022-07-25T18:10:06Z"
                    },
                    {
                        "body": "Test Comment 725C",
                        "createdAt": "2022-07-25T18:10:05Z"
                    },
                    {
                        "body": "Test Comment 725C",
                        "createdAt": "2022-07-25T18:10:00Z"
                    },
                    {
                        "body": "Test Comment 725B",
                        "createdAt": "2022-07-25T17:06:47Z"
                    },
                    {
                        "body": "Test Comment 725B",
                        "createdAt": "2022-07-25T16:58:02Z"
                    },
                    {
                        "body": "Test Comment 725A",
                        "createdAt": "2022-07-25T16:56:25Z"
                    },
                    {
                        "body": "Test NEW Comments 724",
                        "createdAt": "2022-07-24T20:23:59Z"
                    }
                ],
                "events": [
                    {
                        "causer": null,
                        "createdAt": "2022-07-24T19:45:15Z",
                        "eventType": "CREATED",
                        "events": null,
                        "id": "***-***-***-***-***",
                        "triggerer": null
                    },
                    {
                        "causer": "Phish ML",
                        "createdAt": "2022-07-24T19:45:25Z",
                        "eventType": "OTHER",
                        "events": {
                            "clean": 0,
                            "spam": 99.95,
                            "threat": 0.06
                        },
                        "id": "***-***-***-***-***",
                        "triggerer": null
                    },
                    {
                        "causer": null,
                        "createdAt": "2022-07-24T19:45:25Z",
                        "eventType": "OTHER",
                        "events": {
                            "changes": [
                                {
                                    "from": "processing",
                                    "name": "pipeline_status",
                                    "to": "processed"
                                }
                            ]
                        },
                        "id": "***-***-***-***-***",
                        "triggerer": null
                    },
                    {
                        "causer": null,
                        "createdAt": "2022-07-24T20:28:14Z",
                        "eventType": "OTHER",
                        "events": {
                            "changes": [
                                {
                                    "from": "unknown_severity",
                                    "name": "severity",
                                    "to": "low"
                                }
                            ]
                        },
                        "id": "***-***-***-***-***",
                        "triggerer": null
                    },
                    {
                        "causer": null,
                        "createdAt": "2022-07-24T20:28:27Z",
                        "eventType": "OTHER",
                        "events": {
                            "changes": [
                                {
                                    "from": "received",
                                    "name": "action_status",
                                    "to": "in_review"
                                }
                            ]
                        },
                        "id": "***-***-***-***-***",
                        "triggerer": null
                    }
                ],
                "headers": [
                    {
                        "data": "test@example.com",
                        "header": "Delivered-To",
                        "order": "1"
                    },
                    {
                        "data": "by *** with SMTP id *****; Wed, 4 May 2022 17:39:09 -0700 (PDT)",
                        "header": "Received",
                        "order": "2"
                    }
                ],
                "id": "***-***-***-***-***",
                "links": [],
                "phishmlReport": {
                    "confidenceClean": 0.0000100000033853576,
                    "confidenceSpam": 0.999451458454132,
                    "confidenceThreat": 0.000568497227504849
                },
                "pipelineStatus": "PROCESSED",
                "rawUrl": "https://phisher-parts-production-ca-central-1.s3.ca-central-1.amazonaws.com/***-***-***-***-***/2022-07-24/***/***?response-content-disposition=attachment%3B%20filename%3D%22%22%3B%20filename%2A%3DUTF-8%27%27&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=***%***%2Fca-central-1%2Fs3%2Faws4_request&X-Amz-Date=20220725T193058Z&X-Amz-Expires=86400&X-Amz-Security-Token=***%***%2B4qkQQIrP%2F%2F%2F%2F%2F%2F%2F%2F%2F%***",
                "reportedBy": "test@example.com",
                "rules": [],
                "severity": "MEDIUM",
                "from": "test1@example.com",
                "subject": "5;37",
                "tags": [
                    {
                        "name": "SUSPECTSPAM725",
                        "type": "STANDARD"
                    },
                    {
                        "name": "REDTAG",
                        "type": "STANDARD"
                    }
                ]
            }
        }
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "MessageIDs": "\"[ \\\"***-***-***-***-***\\\" ]\"",
    "CleanConfidence": "\"[ 0 ]\"",
    "SpamConfidence": "\"[ 100 ]\"",
    "ThreatConfidence": "\"[ 0 ]\""
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Messages failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the KnowBe4 PhishER portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Get Messages failed.

Error Sample Data

Get Messages failed.

Status Code: 404.

Message: Get Messages failed.

Update Message

Updates the attributes of a specified PhishER message, including category, status and priority. At least one attribute must be updated for the command to run successfully.

Reader Note

The parameter Message IDs is required to run this command.

You should already have your desired Message ID on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired Message ID. Message IDs can be found in the returned raw data at the path $.data.phisherMessages.nodes.id.

At least one attribute (i.e., Category, Status or Severity) must be updated for the command to run successfully.

Input

Input Parameter	Required/Optional	Description	Example
Message ID	Required	The ID of the PhishER message to update. Message IDs can be obtained using the Fetch Event command.	*----**
Category	Optional	The updated category of the specified message. The available categories are Unknown, Clean, Spam and Threat.	Spam
Status	Optional	The updated status of the specified message. The available statuses are Received, In Review, and Resolved.	Resolved
Severity	Optional	The updated severity level of the specified message. The available severity levels are Unknown Severity, Low, Medium, High and Critical.	Medium

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "data": {
        "phisherMessageUpdate": {
            "errors": null,
            "node": {
                "actionStatus": "RESOLVED",
                "attachments": [],
                "category": "SPAM",
                "comments": [
                    {
                        "body": "Test Comment 725B",
                        "createdAt": "2022-07-25T17:06:47Z"
                    },
                    {
                        "body": "Test Comment 725B",
                        "createdAt": "2022-07-25T16:58:02Z"
                    },
                    {
                        "body": "Test Comment 725A",
                        "createdAt": "2022-07-25T16:56:25Z"
                    },
                    {
                        "body": "Test NEW Comments 724",
                        "createdAt": "2022-07-24T20:23:59Z"
                    }
                ],
                "events": [
                    {
                        "causer": null,
                        "createdAt": "2022-07-24T19:45:15Z",
                        "eventType": "CREATED",
                        "events": null,
                        "id": "***-***-***-***-***",
                        "triggerer": null
                    },
                    {
                        "causer": "Phish ML",
                        "createdAt": "2022-07-24T19:45:25Z",
                        "eventType": "OTHER",
                        "events": {
                            "clean": 0,
                            "spam": 99.95,
                            "threat": 0.06
                        },
                        "id": "***-***-***-***-***",
                        "triggerer": null
                    },
                    {
                        "causer": null,
                        "createdAt": "2022-07-24T19:45:25Z",
                        "eventType": "OTHER",
                        "events": {
                            "changes": [
                                {
                                    "from": "processing",
                                    "name": "pipeline_status",
                                    "to": "processed"
                                }
                            ]
                        },
                        "id": "***-***-***-***-***",
                        "triggerer": null
                    },
                    {
                        "causer": null,
                        "createdAt": "2022-07-24T20:28:14Z",
                        "eventType": "OTHER",
                        "events": {
                            "changes": [
                                {
                                    "from": "unknown_severity",
                                    "name": "severity",
                                    "to": "low"
                                }
                            ]
                        },
                        "id": "***-***-***-***-***",
                        "triggerer": null
                    },
                    {
                        "causer": null,
                        "createdAt": "2022-07-24T20:28:27Z",
                        "eventType": "OTHER",
                        "events": {
                            "changes": [
                                {
                                    "from": "received",
                                    "name": "action_status",
                                    "to": "in_review"
                                }
                            ]
                        },
                        "id": "***-***-***-***-***",
                        "triggerer": null
                    },
                    {
                        "causer": "Test User",
                        "createdAt": "2022-07-25T01:13:10Z",
                        "eventType": "OTHER",
                        "events": {
                            "changes": [
                                {
                                    "from": "false",
                                    "name": "viewed",
                                    "to": "true"
                                }
                            ]
                        },
                        "id": "***-***-***-***-***",
                        "triggerer": null
                    }
                ],
                "from": "test@example.com",
                "headers": [
                    {
                        "data": "test@example.com",
                        "header": "Delivered-To",
                        "order": "1"
                    },
                    {
                        "data": "by *****; Wed, 4 May 2022 17:39:09 -0700 (PDT)",
                        "header": "Received",
                        "order": "2"
                    }
                ],
                "id": "***-***-***-***-***",
                "links": [],
                "phishmlReport": {
                    "confidenceClean": 0.0000100000033853576,
                    "confidenceSpam": 0.999451458454132,
                    "confidenceThreat": 0.000568497227504849
                },
                "pipelineStatus": "PROCESSED",
                "rawUrl": "https://phisher-parts-production-ca-central-1.s3.ca-central-1.amazonaws.com/***-***-***-***-***/2022-07-24/***/***?response-content-disposition=attachment%3B%20filename%3D%22%22%3B%20filename%2A%3DUTF-8%27%27&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=***%2F20220725%2Fca-central-1%2Fs3%2Faws4_request&X-Amz-Date=20220725T173558Z&X-Amz-Expires=86400&X-Amz-Security-Token=***%***",
                "reportedBy": "tets@example.com",
                "rules": [],
                "severity": "MEDIUM",
                "subject": "5;37",
                "tags": []
            }
        }
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "MessageID": "\"***-***-***-***-***\""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Update Message failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the KnowBe4 PhishER portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Update Messages failed, API responded with no comment updated, please check your Query.

Error Sample Data

Update Message failed.

Status Code: 403.

Message: Update Messages failed, API responded with no comment updated, please check your Query.

Update Messages

Updates the attributes of a list of specified PhishER messages, including category, status and priority. At least one attribute must be updated for the command to run successfully.

Reader Note

The parameter Message IDs is required to run this command.

You should already have your desired Message ID on hand to run this command. If you don’t, you may use the Fetch Event command with defined filters to retrieve the desired Message ID. Message IDs can be found in the returned raw data at the path $.data.phisherMessages.nodes.id.

At least one attribute (i.e., Category, Status or Severity) must be updated for the command to run successfully.

Input

Input Parameter	Required/Optional	Description	Example
Query	Optional	The query condition to filter the PhishER messages to update. If this parameter is not defined, the update action will be applied to all messages. For more information about the Lucene Query Syntax, see How to Use Lucene Query Syntax – Knowledge Base.	subject: phishing AND -category:clean
Category	Optional	The updated category of the specified messages. The available categories are Unknown, Clean, Spam and Threat.	Spam
Status	Optional	The updated status of the specified messages. The available statuses are Received, In Review, and Resolved.	Resolved
Priority	Optional	The updated priority level of the specified messages. The available severity levels are Unknown Severity, Low, Medium, High and Critical.	Medium

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "data": {
        "phisherMessagesUpdate": {
            "errors": null,
            "updated": 1
        }
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "UpdatedCount": "\"1\""
}

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

data	{'phisherMessagesUpdate': {'errors': None, 'updated': 1}}

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Update Messages failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the KnowBe4 PhishER portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Update Messages failed, API responded with no comment updated, please check your Query.

Error Sample Data

Update Messages failed.

Status Code: 403.

Message: Update Messages failed, API responded with no comment updated, please check your Query.

Test Connection

Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

SAMPLE DATA

CODE

Successful

Error Handling

If the Return Data is failed, an Error tab will appear in the Test Result window.

The error tab contains the responses from the third-party API calls including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed. Failed to check the connector.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the KnowBe4 PhishER portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Please check your Server URL or API Token.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 401.

Message: "Please check your Server URL or API Token.