ChatGPT

LAST UPDATED: OCT 23, 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

Login https://platform.openai.com with your account credentials.
Click Dashboard. On the left sidebar select API Keys, click the + Create new secret key button to generate your credentials.
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.
Copy the API key into VSOC.

Configuring D3 SOAR to Work with ChatGPT

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.
Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to 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.
Test the connection.
1. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green check mark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

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. The model will return a response with the analysis result. This feature is only supported by GPT-4 and later 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.

File ID and File Source

It is not recommended to use the Test Command feature with the Analyze Image 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:

Navigate to Configuration on the top bar menu.
Click on Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Click on the Test tab.
Input the required information for the parameters.
Click on the Test Command button. A D3 File ID will appear in the output data after the file has been successfully created. The D3 File Source of the created file will be Playbook File.

Input Parameter	Required/Optional	Description	Example
Model ID	Required	The ID of your large language model. Model IDs 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 comprising the conversation.	[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} ]
Instructions	Required	The instructions provided to the model for image analysis.	["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 are accepted.	[ "***", "***" ]
File Source	Optional	The file source of the file to be retrieved, with the options: Incident Attachment File: Manually within Incident Playbook File: Output from another task Artifact File: Ingested Artifact in an event	Playbook File
Response Format	Optional	The format in which the model must output, with the options: Text \| JSON Object. Setting the format to JSON Object returns the output in valid JSON. By default, the value is text.	Text
Max Words	Optional	The maximum number of words to generate in the completed output. 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, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. It is recommended to alter either the temperature or top_p, but not both. By default, the value is 1.	0.5
Top P	Optional	The alternative to sampling with temperature, nucleus sampling, where the model considers the results of the tokens with top_p probability mass. Acceptable values are between 0 and 1. For example, 0.1 means only the tokens comprising the top 10% probability mass are considered. It is recommended to alter either top_p or temperature, but not both. By default, the value is 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 IDs can be obtained using the List Models command. Supported by "text-embedding" models.	text-embedding-3-small
Encoding Format	Optional	The format (Float or Base64) in which to return the embeddings. By default, the 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 containing training data. Training File IDs can be obtained using the List Files command.	file-*****
Validation File ID	Optional	The ID of an uploaded file containing validation data. Validation File IDs 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. By default, the 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) using the given prompt(s).

Input

Input Parameter	Required/Optional	Description	Example
Prompts	Required	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. Permissible values are between 1 and 10. By default, the number is 1.	2
Image Size	Optional	The size of the generated images. By default, the size is 1024x1024.	512x512
Response Format	Optional	The format in which the generated images are returned. The available options are: URL \| Base64 JSON. By default, the 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 that the model intelligently chooses to output as 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 IDs 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!"} ]
Functions Summary	Required	Describes 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	Provides options for choosing which tool is called by the model. None means that the model will not call any tool and will instead generate a message. Auto means that the model can pick between generating a message or calling one or more tools. Required means that the model must call one or more tools. By default, the value is Auto.	Auto
Temperature	Optional	The sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. It is recommended to alter either temperature or top_p, but not both. By default, the value is 1.	0.5
Top P	Optional	An alternative to sampling temperature called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. Acceptable values are between 0 and 1. 0.1 indicates that only the tokens comprising the top 10% probability mass are considered. It is recommended to alter either topP or temperature, but not both. By default, the value is 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, which the model will use to 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 IDs 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 in which the model must output, with the options Text \| JSON Object. Setting the format to JSON Object returns the output in valid JSON.	Text
Max Words	Optional	The maximum number of words to generate in the completion. 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 words).	10
Temperature	Optional	The sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. It is recommended to alter either the temperature or the top_p parameter, but not both. By default, the value is 1.	0.5
Top P	Optional	An alternative to sampling temperature called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. Acceptable values are between 0 and 1. 0.1 indicates that only the tokens comprising the top 10% probability mass are considered. It is recommended to alter either nucleus sampling or the temperature, but not both. By default, the value is 1.	0.5
Response Number	Optional	The number of chat completion choices to generate for each input message, greater than or equal to 1. You will be charged based on the number of generated tokens across all completion choices. Keep response number(n) as 1 to minimize costs. By default, the value is 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 belonging to the user's organization.

Input

Input Parameter	Required/Optional	Description	Example
Purpose	Optional	The 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. By default, 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 information on the specified indicators.

Input

Input Parameter	Required/Optional	Description	Example
Model IDs	Optional	The ID(s) of the model(s) to retrieve. By default, 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 maximum size of all files uploaded by one organization is 1 GB.

File ID and File Source

It is not recommended to use the Test Command feature with the Upload 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:

Navigate to Configuration on the top bar menu.
Click on Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Click on the Test tab.
Input the required information for the parameters.
Click on the Test Command button. A D3 File ID will appear in the output data after the file has been successfully created. The D3 File Source of the created file will be Playbook File.

Input

Input Parameter	Required/Optional	Description	Example
Purpose	Optional	The 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. By default, the value is fine-tune.	fine-tune
File IDs	Required	The file IDs of the JSON Lines file(s) to be uploaded. 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, a line may look like: {"prompt": "<prompt text>", "completion": "<ideal generated text>"}.	[ "*****" ]
File Source	Required	The file source of the file to attach, with the options: Incident Attachment File: Manually uploaded file within 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

The Test Connection Command 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.