Mattermost

LAST UPDATED: 10/09/2024

RELATED RESOURCE

When a user needs to send an interactive message in Mattermost for another user to approve or select an operation in D3 vSOC, they can do so without requiring the recipient to log in to D3's platform to take action. For further information, refer to the D3 - Mattermost Bi-Directional Automation Configuration Guide.

Overview

Mattermost is a self-hosted online chat service that includes features such as file sharing, search functionality, and various integrations.

D3's integration with Mattermost's latest API (v4) enables the consolidation of all team and user communications into one place.

D3 SOAR is providing REST operations to function with Mattermost. Mattermost is available for use in:

D3 SOAR	V16.8+
Category	Email & Messaging
Deployment Options	Option I, Option III

Known Limitations

Mattermost rate limiting configuration settings are intended for small deployments of Mattermost up to a few hundred users, and are not intended for larger, Enterprise-scale deployments.

Refer to Enable rate limiting - Mattermost documentation for detailed rate limiting information.

Connection

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

Parameter	Description	Example
Server URL	The server URL of the integration.	http://Your_Mattermost_Server:****
Access Token	The access token of the integration.	9xuq*****357a
API Version	The API version of the integration.	v4

Permission Requirements

Each endpoint in the Mattermost API requires a certain permission scope. The following are required scopes for the commands in this integration:

Command	Required Permissions
Add Channel Member	To manage members of a public channel, the manage_public_channel_members permission is required. To manage members of a private channel, the manage_private_channel_members permission is required.
Create Channel	To create a public channel, the create_public_channel permission is required. To create a private channel, the create_private_channel permission is necessary.
Fetch Event	N/A
List Channels	sysconsole_read_user_management_channels
List Roles	manage_system (admins only)
List Teams	list_private_teams list_public_teams
List Users	N/A
Remove Channel Member	To manage members of a public channel, the manage_public_channel_members permission is required. To manage members of a private channel, the manage_private_channel_members permission is required.
Send File	create_post upload_file
Send Message	create_direct_channel or manage_system create_post
Update Message	edit_post
Test Connection	sysconsole_read_user_management_channels

Configuring Mattermost to Work with D3 SOAR

Login to Mattermost.
Click on the icon, then click on System Console.
Enable personal access tokens in the Integration Management page.
(Optional) To create an access token using a non-admin account, assign the necessary role first.
1. Navigate to System Console > User Management > Users.
2. Search for the account, then select Manage roles option from the dropdown menu.
3. Check the Allow this account to generate user access tokens checkbox, then click on the Save button.
Click on your profile icon in the top right corner, then select Profile.
Click on the Security module on the left, then click on the Edit button in the Personal Access Tokens section.
Click on the Create Token button.
Enter a description, then click Save.
Store and copy your access token to D3 vSOC (refer to step 3i sub-step 2 in the Configuring D3 SOAR to Work with Mattermost section).

ALERT

Store your access token securely, as it will no longer be visible afterward.

Configuring D3 SOAR to Work with Mattermost

Log in to D3 SOAR.
Find the Mattermost integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Mattermost 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 Mattermost.
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. Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: Check the checkbox to ensure the connection is available for use.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input the Server URL.
  2. Copy the Access Token from the Mattermost platform. See step 9 in the Configuring Mattermost to Work with D3 SOAR section.
  3. Input the API Version. The default value is v4.
10. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Refer to the password vault connection guide if needed.
11. 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 tick box. 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 check mark appear beside the Test Connection button. If the test connection fails, 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

Mattermost 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 Mattermost API, refer to the Mattermost API reference.

READER NOTE

Certain permissions are required for each command. Refer to the Permission Requirements section for details.

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, then click on the Save button.

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

Add Channel Member

Adds users to a channel by creating channel member objects.

READER NOTE

Channel IDs and User ID are required parameters to run this command.

Run the List Channels command to obtain the Channel ID. Channel IDs can be found in the raw data at the path $.channels[*].id.
Run the List Users command to obtain the User ID. User IDs can be found in the raw data at the path $.Results[*].id.

Input

Input Parameter

Required/Optional

Description

Example

Channel ID

Required

The ID corresponding to a channel where members will be added. Channel ID can be obtained using the List Channels command.

fwbi*****wz1e

User IDs

Required

The IDs corresponding to users to be added to the channel. User IDs can be obtained using the List Users command.

JSON

["6tqx*****7zoe"]

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.

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Results": [
        {
            "channel_id": "*****",
            "user_id": "*****",
            "roles": "channel_user channel_admin",
            "last_viewed_at": 1727874211688,
            "msg_count": 1,
            "mention_count": 0,
            "mention_count_root": 0,
            "urgent_mention_count": 0,
            "msg_count_root": 1,
            "notify_props": {
                "channel_auto_follow_threads": "off",
                "desktop": "default",
                "email": "default",
                "ignore_channel_mentions": "default",
                "mark_unread": "all",
                "push": "default"
            },
            "last_update_at": 1727874211688,
            "scheme_guest": false,
            "scheme_user": true,
            "scheme_admin": true,
            "explicit_roles": ""
        }
    ]
}

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

{
  "ChannelID": "*****"
}

Result

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

SAMPLE DATA

AddChannelMemberCount

1

Error Handling

If the Return Data displays 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.	Add Channel Member 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 Mattermost portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Bad Request.

Error Sample Data

Add Channel Member failed.

Status Code: 400.

Message: Bad Request.

Create Channel

Creates a new channel.

READER NOTE

Team ID is a required parameter to run this command.

Run the List Teams command to obtain the Team ID. Team IDs can be found in the raw data at the path $.teams[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Team ID	Required	The ID corresponding to the team where the channel will be created. Team ID can be obtained using the List Teams command.	7757*****1byw
Channel Name	Required	The name of the channel, which will serve as its unique handle and will appear in the channel URL.	Demo Channel
Display Name	Required	The display name of the channel.	Demo Channel
Channel Type	Required	Whether the channel is public or private.	Public
Purpose	Optional	The purpose of the channel.	Testing

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.

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "id": "*****",
    "create_at": 1727874067417,
    "update_at": 1727874067417,
    "delete_at": 0,
    "team_id": "*****",
    "type": "P",
    "display_name": "D3 QA",
    "name": "d3qa",
    "header": "",
    "purpose": "Testing",
    "last_post_at": 0,
    "total_msg_count": 0,
    "extra_update_at": 0,
    "creator_id": "*****",
    "scheme_id": null,
    "props": null,
    "group_constrained": null,
    "shared": null,
    "total_msg_count_root": 0,
    "policy_id": null,
    "last_root_post_at": 0
}

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

{
  "ChannelID": "*****",
  "ChannelName": "Demo Channel Name",
}

Result

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

SAMPLE DATA

ChannelName

Demo Channel Name

Error Handling

If the Return Data displays 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 Channel 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 Mattermost 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: Not Found.

Error Sample Data

Create Channel failed.

Status Code: 404.

Message: Not Found.

Fetch Event

Returns event(s) from Mattermost.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Required	The start time for the specified time range to retrieve event(s). The format for the time is yyyy-MM-dd HH:mm.	fwbi*****wz1e
End Time	Required	The end time for the specified time range to retrieve event(s). The format for the time is yyyy-MM-dd HH:mm.	JSON `["6tqx*****7zoe"]`
Number of Event(s) Fetched	Optional	The maximum number of events to return.	20
Search Condition	Optional	Queries in JSON format used to filter results.	No Sample Data

Output

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

No Sample Data

Context Data

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

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

No Sample Data

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

No Sample Data

Result

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

SAMPLE DATA

CODE

No Sample Data

Fetch Event Field Mapping

Fetch Event commands require event field mapping. Field mapping plays a key role for data normalization within the event pipeline. Field mapping converts the original data fields from the different providers to standardized D3 fields as defined by the D3 Model. Refer to Event and Incident Intake Field Mapping for details.

To customize field mapping, click + Add Field and add the custom field of your choice. You can also remove built-in field mappings by clicking x. 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 Mattermost integration has some pre-configured field mappings for default field mapping.

Default Event Source
The Default Event Source is the default set of field mappings that are 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. Default event source provides field mappings for common fields from fetched events. The default event source has a "Main Event JSON Path" (i.e. $.) that is used to extract a batch of events from the response raw data. Click Edit Main JSON Path to view the "Main Event JSON Path".
- Main Event JSON Path: $
  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 $ and the child node denoting the Unique Event Key field is id. Putting it together, the JSON Path expression to extract the Unique Event Key is $.id.

Error Handling

If the Return Data displays 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.	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 Mattermost portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server URL is not valid in format.

Error Sample Data

Fetch Event failed.

Status Code: 400.

Message: Server URL is not valid in format.

List Channels

Retrieves the channels that match the criteria.

READER NOTE

The sysconsole_read_compliance permission is required to use the Exclude Policy Constrained parameter.

Input

Input Parameter	Required/Optional	Description	Example
Include Deleted Channels	Optional	If set to True, the returned list will include the deleted channels.	True
Include Default Channels	Optional	If set to True, the returned list will include the default channels.	True
Exclude Policy Constrained	Optional	If set to True, channels that are part of a data retention policy will be excluded. The sysconsole_read_compliance permission is required to use this parameter.	False

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.

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "channels": [
        {
            "id": "*****",
            "create_at": 1660348594940,
            "update_at": 1660348594940,
            "delete_at": 0,
            "team_id": "*****",
            "type": "P",
            "display_name": "testChannelPrivate",
            "name": "testchannelprivate",
            "header": "",
            "purpose": "",
            "last_post_at": 1660348594963,
            "total_msg_count": 0,
            "extra_update_at": 0,
            "creator_id": "*****",
            "scheme_id": "",
            "props": null,
            "group_constrained": false,
            "shared": null,
            "total_msg_count_root": 0,
            "policy_id": null,
            "last_root_post_at": 1660348594963,
            "team_display_name": "teamSite",
            "team_name": "main",
            "team_update_at": 1659034102290,
            "typeName": "Private"
        },
        {
            "id": "*****",
            "create_at": 1660348566809,
            "update_at": 1660348566809,
            "delete_at": 0,
            "team_id": "*****",
            "type": "O",
            "display_name": "testChannel(Public)",
            "name": "testchannelpublic",
            "header": "",
            "purpose": "",
            "last_post_at": 1660348566833,
            "total_msg_count": 0,
            "extra_update_at": 0,
            "creator_id": "*****",
            "scheme_id": "",
            "props": null,
            "group_constrained": false,
            "shared": null,
            "total_msg_count_root": 0,
            "policy_id": null,
            "last_root_post_at": 1660348566833,
            "team_display_name": "teamSite",
            "team_name": "main",
            "team_update_at": 1659034102290,
            "typeName": "Public"
        }
    ],
    "total_count": 3
}

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

{
  "ChannelIDs": ["*****","*****"],
  "ChannelNames": ["testchannelprivate","testchannelpublic"]
}

Result

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

SAMPLE DATA

PrivateChannelCount	1
PublicChannelCount	1

Error Handling

If the Return Data displays 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.	List Channels 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 Mattermost portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server URL is not valid in format.

Error Sample Data

List Channels failed.

Status Code: 400.

Message: Server URL is not valid in format.

List Roles

Retrieves all available roles.

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.

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Results": [
        {
            "id": "*****",
            "name": "playbook_admin",
            "display_name": "authentication.roles.playbook_admin.name",
            "description": "authentication.roles.playbook_admin.description",
            "create_at": 1659034077948,
            "update_at": 1659034079902,
            "delete_at": 0,
            "permissions": [
                "playbook_public_manage_members",
                "playbook_public_manage_roles",
                "playbook_public_manage_properties",
                "playbook_private_manage_members",
                "playbook_private_manage_roles",
                "playbook_private_manage_properties",
                "playbook_public_make_private"
            ],
            "scheme_managed": true,
            "built_in": true
        }
    ]
}

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

{
  "RoleIDs": ["*****","*****"],
  "RoleNames": ["playbook_admin","channel_admin"]
}

Result

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

SAMPLE DATA

RoleCount

2

Error Handling

If the Return Data displays 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.	List Roles 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 Mattermost portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server URL is not valid in format.

Error Sample Data

List Roles failed.

Status Code: 400.

Message: Server URL is not valid in format.

List Teams

Retrieves all the teams.

READER NOTE

The sysconsole_read_compliance permission is required to use the Exclude Policy Constrained parameter.

Input

Input Parameter	Required/Optional	Description	Example
Exclude Policy Constrained	Optional	If set to True, teams participating in a data retention policy will be excluded. The sysconsole_read_compliance permission is required to use this parameter.	True

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.

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "teams": [
        {
            "id": "*****",
            "create_at": 1727871593629,
            "update_at": 1727871593629,
            "delete_at": 0,
            "display_name": "D3 Security",
            "name": "d3-security",
            "description": "",
            "email": "*****@*****.com",
            "type": "O",
            "company_name": "",
            "allowed_domains": "",
            "invite_id": "*****",
            "allow_open_invite": false,
            "scheme_id": "",
            "group_constrained": false,
            "policy_id": null,
            "cloud_limits_archived": false
        }
    ],
    "total_count": 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

{
  "TeamIDs": ["*****"],
  "TeamNames": ["d3-security"]
}

Result

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

SAMPLE DATA

Teams Count

1

Error Handling

If the Return Data displays 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.	List Teams 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 Mattermost portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server URL is not valid in format.

Error Sample Data

List Teams failed.

Status Code: 400.

Message: Server URL is not valid in format.

List Users

Retrieves the users that match the criteria.

READER NOTE

Roles, Team ID and Channel ID are required parameters to run this command.

Run the List Roles command to obtain the Roles. Roles can be found in the raw data at the path $.Results[*].name.
Run the List Teams command to obtain the Team ID. Team IDs can be found in the raw data at the path $.teams[*].id.
Run the List Channels command to obtain the Channel ID. Channel IDs can be found in the raw data at the path $.channels[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Roles	Optional	Filters for users based on the provided role names. Roles can be obtained using the List Roles command.	JSON `[ "system_user", "system_admin" ]`
Team ID	Optional	Whether users belong to a team based on the Is In Team parameter. The team ID is required if the channel ID is provided as NotInChannel. Team ID can be obtained using the List Teams command.	5b7x*****57uw
Is In Team	Optional	If set to True, the returned list will include users who belong to the specified team.	True
Channel ID	Optional	Indicates whether users belong to a channel based on the Is In Channel parameter. Channel ID can be obtained using the List Channels command.	xxef*****b4w
Is In Channel	Optional	If set to True, the returned list will include users who belong to the specified channel. If set to False, the Team ID is required, and the Is In Team parameter must be set to True.	True
Is Inactive	Optional	If set to True, the returned list will contain only deactivated users. If set to False, the list will include only active users. If not specified, all users will be returned, regardless of their status.	False
Without Team	Optional	If set to True, the returned list will only include users that are not on a team. This option takes precedence over Is In Team, and Is In Channel parameter.	False
Page Size	Optional	Sets the maximum number of results for each page of the returned channels. The maximum allowable value is 200.	20

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.

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Results": [
        {
            "id": "*****",
            "create_at": 1659034083300,
            "update_at": 1659048743795,
            "delete_at": 0,
            "username": "*****",
            "auth_data": "",
            "auth_service": "",
            "email": "*****@*****.***",
            "nickname": "",
            "first_name": "Playbooks",
            "last_name": "",
            "position": "",
            "roles": "system_user",
            "last_picture_update": 1659034083839,
            "locale": "en",
            "timezone": {
                "automaticTimezone": "",
                "manualTimezone": "",
                "useAutomaticTimezone": "true"
            },
            "is_bot": true,
            "bot_description": "Playbooks bot.",
            "disable_welcome_email": false
        },
        {
            "id": "*****",
            "create_at": 1659034101737,
            "update_at": 1660352373273,
            "delete_at": 0,
            "username": "*****",
            "auth_data": "",
            "auth_service": "",
            "email": "*****@*****.***",
            "nickname": "",
            "first_name": "",
            "last_name": "",
            "position": "",
            "roles": "system_user system_admin",
            "props": {
                "focalboard_onboardingTourStep": "999",
                "focalboard_tourCategory": "board",
                "focalboard_welcomePageViewed": "1",
                "last_search_pointer": "1"
            },
            "locale": "en",
            "timezone": {
                "automaticTimezone": "America/Los_Angeles",
                "manualTimezone": "",
                "useAutomaticTimezone": "true"
            },
            "disable_welcome_email": false
        }
    ]
}

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

{
  "UserIDs": ["*****","*****"],
  "Usernames": ["*****","*****"],
  "UserRoles": [ "system_user", "system_user system_admin" ]
}

Result

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

SAMPLE DATA

UserCount

2

Error Handling

If the Return Data displays 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.	List Users 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 Mattermost portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server URL is not valid in format.

Error Sample Data

List Users failed.

Status Code: 400.

Message: Server URL is not valid in format.

Remove Channel Member

Removes user(s) from a channel.

READER NOTE

Channel IDs and User ID are required parameters to run this command.

Run the List Channels command to obtain the Channel IDs. Channel IDs can be found in the raw data at the path $.channels[*].id.
Run the List Users command to obtain the User ID. User IDs can be found in the raw data at the path $.Results[*].id.

Input

Input Parameter

Required/Optional

Description

Example

Channel ID

Required

The ID corresponding to a channel where members will be removed. Channel ID can be obtained using the List Channels command

fwbi*****wz1e

User IDs

Required

The IDs corresponding to users to be removed from the channel. User IDs can be obtained using the List Users command.

JSON

["6tqx*****7zoe"]

Output

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Results": [
        {
            "status": "OK",
            "UserID": "*****",
            "D3Messages": "The member has been successfully removed from the channel."
        }
    ],
    "D3Errors": []
}

Result

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

SAMPLE DATA

RemovedMemberCount

1

Error Handling

If the Return Data displays 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.	Remove Channel Member 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 Mattermost portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server URL is not valid in format.

Error Sample Data

Remove Channel Member failed.

Status Code: 400.

Message: Server URL is not valid in format.

Send File

Sends files to a channel.

READER NOTE

Channel IDs and User ID are required parameters to run this command.

Run the List Channels command to obtain the Channel IDs. Channel IDs can be found in the raw data at the path $.channels[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Channel ID	Required	The ID corresponding to a channel where the file will be uploaded. Channel ID can be obtained using the List Channels command.	fwbi*****wz1e
Filenames	Optional	The name of the files.	JSON `["file1", "file2"]`
Message	Required	The message to be posted on the channel.	Upload Files
D3 File IDs	Required	The file id of the file source.	JSON `[ "278" ]`
D3 File Source	Required	The file source of the file to send. The options for file sources are: Incident Attachment File: Manually uploaded file from Incident Playbook File: Output from another Task Artifact File: Ingested Artifact in an Event	Playbook File

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.

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "id": "*****",
    "create_at": 1727876391389,
    "update_at": 1727876391389,
    "edit_at": 0,
    "delete_at": 0,
    "is_pinned": false,
    "user_id": "*****",
    "channel_id": "*****",
    "root_id": "",
    "original_id": "",
    "message": "Upload Files",
    "type": "",
    "props": {},
    "hashtags": "",
    "file_ids": [
        "*****"
    ],
    "pending_post_id": "",
    "remote_id": "",
    "reply_count": 0,
    "last_reply_at": 0,
    "participants": null,
    "metadata": {
        "files": [
            {
                "id": "*****",
                "user_id": "*****",
                "post_id": "*****",
                "channel_id": "*****",
                "create_at": 1727876198458,
                "update_at": 1727876198458,
                "delete_at": 0,
                "name": "Test Messages.eml",
                "extension": "eml",
                "size": 16243,
                "mime_type": "message/rfc822",
                "mini_preview": null,
                "remote_id": "",
                "archived": false
            }
        ]
    }
}

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

{
  "FileIDs": ["*****"]
}

Result

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

SAMPLE DATA

SendFileCount

1

Error Handling

If the Return Data displays 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.	Send File 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 Mattermost portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server URL is not valid in format.

Error Sample Data

Send File failed.

Status Code: 400.

Message: Server URL is not valid in format.

Send Message

Sends a message on a channel.

READER NOTE

Channel IDs and Target User ID are required parameters to run this command.

Run the List Channels command to obtain the Channel IDs. Channel IDs can be found in the raw data at the path $.channels[*].id.
Run the List Users command to obtain the Target User ID. Target User IDs can be found in the raw data at the path $.Results[*].id.

This command supports the following types of interactive message contents:

Menu: Only the selected option will be submitted to D3 via the URL configured for the message.
Buttons: Only the clicked button value will be submitted to D3 via the URL configured for the message.

Input

Input Parameter	Required/Optional	Description	Example
Channel ID	Required	The ID corresponding to a channel where the message will be posted. This parameter and the Target User ID parameter cannot both be empty. If both Channel ID and Target User ID are provided, Target User ID will be ignored. Channel ID can be obtained using the List Channels command.	taj4*****549a
Target User ID	Required	The ID corresponding to a user to whom a direct message will be sent. This parameter and the Channel ID cannot both be empty. If both Channel ID and Target User ID are provided, Target User ID will be ignored. Target User ID can be obtained using the List Users command.	JSON `["6tqx*****7zoe"]`
Message	Required	The message to be posted in the specified channel.	Test message.
Set Online Status	Optional	If set to True, the user's status will be updated to online.	True
Root Message ID	Optional	The root message ID that the new message will comment on.	xxef*****hb4w
Properties	Optional	The JSON-formatted properties to be attached to the message as the interactive message. This parameter can accept any valid JSON format strings. The placeholder "<<D3Automation>>" could be used in the button or menu item's URL "$.actions.integration.url" to provide the Webhook URL to D3. The value of the Webhook could be configured in the "$.actions.integration.context" field and could be any JSON format value. And the selected value will also be set into the context field with the key "selected_option". Only the configured value will be set in the context for the button clicked and sent back.	JSON `{ "bkcolor":"red" }`

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.

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "id": "*****",
    "create_at": 1660672005487,
    "update_at": 1660672005487,
    "edit_at": 0,
    "delete_at": 0,
    "is_pinned": false,
    "user_id": "*****",
    "channel_id": "*****",
    "root_id": "*****",
    "original_id": "",
    "message": "A comment from API on Aug.16 (5) with set the set_online parameter to false",
    "type": "",
    "props": {
        "bkcolor": "red"
    },
    "hashtags": "",
    "pending_post_id": "",
    "reply_count": 1,
    "last_reply_at": 0,
    "participants": null,
    "metadata": {}
}

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": *****
}

Result

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

SAMPLE DATA

messageCount

1

Error Handling

If the Return Data displays 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.	Send 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 Mattermost portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server URL is not valid in format.

Error Sample Data

Send Message failed.

Status Code: 400.

Message: Server URL is not valid in format.

Update Message

Updates a message with the given values. This command can be used to update part of the message or overwrite the whole message.

READER NOTE

Message ID is a required parameter to run this command.

Run the Send Message command to obtain the Message ID. Message IDs can be found in the raw data at the path $.id.

To enhance the user experience, D3 recommends incorporating an Update Message task to update the sent message. This task will provide a reply or remove the interactive part to avoid confusing users if the option has been submitted.

Input

Input Parameter	Required/Optional	Description	Example
Message ID	Required	The ID corresponding to the message that will be updated. Message IDs can be obtained using the Send Message command.	smjx*****xxsw
Message	Optional	The text message that will overwrite the existing message. The message can be in the markdown format. When Update Whole Message is set to True, leaving Message empty will clear the pre-existing message. When Update Whole Message is set to False, leaving Message empty will keep the original message	The action has been updated
Properties	Optional	The JSON-formatted properties to be attached to the message to make it an interactive message. This parameter can accept any valid JSON format strings. When Update Whole Message is set to False, leaving this parameter empty will keep the original interactive message. When Update Whole Message is set to True, all previous message properties will be cleared and set with the input value.	JSON `{ "attachments": [ { "pretext": "2nd update", "text": "the action approval has been submitted" } ] }`
Update Whole Message	Optional	Whether the whole message or only the field(s) with value will be updated. If set to True, then the whole message will be updated. By default, the value is False.	True

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.

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "id": "*****",
    "create_at": 1728181153377,
    "update_at": 1728182105634,
    "edit_at": 1728182105634,
    "delete_at": 0,
    "is_pinned": false,
    "user_id": "*****",
    "channel_id": "*****",
    "root_id": "",
    "original_id": "",
    "message": "**The action has been updated**",
    "type": "",
    "props": {
        "attachments": [
            {
                "id": *****,
                "fallback": "",
                "color": "",
                "pretext": "4th update",
                "author_name": "",
                "author_link": "",
                "author_icon": "",
                "title": "",
                "title_link": "",
                "text": "full updated ",
                "fields": null,
                "image_url": "",
                "thumb_url": "",
                "footer": "",
                "footer_icon": "",
                "ts": null,
                "actions": [
                    {
                        "id": "*****"
                    }
                ]
            }
        ]
    },
    "hashtags": "",
    "pending_post_id": "",
    "reply_count": 0,
    "last_reply_at": 0,
    "participants": null,
    "metadata": {
        "embeds": [
            {
                "type": "message_attachment"
            }
        ]
    }
}

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

JSON

{
    "Messages Count": 1
}

Result

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

SAMPLE DATA

messageCount

1

Error Handling

If the Return Data displays 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 Mattermost portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server URL is not valid in format.

Error Sample Data

Update Message failed.

Status Code: 400.

Message: Server URL is not valid in format.

Test Connection

Allows you to perform a health check on an integration connection. Users 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 displays 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.	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 Mattermost portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server URL is not valid in format.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 400.

Message: You must have a valid Support account to call this API