Debricked CLI

We provide a Command Line Tool (CLI) for interacting with Debricked. It supports uploading and checking your dependency files for vulnerabilities from your console. This could be useful when you want to check whether your dependency files are vulnerable before uploading them to your repository or in a custom CI pipeline. This tool also powers some of our integrations, such as the Bitbucket “pipe” integration. Our tool is available here (opens new window).

You can chose to install the CLI tool locally, or by using Docker.

Local installation

• PHP is required, run php -v on your system to see if it is installed or not. If it is not installed, refer to your favourite package manager or, if you are on Windows, installthe - latest version available on PHP for Windows (opens new window).
• Install the CLI tool
• Install using composer (opens new window) (recommended, omit global if you want to install into current project) composer global require debricked/cli, or
• Download it manually from GitHub (opens new window)
• [Windows only] In order to be able to run the first time setup, cd to your installation directory such as cd ~/AppData/Roaming/Composer/vendor/debricked/cli, and then execute bin/console debricked:scan --help
• Done! You can now run any of the available commands using php ~/.composer/vendor/debricked/cli/bin/console *command*. If you using Windows it will be available at php ~/- AppDataRoaming/Composer/vendor/debricked/cli/bin/console *command*

Additional note when running on Windows

If you are on Windows, make sure to execute the commands using a bash script (.sh) compatible shell. If you do not have a bash script compatible shell installed already, we recommend the one bundled with Git for windows called “Git Bash”.

Available commands

All commands have a help command available listing possible arguments and options by passing the flag “help”, for example:

php bin/console debricked:scan --help

All-in-one vulnerability scan

Combines uploading dependency files with monitoring their vulnerability status.

php bin/console debricked:scan *username* *password* *product_name* *release_name* *repository url* cli

Example:

php bin/console debricked:scan user1@email.com pass1 myproduct 1.0.1 local cli

Using an access token instead of username and password

Replace the username with '' and use the access token as the password. This can be done for all examples below as well.

Example:

php bin/console debricked:scan '' your-access-token myproduct 1.0.1 local cli

Upload dependency files and trigger a vulnerability scan

php bin/console debricked:find-and-upload-files *username* *password* *product_name* *release_name* *repository url* cli

Check vulnerability scan

php bin/console debricked:check-scan *username* *password* *upload_id*

License report

To generate a license report, you first need to perform a regular vulnerability scan using either the CLI as above, or by using one of our CI/Build systems. After performing a scan, you get an upload id, for the example below, the upload id is 1443821.

After finding the upload id, you also need to decide which license risk profile that is most suitable for your project. The chosen risk profile will affect the risk assessment for licenses found in your dependencies. The available risk profiles are:

• internal: Non-distributed application, used only internally within e.g. a company
• network: Non-distributed application, but publicly available as a network service, e.g. a web service
• distributed: Distributed application, running in a generic environment such as Windows, macOS or Linux
• consumer-electronic: Distribued application running on devices that can be classified as consumer electronics

After this, run the following command to generate the license report.

php bin/console debricked:license-report *username* *password* *upload_id* *risk_profile*

By default, the output is written directly to the terminal formatted as JSON. If you prefer a CSV format, you can add the flag -f csv. Additionally, if you prefer to have the license report exported to a file, instead of printed to the terminal, add the flag -o file.json or -o file.csv.

Example:

php bin/console debricked:license-report user1@email.com pass1 1443821 distributed -f csv -o myreport.csv

Code snippet analysis

As an additional feature, not included in the default subscription, you can also perform code snippet analysis. This feature allows you to detect code snippets that have been copied into your own application's source code from other projects, and the licenses that these code snippets have. To enable code snippet analysis, first contact Debricked Sales. After this, you can generate reports using the additional -s / --snippets flag to the license report command above.

Using Docker

To run the tool using only Docker, instead of a local install, use it as below, where the current directory is assumed to contain the project you wish to scan.

docker run -it --rm -v $PWD:/data debricked/debricked-cli <command>

A practical example of scanning a local repository in your current working directory:

docker run -it --rm -v $PWD:/data debricked/debricked-cli debricked:scan user@example.com password myrepository mycommit null cli

To be clear, you need to modify these parts of the command:

• user@example.com and password: Replace with your e-mail and password to the service. Alternatively, use an access token as password, and set the username to the empty string ''.
• myrepository: Replace with the name of the repository.
• mycommit: A unique identifier (for example the commit hash in Git) for this particular commit.

You do not need to replace null cli. It is simply a marker used by the server to distinguish between different integrations.

If you are building your CI pipeline integration, you can typically get myrepository and mycommit as environmental variables from you CI system.

If you use languages that need a copy of the whole repository

In most cases, such as above, the tool only needs to upload your dependency files to the service. However, for certain languages, you may need to upload a complete copy of the repository. You then need to add the --upload-all-files=true to the command, such as in the following example.

docker run -it --rm -v $PWD:/data debricked/debricked-cli debricked:scan --upload-all-files=true user@example.com password myrepository mycommit null cli

Source-codeless scans

For Maven and Gradle builds, that normally require a complete copy of the source code, an alternative solution can be used as well. This requires you to generate certain dependency tree artifacts locally, and then submit them to Debricked. By doing so, you can avoid submitting a complete copy of the repository to Debricked, while still getting optimal dependency results. However, this requires you to perform certain steps as a part of your pipeline.

To learn more, visit our documentation about source-codeless scans to get further instructions.

If you have an on-premise solution

For customers with a deployed on-premise solution, you also need to modify the destination server. You can do this by setting the DEBRICKED_API_URI environment variable to your own server, as in the example command below:

docker run -it --rm -e DEBRICKED_API_URI=https://your.on.prem.server -v $PWD:/data debricked/debricked-cli debricked:scan user@example.com password myrepository mycommit null cli