Upgrading to the .NET 8.0 D3 Agent

LAST UPDATED: SEPTEMBER 08, 2025

Linux Agent Upgrade

Create a new docker-compose.yml file in a different directory from the original.

New Docker Compose File Template *

YAML

services:
  d3agent:
    image: "d3soar.azurecr.io/d3prod/d3agentn8:<D3 vSOC version>"
    restart: always
    environment:
      - REMOTE_SERVER_URL=<D3 vSOC URL>
      - PROXY_IDENTITY=<D3 vSOC Agent Security Token>
      - PYTHON_REMOTE_URL=http://<Docker Host IP>:<Docker Host Port>/
      - PYTHON_REMOTE_GUID=<Executor Identifier>
      - SERVICE_DISPLAY_NAME=<Proxy Agent Display Name>
      - DOCKER_GID=<Docker Group ID>
      - DOCKER_PORT=<Docker Host Port>
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
  
  d3executor:
    image: "d3soar.azurecr.io/d3prod/d3executor:<D3 vSOC version>"
    privileged: true
    ports:
      - "<Docker Host Port>:9090"
    restart: always
    environment:
      - EXECUTOR_GUID=<Executor Identifier>

Ensure n8 is inserted at the end of the image name (i.e., image: "d3soar.azurecr.io/d3prod/d3agentn8:<D3 vSOC version>").
Replace all placeholders within the new template.
- D3 VSOC VERSION – The vSOC version with the + sign replaced with an _.
- D3 VSOC URL – The vSOC login page URL, ending with /VSOC.
- D3 VSOC AGENT SECURITY TOKEN – Reuse the existing security token from the original docker-compose.yml file.
- DOCKER HOST IP – The private IP of the Docker host. Run the following command to retrieve it.
  BASH
```
ip addr show
```
- DOCKER HOST PORT – A unique, unoccupied Docker host port mapping to the d3executor's internal port. Run the following command, then retrieve it under the PORTS column:
  BASH
```
sudo docker ps
```
  - The <Docker Host Port> specified in the PYTHON_REMOTE_URL and DOCKER_PORT environment variables of the d3agent service must identically match the <Docker Host Port> specified in the ports field of the d3executor service.
  - Run the following pipeline command to check whether a specific port is being used:
    BASH
```
netstat -nlp | grep ':<port>'
```
- EXECUTOR IDENTIFIER – Reuse the existing executor identifier from the original docker-compose.yml file.
- PROXY AGENT DISPLAY NAME – A name for the new agent displayed in vSOC.
- DOCKER GROUP ID – Reuse the existing Docker group ID from the original docker-compose.yml file.
Run the following command from the directory with the new docker-compose.yml file:
BASH
```
sudo docker compose up -d
```

READER NOTE

Unlike the .NET 8 Windows agent, the .NET 8 Linux agent does not create an additional record in the vSOC Agent Management module. Since it reuses the same D3 vSOC Agent Security Token, only one active Linux agent instance exists at any time.
The agent will switch over automatically during a later .NET 8 vSOC upgrade.

Windows Agent Upgrade

Request D3 to provide the download link for the .NET 8 Windows agent.
Generate a new, unused security token from vSOC.
1. Click on the button.
2. Click on the button, then store the security token for step 9b.
Download the installation package obtained from step 1.
Inspect the zip folder's properties, and unblock it in the Security section (if applicable).
Extract the installation package (approximately 1.5 GB).
Run the D3PlaybookAgentInstaller.exe file as an administrator.
Select the "Install a new agent" radio option.
Use a new, empty installation folder for the .NET 8 Windows agent.
Input the required fields, then click on the Next button.
1. Server URL – The vSOC login page URL, ending with /VSOC.
2. Security Token – The token generated in step 2.
3. Agent Service Name – A unique internal service name —different from the previous agent's—under which the agent runs.
4. Agent Name – The display name of the .NET 8.0 agent that will appear in vSOC. Assign a unique name that distinguishes it from the previous .NET 4.8 agent.
Complete the installation, then confirm in the Services table of Task Manager (Ctrl + Alt + Esc) that the agent service defined in step 9c is running.
Add the .NET 8 Windows agent to all integration connections—in the Connections or Integrations modules, under the Agent Name field—that are using the .NET 4.8 Windows agent.
- The agent will switch over automatically during a later .NET 8 vSOC upgrade.

CAUTION *

Do not remove the .NET 4.8 Windows agent from the Agent Name field until the switch-over is complete.