OpenCTI

LAST UPDATED: 05/30/2024

Overview

OpenCTI is an open-source platform allowing organizations to structure, store, and organize information about Cyber Threats. OpenCTI enables you to go beyond only technical (TTPs and observables) and non-technical information (suggested attribution, victimology).

D3 SOAR is providing REST operations to function with OpenCTI.

OpenCTI is available for use in:

D3 SOAR	V14.5.56.0+
Category	SIEM
Deployment Options	Option I, Option III

ALERT

As of April 2023, the current OpenCTI versions supported by D3 SOAR are limited to 5.5.0 and 5.6.2. The availability of support for future release of the OpenCTI platform will be contingent on the API support offered by OpenCTI. Please contact the D3 support team if you have compatibility issues.

Connection

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

Parameter	Description	Example
Server URL	The server URL of the OpenCTI instance.	http://192.168.87.91:8080
API Key	The API key to authenticate the connection.	024948c1-**--**-6a89d86bed5a

Permission Requirements

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

Command	Required Permission
Add Observable	Access knowledge > Create / Update knowledge
Create Indicator	Access knowledge > Create / Update knowledge
Create Observable	Access knowledge > Create / Update knowledge If you need to input Labels, Author, Markings, and External References parameters, Bypass all capabilities is needed.
Get Indicators	Access knowledge
List Authors	Bypass all capabilities
List External References	Access knowledge
List indicators	Access knowledge
List Labels	Access knowledge
List Marking	Access knowledge
List Observables	Access knowledge
Test Connection	Bypass all capabilities or Access knowledge

OpenCTI is using role-based access control (RBAC), and the API Key is generated based on a specific user account and the use case. Therefore, the command permissions are inherited from the user account’s role. The administrator needs to create a connector role with the required capabilities and link that role with a user before obtaining the API key to build the integration connection in D3 SOAR (see Creating a user and assigning roles and Generating an API Key). Users can then configure their user profile from the OpenCTI console for each command in this integration.

Configuring OpenCTI to Work with D3 SOAR

Log in to the server of the OpenCTI platform (http://<Server URL>:8080) with an administrator account.

Creating Roles and adding to group

Navigate to Dashboard > Settings > Security > Roles, and click + located at the bottom right corner to add a new role. The Create a role window will appear.

Input a name and description (optional) for the role, then click Create.

Find the newly created role and click on the corresponding three-dot button. Click Update.

Click CAPABILITIES. Then select and enable the required capabilities for the role (see Permission Requirements).

Reader Note

To run all available commands for this integration in D3 SOAR, only the Bypass all capabilities, Access knowledge and Create/Update knowledge capabilities are required. Please refer to Permission Requirements for the required permissions for specific commands for this integration. Please note that the OpenCTI Connectors Guide recommends enabling all capabilities for all connectors to work properly.

Since roles cannot be directly assigned to a user, we need to create a group and assign the role to the group, then add the user to the group to inherit the role. Navigate to Groups from the right sidebar, click + to add group.

Fill in the information, then click CREATE.

Find the newly created group and click on the corresponding three-dot button. Click Update.
Choose ROLES at the top, then choose the role you just created.

If you want to update the user role, the access permissions will change for the group as well.

Creating a user and assigning roles

Navigate to Settings > Security > Users, and click + located at the bottom right corner to add a new user. The Create a role window will appear.

Input a name, email and password for the new user and click Create. Please note that the user will be created with default roles, please follow the steps below if you wish to update the user's role.

Select the created user. You will be directed to the user configuration page.

Alert

The user cannot be directly assigned a role, the role can only be in a group to assign. The user you created will be default in the Default Groups. The permission will be the default permission. Please update the user with the following steps.

Click on the three-dot menu and select Update. An Update a user window will appear.

Click GROUPS at the top, then select the group you just created.

Generating an API Key

Log in to the server of the OpenCTI platform (http://<Server URL>:8080) with the created account credentials.

Click on the user icon located near the top right corner, then select Profile. You will be directed to the Profile page.

Under API access, you will see the API KEY.

Configuring D3 SOAR to Work with OpenCTI

Log in to D3 SOAR.
Find the OpenCTI integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type OpenCTI in the search box to find the integration, then click it to select it.
4. Click + New Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to OpenCTI.
1. Connection Name: The desired name for the connection.
2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): Add your desired description for the connection.
6. Configure User Permissions: Defines which users have access to the connection.
7. Active: Check the tick box to ensure the connection is available for use.
8. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input your domain level Server URL. Please replace your domain with the <HOST_IP>.
  2. Input your saved API Key from step 3 of Generating API Key.
9. Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.
  To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
10. 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 checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

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

Reader Note

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

Add Observable

Adds a Stix-Observable object to the specified indicator object.

Reader Note

Indicator ID and Stix Cyber Observable ID are required parameters to run this command.

Run the List Indicators command to obtain Indicator IDs. Indicator IDs can be found from the returned raw data at the path $[*].id.
Run the List Observables command to obtain Stix Cyber Observable IDs. Stix Cyber Observable IDs can be found from the returned raw data at the path $[*].standard_id.

Currently, this command only supports version 5.5.0 and above, please check your platform version if you encounter an error.

Input

Input Parameter	Required/Optional	Description	Example
Indicator ID	Required	The ID of the indicator to add an observable. Indicator ID can be obtained using the List Indicators command.	5e***-*-**-*-****
Stix Cyber Observable ID	Required	The ID of the Stix-Observable to add to the specified indicator. Stix Cyber Observable ID can be obtained using the List Observables command.	domain-name--***-*-**-*-****

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "D3 Message": "Adding a Stix-Cyber-Observable object to Indicator successfully."
}

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

CODE

No Sample Data

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Add Observable 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 OpenCTI portal. Refer to the HTTP Status Code Registry for details.	Status Code: 402.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Fail to add a Stix-Cyber-Observable object to Indicator.

Error Sample Data

Add Observable failed.

Status Code: 402.

Message: Fail to add a Stix-Cyber-Observable object to Indicator.

Create Indicator

Creates an indicator object. Note: When creating a new indicator, ensure that its pattern value is distinct from that of existing indicators. You cannot create a new indicator with the same pattern value as an existing one.

Reader Note

Pattern Type is a required parameter to run this command. Below are the supported pattern types along with their descriptions:

STIX - Structured Threat Information eXpressions.
PCRE - Perl Compatible Regular Expressions.
SIGMA - A common language used by SIEM platforms and malware researchers for communication.
SNORT - A rule format used by the open-source intrusion prevention system offered by Cisco.
Suricata - A rule format used by the high-performance Network IDS, IPS, and Network Security Monitoring engine.
YARA - Created by VirusTotal, YARA helps malware researchers identify and classify malware samples.
Tanium Signal - Implements a specific language that the Detect service uses for both language syntax and currently supported terms and conditions.

Please note that the input pattern value cannot be used, otherwise an error will be returned.

Input

Input Parameter	Required/Optional	Description	Example
Indicator Name	Required	The name for the indicator.	A new indicator
Pattern Type	Required	The type of the observable. The available pattern types are STIX, PCRE, SIGMA, SNORT, Suricata, YARA and Tanium Signal.	STIX
Pattern	Required	The pattern of the stix indicator.	[ domain-name:value = 'www.*****.info' ]
Observable Type	Required	The type of the observable.	Artifact

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "id": "***-***-***-***-***",
    "standard_id": "indicator--***-***-***-***-***",
    "entity_type": "Indicator",
    "parent_types": [
        "Basic-Object",
        "Stix-Object",
        "Stix-Core-Object",
        "Stix-Domain-Object"
    ],
    "observables": [],
    "createdById": null,
    "observablesIds": []
}

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

{
    "IndicatorID": "\"\\\"***-**-***-***-***\\\"\"",
    "IndicatorStandardID": "\"\\\"indicator--***-***-***-***-***\\\"\""
}

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

id	***-*-**-*-****
standard_id	indicator--***-*-**-*-****
entity_type	Indicator
parent_types	Basic-Object Stix-Object Stix-Core-Object Stix-Domain-Object
observables	[]
createdById	None
observablesIds	[]

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Create Indicator 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 OpenCTI portal. Refer to the HTTP Status Code Registry for details.	Status Code: 406.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Indicator of type stix is not correctly formatted.

Error Sample Data

Create Indicator failed.

Status Code: 406.

Message: Indicator of type stix is not correctly formatted.

Create Observable

Creates a Stix-Observable object.

Reader Note

Labels, Author, Markings and External References are optional parameters to run this command.

Run the List Labels command to obtain Labels. Labels can be obtained from the returned raw data at the path $.entities[*].id.
Run the List Authors command to obtain Author. Authors can be obtained from the returned raw data at the path $.entities[*].id.
Run the List Markings command to obtain Markings. Markings can be obtained from the returned raw data at the path $.entities[*].id.
Run the List External References command to obtain External References. External References can be obtained from the returned raw data at the path $.entities[*].id.

Please note that the Type and Values must match. Otherwise, errors will be returned. Please see Create Observable - Types and Corresponding Fields and Values for more info on Type and Values.

Input

Input Parameter	Required/Optional	Description	Example
Type	Required	The type of observable.	Email Addr
Values	Required	Input the required fields and values depending on the observable type. Please refer to https://github.com/OpenCTI-Platform/client-python/blob/fecbfc495eb3a2a82a89a49c78698d3aabbb8936/pycti/entities/opencti_stix_cyber_observable.py#L122. Please see the table in Create Observable - Types and Corresponding Fields and Values for more detailed available fields and types.	{ "value": "test@example.com", "display_name":"Test" }
Description	Optional	The description for the observable.	Test description 0529
Score	Optional	The score of the observable.	90
Labels	Optional	The labels for the observable. Labels can be obtained using the List Labels command. Inputting a label that does not already exist in the system will create a new label.	["hardbit"]
Author	Optional	The author ID of the observable. Author can be obtained using the List Authors command.	***-*-**-*-****
Markings	Optional	The ID(s) of marking definition of the observable. You can obtain the marking definition IDs from List Markings command.	["***-*-**-*-****"]
External References	Optional	The ID(s) of external references of the observable. External reference IDs can be obtained using the List External References command.	["***-*-**-*-****"]
Create Indicator	Optional	The option to create an indicator. The available values are True or False. The default value is False.	True

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "id": "*****-*****-******-*****-******",
    "standard_id": "email-addr--*****-*****-******-*****-******",
    "entity_type": "Email-Addr",
    "parent_types": [
        "Basic-Object",
        "Stix-Object",
        "Stix-Core-Object",
        "Stix-Cyber-Observable"
    ],
    "spec_version": "2.1",
    "created_at": "2023-05-30T17:28:20.889Z",
    "updated_at": "2023-05-30T17:28:23.357Z",
    "createdBy": {
        "id": "*****-*****-******-*****-******",
        "standard_id": "identity--*****-*****-******-*****-******",
        "entity_type": "Organization",
        "parent_types": [
            "Basic-Object",
            "Stix-Object",
            "Stix-Core-Object",
            "Stix-Domain-Object",
            "Identity"
        ],
        "spec_version": "2.1",
        "identity_class": "organization",
        "name": "Microsoft",
        "description": "",
        "roles": null,
        "contact_information": null,
        "x_opencti_aliases": null,
        "created": "2023-01-16T15:52:18.967Z",
        "modified": "2023-01-16T15:52:18.967Z",
        "objectLabel": [],
        "x_opencti_organization_type": null,
        "x_opencti_reliability": null,
        "objectLabelIds": []
    },
    "objectMarking": [
        {
            "id": "*****-*****-******-*****-******",
            "standard_id": "marking-definition--*****-*****-******-*****-******",
            "entity_type": "Marking-Definition",
            "definition_type": "statement",
            "definition": "CAPEC is sponsored by US-CERT in the office of Cybersecurity and Communications at the U.S. Department of Homeland Security. Copyright ? 2007 - 2023, The MITRE Corporation. CAPEC and the CAPEC logo are trademarks of The MITRE Corporation.",
            "created": "2023-01-30T20:40:28.791Z",
            "modified": "2023-02-22T09:58:44.506Z",
            "x_opencti_order": 0,
            "x_opencti_color": "#ffffff",
            "createdById": null
        }
    ],
    "objectLabel": [
        {
            "id": "*****-*****-******-*****-******",
            "value": "hardbit",
            "color": "#429083",
            "createdById": null
        }
    ],
    "externalReferences": [
        {
            "id": "*****-*****-******-*****-******",
            "standard_id": "external-reference--*****-*****-******-*****-******",
            "entity_type": "External-Reference",
            "source_name": "External analysis",
            "description": null,
            "url": "https://www.virustotal.com/file/*****/analysis/*****/",
            "hash": null,
            "external_id": "*****-*****-******-*****-******",
            "created": "2023-01-18T22:49:16.487Z",
            "modified": "2023-01-18T22:49:16.487Z",
            "importFiles": [],
            "createdById": null,
            "importFilesIds": []
        }
    ],
    "observable_value": "test@example.com",
    "x_opencti_description": "Test description 0529",
    "x_opencti_score": 90,
    "indicators": [
        {
            "id": "*****-*****-******-*****-******",
            "pattern": "[email-addr:value = 'test@example.com']",
            "pattern_type": "stix",
            "createdById": null
        }
    ],
    "value": "test@example.com",
    "display_name": "Test",
    "importFiles": [],
    "createdById": "*****-*****-******-*****-******",
    "objectMarkingIds": [
        "*****-*****-******-*****-******"
    ],
    "objectLabelIds": [
        "*****-*****-******-*****-******"
    ],
    "externalReferencesIds": [
        "*****-*****-******-*****-******"
    ],
    "indicatorsIds": [
        "*****-*****-******-*****-******"
    ],
    "importFilesIds": []
}

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

{
    "ObservableID": "\"*****-*****-******-*****-******\"",
    "Type": "\"Email-Addr\"",
    "Value": "\"test@example.com\"",
    "IndicatorsIDs": "\"[\\\"*****-*****-******-*****-******\\\"]\""
}

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

id	***-*-**-*-****
standard_id	email-addr--***-*-**-*-****
entity_type	Email-Addr
parent_types	Basic-Object Stix-Object Stix-Core-Object Stix-Cyber-Observable
spec_version	2.1
created_at	2023-05-30T17:28:20.889Z
updated_at	2023-05-30T17:28:23.357Z
createdBy	{'id': '***-*-**-*-**', 'standard_id': 'identity--*-*-**-*-****', 'entity_type': 'Organization', 'parent_types': ['Basic-Object', 'Stix-Object', 'Stix-Core-Object', 'Stix-Domain-Object', 'Identity'], 'spec_version': '2.1', 'identity_class': 'organization', 'name': 'Microsoft', 'description': '', 'roles': None, 'contact_information': None, 'x_opencti_aliases': None, 'created': '2023-01-16T15:52:18.967Z', 'modified': '2023-01-16T15:52:18.967Z', 'objectLabel': [], 'x_opencti_organization_type': None, 'x_opencti_reliability': None, 'objectLabelIds': []}
objectMarking	{'id': '***-*-**-*-**', 'standard_id': 'marking-definition--*-*-**-*-****', 'entity_type': 'Marking-Definition', 'definition_type': 'statement', 'definition': 'CAPEC is sponsored by US-CERT in the office of Cybersecurity and Communications at the U.S. Department of Homeland Security. Copyright ? 2007 - 2023, The MITRE Corporation. CAPEC and the CAPEC logo are trademarks of The MITRE Corporation.', 'created': '2023-01-30T20:40:28.791Z', 'modified': '2023-02-22T09:58:44.506Z', 'x_opencti_order': 0, 'x_opencti_color': '#ffffff', 'createdById': None}
objectLabel	{'id': '***-*-**-*-****', 'value': 'hardbit', 'color': '#429083', 'createdById': None}
externalReferences	{'id': '***-*-**-*-**', 'standard_id': 'external-reference--*-*-**-*-**', 'entity_type': 'External-Reference', 'source_name': 'External analysis', 'description': None, 'url': 'https://www.virustotal.com/file/*/analysis/*/', 'hash': None, 'external_id': '*-*-**-*-****', 'created': '2023-01-18T22:49:16.487Z', 'modified': '2023-01-18T22:49:16.487Z', 'importFiles': [], 'createdById': None, 'importFilesIds': []}
observable_value	test@example.com
x_opencti_description	Test description 0529
x_opencti_score	90
indicators	{'id': '***-*-**-*-****', 'pattern': "[email-addr:value = 'test@example.com']", 'pattern_type': 'stix', 'createdById': None}
value	test@example.com
display_name	Test
importFiles	[]
createdById	***-*-**-*-****
objectMarkingIds	***-*-**-*-****
objectLabelIds	***-*-**-*-****
externalReferencesIds	***-*-**-*-****
indicatorsIds	***-*-**-*-****
importFilesIds	[]

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Create Observable 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 OpenCTI 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: Please make sure to input the required value for specific observable Type ('path',). For more information, please refer to the parameter description of Values.

Error Sample Data

Add Observable failed.

Status Code: 400.

Message: Please make sure to input the required value for specific observable Type ('path',). For more information, please refer to the parameter description of Values.

Get Indicators

Retrieves a list of specified indicators.

Reader Note

The input parameter Indicator IDs is required to run this command.

Run the List Indicators command to obtain Indicator IDs.

The difference between this command and the List Indicators command is that the List Indicators command will return all Indicators, while this command can only search for one indicator.

Input

Input Parameter

Required/Optional

Description

Example

Indicator IDs

Required

The IDs of the indicators to retrieve. Indicator IDs can be obtained using the List Indicators command.

[

"*****-*****-******-*****-******" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

[
    {
        "id": "*****-*****-******-*****-******",
        "standard_id": "indicator--*****-*****-******-*****-******",
        "entity_type": "Indicator",
        "parent_types": [
            "Basic-Object",
            "Stix-Object",
            "Stix-Core-Object",
            "Stix-Domain-Object"
        ],
        "spec_version": "2.1",
        "created_at": "2021-11-08T19:10:42.888Z",
        "updated_at": "2021-11-08T19:10:42.888Z",
        "createdBy": null,
        "objectMarking": [],
        "objectLabel": [],
        "externalReferences": [],
        "revoked": false,
        "confidence": 15,
        "created": "2021-11-08T19:10:42.888Z",
        "modified": "2021-11-08T19:10:42.888Z",
        "pattern_type": "stix",
        "pattern_version": null,
        "pattern": "[domain-name:value = 'www.*****.info']",
        "name": "C2 test new indicator",
        "description": null,
        "indicator_types": [
            "malicious-activity"
        ],
        "valid_from": "2021-11-08T19:10:42.876Z",
        "valid_until": "2022-11-08T19:10:42.876Z",
        "x_opencti_score": 50,
        "x_opencti_detection": false,
        "x_opencti_main_observable_type": "Url",
        "x_mitre_platforms": null,
        "observables": [],
        "killChainPhases": [],
        "importFiles": [],
        "createdById": null,
        "objectMarkingIds": [],
        "objectLabelIds": [],
        "killChainPhasesIds": [],
        "externalReferencesIds": [],
        "observablesIds": [],
        "importFilesIds": []
    }
]

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

{
    "IndicatorIDs": "\"[\\\"*****-*****-******-*****-******\\\"]\"",
    "IndicatorStandardIDs": "\"[\\\"indicator--*****-*****-******-*****-******\\\"]\"",
    "EntityTypes": "\"[\\\"Indicator\\\"]\"",
    "CreatedAt": "\"[\\\"2021-11-08T19:10:42.888Z\\\"]\"",
    "Confidences": "\"[15]\"",
    "PatternTypes": "\"[\\\"stix\\\"]\"",
    "Patterns": "\"[ \\\"[domain-name:value = 'www.*****.info']\\\" ]\"",
    "IndicatorNames": "\"[ \\\"C2 test new indicator\\\" ]\"",
    "Scores": "\"[ 50 ]\"",
    "ObservableTypes": "\"[ \\\"Url\\\" ]\""
}

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

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

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

ID	STANDARD_ID	ENTITY_TYPE	PARENT_TYPES	SPEC_VERSION	CREATED_AT	UPDATED_AT	CREATEDBY	OBJECTMARKING	OBJECTLABEL	EXTERNALREFERENCES	REVOKED	CONFIDENCE	CREATED	MODIFIED	PATTERN_TYPE	PATTERN_VERSION	PATTERN	NAME	DESCRIPTION	INDICATOR_TYPES	VALID_FROM	VALID_UNTIL	X_OPENCTI_SCORE	X_OPENCTI_DETECTION	X_OPENCTI_MAIN_OBSERVABLE_TYPE	X_MITRE_PLATFORMS	OBSERVABLES	KILLCHAINPHASES	IMPORTFILES	CREATEDBYID	OBJECTMARKINGIDS	OBJECTLABELIDS	KILLCHAINPHASESIDS	EXTERNALREFERENCESIDS	OBSERVABLESIDS	IMPORTFILESIDS
***-*-**-*-****	indicator--***-*-**-*-****	Indicator	['Basic-Object', 'Stix-Object', 'Stix-Core-Object', 'Stix-Domain-Object']	2.1	2021-11-08T19:10:42.888Z	2021-11-08T19:10:42.888Z	None	[]	[]	[]	False	15	2021-11-08T19:10:42.888Z	2021-11-08T19:10:42.888Z	stix	None	[domain-name:value = 'www.*****.info']	C2 test new indicator	None	['malicious-activity']	2021-11-08T19:10:42.876Z	2022-11-08T19:10:42.876Z	50	False	Url	None	[]	[]	[]	None	[]	[]	[]	[]	[]	[]

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Indicators 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 OpenCTI 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: Can not find the indicator XXX.

Error Sample Data

Get Indicators failed.

Status Code: 404.

Message: Can not find the indicator XXX.

List Authors

Retrieves all available authors in the OpenCTI instance.

Reader Note

If the name is not specified, then all available authors will be returned. If the input search value for name does not exist, then it will return success with no result.

Input

Input Parameter

Required/Optional

Description

Example

Names

Optional

The author's name. Author IDs will not be accepted for this parameter. To search by name, ensure your input is the full name. Partial names and keywords are not accepted.

[

"kaspersky"

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "entities": [
        {
            "id": "*****-*****-******-*****-******",
            "standard_id": "identity--*****-*****-******-*****-******",
            "entity_type": "Organization",
            "parent_types": [
                "Basic-Object",
                "Stix-Object",
                "Stix-Core-Object",
                "Stix-Domain-Object",
                "Identity"
            ],
            "spec_version": "2.1",
            "created_at": "2023-01-16T15:51:44.500Z",
            "updated_at": "2023-01-16T15:51:44.500Z",
            "createdBy": null,
            "objectMarking": [],
            "objectLabel": [],
            "externalReferences": [],
            "revoked": false,
            "confidence": 15,
            "created": "2023-01-16T15:51:44.500Z",
            "modified": "2023-01-16T15:51:44.500Z",
            "identity_class": "organization",
            "name": "Kaspersky",
            "description": "",
            "x_opencti_aliases": null,
            "contact_information": null,
            "x_opencti_organization_type": null,
            "x_opencti_reliability": null,
            "importFiles": [],
            "createdById": null,
            "objectMarkingIds": [],
            "objectLabelIds": [],
            "externalReferencesIds": [],
            "importFilesIds": []
        }
    ],
    "pagination": {
        "startCursor": "*****==",
        "endCursor": "*****==",
        "hasNextPage": false,
        "hasPreviousPage": false,
        "globalCount": 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

{
    "AuthorIDs": "\"[\\\"*****-*****-******-*****-******\\\"]\"",
    "Types": "\"[\\\"Organization\\\"]\"",
    "Names": "\"[\\\"Kaspersky\\\"]\""
}

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

entities

{'id': '*****-*****-******-*****-******', 'standard_id': 'identity--*****-*****-******-*****-******', 'entity_type': 'Organization', 'parent_types': ['Basic-Object', 'Stix-Object', 'Stix-Core-Object', 'Stix-Domain-Object', 'Identity'], 'spec_version': '2.1', 'created_at': '2023-01-16T15:51:44.500Z', 'updated_at': '2023-01-16T15:51:44.500Z', 'createdBy': None, 'objectMarking': [], 'objectLabel': [], 'externalReferences': [], 'revoked': False, 'confidence': 15, 'created': '2023-01-16T15:51:44.500Z', 'modified': '2023-01-16T15:51:44.500Z', 'identity_class': 'organization', 'name': 'Kaspersky', 'description': '', 'x_opencti_aliases': None, 'contact_information': None, 'x_opencti_organization_type': None, 'x_opencti_reliability': None, 'importFiles': [], 'createdById': None, 'objectMarkingIds': [], 'objectLabelIds': [], 'externalReferencesIds': [], 'importFilesIds': []}

pagination

{'startCursor': '*****==', 'endCursor': '*****==', 'hasNextPage': False, 'hasPreviousPage': False, 'globalCount': 1}

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Authors 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 OpenCTI portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API Key expired. Please check your API Key.

Error Sample Data

List Authors failed.

Status Code: 401.

Message: API Key expired. Please check your API Key.

List Connectors

Retrieves a list of available connectors.

Reader Note

This command can return a maximum of 100 results.

Input

N/A

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

[
    {
        "id": "*****-*****-******-*****-******",
        "name": "ImportDocument",
        "config": {
            "connection": {
                "host": "*****",
                "vhost": "/",
                "use_ssl": false,
                "port": *****,
                "user": "user",
                "pass": "password!"
            },
            "listen": "listen_*****-*****-******-*****-******",
            "push": "push_*****-*****-******-*****-******"
        }
    },
    {
        "id": "*****-*****-******-*****-******",
        "name": "*****",
        "config": {
            "connection": {
                "host": "*****",
                "vhost": "/",
                "use_ssl": false,
                "port": *****,
                "user": "user",
                "pass": "password!"
            },
            "listen": "listen_*****-*****-******-*****-******",
            "push": "push_*****-*****-******-*****-******"
        }
    }
]

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

{
    "ConnectorIDs": "\"[\\\"*****-*****-******-*****-******\\\",\\\"*****-*****-******-*****-******\\\",\\\"*****-*****-******-*****-******\\\]\"",
    "Names": "\"[\\\"ImportDocument\\\",\\\"MISP\\\",\\\"ExportFileTxt\\\",\\\"EXPORTFILESTIX2\\\"]\""
}

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

conenctorsCount

2

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Connectors 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 OpenCTI 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: Connectors cannot be found.

Error Sample Data

List Connectors failed.

Status Code: 404.

Message: Connectors cannot be found.

List External References

Retrieves all external references in the OpenCTI platform. Please note that there is a limit for results, only 5000 will be retrieved. If there are more than 5000 external references, you will need to use Next Page to retrieve the data.

Reader Note

If this command's returned raw data path $.pagination.hasNextPage is true, then the value in $.pagination.endCursor can be used to apply in the Next Page parameter.
This command allows for search keywords that are not limited to exact matches with values. Instead, a string with an approximate match can also be used. When entering multiple keywords, a space between them will indicate an or logic while a dash (-) will indicate an and logic.

For example, if the input keyword is "Stix 2021", the command will return External References that include "Stix" or "2021". Conversely, if the input keyword is "Stix-2021", the command will only return external references with names that match the string "Stix 2021".

If the command returns a success message but no results, it is possible that no related external references are found in the system.

Input

Input Parameter

Required/Optional

Description

Example

Search

Optional

The keywords to search for the values.

[

"mitre-attack"

]

When hasNextPage is true in the result (the number of returned external references exceeds the limit of 5000), this parameter sets the cursor to get data from the next page, which can be obtained from the EndCursor of the result.

*****=

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "entities": [
        {
            "id": "*****-*****-******-*****-******",
            "standard_id": "external-reference--*****-*****-******-*****-******",
            "entity_type": "External-Reference",
            "parent_types": [
                "Basic-Object",
                "Stix-Object",
                "Stix-Meta-Object"
            ],
            "created_at": "2023-01-16T15:49:28.800Z",
            "updated_at": "2023-04-04T15:09:54.131Z",
            "created": "2023-01-16T15:49:28.800Z",
            "modified": "2023-04-04T15:09:54.131Z",
            "source_name": "mitre-attack",
            "description": null,
            "url": "https://attack.mitre.org/techniques/*****/011",
            "hash": null,
            "external_id": "*****",
            "importFiles": [],
            "createdById": null,
            "importFilesIds": []
        }
    ],
    "pagination": {
        "startCursor": "*****=",
        "endCursor": "*****=",
        "hasNextPage": true,
        "hasPreviousPage": false,
        "globalCount": 37144
    }
}

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

{
    "ExternalReferenceIDs": "\"[\\\"*****-*****-******-*****-******\\\"]\"",
    "SourceNames": "\"[\\\"External analysis\\\"]\"",
    "URLs": "\"[\\\"https://www.virustotal.com/file/*****/analysis/*****/\\\"]\"",
    "ExternalIDs": "\"[\\\"*****\\\"]\"",
    "EndCursor": "\"*****=\"",
    "HasNextPage": "\"True\""
}

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

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

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

entities

{'id': '*****-*****-******-*****-******', 'standard_id': 'external-reference--*****-*****-******-*****-******b', 'entity_type': 'External-Reference', 'parent_types': ['Basic-Object', 'Stix-Object', 'Stix-Meta-Object'], 'created_at': '2023-01-16T15:49:28.800Z', 'updated_at': '2023-04-04T15:09:54.131Z', 'created': '2023-01-16T15:49:28.800Z', 'modified': '2023-04-04T15:09:54.131Z', 'source_name': 'mitre-attack', 'description': None, 'url': 'https://attack.mitre.org/techniques/*****/011', 'hash': None, 'external_id': '*****', 'importFiles': [], 'createdById': None, 'importFilesIds': []}

pagination

{'startCursor': '****=', 'endCursor': '*****=', 'hasNextPage': True, 'hasPreviousPage': False, 'globalCount': 37144}

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List External References 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 OpenCTI 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: Can not find the indicator XXX.

Error Sample Data

List External References failed.

Status Code: 404.

Message: Can not find the indicator XXX.

List Indicators

Retrieves indicators matching the specified keyword.

Reader Note

This command allows for search keywords that are not limited to exact matches with indicator names. Instead, a string with an approximate match can also be used. When entering multiple keywords, a space between them will indicate an or logic while a dash (-) will indicate an and logic.

For example, if the input keyword is "Stix 2021", the command will return indicators that include "Stix" or "2021". Conversely, if the input keyword is "Stix-2021", the command will only return indicators with names that match the string "Stix 2021".

If the command returns a success message but no results, it is possible that no indicators or related keywords are found in the system.

This command can return a maximum of 100 results.

Input

Input Parameter	Required/Optional	Description	Example
Keyword	Optional	The keyword to filter the returned indicators.	server

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

[
    {
        "id": "*****-*****-******-*****-******",
        "standard_id": "indicator--*****-*****-******-*****-******",
        "entity_type": "Indicator",
        "parent_types": [
            "Basic-Object",
            "Stix-Object",
            "Stix-Core-Object",
            "Stix-Domain-Object"
        ],
        "spec_version": "2.1",
        "created_at": "2021-11-02T20:14:56.164Z",
        "updated_at": "2021-11-02T20:14:56.164Z",
        "createdBy": null,
        "objectMarking": [],
        "objectLabel": [],
        "externalReferences": [],
        "revoked": false,
        "confidence": 15,
        "created": "2021-11-02T20:14:56.164Z",
        "modified": "2021-11-02T20:14:56.164Z",
        "pattern_type": "stix",
        "pattern_version": null,
        "pattern": "[domain-name:value = 'www.*****.info1']",
        "name": "test23",
        "description": "",
        "indicator_types": [
            "malicious-activity"
        ],
        "valid_from": "2021-11-02T20:14:56.154Z",
        "valid_until": "2022-11-02T20:14:56.154Z",
        "x_opencti_score": 50,
        "x_opencti_detection": false,
        "x_opencti_main_observable_type": "Url",
        "x_mitre_platforms": [],
        "observables": [],
        "killChainPhases": [],
        "importFiles": [],
        "createdById": null,
        "objectMarkingIds": [],
        "objectLabelIds": [],
        "killChainPhasesIds": [],
        "externalReferencesIds": [],
        "observablesIds": [],
        "importFilesIds": []
    }
]

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

{
    "IndicatorIDs": "\"[\\\"*****-*****-******-*****-******\\\"]\"",
    "IndicatorStandardIDs": "\"[\\\"indicator--*****-*****-******-*****-******\\\"]\"",
    "EntityTypes": "\"[\\\"Indicator\\\"]\"",
    "CreatedAt": "\"[\\\"2021-11-08T19:10:42.888Z\\\"]\"",
    "Confidences": "\"[15]\"",
    "PatternTypes": "\"[\\\"stix\\\"]\"",
    "Patterns": "\"[ \\\"[domain-name:value = 'www.*****.info']\\\" ]\"",
    "IndicatorNames": "\"[ \\\"C2 test new indicator\\\" ]\"",
    "Scores": "\"[ 50 ]\"",
    "ObservableTypes": "\"\""
}

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

ID	STANDARD_ID	ENTITY_TYPE	PARENT_TYPES	SPEC_VERSION	CREATED_AT	UPDATED_AT	CREATEDBY	OBJECTMARKING	OBJECTLABEL	EXTERNALREFERENCES	REVOKED	CONFIDENCE	CREATED	MODIFIED	PATTERN_TYPE	PATTERN_VERSION	PATTERN	NAME	DESCRIPTION	INDICATOR_TYPES	VALID_FROM	VALID_UNTIL	X_OPENCTI_SCORE	X_OPENCTI_DETECTION	X_OPENCTI_MAIN_OBSERVABLE_TYPE	X_MITRE_PLATFORMS	OBSERVABLES	KILLCHAINPHASES	IMPORTFILES	CREATEDBYID	OBJECTMARKINGIDS	OBJECTLABELIDS	KILLCHAINPHASESIDS	EXTERNALREFERENCESIDS	OBSERVABLESIDS	IMPORTFILESIDS
***-*-**-*-****	indicator--***-*-**-*-****	Indicator	['Basic-Object', 'Stix-Object', 'Stix-Core-Object', 'Stix-Domain-Object']	2.1	2021-11-02T20:14:56.164Z	2021-11-02T20:14:56.164Z	None	[]	[]	[]	False	15	2021-11-02T20:14:56.164Z	2021-11-02T20:14:56.164Z	stix	None	[domain-name:value = 'www.*****.info1']	test23		['malicious-activity']	2021-11-02T20:14:56.154Z	2022-11-02T20:14:56.154Z	50	False	Url	[]	[]	[]	[]	None	[]	[]	[]	[]	[]	[]

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List indicators 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 OpenCTI 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: OpenCTI API is not reachable. Waiting for OpenCTI API to start or check your configuration.

Error Sample Data

List indicators failed.

Status Code: 400.

Message: OpenCTI API is not reachable. Waiting for OpenCTI API to start or check your configuration.

List Labels

Retrieves all labels in the OpenCTI instance.

Reader Note

Please note that the label name must be the full name. Partial names and keywords are not accepted.

Input

Input Parameter

Required/Optional

Description

Example

Label Names

Optional

The name(s) of the label(s) to retrieve.

[

"hyperv"

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "entities": [
        {
            "id": "*****-*****-******-*****-******",
            "value": "hyperv",
            "color": "#8a8f55",
            "created_at": "2023-01-20T01:28:29.995Z",
            "updated_at": "2023-01-20T01:28:29.995Z",
            "standard_id": "label--*****-*****-******-*****-******3",
            "createdById": null
        }
    ],
    "pagination": {
        "startCursor": "*****==",
        "endCursor": "*****==",
        "hasNextPage": false,
        "hasPreviousPage": false,
        "globalCount": 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

{
    "LabelIDs": "\"[\\\"*****-*****-******-*****-******\\\"]\"",
    "LabelNames": "\"[\\\"hyperv\\\"]\"",
    "Colors": "\"[\\\"#8a8f55\\\"]\""
}

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

entities	{'id': '***-*-**-*-**', 'value': 'hyperv', 'color': '#8a8f55', 'created_at': '2023-01-20T01:28:29.995Z', 'updated_at': '2023-01-20T01:28:29.995Z', 'standard_id': 'label--*-*-**-*-****', 'createdById': None}
pagination	{'startCursor': '***==', 'endCursor': '***==', 'hasNextPage': False, 'hasPreviousPage': False, 'globalCount': 1}

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Labels 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 OpenCTI 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 all label names existing.

Error Sample Data

List Labels failed.

Status Code: 404.

Message: Not all label names existing.

List Markings

Retrieves all marking definitions in the OpenCTI instance.

Reader Note

This command allows for search keywords that are not limited to exact matches. Instead, a string with an approximate match can also be used. When entering multiple keywords, a space between them will indicate an or logic while a dash (-) will indicate an and logic.
If the command returns a success message but no results, it is possible that no indicators or related keywords are found in the system.

Input

Input Parameter

Required/Optional

Description

Example

Search

Optional

The keywords to search for the values.

[

"TLP:CLEAR"

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "entities": [
        {
            "id": "*****-*****-******-*****-******",
            "standard_id": "marking-definition--*****-*****-******-*****-******",
            "entity_type": "Marking-Definition",
            "parent_types": [
                "Basic-Object",
                "Stix-Object",
                "Stix-Meta-Object"
            ],
            "definition_type": "TLP",
            "definition": "TLP:CLEAR",
            "x_opencti_order": 1,
            "x_opencti_color": "#ffffff",
            "created": "2023-01-16T14:58:38.581Z",
            "modified": "2023-03-09T18:25:44.369Z",
            "created_at": "2023-01-16T14:58:38.581Z",
            "updated_at": "2023-03-09T18:25:44.369Z",
            "createdById": null
        }
    ],
    "pagination": {
        "startCursor": "*****=",
        "endCursor": "*****=",
        "hasNextPage": false,
        "hasPreviousPage": false,
        "globalCount": 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

{
    "MarkingDefinitionIDs": "\"[\\\"*****-*****-******-*****-******\\\"]\"",
    "DefinitionTypes": "\"[\\\"TLP\\\"]\"",
    "Definitions": "\"[\\\"TLP:CLEAR\\\"]\""
}

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

entities

{'id': '*****-*****-******-*****-******', 'standard_id': 'marking-definition--*****-*****-******-*****-******', 'entity_type': 'Marking-Definition', 'parent_types': ['Basic-Object', 'Stix-Object', 'Stix-Meta-Object'], 'definition_type': 'TLP', 'definition': 'TLP:CLEAR', 'x_opencti_order': 1, 'x_opencti_color': '#ffffff', 'created': '2023-01-16T14:58:38.581Z', 'modified': '2023-03-09T18:25:44.369Z', 'created_at': '2023-01-16T14:58:38.581Z', 'updated_at': '2023-03-09T18:25:44.369Z', 'createdById': None}

pagination

{'startCursor': '*****=', 'endCursor': '*****=', 'hasNextPage': False, 'hasPreviousPage': False, 'globalCount': 1}

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Marking 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 OpenCTI portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API Key expired. Please check your API Key.

Error Sample Data

Get Indicators failed.

Status Code: 401.

Message: API Key expired. Please check your API Key.

List Observables

Retrieves observables matching the specified keyword.

Reader Note

This command allows for search keywords that are not limited to exact matches with observable names. Instead, a string with an approximate match can also be used. When entering multiple keywords, a space between them will indicate an or logic while a dash (-) will indicate an and logic.

For example, if the input keyword is "url hostname", the command will return indicators that include "url" or "hostname". Conversely, if the input keyword is "url-hostname", the command will only return indicators with names that match the string "url hostname".

If the command returns a success message but no results, it is possible that no indicators or related keywords are found in the system.

This command can return a maximum of 100 results.
Currently, this command only supports version 5.5.0 and above, please check your platform version if you encounter an error.

Input

Input Parameter	Required/Optional	Description	Example
Keyword	Optional	The keyword to filter the returned indicators.	www.example.xyz

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

[
    {
        "id": "*****-*****-******-*****-******",
        "standard_id": "hostname--*****-*****-******-*****-******",
        "entity_type": "Hostname",
        "parent_types": [
            "Basic-Object",
            "Stix-Object",
            "Stix-Core-Object",
            "Stix-Cyber-Observable"
        ],
        "spec_version": "2.1",
        "created_at": "2023-03-15T04:43:39.812Z",
        "updated_at": "2023-03-15T04:43:39.812Z",
        "createdBy": "None",
        "objectMarking": [],
        "objectLabel": [],
        "externalReferences": [],
        "observable_value": "www.example.xyz",
        "x_opencti_description": "None",
        "x_opencti_score": 50,
        "indicators": [],
        "value": "www.example.xyz",
        "importFiles": [],
        "createdById": "None",
        "objectMarkingIds": [],
        "objectLabelIds": [],
        "externalReferencesIds": [],
        "indicatorsIds": [],
        "importFilesIds": []
    },
    {
        "id": "*****-*****-******-*****-******",
        "standard_id": "domain-name--*****-*****-******-*****-******",
        "entity_type": "Domain-Name",
        "parent_types": [
            "Basic-Object",
            "Stix-Object",
            "Stix-Core-Object",
            "Stix-Cyber-Observable"
        ],
        "spec_version": "2.1",
        "created_at": "2023-03-15T18:00:29.054Z",
        "updated_at": "2023-03-15T18:00:29.054Z",
        "createdBy": "None",
        "objectMarking": [],
        "objectLabel": [],
        "externalReferences": [],
        "observable_value": "www.example.xyz",
        "x_opencti_description": "None",
        "x_opencti_score": 50,
        "indicators": [
            {
                "id": "*****-*****-******-*****-******",
                "pattern": "[domain-name:value = '*****.*****.com']",
                "pattern_type": "stix",
                "createdById": "None"
            }
        ],
        "value": "www.example.xyz",
        "importFiles": [],
        "createdById": "None",
        "objectMarkingIds": [],
        "objectLabelIds": [],
        "externalReferencesIds": [],
        "indicatorsIds": [
            "*****-*****-******-*****-******"
        ],
        "importFilesIds": []
    }
]

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

{
    "ObservationID": "\"[ \\\"*****-*****-******-*****-******\\\", \\\"*****-*****-******-*****-******\\\" ]\"",
    "StixIDs": "\"[ \\\"hostname--*****-*****-******-*****-******\\\", \\\"domain-name--*****-*****-******-*****-******\\\" ]\"",
    "EntityTypes": "\"[ \\\"Hostname\\\", \\\"Domain-Name\\\" ]\""
}

Return Data

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

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

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

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

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

SAMPLE DATA

CODE

Successful

Result

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

SAMPLE DATA

observalblesCount	2

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Observables 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 OpenCTI portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API Key expired. Please check your API Key.

Error Sample Data

List Observables failed.

Status Code: 401.

Message: API Key expired. Please check your API Key.

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 is Failed, an Error tab will appear in the Test Result window.

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	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 OpenCTI portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: API Key expired. Please check your API Key.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 401.

Message: API Key expired. Please check your API Key.

Create Observable - Types and Corresponding Fields and Values

The below table provides details of the available fields corresponding to each type of observable, and the required/optional values for each.

Type

Fields (type) (req/opt) format

Sample

AutonomousSystem

{

"number": int, # number is required

"rir": "string",

"name": "string"

}

{

"number": 2,

"rir": "test rir",

"name": "Test Autonomous-System"

}