Docker

LAST UPDATED: 04/02/2024

Overview

Docker allows developers to easily pack, ship, and run any application as a lightweight, portable, self-sufficient container.

D3 SOAR is providing REST operations to function with Docker.

Docker is available for use in:

Known Limitations

When you issue a pull request and you are over the limit for your account type, Docker Hub will return a 429 response code with the following body when the manifest is requested:

You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits

Please refer to Download rate limit and Understanding Docker Hub Rate Limiting for detailed information.

Connection

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

Permission Requirement

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

READER NOTE

The execution of the remaining commands, Test Connection, Build Docker, Build Docker Image From Text, List Docker Images, does not need Remote Registry which means those commands have no dedicated permission requirement but the correct Docker server address.

Configuring Docker to Work with D3 SOAR

Docker installation on the remote server or the local server is required.

Configuring Azure Container Registry (ACR)

1. Open Microsoft Azure Portal and sign in. Select Container registries.

2. Create or select a registry.

3. Under your selected registry, click Access keys. You will see the Login server, Username, and Password fields on the right.

Configuring Google Container Registry (GCR)

To connect with Google Container Registry, we need to get the Service Account JSON and Registry URI.

Step 1: Follow the Obtaining the Service Account JSON section to obtain the Service Account JSON file.

Step 2: The registry URI format is: gcr.io/PROJECT-ID. Follow the Obtaining the Project ID section to obtain the registry URI.

Obtaining the Service Account JSON

1. In order to connect Google Kubernetes Engine with D3 SOAR, we need to configure the Service Account JSON file. Log in to the Google Cloud Platform(GCP) console with admin credentials.

2. Click the Hamburger Menu in the top left corner to reveal the sidebar menu. Navigate to APIs and services, in its submenu, select Credentials.

3. Click + CREATE CREDENTIALS, and select Service account.

4. Input the Service account name and description, and click CREATE AND CONTINUE.

5. Assign a role to the service account, such as owner, then click CONTINUE.

READER NOTE

You can narrow down the service account’s access permissions by assigning the following roles according to your request:

• Kubernetes Engine Admin

• Kubernetes Engine Cluster Admin

• Kubernetes Engine Cluster Viewer,

• Kubernetes Engine Developer

• Kubernetes Engine Host Service Agent User

• Kubernetes Engine Viewer

6. You can opt to grant users access to this service account. Click DONE to confirm your configurations.

7. You will find the service account you have just created on the credentials page. Click and open the service account.

8. In the KEYS tab, click ADD KEY, then select Create new key.

9. Choose JSON as the key type, then click CREATE.

10. The Service Account JSON file (Private key) will be downloaded to your computer automatically.

READER NOTE

Please refer to Using OAuth 2.0 for Server to Server Applications | Google Identity for more details.

Configuring the Service Account Domain-wide Delegation

You also need to enable Google Workspace domain-wide delegation for your created service account, please follow the steps below.

1. Login Google Workspace Admin Console with admin credentials. Click Security > Access and data control > API controls. Scroll down and click MANAGE DOMAIN-WIDE DELEGATION.

2. Click Add new to add a new API client.

3. Find your Client ID in the service account you created and paste it into the Client ID field. Input https://www.googleapis.com/auth/cloud-platform into the OAuth scopes field, then click AUTHORISE.

4. Finally, the service account domain-wide delegation is found on the API controls page. Your created service account is now ready to use.

Obtaining the Project ID

1. Log in to Google Cloud Platform Portal.

2. Click “My First Project” on the top bar menu.

3. A pop-up window wil appear. Select a project, e.g. "My First Project", or create a new project by clicking NEW PROJECT on the top right corner of the window.

4. Copy the ID next to the project name.

   

Configure Docker Integration on D3 SOAR

1. Log in to D3 SOAR.

2. Find the Docker integration.

a. Navigate to Configuration on the top header menu.

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

c. Type Docker in the search box to find the integration, then click it to select it.

d. Click New 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 Docker.

a. Connection Name: The desired name for the connection.

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

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

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

e. Description (Optional): Add your desired description for the connection.

f. Configure User Permissions: Defines which users have access to the connection.

g. Active: Check the tick box to ensure the connection is available for use.

h. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.

i. Input the Docker Server Address. The format is “IP Address:2375”.

ii. Select the Remote Registry Type. Here are two types of the registry you can select: Azure Container Registry (ACR) and Google Container Registry (GCR).

1. If you choose Azure Container Registry (ACR)

a. Input the saved Username in Username field.

b. Input the saved password in Password field.

c. Input the saved Login server in Registry URI field.

Please refer to Configuring Docker to Work with D3 SOAR>Configuring Azure Container Registry (ACR) for more details on how to get the required information.

2. If you choose Google Container Registry (GCR)

a. Input your downloaded Service Account JSON

b. Registry URI format is: gcr.io/PROJECT-ID. Please get your project ID by referring to Obtaining project ID.

Please refer to Configuring Docker to Work with D3 SOAR>Configuring Google Container Registry (GCR) for more details on how to get the required information.

i. Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.

To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.

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

   

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

b. Click OK to close the alert window.

c. Click Add to create and add the configured connection.

Commands

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

READER NOTE

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

Build Docker Image

Builds a docker image with a tar file which is stored in the D3 SOAR system.

Only a Docker File is accepted to build Docker Image. The wrong file type will cause a command execution failure. Please ensure the selected file is a Docker file. Refer to the Docker file reference from Docker’s documentation for more details.

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. In D3 SOAR, 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

Output

[
    {
        "stream": "Step 1/2 : FROM ubuntu:**.**"
    },
    {
        "stream": "\n"
    },
    {
        "stream": " ---> *****\n"
    },
    {
        "stream": "Step 2/2 : EXPOSE 8080/tcp"
    },
    {
        "stream": "\n"
    },
    {
        "stream": " ---> Using cache\n"
    },
    {
        "stream": " ---> *****\n"
    },
    {
        "aux": {
            "ID": "sha256:*****"
        }
    },
    {
        "stream": "Successfully built *****\n"
    },
    {
        "stream": "Successfully tagged ubuntuj:v***.***\n"
    }
]

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.

Build Docker Image From Text

Builds a docker image with the specified content of a docker file.

Input

Output

{
    "result": "(<Image: 'demo20200225:latest'>, <itertools._tee object at 0x*******>)",
    "imageTag": "demo20200225:latest"
}

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.

List Docker Images

Returns a list of images on the Docker server.

Input

N/A

Output

[
    {
        "Containers": -1,
        "Created": 1647044720,
        "Id": "sha256:*****",
        "Labels": null,
        "ParentId": "sha256:*****",
        "RepoDigests": [
            "<none>@<none>"
        ],
        "RepoTags": [
            "<none>:<none>"
        ],
        "SharedSize": -1,
        "Size": 951300900,
        "VirtualSize": 951300900
    },
    {
        "Containers": -1,
        "Created": 1646344731,
        "Id": "sha256:*****",
        "Labels": null,
        "ParentId": "",
        "RepoDigests": [
            "mongo@sha256:*****"
        ],
        "RepoTags": [
            "mongo:latest"
        ],
        "SharedSize": -1,
        "Size": 697604899,
        "VirtualSize": 697604899
    },
    {
        "Containers": -1,
        "Created": 1646338773,
        "Id": "sha256:*****",
        "Labels": null,
        "ParentId": "",
        "RepoDigests": [
            "ubuntu@sha256:*****"
        ],
        "RepoTags": [
            "ubuntu:latest"
        ],
        "SharedSize": -1,
        "Size": 72759661,
        "VirtualSize": 72759661
    },
    {
        "Containers": -1,
        "Created": 1594695486,
        "Id": "sha256:*****",
        "Labels": null,
        "ParentId": "",
        "RepoDigests": [
            "python@sha256:*****"
        ],
        "RepoTags": [
            "python:3.8.4"
        ],
        "SharedSize": -1,
        "Size": 934365956,
        "VirtualSize": 934365956
    },
    {
        "Containers": -1,
        "Created": 1565767693,
        "Id": "sha256:*****",
        "Labels": {
            "maintainer": "NGINX Docker Maintainers <*****@nginx.com>"
        },
        "ParentId": "",
        "RepoDigests": [
            "nginx@sha256:*****"
        ],
        "RepoTags": [
            "nginx:1.16.0"
        ],
        "SharedSize": -1,
        "Size": 109369748,
        "VirtualSize": 109369748
    }
]

{
    "ImageIDs": ["ngsha256:*****inxj0309b"],
    "RepoTags": ["mongo:latest"]
}

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.

Push Docker Image

Pushes a docker image to a repository in the remote registry (Azure container registry or Google container registry).

READER NOTE

Image and Tag is a required parameter to run this command.

• Run the List Docker Images command to obtain Image and Tag. Image and Tag can be found in the returned raw data at the path $[*].RepoTags[*].

Input

Output

{
    "result": [
        {
            "stream": "Step 1/3 : FROM python:3.8.4"
        },
        {
            "stream": " ---> *****\n"
        },
        {
            "stream": "Step 2/3 : ADD /tmp /tmp"
        },
        {
            "stream": " ---> Using cache\n"
        },
        {
            "stream": " ---> d0d979d446df\n"
        },
        {
            "stream": "Step 3/3 : EXPOSE 8080/tcp"
        },
        {
            "stream": " ---> Using cache\n"
        },
        {
            "stream": " ---> *****\n"
        },
        {
            "aux": {
                "ID": "sha256:*****"
            }
        },
        {
            "stream": "Successfully built *****\n"
        },
        {
            "stream": "Successfully tagged *****:latest\n"
        }
    ]
}

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.

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

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.