Run Sysdig CLI Scanner in VM Mode

Prerequisites

• Ensure that you have the role-based access control (RBAC) CLI execution permission to use the CLI VM Scanner. See Detailed Role Permissions.

Integrate in your CI/CD Pipelines

The sysdig-cli-scanner can be included as a step in your CI/CD pipelines, such as Jenkins and Github actions simply by running the sysdig-cli-scanner command as part of your pipeline.

• Make sure that the sysdig-cli-scanner binary is available as part of the worker or runner where the pipeline is executing.
  • If you are running an ephemeral environment in the pipeline, include the download and set executable steps in your pipeline to download the tool on every execution.
• Define a secret containing the API-Token and make it available in the pipeline (i.e. via a SECURE_API_TOKEN environment variable).
• Include a step in your pipeline to run the sysdig-cli-scanner after building the container image, and providing the image name as paremeter. For example:

./sysdig-cli-scanner --apiurl <sysdig-api-url> ${IMAGE_NAME}

See some examples on how to use it on different CI/CD pipelines:

• AWS CodeBuild
• Azure Pipelines
• GitHub
• GitLab
• Jenkins

Integrating Vulnerability Policies

Policies allow you to define a set of rules that will evaluate each scan result. After the evaluation, each policy will pass or fail. A policy failure or non-compliance happens if the scan result doesn’t meet all the rules in a policy.

For CI/CD and manual image scans, you can tell the sysdig-cli-scanner tool to explicitly evaluate one or more policies using the --policy= policy1,policy2,... flag and provide a comma-separated list of policy IDs.

CI/CD policies can be configured as Always apply. If a policy has the Always apply flag, it will be evaluated on every scanned image even if you don’t specify it explicitly.

Learn more about Vulnerability Management policies, the available rules, and how to define policies in Vulnerability Policies.

Parameters

Basic usage of the sysdig-cli-scanner:

sysdig-cli-scanner [OPTIONS] <ImageName>

Required

• The Sysdig CLI scanner will try to find a local image in Docker, ContainerD or other container runtimes, or try to pull if from the remote registry.
• Once the scan is complete, you will see the results directly in the console, and they will be available in the Pipeline section of the UI.

Registry Credentials

Registry credentials can be supplied via the following environment variables

Example

REGISTRY_USER=<YOUR_REGISTRY_USERNAME> REGISTRY_PASSWORD=<YOUR_REGISTRY_PASSWORD> SECURE_API_TOKEN=<YOUR_API_TOKEN> ./sysdig-cli-scanner --apiurl https://secure.sysdig.com ${REPO_NAME}/${IMAGE_NAME}

Display Image Layers

Additional Parameters

Usage:
  sysdig-cli-scanner [OPTIONS] [ImageName]

Application Options:
      --iac                     Execute IaC scan. Use --iac -h for help about IaC commands
  -a, --apiurl=                 Secure API base URL
  -n, --standalone              Do not depend on Sysdig backend for execution, avoiding the need of specifying --apiurl and SECURE_API_TOKEN. Implies activating all flags
                                marked with [standalone mode] (default: false)
      --no-cache                Do not use any cache throughout the scan; other cache-related parameters will be ignored (default: false)
      --offline-analyzer        [standalone mode] The analyzer does not perform backend calls (default: false)
      --override-pullstring=    Specify a custom image name that will be displayed on the Sysdig UI
      --output-json=            DEPRECATED (use --output=json-file=<destination> --output-schema=legacy) - Output path of the scan result report in json format
      --json-scan-result=       DEPRECATED (use --output=json-file=<destination> --output-schema=v1beta3) - Output file of the json scan result in the new format in technical preview (breaking changes are possible)
      --output=                 Output format. One of [json,json-file=<destination_path>]
      --output-schema=          Schema of the output file. One of [legacy,v1beta2, v1beta3, v1]. To be used in conjunction with --output=<json,json-file> (default: v1)
      --policy=                 Identifier of policy to apply
  -d, --dbpath=                 Database directory absolute path. PLEASE NOTE THAT FILES IN THIS DIRECTORY COULD BE WIPED OUT. Defaults to {executablePath}/main.db
  -p, --cachepath=              Cache path
  -c, --clearcache              Clear the cache before to run (default: false)
  -l, --loglevel=               Log level (default: info)
  -o, --logfile=                File destination for logs, mutually exclusive with --console-log
      --console-log             Force logs to console, mutually exclusive with --logfile
  -s, --skiptlsverify           Skip TLS certificate verification (default: false)
  -u, --skipupload              [standalone mode] Do not upload the scan results (default: false)
      --skip-get-database       [standalone mode] Do not download DB even if obsolete or corrupted (default: false)
      --full-vulns-table        Show the entire list of packages found
      --detailed-policies-eval  Show a detailed view of the policies evaluation
      --version                 Show the version and exit
      --separate-by-image       Show detailed layer information separating packages by base image, mutually exclusive with --separate-by-layer
      --separate-by-layer       Show detailed layer information separating packages by layer, mutually exclusive with --separate-by-image

Help Options:
  -h, --help                    Show this help message

Arguments:
  ImageName:                    Image name

Exit Codes:
  0: Scan evaluation "pass"
  1: Scan evaluation "fail"
  2: Invalid parameters
  3: Internal error

CLI Scanner Exit Codes

Access the container exit codes with -h

The codes are:

Use the exit code, for example, to decide whether to abort the CI/CD pipeline.

Image Sources

The Sysdig CLI scanner can load images from different sources. By default, it will try to automatically find the provided image name from all supported sources, in the order specified by the following list. However, you can explicitly select the image source by using the corresponding prefix for the image name:

i.e. pull the image from remote registry even if it is locally available:

./sysdig-cli-scanner -a https://secure.sysdig.com pull://nginx:latest

Sample Result in Terminal

It is possible to view scan results in the terminal window (see below)

$ SECURE_API_TOKEN=<YOUR_API_TOKEN> ./sysdig-cli-scanner --apiurl https://secure.sysdig.com redis

Type: dockerImage
ImageID: sha256:7614ae9453d1d87e740a2056257a6de7135c84037c367e1fffa92ae922784631
Digest: redis@sha256:db485f2e245b5b3329fdc7eff4eb00f913e09d8feb9ca720788059fdc2ed8339
BaseOS: debian 11.2
PullString: pull:*//redis*

66 vulnerabilities found
8 Critical (0 fixable)
2 High (0 fixable)
4 Medium (0 fixable)
5 Low (0 fixable)
47 Negligible (0 fixable)

  POLICIES EVALUATION
  Policy: Sysdig Best Practices FAILED (9 failures)`

You can use --full-vulns-table or --detailed-policies-eval flags to include further details in the output.

For a more user-friendly scan result, find the image in the UI.

Scan Logs for Troubleshooting

The sysdig-cli-scanner automatically writes a log file on every execution. You can change the output path using -o or --logfile flags. For troubleshooting purposes, you can change the log level by setting --loglevel=debug. This will increase the verbosity of the log messages to the debug level.

Next Steps

Review the scan results in the Vulnerabilities > Pipeline UI.