What is the Debricked CLI?

The Debricked CLI is Debricked's command line interface, bringing open-source security, and license compliance to your project via the command prompt. 

The Debricked CLI is currently available for: Windows, Linux, and macOS operating systems. It might work on other operating systems but has not been thoroughly tested yet.
Supported languages: Javascript, Java, C#, Ruby, PHP, and more.

Supported package managers: Yarn, Npm, Bowel, Bazel, Gradle, and more.

Getting started

To use the Debricked CLI, you must have a Debricked account, create an access token and install the CLI.  

The CLI can be run:

• locally in your terminal as an interactive shell
• in your CI/CD pipeline
• through docker

 1. Authentication

To create an access token, log in to debricked.com/app and follow the steps to generate an access token. Make sure to keep the access token in a safe place for later use.

2. Installation

The CLI can be installed and used through: 

1. Local installations:
   - Standalone
   - Installation using Go
2. Adding the CLI into your CI/CD pipeline
3. Using a docker image

If you run into any issues during the installation process, feel free to contact us.

2.1 Local installation:

2.1.1 Standalone:

Here are the latest GitHub releases to download a standalone executable:
 

Linux:

• cli_linux_arm64.tar.gz
• cli_linux_i386.tar.gz
• cli_linux_x86_64.tar.gz

Windows:

• cli_windows_arm64.tar.gz
• cli_windows_i386.tar.gz
• cli_windows_x86_64.tar.gz

MacOs:

• cli_macOS_arm64.tar.gz
• cli_macOS_x86_64.tar.gz

Command example for Linux:

curl -L https://github.com/debricked/cli/releases/latest/download/cli_linux_x86_64.tar.gz | tar -xz debricked

Command example for Windows:

curl -L https://github.com/debricked/cli/releases/latest/download/cli_windows_x86_64.tar.gz | tar -xz debricked

Command example for MacOS:

curl -L https://github.com/debricked/cli/releases/latest/download/cli_macOS_arm64.tar.gz | tar -xz debricked

2.1.2 Installation using Go

Requirements: 

Local compilation of Debricked CLI requires Go to be installed on your system. In order to check whether you already have the compiler installed on your device, run the command ‘go version’ on your terminal. If there is no command available, install the Go compiler.

Installation:

1. Install Go on your operating system following the official documentation
    
2. Clone the CLI repository to your local directory: https://github.com/debricked/cli
    

2.2 Adding the CLI to your CI/CD pipeline

The CLI can be integrated into your continuous integration (CI) to run scans on the pipeline. You can integrate using:

• Docker image 
• Binary standalone

2.2.1 Using the docker debricked/cli image

1. Log in to debricked.com/app and follow the steps to generate an access token. 
2. Set your access token, named DEBRICKED_TOKEN, as an environment variable within your continuous integration (CI). If you don’t know how to configure your environment variable, check our documentation for the most common CI integrations.
3. Configure a new job in your CI pipeline::

• debricked/cli docker image
• Run debricked scan
• Add the DEBRICKED_TOKEN as a variable or (if possible) as a secret

 See the example below for the GitHub actions integration (see the debricked.yml file):

name: Debricked scan

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    container: debricked/cli
    steps:
      - uses: actions/checkout@v3
      - run: debricked scan
        env:
          DEBRICKED_TOKEN: ${{ secrets.DEBRICKED_TOKEN }}

For more details, please visit our sample templates for the integration you are using (CI Build system).

2.2.2 Using the Standalone 

1. Log in to debricked.com/app and follow the steps to generate an access token. 
2. Set your access token, named DEBRICKED_TOKEN, as an environment variable within your continuous integration (CI). If you don’t know how to configure your environment variable, visit our documentation for the most common CI integrations. 
3. Configure a new job in your CI pipeline::

• Run:

  curl -L https://github.com/debricked/cli/releases/latest/download/cli_linux_x86_64.tar.gz | tar -xz debricked

   to use the executable Debricked CLI.
• Run debricked scan.

 Here’s an example of the Circle CI integration: circleci/config.yml file. For more examples check out: https://github.com/debricked/cli/tree/main/examples/templates

jobs:
  build:
    docker:
      # specify the version here
      - image: cimg/go:1.17

    steps:
      - checkout
      - run: |
          printf "$(go mod graph)\n\n$(go list -mod=readonly -e -m all)" > .debricked-go-dependencies.txt
      # It is important that the generated dependency tree files are persisted and attached to the following scan step
      - persist_to_workspace:
          root: ~/repo
          paths:
            - '**.debricked-go-dependencies.txt'
            # Make sure to add all generated .debricked-go-dependencies.txt files

  scan:
    docker:
      - image: cimg/go:1.17
    working_directory: ~/repo
    steps:
      - checkout
      - run: curl -L https://github.com/debricked/cli/releases/latest/download/cli_linux_x86_64.tar.gz | tar -xz debricked
      - run: ./debricked scan

workflows:
  debricked-scan:
    jobs:
      - build
      - scan:
          requires:
            - build

3. Test your installation

To confirm whether the installation was successful, run the command ‘./debricked --help’. If you can see the menu as seen below, you are ready to scan your first project!

4. Scan your first project

Once you've installed the CLI, you're ready to scan your project. You can scan a local project allocated on your local machine or a project in a remote repository via a CI integration, follow the instructions below to perform your first scan:

1. Run debricked scan --help to see the main menu and check if the CLI is running
2. Scan your project locally using the command: debricked scan [path] [options]

The path is the folder that contains your project's dependency file. See this practical example, scanning a local project:

Debricked scan ~/Desktop/myproject/EasyApp --access-token “<token>”

The path is the ~/Desktop/myproject/EasyApp and the options included are the access-token (required). Since EasyApp is a git repository, no other flags are needed for the scan.

Include some [option]s within your scan: 

Debricked scan ~/Desktop/myproject/EasyApp --access-token “<token>” --commit "044bdc7c22e46be010969e9360dbe679830100f1" --branch "dev"  --exclusion "**/test/**"

The commit --commit  specifies the hash commit,  and the branch with the command --branch. Note that --commit and --branch are only required when the target path does not contain a git repository.

Another option is to change the directory to a folder that contains your project's dependency file. So you can use "." For example

Debricked scan . --access-token <token>

After the scan is complete, you will see the total number of vulnerabilities found and a list of automation rules that have been evaluated. See the picture below:

You can log in to the Debricked web tool to see the scan results, by following the link with all the details.

5. List of Commands

These are the main commands for the Debricked CLI:

help

• debricked [command] --help

Type debricked –-help to display the main menu. 

To display the options on any command just execute the [command], followed by the --help option.  For example, type debricked scan -–help to list the options for the scan command.

scan

• debricked scan [path] [flags]
• debricked scan –-help to see all the options.

The scan command uploads and check your dependency files for open-source vulnerabilities and license compliance.
 

Path:

• Use the path argument to specify which directory the dependency file is in, or to exclude it. For example: debricked scan ~/Desktop/Coder-2022/Eccomerce2/ -t <token>.

• Use the path to specify where the dependency file is allocated, you can use "." to search the current working directory. For instance: debricked files find . -t <token> or debricked files find ~/Desktop/Coder-2022/Eccomerce2/ -t <token>

Flags

-t --access-token Required

Use this parameter to authenticate. Run -t, or --access-token and enter your access token created in the authentication. Example:  --access-token <token>

-e, --exclusions Optional 

Use this command to exclude files or folders you don't want to be scanned for some reason.  The following terms are supported to exclude paths:

•  "*": matches any sequence of non-Separator characters.
• "/**/": matches zero or multiple directories.

•  "?":  matches any single non-Separator character.
•  "[class]": matches any single non-Separator character against a class of characters
•  "{alt1,...}": matches a sequence of characters if one of the comma-separated alternatives matches.

Examples: -e "*/**.lock",  -e "**/node_modules/**", -e "*\**.exe, -e "**\node_modules\**
You can use this command to ignore multiple terms.  For example: debricked files find . -e "**/node_modules/**" -e "**/package-lock.json"

Default: in case you don’t provide this parameter will be set by default to ignore the “node_modules”, "vendor", and “.git”.
 

-b, --branch Optional

Use this parameter to specify the branch to analyze in your project. For example: -–branch main

Default: if you don’t provide this parameter will be set by default to scan all the branches.

-c, --commit  Optional

Use this parameter to specify the commit to analyze in your project. Type -–commit followed by the hash commit. Example: --commit 2609d8385125ddd2d7aa4cfb5be8fcd392e3280a. 

Default: if you don’t provide this parameter, Debricked will scan the last commit. 

 -i, --integration Optional

Use this parameter to specify the name of the integration used to trigger the scan. For example --integration “GitHub Actions”

Default: if you don’t provide this parameter, it will be set to “CLI” by default 

 -p, --pass-on-timeout Optional

Use this parameter to pass scans if there is a service access timeout

-r, --repository Optional

Use this parameter to specify the name of the repository to analyze. For example: --repository EasyApp

 -u, --repository-url  Optional  

Use this parameter to specify the URL address of the repository to analyze. For example:--repository-url  https://github.com/nordisk/myrepository

--resolve Optional 

Use this parameter to resolve manifest files to lock files before the scanning starts. See here for more details about the High Performance Scan.

More examples:

In this example, we analyze all the dependencies files in our current directory. The “.” starts the scanning in the current working directory. 

debricked scan . -t "<token>"

In this example, we are going to scan a project called “EasyApp” in the local directory “~/Desktop/myproject/EasyApp”:

Debricked scan ~/Desktop/myproject/EasyApp --access-token "<token>" --commit "044bdc7c22e46be010969e9360dbe679830100f1" --branch "dev"  --exclusion "**/node_modules/**"

resolve

• debricked resolve [path] [flags]
• debricked resolve –help to see all the options.

The resolve command resolves manifest files to lock files. See here for more details about the High Performance Scan.

Path:

• Use the path argument to specify what manifest file to resolve or what directory to resolve manifest files in. For example: debricked resolve ~/Desktop/Coder-2022/Eccomerce2/ -t <token> or debricked resolve ~/Desktop/Coder-2022/Eccomerce2/pom.xml -t <token>.
   

Flags:

-t --access-token Required

Use this parameter to authenticate. Run -t, or --access-token and enter your access token created in the authentication. Example:  --access-token <token>

-e, --exclusions Optional 

Use this command to exclude files or folders you don't want to be scanned for some reason.  The following terms are supported to exclude paths:

•  "*": matches any sequence of non-Separator characters.
• "/**/": matches zero or multiple directories.

•  "?":  matches any single non-Separator character.
•  "[class]": matches any single non-Separator character against a class of characters
•  "{alt1,...}": matches a sequence of characters if one of the comma-separated alternatives matches.

Examples: -e "*/**.lock",  -e "**/node_modules/**", -e "*\**.exe, -e "**\node_modules\**
You can use this command to ignore multiple terms.  For example: debricked files find . -e "**/node_modules/**" -e "**/package-lock.json"

Default: in case you don’t provide this parameter will be set by default to ignore the “node_modules”, "vendor", and “.git”.

files find

• debricked files find [path] [flags]
• debricked files find –-help to see all the options.

Use this command to search all the dependencies files in your project. 

Path:

• Use the path argument to specify which directory the dependency file is in, or to exclude it. For example: debricked files find ~/Desktop/Coder-2022/Eccomerce2/ -t <token>.
• Use the path to specify where the dependency file is allocated, you can use "." to search the current working directory. For instance: debricked files find .  -t <token> or debricked files find ~/Desktop/Coder-2022/Eccomerce2/ -t <token>.

Note: If the path is inside a git repository, all the necessary flags branch, commit, etc) will be set for you automatically.

Flags:

-l, --lockfile Optional 

Use this parameter to find only the lock files in your project. 

-j, --json Optional                   

Use this parameter to print the file from the path in JSON format. Here’s an example, where we look for all the dependency files in the folder “project7” and print them in JSON format.

debricked files find  ~/Desktop/project7 -t <token> -e "**/node_modules/**" --json

Output:

[
  {
    "manifestFile": "go.mod",
    "lockFiles": [
      ".gomod.debricked.lock"
    ]
  }
]

-s, --strict int

Allows controlling which files are matched:

- 0 (default) - returns all matched manifest and lock files regardless if they're paired or not

- 1 - returns only lock files and pairs of manifest and lock-file

- 2 - returns only pairs of manifest and lock-file

 

report license

Note that this feature is only available for premium users. Visit our Pricing page for more info.

Example:

debricked report license -t "<token>" --commit 044bdc7c22e46be010969e9360dbe679830100f1 --email user1@email.com

Flags

-t --access-token Required

Use this parameter to authenticate.  -t, or --access-token and enter your access token created in the authentication. For example:  --access-token <token>

  -c, --commit Required

Use this parameter to specify the hash commit of the repository to analyze. For example: --commit 2609d8385125ddd2d7aa4cfb5be8fcd392e3280a

  -e, --email Required 

Use this parameter to set the email address to which the report will be sent to.  For example: --email user1@email.com

report vulnerability

Note that this feature is only available for premium users. Visit our Pricing page for more info.

 Example generating a Vulnerability report:

debricked report vulnerability-t "<token>" --commit 044bdc7c22e46be010969e9360dbe679830100f1 --email user1@email.com

Flags:

  -e, --email Required 

Use this parameter to set the email address to which the report will be sent to.  For example: --email user1@email.com

6. Troubleshooting and Error Message

Below you can find the list of some of the most common error messages. If the problem persists and you can’t solve it for yourself or have additional questions feel free to reach contact our support team.

⨯ Unauthorized. Specify access-token. 
Read more at https://debricked.com/docs/administration/access-tokens.html

This error message appears when the access-token is missing or if you provide an invalid access token. For more information, see the `-t -- access-token`  command.

Error: required flag(s) "email" not set

This error message appears when you run the `debricked report vulnerability/license` command without a valid email address. To resolve this, use the `--email, -e` [options] to set an email the report should be sent to. For example: `debricked report license -t “<token>”  –email ”usuario1@gmail.com”`

Error: ⨯ No commit was found with the name

This error message appears when you run the `debricked report vulnerability/license` command but the CLI can’t find the commit. To resolve this, use the `--commit, -c` [options] to provide a commit hash.

For example: `debricked report license -t “<token>”  –email ”usuario1@gmail.com” –commit 044bdc7c22e46be010969e9360dbe679830100f1`

Error: required flag(s) "commit" not set

This error message appears when you run the `debricked report vulnerability/license` command without any commits. To resolve this, use the `--commit, -c` [options] to provide a commit hash.

For example: `debricked report license -t “<token>”  –email ”usuario1@gmail.com” –commit 044bdc7c22e46be010969e9360dbe679830100f1`

Error: invalid directory path specified: "~/Desktop/../../EasyApp"

This error message appears when the scan can't find any valid directory in the path. To resolve it, check if the path provided is correct. 

Error: ⨯ failed to find repository name

This error message appears when the scan can’t find any dependency file in the path. See the languages supported and check if there is a file with the supported format in the path. 

Getting support

If you need help, contact us via our live chat, open Monday-Friday 9 am-5 pm CET, or email support@debricked.com.

Uninstallation

The only thing that is needed to uninstall is to remove the binary - the file called debricked or debricked.exe depending on your operating system.

Create an issue or report a bug

Before creating an issue or reporting a bug, make sure to contact support and discuss the issue or feedback with us first. 

If you want to create an issue or report a bug you can do it directly by submitting an issue via GitHub.

Contributors

If you'd like to contribute directly to the project, check out our guide.  Keep in mind that it might take us some time to answer your questions. For a better experience, we recommend joining our Portal community, where you can learn more about Debricked, improve the way you use open source, and help others.

Feel free to reach out to any of the maintainers or other community members if you have any questions.