Skip to main content
Skip table of contents

ChatGPT

LAST UPDATED: 07/03/2024

Overview

ChatGPT is an AI-powered chatbot developed by OpenAI, based on the GPT (Generative Pretrained Transformer) language model. It uses deep learning techniques to generate human-like responses to text inputs in a conversational manner.

D3 SOAR is providing REST operations to function with ChatGPT.

ChatGPT is available for use in:

D3 SOAR

V15.2+

Category

Other

Deployment Options

Option II, Option IV

Known limitation

Please check your account rate limit by the link https://platform.openai.com/settings/organization/limits.

Connection

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

Parameter

Description

Example

Server URL

The base URL.

https://api.openai.com

API Key

The API Key you obtained from OpenAI UI.

sk-********************************

API Version

The API version.

v1

Permission Requirements

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

Command

Required Permissions

Analyze Image

Restricted: Model Capabilities > Write

Create Embeddings

Restricted: Model Capabilities > Write

Train Model

Restricted: Fine-tuning > Write

Create Images

Restricted: Model Capabilities > Write

Function Calling

Restricted: Model Capabilities > Write

Generate Conversation

Restricted: Model Capabilities > Write

Get File Content

Read Only or Restricted: Files > Read

List Files

Read Only or Restricted: Files > Read

List Models

Read Only or Restricted: Models > Read

Upload Files

Restricted: Models > Read + Files > Write

Test Connection

Read Only or Restricted: Models > Read

READER NOTE

ChatGPT’s default permission options are as follows:

  • All - Full permission to execute all commands.

  • Restricted - Allows you to select detailed permissions. Please refer to the table above for specific permissions associated with each command.

  • Read Only - Limited read-only permission.

Configuring ChatGPT to Work with D3 SOAR

  1. Login https://platform.openai.com with your account credentials.

  2. Click Dashboard. On the left sidebar select API Keys, click the + Create new secret key button to generate your credentials.

  3. Name your secret key and choose your project. Select your permissions, then click on the Create secret key button. Please check Permission Requirements for the required permissions for each command.

  4. Copy the API key into VSOC.

Configuring D3 SOAR to Work with ChatGPT

  1. Log in to D3 SOAR.

    1. Find the ChatGPT integration.

    2. Navigate to Configuration on the top header menu.

    3. Click on the Integration icon on the left sidebar.

    4. Type ChatGPT in the search box to find the integration, then click it to select it.

  2. Click + Connection, on the right side of the Connections section. A new connection window will appear.

  3. Configure the following fields to create a connection to ChatGPT.

    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 tick box 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. The default value is https://api.openai.com.
      2. Copy the API Key from the ChatGPT platform. Refer to step 4 of Configuring ChatGPT to Work with D3 SOAR.
      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.

  4. 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

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

READER NOTE

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

Analyze Image

Provides the image URLs for analysis along with instructions to influence the analysis process, and the model will return a response with the analysis result. This feature is only supported by GPT-4 and later models.

File IDs and File Source parameters

It is not recommended to use the Test Command feature with the Submit Sample Files command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:

  1. Navigate to Configuration on the top bar menu.

  2. Click Utility Commands on the left sidebar menu.

  3. Use the search box to find and select the Create a File from input Text Array command.

  4. Select the Test tab, then input the required information for the parameters. Click Test Command. A D3 File ID will appear in the output data after the file has been successfully created.
    (Note: The D3 File Source of the created file will be Playbook File)

Input

READER NOTE

Model ID is a required parameter to run this command.

  • Run the List Models command to obtain Model IDs. Model IDs can be found in the raw data at the path $.data[*].id.

Input Parameter

Required/Optional

Description

Example

Model ID

Required

The ID of your large language model. The Model ID can be obtained using the List Models command. This feature is only supported by GPT-4 and later models.

gpt-4-turbo

Messages

Optional

The list of messages that make up the conversation.

[

{"role": "system", "content": "You are a helpful assistant."},

{"role": "user", "content": "Hello!"}

]

Instructions

Required

The instructions provided to the model for analyzing images.

["Analyze the image to determine if it contains phishing advertisements"]

Image Urls

Optional

The image URLs for the model to analyze.

["https://www.apple.com/ca/"]

File IDs

Optional

The file id of the file source. Only image-type files will be selected; all other file types will be ignored.

[ "*****", "*****" ]

File Source

Optional

The file source of the file to be retrieved. The options for file sources are:

Incident Attachment File: Manually uploaded file from Incident

Playbook File: Output from another Task

Artifact File: Ingested Artifact in an Event

Playbook File

Response Format

Optional

The format that the model must output. Setting it to JSON Object enables JSON mode, ensuring that the generated message from the model complies with JSON format standards.

Text

Max Words

Optional

The maximum number of words to generate in the completion. Please note, the word count of your prompt plus Max Words cannot exceed the model's context length. The context length of most models is 2048 words; only the latest models can support up to 4096 words.

10

Temperature

Optional

The sampling temperature to use. Higher values like 0.8 increase randomness, while lower values like 0.2 enhance focus and determinism. Adjusting either temperature or top_p is recommended, but not simultaneously. If unspecified, the default value is 1, with an acceptable range from 0 to 2.

0.5

Top P

Optional

The alternative to sampling with temperature is nucleus sampling, where the model considers the results of the tokens with top_p probability mass. For example, 0.1 means only the tokens comprising the top 10% probability mass are considered. It is recommended to alter this or temperature, but not both. If not specified, the default value is 1, with available values between 0 and 1.

0.5

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": "*****",
    "object": "chat.completion",
    "created": 1677652288,
    "model": "gpt-3.5-turbo-0125",
    "system_fingerprint": "fp_*****",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\n\nHello there, how may I assist you today?"
            },
            "logprobs": null,
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}
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
{
  "Model": "gpt-4-turbo",
  "Responses": [
    {
      "role": "assistant",
      "content": "Hello there, how may I assist you today?"
    }
  ]
}
Result

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

SAMPLE DATA

id

*****

object

chat.completion

created

1677652288

model

gpt-3.5-turbo-0125

system_fingerprint

fp_*****

choices

  • {'index': 0, 'message': {'role': 'assistant', 'content': '\n\nHello there, how may I assist you today?'}, 'logprobs': None, 'finish_reason': 'stop'}

usage

{'prompt_tokens': 9, 'completion_tokens': 12, 'total_tokens': 21}

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.

Analyze Image 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 ChatGPT 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 (Messages) is invalid.

Error Sample Data

Analyze Image failed.

Status Code: 400.

Message: The value for parameter (Messages) is invalid.

Create Embeddings

Creates an embedding vector representing the input text. Supported by "text-embedding" models.

Input

READER NOTE

Model ID is a required parameter to run this command.

  • Run the List Models command to obtain Model IDs. Model IDs can be found in the raw data at the path $.data[*].id.

Input Parameter

Required/Optional

Description

Example

Texts

Required

The input text to embed, encoded as a string or array of tokens. To embed multiple inputs in a single request, pass an array of strings or array of token arrays. The input must not exceed the max input tokens for the model (8192 tokens for text-embedding-ada-002).

["Hello World"]

Model ID

Required

The ID of the model to use. Model ID can be obtained using the List Models command. Supported by "text-embedding" models.

text-embedding-3-small

Encoding Format

Optional

The format to return the embeddings in. Can be either Float or Base64. The default value is Float.

Float

Dimensions

Optional

The number of dimensions the resulting output embeddings should have. Only supported in text-embedding-3 and later models. Please refer to Models - OpenAI API for maximum output dimensions.

10

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
{
    "object": "list",
    "data": [
        {
            "object": "embedding",
            "index": 0,
            "embedding": [
                0.047788173,
                -0.54172826,
                0.45133704,
                0.3118807,
                -0.28030568,
                -0.2945454,
                -0.3112616,
                0.31311893,
                -0.14061718,
                0.15245782
            ]
        }
    ],
    "model": "text-embedding-3-small",
    "usage": {
        "prompt_tokens": 2,
        "total_tokens": 2
    }
}
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
{
  "Model": "text-embedding-3-small",
  "Embeddings": [
    [
      0.047788173,
      -0.54172826,
      0.45133704,
      0.3118807,
      -0.28030568,
      -0.2945454,
      -0.3112616,
      0.31311893,
      -0.14061718,
      0.15245782
    ]
  ]
}
Result

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

SAMPLE DATA

object

list

data

  • {'object': 'embedding', 'index': 0, 'embedding': [0.047788173, -0.54172826, 0.45133704, 0.3118807, -0.28030568, -0.2945454, -0.3112616, 0.31311893, -0.14061718, 0.15245782]}

model

text-embedding-3-small

usage

{'prompt_tokens': 2, 'total_tokens': 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.

Create Embeddings 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 ChatGPT 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, API Key, API Version are all required.

Error Sample Data

Create Embeddings failed.

Status Code: 400.

Message: Server URL, API Key, API Version are all required.

Train Model

Creates a job that fine-tunes a specified model from a given dataset.

READER NOTE

Training File ID is a required parameter to run this command.

  • Run the List Files command to obtain the Training File ID. Training File IDs can be found in the raw data at the path $.data[*].id.

Validation File ID is an optional parameter to run this command.

  • Run the List Files command to obtain the Validation File IDs. Validation File IDs can be found in the raw data at the path $.data[*].id.

Input

Input Parameter

Required/Optional

Description

Example

Training File ID

Required

The ID of an uploaded file that contains training data. Training File ID can be obtained using the List Files command.

file-*****

Validation File ID

Optional

The ID of an uploaded file that contains validation data. Validation File ID can be obtained using the List Files command.

file-*****

Model Name

Optional

The name of the base model to fine-tune. The available inputs are: ada, babbage, curie, davinci, or a fine-tuned model created after 2022-04-21. If not specified, the default value is curie.

ada

Suffix

Optional

A string of up to 40 characters that will be added to your fine-tuned model name. For example, a suffix of "custom-model-name" would produce a model name like ada:ft-your-org:custom-model-name-2022-02-15-04-21-04.

cyberLab

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
{
    "object": "fine-tune",
    "id": "ft-*****",
    "hyperparams": {
        "n_epochs": 4,
        "batch_size": null,
        "prompt_loss_weight": 0.01,
        "learning_rate_multiplier": null
    },
    "organization_id": "org-*****",
    "model": "ada",
    "training_files": [
        {
            "object": "file",
            "id": "file-*****",
            "purpose": "fine-tune",
            "filename": "*****.jsonl",
            "bytes": 80,
            "created_at": 1675974438,
            "status": "processed",
            "status_details": null
        }
    ],
    "validation_files": [
        {
            "object": "file",
            "id": "file-*****",
            "purpose": "fine-tune",
            "filename": "*****.jsonl",
            "bytes": 80,
            "created_at": 1676075980,
            "status": "processed",
            "status_details": null
        }
    ],
    "result_files": [],
    "created_at": 1676079020,
    "updated_at": 1676079020,
    "status": "pending",
    "fine_tuned_model": null,
    "events": [
        {
            "object": "fine-tune-event",
            "level": "info",
            "message": "Created fine-tune: ft-*****",
            "created_at": 1676079020
        }
    ]
}
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
{
  "FineTuneID": "ft-*****",
  "Model": "ada",
  "Status": "pending"
}
Result

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

SAMPLE DATA

object

fine-tune

id

ft-*****

created_at

1676079020

updated_at

1676079020

status

pending

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.

Train Model 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 ChatGPT 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: You have insufficient permissions for this operation. Missing scopes: api.fine_tuning.jobs.write. Check that you have the correct role in your organization (Reader, Writer, Owner) and project (Member, Owner), and if you're using a restricted API key, that it has the necessary scopes.

Error Sample Data

Train Model failed.

Status Code: 401.

Message: You have insufficient permissions for this operation. Missing scopes: api.fine_tuning.jobs.write. Check that you have the correct role in your organization (Reader, Writer, Owner) and project (Member, Owner), and if you're using a restricted API key, that it has the necessary scopes.

Create Images

Creates image(s) given prompt(s).

Input

Input Parameter

Required/Optional

Description

Example

Prompts

Required

The text description(s) of the desired image(s). The maximum length for each prompt is 1000 characters.

[ "A cute baby sea otter" ]

Response Number

Optional

The number of images to generate. Must be between 1 and 10. The default number is 1.

2

Image Size

Optional

The size of the generated images. The default size is 1024x1024.

512x512

Response Format

Optional

The format in which the generated images are returned. The available options are: URL and Base64 JSON. The default format is URL.

URL

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
[
    {
        "created": 1676075027,
        "prompt": "A cute baby sea otter",
        "data": [
            {
                "url": "https://oaidalleapiprodscus.blob.core.windows.net/private/org-*****/user-*****/img-*****.png?st=2023-02-10T23%3A23%3A47Z&se=2023-02-11T01%3A23%3A47Z&sp=r&sv=2021-08-06&sr=b&rscd=inline&rsct=image/png&skoid=*****-*****&sktid=*****&skt=2023-02-10T21%3A36%3A35Z&ske=2023-02-11T21%3A36%3A35Z&sks=b&skv=2021-08-06&sig=*****/*****/*****/*****/*****"
            },
            {
                "url": "https://oaidalleapiprodscus.blob.core.windows.net/private/org-*****/user-*****/img-*****.png?st=2023-02-10T23%3A23%3A47Z&se=2023-02-11T01%3A23%3A47Z&sp=r&sv=2021-08-06&sr=b&rscd=inline&rsct=image/png&skoid=*****-*****&sktid=*****&skt=2023-02-10T21%3A36%3A35Z&ske=2023-02-11T21%3A36%3A35Z&sks=b&skv=2021-08-06&sig=*****%*****/*****"
            }
        ]
    }
]
Result

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

SAMPLE DATA

Images Count

2

Error Handling

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

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

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Create Images 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 ChatGPT 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: Billing hard limit has been reached.

Error Sample Data

Create Images failed.

Status Code: 400.

Message: Billing hard limit has been reached

Function Calling

Describes functions and have the model intelligently choose to output a JSON object containing arguments to call one or many functions. The OpenAI model does not call the function; instead, the model generates JSON that you can use to call the function in your code.

Input

Input Parameter

Required/Optional

Description

Example

Model ID

Required

The ID of the model to use. Model ID can be obtained using the List Models command.

gpt-3.5-turbo

Messages

Required

A list of messages exchanged in the conversation.

[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
]

Functions Summary

Required

The descriptions of the functions that define the model.

[

{

"name": "send_email",

"description": "template to have an email sent.",

"parameters": {

"type": "object",

"properties": {

"to_address": {

"type": "string",

"description": "To address for email"

},

"body": {

"type": "string",

"description": "Body of the email"

},

"date": {

"type": "string",

"description": "the specific date in format 'yyyy:mm:d' the email must be sent."

},

"time": {

"type": "string",

"description": "the time the email must be sent."

}

}

}

}

]

Tool Choice

Optional

The option to choose which tool is called by the model.

  • None means the model will not call any tool and instead generates a message.

  • Auto means the model can pick between generating a message or calling one or more tools.

  • Required means the model must call one or more tools.

If not specified, the default value is Auto.

Auto

Temperature

Optional

The sampling temperature to use. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. Recommend altering this or top_p but not both. If not specified, the default value is 1. The valid value is between 0 and 2.

0.5

Top P

Optional

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. Recommend altering this or temperature but not both. If not specified, the default value is 1. The valid value is between 0 and 1.

0.5

Output

Return Data

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

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

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

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

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

SAMPLE DATA

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "id": "*****",
    "object": "chat.completion",
    "created": 1717023291,
    "model": "gpt-3.5-turbo-0125",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": null,
                "tool_calls": [
                    {
                        "id": "*****",
                        "type": "function",
                        "function": {
                            "name": "get_current_weather",
                            "arguments": "{\"location\": \"Vancouver\", \"unit\": \"fahrenheit\"}"
                        }
                    }
                ]
            },
            "logprobs": null,
            "finish_reason": "tool_calls"
        }
    ],
    "usage": {
        "prompt_tokens": 216,
        "completion_tokens": 80,
        "total_tokens": 296
    },
    "system_fingerprint": null
}
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
{
  "Model": "gpt-3.5-turbo-0125",
  "Functions": [
    {
      "name": "get_current_weather",
      "arguments": "{\"location\": \"Vancouver\", \"unit\": \"fahrenheit\"}"
    }
  ]
}
Result

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

SAMPLE DATA

id

*****

object

chat.completion

created

1677652288

model

gpt-3.5-turbo-0125

system_fingerprint

fp_*****

choices

  • {'index': 0, 'message': {'role': 'assistant', 'content': '\n\nHello there, how may I assist you today?'}, 'logprobs': None, 'finish_reason': 'stop'}

usage

{'prompt_tokens': 9, 'completion_tokens': 12, 'total_tokens': 21}

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.

Function Calling 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 ChatGPT 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, API Key, API Version are all required.

Error Sample Data

Function Calling failed.

Status Code: 400.

Message: Server URL, API Key, API Version are all required.

Generate Conversation

Provides a list of messages comprising a conversation. The model will then generate a response.

Model ID is a required parameter to run this command.

  • Run the List Models command to obtain the Model ID. Model IDs can be found in the raw data at the path $.data[*].id.

Input

Input Parameter

Required/Optional

Description

Example

Model ID

Required

The ID of the model to be used. Model ID can be obtained using the List Models command.

gpt-3.5-turbo

Messages

Required

A list of messages comprising the conversation.

[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
]

Response Format

Optional

An object specifying the format that the model must output. Setting to JSON Object enables JSON mode, which guarantees the message the model generates is valid JSON.

Text

Max Words

Optional

The maximum number of words to generate in the completion. Please note, the word count of your prompt plus Max Words cannot exceed the model's context length. Most models have a context length of 2048 words (except for the newest models, which support 4096).

10

Temperature

Optional

The sampling temperature to use. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. Recommend altering this or top_p but not both. If not specified, the default value is 1. The valid value is between 0 and 2.

0.5

Top P

Optional

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. Recommend altering this or temperature but not both. If not specified, the default value is 1. The valid value is between 0 and 1.

0.5

Response Number

Optional

The number of chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep response number(n) as 1 to minimize costs. If not specified, the default value is 1. The valid value must >= 1.

1

Output

Return Data

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

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

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

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

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

SAMPLE DATA

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "id": "*****",
    "object": "chat.completion",
    "created": 1677652288,
    "model": "gpt-3.5-turbo-0125",
    "system_fingerprint": "fp_*****",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "\n\nHello there, how may I assist you today?"
            },
            "logprobs": null,
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}
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
{
  "Model": "gpt-3.5-turbo-0125",
  "Responses": [
    "Hello there, how may I assist you today?"
  ]
}
Result

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

SAMPLE DATA

id

*****

object

chat.completion

created

1677652288

model

gpt-3.5-turbo-0125

system_fingerprint

fp_*****

choices

  • {'index': 0, 'message': {'role': 'assistant', 'content': '\n\nHello there, how may I assist you today?'}, 'logprobs': None, 'finish_reason': 'stop'}

usage

{'prompt_tokens': 9, 'completion_tokens': 12, 'total_tokens': 21}

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.

Generate Conversation 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 ChatGPT 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 (Messages) is invalid.

Error Sample Data

Generate Conversation failed.

Status Code: 400.

Message: The value for parameter (Messages) is invalid.

Get File Content

Returns the contents of the specified file.

READER NOTE

The parameter File IDs is required to run this command.

  • Run the List Files command to obtain File IDs. File IDs can be found in the raw data at the path $.data[*].id.

Input

Input Parameter

Required/Optional

Description

Example

File IDs

Required

The ID(s) of the file(s) to get content. File IDs can be obtained using the List Files command.

[ "file-*****" ]

Output

Return Data

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

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

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

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

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

SAMPLE DATA

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
No Sample Data
Result

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

SAMPLE DATA

File Count

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.

Get File Content 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 ChatGPT 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: No such File object: <File IDs>.

Error Sample Data

Get File Content failed.

Status Code: 404.

Message: No such File object: <File IDs>.

List Files

Returns a list of files that belong to the user's organization.

Input

Input Parameter

Required/Optional

Description

Example

Purpose

Optional

The intended purpose of the uploaded documents. Use "assistants" for Assistants and Message files, "vision" for Assistants image file inputs, "batch" for Batch API, "fine-tune" for Fine-tuning, and "user_data" for User Data. If not specified, all files will be retrieved.

fine-tune

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
{
    "object": "list",
    "data": [
        {
            "object": "file",
            "id": "file-*****",
            "purpose": "fine-tune",
            "filename": "*****.jsonl",
            "bytes": 80,
            "created_at": 1675974438,
            "status": "processed",
            "status_details": null
        },
        {
            "object": "file",
            "id": "file-*****",
            "purpose": "fine-tune-results",
            "filename": "compiled_results.csv",
            "bytes": 350,
            "created_at": 1675982379,
            "status": "processed",
            "status_details": null
        },
        {
            "object": "file",
            "id": "file-*****",
            "purpose": "fine-tune",
            "filename": "*****.jsonl",
            "bytes": 80,
            "created_at": 1676075964,
            "status": "processed",
            "status_details": null
        },
        {
            "object": "file",
            "id": "file-*****",
            "purpose": "fine-tune",
            "filename": "*****.jsonl",
            "bytes": 80,
            "created_at": 1676075980,
            "status": "processed",
            "status_details": null
        }
    ]
}
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE
{
  "FileIDs": ["file-*****"],
  "FileNames": ["*****.jsonl"],
  "Statuses": ["processed"]
}
Result

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

SAMPLE DATA

File Count

4

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 Files 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 ChatGPT 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: Invalid purpose: <text>.

Error Sample Data

List Files failed.

Status Code: 400.

Message: Invalid purpose: <text>.

List Models

Returns detailed info of the specified indicators.

Input

Input Parameter

Required/Optional

Description

Example

Model IDs

Optional

The ID(s) of the model(s) to retrieve. If not specified, all models will be returned.

[ "ada" ]

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
{
    "object": "list",
    "data": [
        {
            "id": "*****",
            "object": "model",
            "created": 1649357491,
            "owned_by": "openai",
            "permission": [
                {
                    "id": "modelperm-*****",
                    "object": "model_permission",
                    "created": 1669087301,
                    "allow_create_engine": false,
                    "allow_sampling": true,
                    "allow_logprobs": true,
                    "allow_search_indices": false,
                    "allow_view": true,
                    "allow_fine_tuning": false,
                    "organization": "*",
                    "group": null,
                    "is_blocking": false
                }
            ],
            "root": "ada",
            "parent": null
        }
    ]
}
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
{
  "ModelIDs": ["ada"],
  "rootModels": ["ada"],
  "parentModels": [ NULL ]
}
Result

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

SAMPLE DATA

Models Count

1

Error Handling

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

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

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

List Models 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 ChatGPT 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: The model <modelID> does not exist.

Error Sample Data

List Models failed.

Status Code: 404.

Message: The model <modelID> does not exist.

Upload Files

Uploads file(s) that contain document(s) to be used across various endpoints/features. Currently, the size of all the files uploaded by one organization can be up to 1 GB.

File IDs and File Source parameters

It is not recommended to use the Test Command feature with the Submit Sample Files command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:

  1. Navigate to Configuration on the top bar menu.

  2. Click Utility Commands on the left sidebar menu.

  3. Use the search box to find and select the Create a File from input Text Array command.

  4. Select the Test tab, then input the required information for the parameters. Click Test Command. A D3 File ID will appear in the output data after the file has been successfully created.
    (Note: The D3 File Source of the created file will be Playbook File)

Input

Input Parameter

Required/Optional

Description

Example

Purpose

Optional

The intended purpose of the uploaded documents. Use "assistants" for Assistants and Message files, "vision" for Assistants image file inputs, "batch" for Batch API, "fine-tune" for Fine-tuning, and "user_data" for User Data. If not specified, the default value is "fine-tune".

fine-tune

File IDs

Required

The file ids of the JSON Lines file(s) to be uploaded. Please note, if the purpose parameter is set to "fine-tune", each line in the JSON Lines file is a JSON record with "prompt" and "completion" fields representing your training examples. For example, one line looks like: {"prompt": "<prompt text>", "completion": "<ideal generated text>"}.

[ "*****" ]

File Source

Required

The file source of the file to attach. The options for file sources are:

  • Incident Attachment File: Manually uploaded file from Incident

  • Playbook File: Output from another Task

  • Artifact File: Ingested Artifact in an Event

Playbook File

Output

Return Data

Indicates one of the possible command execution states: Successful, 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
[
    {
        "object": "file",
        "id": "file-*****",
        "purpose": "fine-tune",
        "filename": "*****.jsonl",
        "bytes": 80,
        "created_at": 1676075980,
        "status": "uploaded",
        "status_details": null
    }
]
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE
{
  "FileIDs": ["file-*****"],
  "FileNames": ["*****.jsonl"],
  "Statuses": ["uploaded"]
}
Result

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

SAMPLE DATA

Uploaded Files Count

1

Error Handling

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

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

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Upload Files 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 ChatGPT 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: [ "Upload file with ID \"1\" failed: not a valid Artifact File file ID." ]

Error Sample Data

Upload Files failed.

Status Code: 400.

Message: [ "Upload file with ID \"1\" failed: not a valid Artifact File file ID." ].

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 ChatGPT 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, API Key, API Version are all required.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 400.

Message: Server URL, API Key, API Version are all required.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.