dtctl

dtctl is a command-line interface (CLI) tool for interacting with Dependency-Track, allowing you to manage contexts and perform various operations such as fetching projects. Inspired by tools like kubectl, dtctl aims to simplify Dependency-Track operations directly from your terminal.

---

Table of Contents

• Features
• Use Cases
• Installation
• Configuration
• Usage

---

Features

• Manage Multiple Contexts: Easily add, switch, and view different Dependency-Track server configurations.
• Seamless Context Switching: Quickly switch between different server contexts without reconfiguring each time.
• Fetch Projects: Retrieve and display all projects from the current Dependency-Track server.
• Cross-Platform Support: Available for Linux, macOS, and Windows, ensuring broad usability.
• Extensible Architecture: Designed to allow the addition of more commands and functionalities in the future.

---

Use Cases

Use Case 1: When a new build is produced, automatically update the policy’s hash to ensure the latest component is recognized before deployment. This is using the command dtcl set hashpolicycondition then at later stage after the deployment, update the new hash of the component using dtctl set component --fields-sha256="value

Use Case 2: Rapid CLI Queries by Security Admins. A security admin wants quick checks without using the GUI especially if managing multiple Dependency Track. Using the command dtctl config use-context production security admins can switch to other instances quickly and execute further evaluations using available commands.

Use Case 3: Quickly verify violations when there is a security incident. Command dtctl eval policy --uuid="policy-uuid" can be used and easily review the tabulated results.

Other Use Cases: Any quick tasks to be done programmatically can later be added.

---

Installation

You can download the latest version of dtctl from the Releases page.

macOS and Linux

1. Download and unzip the binary:

   For macOS:

   curl -L -o dtctl.zip https://github.com/francislance/dtctl/releases/latest/download/dtctl-macos-amd64.zip

   For Linux:

   curl -L -o dtctl.zip https://github.com/francislance/dtctl/releases/latest/download/dtctl-linux-amd64.zip

2. Download and unzip the binary:

   unzip dtctl.zip

3. Make the binary executable:

   chmod +x dtctl

4. Move the binary to a directory in your PATH:

   sudo mv dtctl /usr/local/bin/

5. Verify the installation:

   dtctl --version

Windows

1. Download and unzip the binary:

   • Download dtctl-vX.X.X-windows.zip from the Releases page.
   • Unzip the file to extract dtctl.exe.

2. Add the binary to your PATH:

   • Move dtctl.exe to a directory that's in your PATH, or add the directory containing dtctl.exe to your PATH environment variable.

3. Verify the installation:

   dtctl --version

---

Configuration

Before using dtctl, you need to configure it with your Dependency-Track server details. This configuration allows you to manage multiple server contexts and switch between them as needed.

The configuration is stored in a file located at ~/.dtctl/config.json.

Adding a Context

To add a new context, use the add-context command with a unique name, the Dependency-Track server URL, and your API token.

dtctl config add-context mycontext --url="https://dependency-track.example.com" --token="your-api-key"

Switching Contexts

Set the current context to use for operations. This allows you to switch between different Dependency-Track server configurations seamlessly.

dtctl config use-context production

---

Usage

Once you have configured your contexts, you can use dtctl to interact with your Dependency-Track server. Below are the primary commands and their usage.

Projects

Retrieve and display all projects from the current context's Dependency-Track server.

dtctl get projects

dtctl get projects --tag="springboot"

Policies

dtctl get policies

Components

# get all components
dtctl get components

# get all components under a project with specific tag
dtctl get components --tag="container"

# get all components under a project with fields
# (available: projectname, projectuuid, sha256, sha1, md5)
dtctl get components --show-fields="projectname,projectuuid,sha256,sha1,md5" --tag="container"

Hash Policy Condition

Sample updating of hash policy condition:

dtctl set hashpolicycondition --uuid="1cf6c518-149a-43a6-991d-276d163c5852" --operator="IS_NOT" --subject="COMPONENT_HASH" --algorithm="SHA-256" --algorithm-value="928b2691494882b361bbe4f70fcf3fa9fbcb5a2bbe88f2b42f7e93f2c8cc726b"

Evaluate a Policy

# set the uuid of the policy
dtctl eval policy --uuid="c4583613-1e43-4346-ac2d-db3d4e19491a"