OneTrust

LAST UPDATED: 08/28/2024

Overview

OneTrust is a comprehensive privacy, security, and data governance platform designed to help organizations comply with global regulations and manage data protection. It offers tools for privacy management, consent management, data mapping, risk assessment, incident response, and vendor management. OneTrust supports compliance with laws like GDPR, CCPA, and others, enabling companies to streamline their compliance processes and protect sensitive data. The platform also includes features for automation and reporting, making it a versatile solution for enterprises seeking to enhance their data governance and privacy practices.

D3 SOAR is providing REST operations to function with OneTrust.

OneTrust is available for use in:

D3 SOAR	V12.7.313+
Category	ITSM
Deployment Options	Option II, Option IV

Known Limitations

API rate limits define the maximum number of API requests a single OneTrust account can make within a given period of time. These limits help us provide the reliable and scalable API that our developer community relies on.

Rate limiting is enabled for Trial, UAT, and Production environments to help control API traffic volumes and to provide reliable service. Analysis of historical usage and minimal account requirements are the key factors to decide the rate limits.

Account-Level Rate Limits

Rate-limiting rules are applicable at the OneTrust account level.

Rule	Rate Limit	If Violated
Default Hour Rule	200,000 / Hour	Traffic is blocked from the account for 1 hour.
Default Minute Rule	20,000 / Minute	Traffic is blocked from the account for 1 minute.

Please refer to OneTrust API Rate Limits for detailed information.

Connection

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

Parameter	Description	Example
Server URL	The server URL for the API connection in domain level is the same as your OneTrust UI portal URL.	https://uat.onetrust.com
Client ID	The client ID used for authenticating the API connection.	f7f*****d83
Client Secret	The Client Secret used for authenticating the API connection.	LCZ*****Ouy
API Version	The API version to use for establishing the connection.	v1

Permission Requirements

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

Command	Required Scope
Create Incident	INCIDENT_CREATE SCIM ORGANIZATION
Fetch Event	INCIDENT_READ
Get Assessment Details	ASSESSMENT_READ
Get Incident Details	INCIDENT_READ
Launch Assessment	ASSESSMENT SCIM ORGANIZATION
List Assessments	ASSESSMENT_READ
List Inventories	INVENTORY_READ
List Organization Group	ORGANIZATION
Search Incidents	INCIDENT_READ
Submit Assessment	ASSESSMENT
Submit Responses	ASSESSMENT
Update Incident	INCIDENT SCIM ORGANIZATION
Test Connection	INCIDENT_READ

Administrators define the scope when creating the OneTrust API Client Credentials.

READER NOTE

If the scope of a OneTrust Client Credential needs to be modified, delete the existing credential entirely and create a new one with the correct scopes, rather than editing the scope within the existing credential.

Configuring OneTrust to Work with D3 SOAR

Login to OneTrust using your account credentials.
Navigate to the Users and Groups page.
1. Click on the menu icon on the top left corner.
2. Click on the Users and Groups option under the GENERAL APPS section.
Add a new client credential.
1. Click on the Client Credentials menu item.
2. Click on the Add button.
3. Enter a display name for the new client credential.
4. Click on the Next button.
5. Choose the appropriate scopes for the new client credential based on the vSOC commands that need to be accessed. A comprehensive list of commands and their required scopes can be found in the table located under the Permission Requirements section.
6. Click on the Create button.
Copy and paste the Client ID and Client Secret into D3 vSOC. Store the Client ID and Client Secret in a secure location.

READER NOTE

The Client Secret will only be displayed once. If it is lost, a new one is required. Follow these steps to generate a new Client Secret:

Return to the Client Credentials dashboard and click on the row that corresponds to the forgotten Client Secret.
Click on the Reset Secret button, then click on the Reset button in the popup.

Configuring D3 SOAR to Work with OneTrust

Log in to D3 SOAR.
Find the OneTrust integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type OneTrust 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 OneTrust.
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 Client ID and Client Secret from the OneTrust platform (step 4 in Configuring OneTrust to Work with D3 SOAR) and paste it into the corresponding fields in D3 vSOC.
  3. Input the API Version. The default value is v1.
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 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.
11. 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.
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, 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

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

READER NOTE

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring OneTrust to Work with D3 SOAR 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.

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

Create Incident

Creates a new incident in the Incident Register.

READER NOTE

Organization Name is a required parameter to run this command.

Run the List Organization Group command to obtain Organization Name. Organization Names can be found in the raw data at the path $..name.

Input

Input Parameter	Required/Optional	Description	Example
Incident Name	Optional	The name of the incident. Assign a descriptive name to the incident to quickly reference it in the incident register. If no name is provided, one will be automatically generated using the Incident Number and the creation date.	TestIR0806a
Incident Type	Optional	The type of incident that has occurred. If no type is specified, the default incident type will be set to Unknown.	Social Engineering (e.g. Phishing)
Organization Name	Required	The organization where the incident will be created. Organization Name can be obtained using the List Organization Group command.	HRDepartment2
Assignee Emails or User Group Names	Optional	The email addresses of the incident assignees or the display names of the user groups. The assignee must hold at least an Incident General User role. A user can only be the assignee for their own organization or a downstream organization.	[ "test@d3security.com", "My User Group 1" ]
Description	Optional	A brief description of the incident.	test description
Date Discovered	Optional	The date on which the reporter discovered the incident.	2024-08-05T19:05:00
Date Occurred	Optional	The date on which the incident occurred.	2024-08-05T19:03:00
Deadline	Optional	The date by which the incident investigation or notification is due.	2024-08-05T23:59:59
Root Cause	Optional	A summary of the root cause of the incident.	mis-operation
Source Type	Optional	Indicates how the incident was created. Accepted values are MANUAL or ASSESSMENT. If not specified, the default value is MANUAL.	ASSESSMENT
Additional Fields	Optional	The additional fields to include in the incident beyond the parameters specified above. Prior to inputting this parameter, a custom attribute must be created. Using the sample data format, modify the value1 sub-attribute to your desired custom attribute. The first custom attribute created in OneTrust will be value1, the second will be value2 and so forth. When tracking custom attributes becomes challenging, add a test incident in OneTrust with a test value for the desired custom attribute, then run the Get Incident Details command to determine the <value#> sub-attribute.	{ "attributeValues": { "attributeTextValue.value1": [ { "value": "Hello!" } ] } }

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

{
    "incidentId": "*****"
}

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

{
  "IncidentId": *****
}

Result

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

SAMPLE DATA

incidentId

*****

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.	Create Incident 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 OneTrust 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: Organization Group Name does not exist.

Error Sample Data

Create Incident failed.

Status Code: 404.

Message: Organization Group Name does not exist.

Fetch Event

Ingests OneTrust incidents into VSOC as events. Incidents are ingested based on creation time rather than the updated time field in the incident schema. Therefore, any incident updates made to incidents after ingestion will not be fetched.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Optional	Incidents created after this time (in UTC) will be ingested. If not specified, the default start time is 365 days before the End Time.	2024-08-06 18:00:00
End Time	Optional	Incidents created before this time (in UTC) will be ingested. If not specified, the default end time is the current time.	2024-08-06 18:59:59
Number of Event(s) Fetched	Optional	The maximum number of incidents to return. The permissible range is from 1 to 2000. If this parameter is not specified, all incidents matching the filter criteria will be returned.	10
Incident Status	Optional	Returns incidents with the specified status. If not specified, both Open and Closed incidents will be returned.	OPEN
Incident Stage Name Keys	Optional	Returns incidents with the specified stage name key(s). If not specified, incidents in any stage will be returned. The available stages include: "Responses", "New", "Complete", "Notifying", "Remediating", "Investigating", "Assessment", "Detection", "LessonsLearnt", "Post-IncidentActivity", "Detection" and "Containment,Eradication&Recovery".	[ "New", "Investigating" ]
Incident Workflow Names	Optional	Returns incidents with the specified incident workflow name(s). If not specified, incidents of any workflow will be returned. The available workflow names include: "ISO/IEC 27035", "NIST 800-61" and "Default Workflow".	[ "ISO/IEC 27035", "NIST 800-61", "Default Workflow" ]
Full Text	Optional	Keywords or phrases, including special characters, used for full-text searching. It can search across Incident name, description, type name, assignee name, organization group name, root cause, creator and stage name.	Social Engineering (e.g. Phishing)

Output

Return Data

Indicates one of the possible command execution states: Successful, Successful with No Event Data, 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

{
    "content": [
        {
            "incidentId": "*****",
            "number": 184,
            "incidentTypeId": "*****",
            "incidentTypeNameKey": "SocialEngineering",
            "incidentTypeName": "Social Engineering (e.g. Phishing)",
            "description": null,
            "sourceType": "MANUAL",
            "orgGroupId": "*****",
            "orgGroupName": "HRDepartment2",
            "dateOccurred": null,
            "dateClosed": null,
            "dateDiscovered": null,
            "deadline": null,
            "assigneeName": "Jason Wiele",
            "totalAssessment": 0,
            "isExtended": null,
            "isDeleted": false,
            "createdBy": "*****",
            "creator": "OneTrust User",
            "createdDate": "2024-08-06T18:21:00.590Z",
            "name": "TestIR0806a",
            "openAssessment": 0,
            "workflowId": "*****",
            "workflowNameKey": "DefaultWorkflow",
            "workflowName": "Default Workflow",
            "incidentStageId": "*****",
            "incidentStageNameKey": "Investigating",
            "incidentStageName": "Investigating",
            "incidentStageBadgeColor": null,
            "notificationNeeded": "UNKNOWN",
            "incidentStatus": "OPEN",
            "attributeValues": null
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 2000,
        "sort": [
            {
                "direction": "DESC",
                "property": "createdDate",
                "ignoreCase": false,
                "nullHandling": "NATIVE",
                "ascending": false,
                "descending": true
            }
        ],
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "totalElements": 1,
    "sort": [
        {
            "direction": "DESC",
            "property": "createdDate",
            "ignoreCase": false,
            "nullHandling": "NATIVE",
            "ascending": false,
            "descending": 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

{
  "IncidentIDs": ["*****"],
  "IncidentNumbers": [184]
}

Result

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

SAMPLE DATA

Start Time (UTC)	2024-07-11 02:19
End Time (UTC)	2024-08-10 02:19
Number of Event(s) Fetched	1

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. Please 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. 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 OneTrust 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., $.content) that is used to extract a batch of events from the response raw data. Click Edit Event Source to view the "Main Event JSON Path".
- Main Event JSON Path: $.content
  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 content. The child node denoting the Assignee Name field would be assigneeName. Putting it together, the JSON Path expression to extract the Assignee Name is $.content.assigneeName.

The pre-configured field mappings are detailed below:

Field Name	Source Field
Document ID	.incidentId
Start Time	.createdDate
Description	.description
Status	.incidentStatus
Occur Time	.dateOccurred
Incident Number	.number
Event Type	.incidentTypeName
Source type	.sourceType
Organization Group Name	.orgGroupName
Organization Group ID	.orgGroupId
Closed TimeSource Field	.dateClosed
Discovered Time	.dateDiscovered
Deadline	.deadline
Assignee Name	.assigneeName
Total Assessment Number	.totalAssessment
Is Deleted	.isDeleted
Creator Name	.creator
Event name	.name
Open Assessment Number	.openAssessment
Workflow Name	.workflowName
Workflow ID	.workflowId
Incident Stage	.incidentStageName
Incident Stage Name Key	.incidentStageNameKey
Incident Stage ID	.incidentStageId

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.	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 OneTrust 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: The Start Time cannot be greater than the End Time.

Error Sample Data

Fetch Event failed.

Status Code: 400.

Message: The Start Time cannot be greater than the End Time.

Get Assessment Details

Retrieves details for the specified assessment(s). The response will include information such as basic assessment, respondents, approvers, assessment questions and responses, and assessment risks.

READER NOTE

Assessment IDs is a required parameter to run this command.

Run the List Assessment command to obtain Assessment IDs. Assessment IDs can be found in the raw data at the path $.content[*].assessmentId.

Input

Input Parameter	Required/Optional	Description	Example
Assessment IDs	Required	The ID(s) of the assessment(s) to get details. Assessment IDs can be obtained using the List Assessment command.	[ "*****" ]

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": [
        {
            "assessmentId": "*****",
            "assessmentNumber": 65,
            "name": "UI 806f",
            "description": "",
            "welcomeText": null,
            "orgGroup": {
                "id": "*****",
                "name": "D3 Security Management Systems Inc - Tech Partner",
                "nameKey": null
            },
            "template": {
                "id": "*****",
                "name": "TestTemplate",
                "nameKey": null
            },
            "status": "IN_PROGRESS",
            "createdBy": {
                "id": "*****",
                "name": "Jason Wiele",
                "nameKey": null
            },
            "createdDT": "2024-08-07T01:36:01.423Z",
            "sections": [
                {
                    "header": {
                        "sectionId": "*****",
                        "name": "TestSection1",
                        "description": null,
                        "sequence": 1,
                        "hidden": false,
                        "invalidQuestionIds": [],
                        "requiredUnansweredQuestionIds": [],
                        "requiredQuestionIds": [],
                        "unansweredQuestionIds": [],
                        "effectivenessQuestionIds": [],
                        "riskStatistics": null,
                        "submitted": false
                    },
                    "questions": [
                        {
                            "question": {
                                "id": "*****",
                                "rootVersionId": "*****",
                                "sequence": 1,
                                "questionType": "TEXTBOX",
                                "required": false,
                                "attributes": "{\"isQuestionHintEnabled\":false,\"requireJustification\":false,\"allowLaws\":true}",
                                "friendlyName": null,
                                "description": null,
                                "hint": null,
                                "parentQuestionId": null,
                                "prePopulateResponse": false,
                                "linkAssessmentToInventory": false,
                                "options": [
                                    {
                                        "id": "*****",
                                        "option": "",
                                        "optionKey": null,
                                        "sequence": 1,
                                        "hint": null,
                                        "hintKey": null,
                                        "attributes": null,
                                        "optionType": "DEFAULT",
                                        "score": null
                                    }
                                ],
                                "valid": true,
                                "businessKeyReference": null,
                                "topic": null,
                                "questionLaws": [],
                                "attachmentRequired": false,
                                "responseFilter": null,
                                "linkAssessmentToResponseEntity": false,
                                "readOnly": false,
                                "type": "TEXTBOX",
                                "attributeId": "*****",
                                "seeded": false,
                                "allowMultiSelect": false,
                                "forceOther": false,
                                "assetQuestion": false,
                                "vendorQuestion": false,
                                "entityQuestion": false,
                                "allowJustification": false,
                                "paquestion": false,
                                "inventoryTypeEnum": null,
                                "requireJustification": false,
                                "schema": null,
                                "content": "Enter your response",
                                "isParentQuestionMultiSelect": false
                            },
                            "hidden": false,
                            "lockReason": null,
                            "copyErrors": null,
                            "hasNavigationRules": false,
                            "questionResponses": [
                                {
                                    "responses": [
                                        {
                                            "responseId": "*****",
                                            "response": "This is a test response 0806j",
                                            "responseKey": null,
                                            "type": "DEFAULT",
                                            "responseSourceType": null,
                                            "errorCode": null,
                                            "responseMap": {},
                                            "scaleResponseMap": {},
                                            "controlResponse": null,
                                            "contractResponse": null,
                                            "relationshipResponseDetails": [],
                                            "valid": true,
                                            "textRedacted": false,
                                            "dataElement": {
                                                "id": null,
                                                "name": null,
                                                "nameKey": null
                                            },
                                            "dataSubject": {
                                                "id": null,
                                                "name": null,
                                                "nameKey": null
                                            },
                                            "dataCategory": {
                                                "id": null,
                                                "name": null,
                                                "nameKey": null
                                            }
                                        }
                                    ],
                                    "justification": null,
                                    "maturityScale": null,
                                    "effectivenessScale": null,
                                    "parentAssessmentDetailId": null
                                }
                            ],
                            "risks": null,
                            "rootRequestInformationIds": [],
                            "totalAttachments": 0,
                            "attachmentIds": [],
                            "canReopenWithAllowEditOption": true,
                            "riskCreationAllowed": true,
                            "riskDeletionPopupAllowed": false,
                            "allowMaturityScaleOnQuestions": false,
                            "questionAssociations": null,
                            "responseEditableWhileUnderReview": false
                        }
                    ],
                    "hasNavigationRules": false,
                    "submittedBy": null,
                    "submittedDt": null,
                    "name": "TestSection1",
                    "hidden": false,
                    "valid": true,
                    "description": null,
                    "sectionId": "*****",
                    "sequence": 1,
                    "submitted": false
                }
            ],
            "approvers": [],
            "respondents": [
                {
                    "id": "*****",
                    "name": "*****",
                    "nameKey": null
                }
            ],
            "respondent": {
                "id": "*****",
                "name": "*****",
                "nameKey": null
            },
            "deadline": null,
            "submittedOn": null,
            "completedOn": null,
            "result": null,
            "resultId": null,
            "resultName": null,
            "lowRisk": 0,
            "mediumRisk": 0,
            "highRisk": 0,
            "veryHighRisk": 0,
            "totalRiskCount": 0,
            "riskLevel": "None",
            "residualRiskScore": null,
            "openRiskCount": 0,
            "inherentRiskScore": null,
            "targetRiskScore": null,
            "lastUpdated": "2024-08-07T02:38:37.303Z",
            "primaryEntityDetails": [],
            "primaryRecordType": null,
            "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

{
  "AssessmentIDs": ["*****"],
  "AssessmentNumbers": [65],
  "AssessmentNames": [ "UI 806f" ],
  "Statuses": ["IN_PROGRESS"]
}

Result

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

SAMPLE DATA

Results

{'assessmentId': '*****', 'assessmentNumber': 65, 'name': 'UI 806f', 'description': '', 'welcomeText': None, 'orgGroup': {'id': '*****', 'name': 'D3 Security Management Systems Inc - Tech Partner', 'nameKey': None}, 'template': {'id': '*****', 'name': 'TestTemplate', 'nameKey': None}, 'status': 'IN_PROGRESS', 'createdBy': {'id': '*****', 'name': 'Jason Wiele', 'nameKey': None}, 'createdDT': '2024-08-07T01:36:01.423Z', 'sections': [{'header': {'sectionId': '*****', 'name': 'TestSection1', 'description': None, 'sequence': 1, 'hidden': False, 'invalidQuestionIds': [], 'requiredUnansweredQuestionIds': [], 'requiredQuestionIds': [], 'unansweredQuestionIds': [], 'effectivenessQuestionIds': [], 'riskStatistics': None, 'submitted': False}, 'questions': [{'question': {'id': '*****', 'rootVersionId': '*****', 'sequence': 1, 'questionType': 'TEXTBOX', 'required': False, 'attributes': '{"isQuestionHintEnabled":false,"requireJustification":false,"allowLaws":true}', 'friendlyName': None, 'description': None, 'hint': None, 'parentQuestionId': None, 'prePopulateResponse': False, 'linkAssessmentToInventory': False, 'options': [{'id': '*****', 'option': '', 'optionKey': None, 'sequence': 1, 'hint': None, 'hintKey': None, 'attributes': None, 'optionType': 'DEFAULT', 'score': None}], 'valid': True, 'businessKeyReference': None, 'topic': None, 'questionLaws': [], 'attachmentRequired': False, 'responseFilter': None, 'linkAssessmentToResponseEntity': False, 'readOnly': False, 'type': 'TEXTBOX', 'attributeId': '*****', 'seeded': False, 'allowMultiSelect': False, 'forceOther': False, 'assetQuestion': False, 'vendorQuestion': False, 'entityQuestion': False, 'allowJustification': False, 'paquestion': False, 'inventoryTypeEnum': None, 'requireJustification': False, 'schema': None, 'content': 'Enter your response', 'isParentQuestionMultiSelect': False}, 'hidden': False, 'lockReason': None, 'copyErrors': None, 'hasNavigationRules': False, 'questionResponses': [{'responses': [{'responseId': '*****', 'response': 'This is a test response 0806j', 'responseKey': None, 'type': 'DEFAULT', 'responseSourceType': None, 'errorCode': None, 'responseMap': {}, 'scaleResponseMap': {}, 'controlResponse': None, 'contractResponse': None, 'relationshipResponseDetails': [], 'valid': True, 'textRedacted': False, 'dataElement': {'id': None, 'name': None, 'nameKey': None}, 'dataSubject': {'id': None, 'name': None, 'nameKey': None}, 'dataCategory': {'id': None, 'name': None, 'nameKey': None}}], 'justification': None, 'maturityScale': None, 'effectivenessScale': None, 'parentAssessmentDetailId': None}], 'risks': None, 'rootRequestInformationIds': [], 'totalAttachments': 0, 'attachmentIds': [], 'canReopenWithAllowEditOption': True, 'riskCreationAllowed': True, 'riskDeletionPopupAllowed': False, 'allowMaturityScaleOnQuestions': False, 'questionAssociations': None, 'responseEditableWhileUnderReview': False}], 'hasNavigationRules': False, 'submittedBy': None, 'submittedDt': None, 'name': 'TestSection1', 'hidden': False, 'valid': True, 'description': None, 'sectionId': '*****', 'sequence': 1, 'submitted': False}], 'approvers': [], 'respondents': [{'id': '*****', 'name': '*****', 'nameKey': None}], 'respondent': {'id': '*****', 'name': '*****', 'nameKey': None}, 'deadline': None, 'submittedOn': None, 'completedOn': None, 'result': None, 'resultId': None, 'resultName': None, 'lowRisk': 0, 'mediumRisk': 0, 'highRisk': 0, 'veryHighRisk': 0, 'totalRiskCount': 0, 'riskLevel': 'None', 'residualRiskScore': None, 'openRiskCount': 0, 'inherentRiskScore': None, 'targetRiskScore': None, 'lastUpdated': '2024-08-07T02:38:37.303Z', 'primaryEntityDetails': [], 'primaryRecordType': None, 'tags': []}

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.	Get Assessment Details 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 OneTrust portal. Refer to the HTTP Status Code Registry for details.	Status Code: 422.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Unable to process request due to invalid content/data type.

Error Sample Data

Get Assessment Details failed.

Status Code: 422.

Message: Unable to process request due to invalid content/data type.

Get Incident Details

Retrieves the key attributes of selected incidents by their unique identifiers.

READER NOTE

Incident IDs is a required parameter to run this command.

Run the Search Incidents command to obtain Incident IDs. Incident IDs can be found in the raw data at the path $.content[*].incidentId.

Input

Input Parameter	Required/Optional	Description	Example
Incident IDs	Required	The ID(s) of the incident(s) for which to retrieve details. Incident ID can be obtained using the Search Incidents command.	[ "*****" ]

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

[
    {
        "id": "*****",
        "number": 185,
        "incidentTypeId": "*****",
        "incidentTypeNameKey": "SocialEngineering",
        "incidentTypeName": "Social Engineering (e.g. Phishing)",
        "name": "TestIR0806a",
        "description": "test description806a",
        "sourceType": "MANUAL",
        "assessmentLinks": [],
        "incidentStageRulesId": [
            "*****",
            "*****"
        ],
        "orgGroupId": "*****",
        "orgGroupName": "HRDepartment2",
        "rootCause": "mis-operation",
        "dateOccurred": "2024-08-05T19:03:00.000Z",
        "dateClosed": "2024-08-07T17:26:53.387Z",
        "dateDiscovered": "2024-08-05T19:05:00.000Z",
        "deadline": "2024-08-05T23:59:59.000Z",
        "createdBy": "*****",
        "creator": "OneTrust User",
        "assigneeId": null,
        "assigneeName": null,
        "affectedSubjectRangeFrom": null,
        "affectedSubjectRangeTo": null,
        "createdDT": "2024-08-06T18:45:05.920Z",
        "workflowId": "*****",
        "workflowNameKey": "DefaultWorkflow",
        "workflowName": "Default Workflow",
        "incidentStageId": "*****",
        "incidentStageNameKey": "Complete",
        "incidentStageName": "Complete",
        "incidentStageBadgeColor": null,
        "notificationNeeded": "UNKNOWN",
        "incidentStatus": "CLOSED",
        "schemaId": "*****",
        "updatedDT": "2024-08-07T17:26:53.417Z",
        "attributeValues": {},
        "incidentAssigneeInformation": [],
        "closedSettingOn": 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

{
  "IncidentTypeNames": [ "Social Engineering (e.g. Phishing)" ],
  "Descriptions": [ "test description806a" ],
  "OrgGroupNames": ["HRDepartment2"],
  "Creators": [ "OneTrust User" ],
  "CreateDates": ["2024-08-06T18:45:05.920Z"],
  "Names": ["TestIR0806a"]
}

Result

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

SAMPLE DATA

id	*****
number	185
incidentTypeId	*****
incidentTypeNameKey	SocialEngineering
incidentTypeName	Social Engineering (e.g. Phishing)
name	TestIR0806a
description	test description806a
sourceType	MANUAL
assessmentLinks	[]
incidentStageRulesId	['***', '***']
orgGroupId	*****
orgGroupName	HRDepartment2
rootCause	mis-operation
dateOccurred	2024-08-05T19:03:00.000Z
dateClosed	2024-08-07T17:26:53.387Z
dateDiscovered	2024-08-05T19:05:00.000Z
deadline	2024-08-05T23:59:59.000Z
createdBy	*****
creator	OneTrust User
assigneeId	None
assigneeName	None
affectedSubjectRangeFrom	None
affectedSubjectRangeTo	None
createdDT	2024-08-06T18:45:05.920Z
workflowId	*****
workflowNameKey	DefaultWorkflow
workflowName	Default Workflow
incidentStageId	*****
incidentStageNameKey	Complete
incidentStageName	Complete
incidentStageBadgeColor	None
notificationNeeded	UNKNOWN
incidentStatus	CLOSED
schemaId	*****
updatedDT	2024-08-07T17:26:53.417Z
attributeValues	{}
incidentAssigneeInformation	[]
closedSettingOn	TRUE

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.	Get Incident Details 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 OneTrust 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: Failed to convert 'incidentId' with value: '12345'.

Error Sample Data

Get Incident Details failed.

Status Code: 400.

Message: Failed to convert 'incidentId' with value: '12345'.

Launch Assessment

Launches a new assessment. The new assessment will be created based on the details provided in the request body and assigned to the specified respondents.

READER NOTE

Organization Group Name is a required parameter to run this command.

Run the List Organization Group command to obtain Organization Group Name. Organization Group Names can be found in the raw data at the path $..name.

Template ID, Template Root Version ID and Inventory ID are optional parameters to run this command.

Run the List Assessments command to obtain Template IDs.
Run the List Assessments command to obtain Template Root Version IDs.
Run the List Inventories command to obtain Inventory IDs.

Input

Input Parameter	Required/Optional	Description	Example
Assessment Name	Required	The name of the assessment.	CASE 0806b D3 POSTMAN
Template ID	Optional	The ID used to launch an assessment using a specific version of a template. You must use either this parameter or the Template Root Version ID parameter to launch an assessment.Template ID can be obtained using the List Assessments command. If both Template ID and Template Root Version ID are provided, Template ID will be ignored.	*****
Template Root Version ID	Optional	The root version ID used to launch an assessment using a specific version of a template. You must use either this parameter or the Template ID parameter to launch an assessment. Template Root Version ID can be obtained using the List Assessments command. If both Template ID and Template Root Version ID are provided, Template ID will be ignored.	*****
Organization Group Name	Required	The name of the organization group that should be assigned to the assessment. Organization Group Name can be obtained using the List Organization Group command.	HRDepartment2
Respondent Emails Or UserGroup Names	Required	The email address(es) of respondent(s) or the display name(s) of user group(s) assigned to the assessment. At least one respondent must be added in order to launch the assessment.	[ "test@d3security.com" ]
Approver Email Or User Group Name	Optional	The email address of a user or the display name of a user group assigned as the Approver of the assessment. The approver must hold the Assessments Manager role. A user can only be the approver for their own organization or a downstream organization.	test@d3security.com
Description	Optional	A description of the assessment.	test desc D3 POSTMAN 0806b
Deadline	Optional	The time by which the assessment should be completed.	2024-08-05T23:59:59
Inventory ID	Optional	The ID of the primary record of the assessment. Inventory ID can be obtained using the List Inventories command. Inventory ID and Inventory Type must be specified together. If only one is provided, both parameters will be disregarded.	*****
Inventory Type	Optional	The Primary Record Type, with available options being Assets, Processing Activities, Vendors and Entities. Inventory ID and Inventory Type must be specified together. If only one is provided, both parameters will be disregarded.	Entities
Respondent Creation Type	Optional	Indicates whether new respondents are created as Invited Users or Project Respondents, when launching an assessment. New users can be designated as Project Respondents only when the 'Allow Creating Project Respondents from Assessment' setting is enabled for the account in OneTrust's Global Settings > Assessments directory.	PROJECT_RESPONDENT
Additional Fields	Optional	The additional field(s) to include in the assessment beyond the parameters specified above.	{ "reminder": 3 }

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

{
    "AssessmentID": "*****"
}

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

{
  "AssessmentID": *****
}

Result

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

SAMPLE DATA

AssessmentID

*****

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.	Launch Assessment 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 OneTrust 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: Organization Group Name does not exist.

Error Sample Data

Launch Assessment failed.

Status Code: 404.

Message: Organization Group Name does not exist.

List Assessments

Retrieves a list of all assessments with basic details, including the assessment ID, number, state, result, and associated organization.

Input

Input Parameter	Required/Optional	Description	Example
Assessment Statuses	Optional	Returns assessments with the specified status(es). The available statuses are NOT_STARTED, IN_PROGRESS, UNDER_REVIEW, and COMPLETED. If no status is specified, assessments of all types will be returned.	[ "UNDER_REVIEW", "COMPLETED" ]

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

{
    "content": [
        {
            "assessmentId": "*****",
            "number": 44,
            "name": "test123",
            "status": "Under Review",
            "state": "ACTIVE",
            "result": null,
            "resultId": null,
            "resultName": null,
            "orgGroupName": "HRDepartment",
            "createDt": "2022-09-09 17:44:56",
            "tags": [],
            "templateName": "TestTemplate",
            "templateId": "*****",
            "templateRootVersionId": "*****",
            "primaryInventoryDetails": null,
            "residualRiskScore": null,
            "openRiskCount": 0,
            "inherentRiskScore": null,
            "targetRiskScore": null,
            "lastUpdated": "2022-09-09T17:45:09.103Z"
        }
    ],
    "page": {
        "totalElements": 32
    }
}

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

{
    "AssessmentIDs": ["*****"],
    "AssessmentStatuses": ["UNDER_REVIEW"],
    "AssessmentNumbers": [44],
    "AssessmentNames": ["test123"],
    "TemplateIDs": ["*****"],
    "TemplateNames": ["TestTemplate"],
    "TemplateRootVersionIDs": ["*****"]
}

Result

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

SAMPLE DATA

Assessments 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 Assessments 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 OneTrust 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: Wrong input parameter data found, the available statuses are NOT_STARTED, IN_PROGRESS, UNDER_REVIEW and COMPLETED.

Error Sample Data

List Assessments failed.

Status Code: 400.

Message: Wrong input parameter data found, the available statuses are NOT_STARTED, IN_PROGRESS, UNDER_REVIEW and COMPLETED.

List Inventories

Retrieves a list of inventories for a given type.

Input

Input Parameter	Required/Optional	Description	Example
Inventory Type	Required	The type of the inventories to be returned. The options are Assets, Entities, Processing Activities, and Vendors.	Entities

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

{
    "data": [
        {
            "id": "*****",
            "name": "LLC",
            "organization": {
                "id": "*****",
                "value": "D3 Security Management Systems Inc - Tech Partner"
            },
            "primaryOperatingLocation": {
                "id": "*****",
                "value": "Unknown",
                "valueKey": "Unknown"
            },
            "isEditable": true,
            "isDeletable": true,
            "canViewDetails": true,
            "status": {
                "key": "active"
            },
            "number": 1,
            "isParent": false,
            "updatedBy": {
                "id": "*****"
            },
            "createdBy": {
                "id": "*****"
            },
            "createdDate": "2021-10-18T19:51:36.440Z",
            "updatedDate": "2021-10-18T19:51:36.507Z",
            "type": [
                {
                    "id": "*****",
                    "value": "Client",
                    "valueKey": "EntitiesTypeClient"
                }
            ]
        }
    ],
    "meta": {
        "page": {
            "totalElements": 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

{
  "InventoryIDs": ["*****"],
  "InventoryNames": ["LLC"]
}

Result

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

SAMPLE DATA

Inventories 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 Inventories 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 OneTrust 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: You are not authorized to access this resource.

Error Sample Data

List Inventories failed.

Status Code: 403.

Message: You are not authorized to access this resource.

List Organization Group

Retrieves the list of all organizations within your tenant.

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

{
    "organizationId": "*****",
    "externalId": null,
    "parentOrganizationId": null,
    "parentExternalId": null,
    "name": "D3 Security Management Systems Inc - Tech Partner",
    "defaultApprover": "*****@d3security.com",
    "defaultLanguageCode": "en-us",
    "description": null,
    "children": [
        {
            "organizationId": "*****",
            "externalId": "HR_Depart",
            "parentOrganizationId": "*****",
            "parentExternalId": null,
            "name": "HRDepartment",
            "defaultApprover": "*****@d3security.com",
            "defaultLanguageCode": "en-us",
            "description": "Human Resource",
            "children": []
        },
        {
            "organizationId": "*****",
            "externalId": "HR_Depart2",
            "parentOrganizationId": "*****",
            "parentExternalId": null,
            "name": "HRDepartment2",
            "defaultApprover": "*****@d3security.com",
            "defaultLanguageCode": "en-us",
            "description": "Human Resource",
            "children": []
        },
        {
            "organizationId": "*****",
            "externalId": "HR_Depart11",
            "parentOrganizationId": "*****",
            "parentExternalId": null,
            "name": "HRDepartment",
            "defaultApprover": "*****@d3security.com",
            "defaultLanguageCode": "en-us",
            "description": "Human Resource",
            "children": []
        }
    ]
}

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

{
    "OrgGroupNames": [ "D3 Security Management Systems Inc - Tech Partner", "HRDepartment", "HRDepartment2", "HRDepartment" ],
    "OrgGroupIds": ["*****","*****","*****","*****"],
    "Descriptions": [ "None", "Human Resource", "Human Resource", "Human Resource" ]
}

Result

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

SAMPLE DATA

organizationId	*****
externalId	None
parentOrganizationId	None
parentExternalId	None
name	D3 Security Management Systems Inc - Tech Partner
defaultApprover	*****@d3security.com
defaultLanguageCode	en-us
description	None
children	{'organizationId': '***', 'externalId': 'HR_Depart', 'parentOrganizationId': '*', 'parentExternalId': None, 'name': 'HRDepartment', 'defaultApprover': '*@d3security.com', 'defaultLanguageCode': 'en-us', 'description': 'Human Resource', 'children': []} {'organizationId': '*', 'externalId': 'HR_Depart2', 'parentOrganizationId': '*', 'parentExternalId': None, 'name': 'HRDepartment2', 'defaultApprover': '*@d3security.com', 'defaultLanguageCode': 'en-us', 'description': 'Human Resource', 'children': []} {'organizationId': '*', 'externalId': 'HR_Depart11', 'parentOrganizationId': '*', 'parentExternalId': None, 'name': 'HRDepartment', 'defaultApprover': '***@d3security.com', 'defaultLanguageCode': 'en-us', 'description': 'Human Resource', 'children': []}

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 Organization Group 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 OneTrust 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: You are not authorized to access this resource.

Error Sample Data

List Organization Group failed.

Status Code: 403.

Message: You are not authorized to access this resource.

Search Incidents

Searches for incidents by key terms.

Input

Input Parameter	Required/Optional	Description	Example
Keyword	Optional	The full-text search terms are used to filter incidents. They can be based on incident name, description, type name, assignee name, organization group name, root cause, creator, and stage name.	Social Engineering (e.g. Phishing)

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

{
    "content": [
        {
            "incidentId": "*****",
            "number": 185,
            "incidentTypeId": "*****",
            "incidentTypeNameKey": "SocialEngineering",
            "incidentTypeName": "Social Engineering (e.g. Phishing)",
            "description": "test description806a",
            "sourceType": "MANUAL",
            "orgGroupId": "*****",
            "orgGroupName": "HRDepartment2",
            "dateOccurred": "2024-08-05T19:03:00.000Z",
            "dateClosed": "2024-08-07T17:26:53.387Z",
            "dateDiscovered": "2024-08-05T19:05:00.000Z",
            "deadline": "2024-08-05T23:59:59.000Z",
            "assigneeName": null,
            "totalAssessment": 0,
            "isExtended": null,
            "isDeleted": false,
            "createdBy": "*****",
            "creator": "OneTrust User",
            "createdDate": "2024-08-06T18:45:05.920Z",
            "name": "TestIR0806a",
            "openAssessment": 0,
            "workflowId": "*****",
            "workflowNameKey": "DefaultWorkflow",
            "workflowName": "Default Workflow",
            "incidentStageId": "*****",
            "incidentStageNameKey": "Complete",
            "incidentStageName": "Complete",
            "incidentStageBadgeColor": null,
            "notificationNeeded": "UNKNOWN",
            "incidentStatus": "CLOSED",
            "attributeValues": null
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 1,
        "sort": [
            {
                "direction": "DESC",
                "property": "createdDate",
                "ignoreCase": false,
                "nullHandling": "NATIVE",
                "ascending": false,
                "descending": true
            }
        ],
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "totalElements": 29,
    "sort": [
        {
            "direction": "DESC",
            "property": "createdDate",
            "ignoreCase": false,
            "nullHandling": "NATIVE",
            "ascending": false,
            "descending": true
        }
    ],
    "numberOfElements": 1,
    "empty": 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

{
    "IncidentIds": ["*****"],
    "IncidentTypeNames": [ "Social Engineering (e.g. Phishing)" ],
    "Descriptions":  [ "test description806a" ],
    "OrgGroupNames": ["HRDepartment2"],
    "Creators": [ "OneTrust User" ],
    "CreateDates": ["2024-08-06T18:45:05.920Z"],
    "Names": ["TestIR0806a"]
}

Result

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

SAMPLE DATA

content	{'incidentId': '***', 'number': 185, 'incidentTypeId': '*', 'incidentTypeNameKey': 'SocialEngineering', 'incidentTypeName': 'Social Engineering (e.g. Phishing)', 'description': 'test description806a', 'sourceType': 'MANUAL', 'orgGroupId': '*', 'orgGroupName': 'HRDepartment2', 'dateOccurred': '2024-08-05T19:03:00.000Z', 'dateClosed': '2024-08-07T17:26:53.387Z', 'dateDiscovered': '2024-08-05T19:05:00.000Z', 'deadline': '2024-08-05T23:59:59.000Z', 'assigneeName': None, 'totalAssessment': 0, 'isExtended': None, 'isDeleted': False, 'createdBy': '*', 'creator': 'OneTrust User', 'createdDate': '2024-08-06T18:45:05.920Z', 'name': 'TestIR0806a', 'openAssessment': 0, 'workflowId': '*', 'workflowNameKey': 'DefaultWorkflow', 'workflowName': 'Default Workflow', 'incidentStageId': '***', 'incidentStageNameKey': 'Complete', 'incidentStageName': 'Complete', 'incidentStageBadgeColor': None, 'notificationNeeded': 'UNKNOWN', 'incidentStatus': 'CLOSED', 'attributeValues': None}
pageable	{'pageNumber': 0, 'pageSize': 1, 'sort': [{'direction': 'DESC', 'property': 'createdDate', 'ignoreCase': False, 'nullHandling': 'NATIVE', 'ascending': False, 'descending': True}], 'offset': 0, 'paged': True, 'unpaged': False}
last	False
totalElements	29
totalPages	29
size	1
number	0
sort	{'direction': 'DESC', 'property': 'createdDate', 'ignoreCase': False, 'nullHandling': 'NATIVE', 'ascending': False, 'descending': True}
first	True
numberOfElements	1
empty	False

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.	Search Incidents 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 OneTrust 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: You are not authorized to access this resource.

Error Sample Data

Search Incidents failed.

Status Code: 403.

Message: You are not authorized to access this resource.

Submit Assessment

Submits an assessment for review. This action will move the assessment to the Under Review stage.

READER NOTE

Assessment IDs is a required parameter to run this command.

Run the List Assessments command to obtain Assessment IDs. Assessment IDs can be found in the raw data at the path $.content[*].assessmentId.
Alternatively, run the Launch Assessment command to obtain an Assessment ID. Assessment ID can be found in the raw data at the path $.AssessmentID.

Input

Input Parameter

Required/Optional

Description

Example

Assessment IDs

Required

The assessment ID(s) to submit.

Assessment ID can be obtained using the List Assessments or Launch Assessment commands.

Only assessments with the statuses of NOT_STARTED and IN_PROGRESS can be submitted.

Responses to all required questions must be submitted prior to using this command, which can be done using the Submit Responses command.

[ "*****" ]

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": [
        {
            "AssessmentID": "*****",
            "Message": "Assessment is submitted."
        }
    ]
}

Result

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

SAMPLE DATA

Submitted Assessments Count

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.	Submit Assessment 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 OneTrust 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: You are not authorized to access this resource.

Error Sample Data

Submit Assessment failed.

Status Code: 403.

Message: You are not authorized to access this resource.

Submit Responses

Submits responses for an assessment. The assessment will be updated with the submitted response. Please note that responses cannot be added to assessments that have already been completed.

Known Issue

[August 2024]

When using the Submit Responses endpoint for the PIA & DPIA Automation - Assessment Actions, empty values may appear in the response body for many key-value pairs from the second submission onwards for the same assessment.

Despite the null values, the response submission is successful if the parameters are correct. The command's logic has been verified to ensure correct input passing to OneTrust.

READER NOTE

Assessment ID is a required parameter to run this command.

Run the List Assessments command to obtain Assessment ID. Assessment IDs can be found in the raw data at the path $.content[*].assessmentId.
Alternatively, run the Launch Assessment command to obtain an Assessment ID. Assessment ID can be found in the raw data at the path $.AssessmentID.

Input

Input Parameter	Required/Optional	Description	Example
Assessment ID	Required	The ID associated with the assessment to which the responses will update. Assessment ID can be obtained using the List Assessments or Launch Assessment commands. Responses cannot be added to assessments that have already been completed.	*****
Parent Assessment Detail ID	Optional	The ID of the parent assessment detail. Parent Assessment Detail ID can be obtained using the Get Assessment Details command.	*****
Question Responses Objects	Required	The JSON array of response objects. Question Responses Object can be obtained using the Get Assessment Details command. If assessmentId and parentAssessmentDetailId are not specified in the JSON object, these fields will be populated with the Assessment ID and Parent Assessment Detail ID parameters.	[ { "sectionId": "***", "questionId": "***", "responses": [ { "response": "This is a test response 0806j" } ] } ]

READER NOTE

Because constructing response objects can be challenging, and the OneTrust API documentation may not offer sufficient guidance, please do not hesitate to reach out to D3 for support.

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

{
    "firstAssignedTemplateId": null,
    "status": null,
    "result": null,
    "sectionHeaders": null,
    "section": null,
    "deadline": null,
    "reminder": null,
    "canSubmit": false,
    "canApproveAssessment": false,
    "displayState": "REFRESH_NONE",
    "questions": null,
    "inventoryLinks": null,
    "hasRequestInformation": false,
    "invalidQuestionToRiskIdMap": {},
    "laws": [],
    "maturityType": null,
    "reviewChangedResponses": false,
    "parentAssessmentId": null,
    "editAllResponsesWhenInProgress": false,
    "assessmentProgressInformation": null,
    "welcomeSectionInformation": null,
    "welcomeText": null,
    "lastSection": false,
    "firstSection": false,
    "welcomeSection": false,
    "viewer": false
}

Result

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

SAMPLE DATA

status	IN_PROGRESS
result	IN_PROGRESS

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.	Submit Responses 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 OneTrust 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: The value for parameter (Question Responses Objects) is invalid.

Error Sample Data

Submit Responses failed.

Status Code: 400.

Message: The value for parameter (Question Responses Objects) is invalid.

Update Incident

Updates the details of a specific incident.

READER NOTE

Incident ID is a required parameter to run this command.

Run the Search Incidents command to obtain Incident ID. Incident IDs can be found in the raw data at the path $.content[*].incidentId.

Organization Name is an optional parameter to run this command.

Run the List Organization Group command to obtain Organization Name. Organization Names can be found in the raw data at the path $..name.

Input

Input Parameter	Required/Optional	Description	Example
Incident ID	Required	The ID of the incident to be updated. Incident ID can be obtained using the Search Incidents command.	*****
Incident Name	Optional	The new name of the incident. Ensure that the name is descriptive to facilitate quick reference in the incident register.	TestIR0806a-NEW
Organization Name	Optional	The organization group that will be associated with or responsible for the incident after the update. Organization Name can be obtained using the List Organization Group command.	D3 Security Management Systems Inc - Tech Partner
Assignee Emails or User Group Names	Optional	The new emails of the incident assignees, or new display names of user groups. The assignee must hold at least an Incident General User role. A user can only be the assignee for their own organization or a downstream organization.	[ "test@d3security.com", "My User Group 1" ]
Description	Optional	The new description of the incident.	New test description 807a
Date Discovered	Optional	The revised date on which the incident was discovered by the reporter.	2024-08-05T19:35:00
Date Occurred	Optional	The revised date on which the incident occurred.	2024-08-05T19:33:00
Deadline	Optional	The revised date by which the incident investigation or notification is due.	2024-08-06T23:59:59
Root Cause	Optional	The revised summary of the root cause of the incident.	mis-configuration
Source Type	Optional	The updated source type. The source type indicates how the incident was created. Accepted values are MANUAL or ASSESSMENT.	ASSESSMENT
Additional Fields	Optional	The additional fields to include in the incident beyond the parameters specified above. Prior to inputting this parameter, a custom attribute must be created. Using the sample data format, modify the value1 sub-attribute to your desired custom attribute. The first custom attribute created in OneTrust will be value1, the second will be value2 and so forth. When tracking custom attributes becomes challenging, add a test incident in OneTrust with a test value for the desired custom attribute, then run the Get Incident Details command to determine the <value#> sub-attribute.	{ "attributeValues": { "attributeTextValue.value1": [ { "value": "Hello!" } ] } }

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

{
    "id": "*****",
    "number": 185,
    "incidentTypeId": "*****",
    "incidentTypeNameKey": "UserAccountCompromise",
    "incidentTypeName": "User Account Compromise",
    "name": "TestIR0806a-NEW",
    "description": "New test description 807a",
    "sourceType": "MANUAL",
    "assessmentLinks": [],
    "incidentStageRulesId": [
        "*****",
        "*****"
    ],
    "orgGroupId": "*****",
    "orgGroupName": "D3 Security Management Systems Inc - Tech Partner",
    "rootCause": "mis-configuration",
    "dateOccurred": "2024-08-05T19:33:00.000Z",
    "dateClosed": null,
    "dateDiscovered": "2024-08-05T19:35:00.000Z",
    "deadline": "2024-08-06T23:59:59.000Z",
    "createdBy": "*****",
    "creator": "OneTrust User",
    "assigneeId": null,
    "assigneeName": null,
    "affectedSubjectRangeFrom": null,
    "affectedSubjectRangeTo": null,
    "createdDT": "2024-08-06T18:45:05.920Z",
    "workflowId": "*****",
    "workflowNameKey": "DefaultWorkflow",
    "workflowName": "Default Workflow",
    "incidentStageId": "*****",
    "incidentStageNameKey": "Complete",
    "incidentStageName": "Complete",
    "incidentStageBadgeColor": null,
    "notificationNeeded": "UNKNOWN",
    "incidentStatus": "CLOSED",
    "schemaId": "*****",
    "updatedDT": "2024-08-07T20:21:57.813Z",
    "attributeValues": {},
    "incidentAssigneeInformation": [],
    "jurisdictions": [],
    "closedSettingOn": 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

{
  "IncidentId": *****
}

Result

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

SAMPLE DATA

id	*****
number	185
incidentTypeId	*****
incidentTypeNameKey	UserAccountCompromise
incidentTypeName	User Account Compromise
name	TestIR0806a-NEW
description	New test description 807a
sourceType	MANUAL
assessmentLinks	[]
incidentStageRulesId	*** ***
orgGroupId	*****
orgGroupName	D3 Security Management Systems Inc - Tech Partner
rootCause	mis-configuration
dateOccurred	2024-08-05T19:33:00.000Z
dateClosed	None
dateDiscovered	2024-08-05T19:35:00.000Z
deadline	2024-08-06T23:59:59.000Z
createdBy	*****
creator	OneTrust User
assigneeId	None
assigneeName	None
affectedSubjectRangeFrom	None
affectedSubjectRangeTo	None
createdDT	2024-08-06T18:45:05.920Z
workflowId	*****
workflowNameKey	DefaultWorkflow
workflowName	Default Workflow
incidentStageId	*****
incidentStageNameKey	Complete
incidentStageName	Complete
incidentStageBadgeColor	None
notificationNeeded	UNKNOWN
incidentStatus	CLOSED
schemaId	*****
updatedDT	2024-08-07T20:21:57.813Z
attributeValues	{}
incidentAssigneeInformation	[]
jurisdictions	[]
closedSettingOn	False

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.	Partially Successful.
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 OneTrust 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: Assignee email example@d3security.com does not exist.

Error Sample Data

Update Incident failed.

Status Code: 404.

Message: Assignee email example@d3security.com does not exist.

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.

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

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 OneTrust 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, Client ID, Client Secret are required.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 400.

Message: Server URL, Client ID, Client Secret are required.