GuardRails CLI Usage Guide

💻 GuardRails CLI Usage Guide

Pre-Requisites
Installation
Usage
CI/CD Integration

Pre-Requisites

To use the GuardRails CLI, you need to have a GuardRails account and obtained a token.

More information on how to get started can be found here.

Once you've setup your GuardRails account, the CLI token can be obtained from dashboard → settings → CLI Authentication.

Installation

There are multiple ways to install the CLI depending on your platform.

For Linux / OSX, you can use our installation script or Brew:

curl -fsSL https://raw.githubusercontent.com/guardrailsio/guardrails-cli/main/etc/scripts/install.sh | bash

brew tap guardrailsio/guardrails
brew install guardrails

For Windows, you will need scoop and you can run our installation script via powershell:

iex ((new-object net.webclient).DownloadString('https://raw.githubusercontent.com/guardrailsio/guardrails-cli/main/etc/scripts/install.ps1'))

You can also directly download the latest binary for your platform from our releases.

For more information on installation methods, please refer to the Installation section of the repository's readme.

Authentication

To authenticate you can pass the --token option to the scan command, or you can set the GUARDRAILS_CLI_TOKEN environment variable.

GUARDRAILS_CLI_TOKEN if set, will be used as token when --token is not provided

guardrails scan --token <token>

export GUARDRAILS_CLI_TOKEN=<token>
guardrails scan

GUARDRAILS_CLI_TOKEN=<token> guardrails scan

Scan

To scan a repository in the current directory, simply run the scan command.

guardrails scan

To scan a repository in a different directory, you can use the --path option.

guardrails scan --path /www/hello-world

To output results in a different format, you can use the --format option.

guardrails scan --format json
guardrails scan --format csv
guardrails scan --format sarif

To save the output to a file, you can use the --output option.

guardrails scan --format json --output /www/hello-world/scan.json

To remove all additional information printed out by the CLI and only output in --format and nothing else, you can use the --quiet option. This can be useful to parse the output in json for example.

guardrails scan --format json --quiet

Reading the results

Let's look at the case for no vulnerabilities detected:

guardrails scan --path ~/www/awesome-project

👀 scanning /Users/john/www/awesome-project ✔️

Project name: awesome-project
Git provider: github
Format: pretty (default)
Output: stdout

📚 compressing awesome-project ✔️

📦 uploading awesome-project.tar.gz ✔️

🔎 scan started, waiting for results of awesome-project ✔️

✔️  No issues detected, well done!

View the detailed report in the dashboard
https://dashboard.guardrails.io/gh/org/repos/1/scans?sha=3be...&type=CLI

Well done! Not much to do here, but you can always follow the link at the end to see the scan on the dashboard.

Now, let's look at the case when vulnerabilities are detected:

guardrails scan --path ~/www/awesome-project


👀 scanning /Users/null/www/awesome-project ✔️

Project name: awesome-project
Git provider: github
Format: pretty (default)
Output: stdout

📚 compressing awesome-project ✔️

📦 uploading awesome-project.tar.gz ✔️

🔎 scan started, waiting for results of awesome-project ✔️

⚠️  We detected 3 security issues

Vulnerable Libraries (2)
● (C) [email protected] - package.json:49
● (M) [email protected] - package-lock.json:29353

Hard-Coded Secrets (1)
● (M) Hard-coded Secret - awesome-project/config.js:2


View the detailed report in the dashboard
https://dashboard.guardrails.io/gh/org/repos/1/scans?sha=ec3...&type=CLI

Whoops! Alright no panic, what happened here?

The CLI outputs the total number of detected vulnerabilities, 3 here. Vulnerabilities are grouped by category, like Hard-Coded Secrets.

For each item within a category, the following information is shown:

A severity index (see table below)
The type of vulnerability containing a hyperlink to a fixing advice in our documentation
The file path and line number

Example: (M) Hard-coded Secret - awesome-project/config.js:2

Here we're looking at a vulnerability of type Hard-coded secret with a Medium severity in the file awesome-project/config.js at line 2.

For Vulnerable Libraries specifically, the type of vulnerability will be replaced by the dependency name and version.

Example: (C) [email protected] - package.json:49

Here we're looking at the vulnerable my-package dependency in version 2.5.2 with a Critical severity declared in the file awesome-product/package.json at line 49.

Again, for more information you can always follow the link at the end to see the full scan on the dashboard.

Severity index table

Index	Severity
(N/A)	Not available
(I)	Informational
(L)	Low
(M)	Medium
(H)	High
(C)	Critical

For more information on reading the results, please refer to the How to read the results section of the repository's readme.

Exit codes

The CLI currently returns 3 different exit codes:

0 - No vulnerabilities reported
1 - Vulnerabilities reported
99 - Failure

On-premise

For the CLI to work with on-premise deployments, you can set the GUARDRAILS_API_HOST environment variable.

GUARDRAILS_API_HOST if set, will replace the API host (defaults to https://api.guardrails.io)

Examples:

export GUARDRAILS_API_HOST=https://guardrails-onpremise.io:1444
guardrails scan

GUARDRAILS_API_HOST=https://guardrails-onpremise.io:1444 guardrails scan

Version

You can run guardrails version to view your current CLI build version.

guardrails version
v0.2.0

Help

You can run guardrails help to view all commands and options available.

guardrails help

  ____                     _ ____       _ _        ____ _     ___
 / ___|_   _  __ _ _ __ __| |  _ \ __ _(_) |___   / ___| |   |_ _|
| |  _| | | |/ _' | '__/ _' | |_) / _' | | / __| | |   | |    | |
| |_| | |_| | (_| | | | (_| |  _ < (_| | | \__ \ | |___| |___ | |
 \____|\__,_|\__,_|_|  \__,_|_| \_\__,_|_|_|___/  \____|_____|___|

Usage: guardrails <command> [<args>]

Commands:
  scan [-t,--token=<token>][-p,--path=<path>][-f,--format=json,csv,sarif,pretty]
       [-o,--output=<path>][-q,--quiet]
  version
  help

scan: scans a repository for vulnerabilities and outputs results
  -t, --token  a valid GuardRails CLI token you can obtain from dashboard -> settings
  -p, --path   the path to the repository to scan, defaults to $PWD
  -f, --format the output format for scan results, defaults to pretty
  -o, --output if provided, will save the output to the specified file path
  -q, --quiet  if provided, will only output scan results in --format and nothing else

version: displays build version

help: displays this help menu

Environment variables:
GUARDRAILS_CLI_TOKEN  if set, will be used as token when --token is not provided
GUARDRAILS_API_HOST   if set, will replace the API host (defaults to https://api.guardrails.io)

CI/CD Integration

You can easily embed GuardRails in any CI/CD pipeline. An example scan step in the gitlab-ci.yml:

guardrails-scan:
  stage: test
  script:
    - git checkout -B "$CI_BUILD_REF_NAME"
    - curl -fsSL https://raw.githubusercontent.com/guardrailsio/guardrails-cli/main/etc/scripts/install.sh | bash
    - export GUARDRAILS_CLI_TOKEN=$GUARDRAILS_CLI_TOKEN
    - guardrails scan

Table of Contents​

Pre-Requisites​

Installation​

Usage​

Authentication​

Scan​

Reading the results​

Severity index table​

Exit codes​

On-premise​

Version​

Help​

CI/CD Integration​

Table of Contents