Getting Started with Canvass for Security (CFS)

Quickly become familiar with Canvass for Security.


Canvass for Security (CFS) is client/server based, so users need a Canvass Labs account to submit a job.

In addition, the Canvass for Security client will need to be downloaded and installed.

CFS relies on the OSS Review Toolkit (ORT) to read declared software dependency information from common package managers. Thus, ORT will need to be downloaded and installed.

Submitting a Job

Canvass For Security works with ORT Analyzer to find known vulnerabilities in your source code. The results of ORT analyze commands are used to capture the versions of dependencies used in your code.

The ORT analyze command that produces the YAML results file should run in production environment for accurate results, but the CFS client does not need to run in production environment.

Once the ORT analyze result has been generated for a source project, the CFS client can be run from any directory to generate a vulnerability report for that project.

CanvassForSecurity scan /path/to/analyzer/result/file.yml

Upon successful submission of a job, CFS should respond with a job number:

Your job number is: 1

Retrieving Results

The get command is used to download the results of CFS jobs given the job ID returned when a job is submitted. If get is called from the command line, then the results for that job will be downloaded automatically to the current directory. If get is otherwise called in interactive mode, then you will be prompted to download the results to the current directory.

CanvassForSecurity> get 25

NUM     STATUS          POSTED TIME             PKGS    RUN TIME        USER
25      Completed+      2021-07-08 14:49:51     5.24 seconds
Get completed jobs? (Y/y/N/n):
Results for job 25 are located in folder '60e772ff760b58d89f09fb62'

If no job IDs are provided, then the job ID of the most recently submitted job will be used. If a job is still in progress, then the command will instead list its status.

Possible job statuses include: New, Processing, Completed, Completed+, Aborted, Requeued, and Failed. (Completed means "completed with issues" while Completed+ means "completed successfully"). For more details, visit the CFS Documentation Page.

Canvass Labs will email you every time the status of a CFS job is changed. You can also use the list command to check on the status of all of your CFS jobs.

  CanvassForSecurity> list

  NUM     STATUS          POSTED TIME             RUN TIME        USER
  25      Completed+      2021-07-08 14:49:51     5.24 seconds
  24      Completed+      2021-07-07 22:19:55     6.55 seconds
  23      Completed+      2021-07-07 22:17:19     6.56 seconds
  22      Aborted         2021-07-07 22:15:34     N/A   
  21      Aborted         2021-07-07 21:41:52     N/A   
  20      Completed+      2021-07-07 21:16:08     6.64 seconds
  19      Completed+      2021-07-07 20:51:10     7.92 seconds
  18      Completed+      2021-07-07 20:38:02     6.98 seconds
  17      Completed+      2021-07-07 17:54:06     8.04 seconds
  16      Completed+      2021-07-07 08:10:07     7.52 seconds
  15      Completed+      2021-07-06 22:00:59     7.25 seconds
  14      Completed+      2021-07-06 21:48:49     6.88 seconds
  13      Completed+      2021-07-06 21:33:01     3.78 seconds
  12      Completed+      2021-07-06 21:23:13     3.78 seconds
  11      Completed+      2021-07-06 21:15:16     3.72 seconds
  10      Completed+      2021-07-06 21:06:09     3.79 seconds
  Press 'Q' to quit, or another key to continue...

A completed job can also be retrieved from the download URL provided by the corresponding completion email.

Completion Email

Job Result Details

Job results are stored in a tar.gz file. On Linux and MacOS, the file can be opened using your operating system’s built-in file decompression GUI menu options, or via the command line using the command tar zxvf my_file.tar.gz. Window 10 users may need to download a file archiver to open this file.

The CFS report is provided in HTML format, in a file called vulnerability_report.html.