Install Vulnerability CLI Scanner
sysdig-cli-scanner
) is a tool that allows manual scanning of container images, locally or remotely. It can be integrated into CI/CD pipelines to automatically scan images before pushing them to a registry.This scanning is done before runtime and the results are displayed in the terminal or on the Vulnerabilities > Pipeline UI of Sysdig Secure. You can also create additional pipeline scanning policies and rules.
The sysdig-cli-scanner has a rate limit of 20 container images per minute.
Deployment
The sysdig-cli-scanner
is a binary you can download and execute locally on your computer or environment.
- Download latest version of
sysdig-cli-scanner
with:
Linux:
Intel Processor (AMD64)
curl -LO "https://download.sysdig.com/scanning/bin/sysdig-cli-scanner/$(curl -L -s https://download.sysdig.com/scanning/sysdig-cli-scanner/latest_version.txt)/linux/amd64/sysdig-cli-scanner"
ARM Processor (ARM64)
curl -LO "https://download.sysdig.com/scanning/bin/sysdig-cli-scanner/$(curl -L -s https://download.sysdig.com/scanning/sysdig-cli-scanner/latest_version.txt)/linux/arm64/sysdig-cli-scanner"
MacOS:
Intel Processor (AMD64)
curl -LO "https://download.sysdig.com/scanning/bin/sysdig-cli-scanner/$(curl -L -s https://download.sysdig.com/scanning/sysdig-cli-scanner/latest_version.txt)/darwin/amd64/sysdig-cli-scanner"
Apple Silicon (M1, M2) Processor (ARM64)
curl -LO "https://download.sysdig.com/scanning/bin/sysdig-cli-scanner/$(curl -L -s https://download.sysdig.com/scanning/sysdig-cli-scanner/latest_version.txt)/darwin/arm64/sysdig-cli-scanner"
Optionally, you can check the sha256sum
as:
Linux:
Intel Processor (AMD64)
sha256sum -c <(curl -sL "https://download.sysdig.com/scanning/bin/sysdig-cli-scanner/$(curl -L -s https://download.sysdig.com/scanning/sysdig-cli-scanner/latest_version.txt)/linux/amd64/sysdig-cli-scanner.sha256")
ARM Processor (ARM64)
sha256sum -c <(curl -sL "https://download.sysdig.com/scanning/bin/sysdig-cli-scanner/$(curl -L -s https://download.sysdig.com/scanning/sysdig-cli-scanner/latest_version.txt)/linux/arm64/sysdig-cli-scanner.sha256")
MacOS:
Intel Processor (AMD64)
shasum -a 256 -c <(curl -sL "https://download.sysdig.com/scanning/bin/sysdig-cli-scanner/$(curl -L -s https://download.sysdig.com/scanning/sysdig-cli-scanner/latest_version.txt)/darwin/amd64/sysdig-cli-scanner.sha256")
Apple Silicon (M1, M2) Processor (ARM64)
shasum -a 256 -c <(curl -sL "https://download.sysdig.com/scanning/bin/sysdig-cli-scanner/$(curl -L -s https://download.sysdig.com/scanning/sysdig-cli-scanner/latest_version.txt)/darwin/arm64/sysdig-cli-scanner.sha256")
Set the executable flag on the file:
chmod +x ./sysdig-cli-scanner
You only need to download and set executable once. Then:
You can scan images by running the
sysdig-cli-scanner
command:SECURE_API_TOKEN=<your-api-token> ./sysdig-cli-scanner --apiurl <sysdig-api-url> <image-name>
See Parameters for more detail.
Integrate in your CI/CD Pipelines
The sysdig-cli-scanner
can be included as a step in your CI/CD pipelines (i.e. Jenkins, Github actions or others) 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:
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
Option | Description |
---|---|
SECURE_API_TOKEN | Provide the API token as environment variable SECURE_API_TOKEN . You can retrieve this from Settings > User Profile in Sysdig Secure. |
--apiurl=<endpoint> | Sysdig Secure Endpoint. In SaaS, this value is region-dependent and is auto-completed on the Get Started page in the UI. |
ImageName | The image that you want to scan. For example mongo-express:0.54.0 . |
- 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
Option | Description |
---|---|
REGISTRY_USER | Provide the registry username as environment variable REGISTRY_USER . |
REGISTRY_PASSWORD | Provide the registry password as environment variable REGISTRY_PASSWORD . |
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}
Additional Parameters
To display a list of all available command line parameters:
-h, --help Show this help message
Example output:
Usage:
sysdig-cli-scanner [OPTIONS] [ImageName]
Application Options:
-a, --apiurl= Secure API base URL
-t, --apitimeout= Secure API timeout (seconds) (default: 120)
-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= Output path of the scan result report in json format
--json-scan-result= Output path of the scan result report in the new json format
--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
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:
0 - image passed policy evaluation
1 - image failed policy evaluation
2 - incorrect parameters (i.e. no API token)
3 - other execution errors
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:
file://
- Load the image from a .tar filedocker://
- Load the image from the Docker daemon (honoringDOCKER_HOST
environment variable or other Docker configuration files)podman://
- Load the image from the Podman daemonpull://
- Force pulling the image from a remote repository (ignoring local images with same name)containerd://
- Load the image from Containerd daemoncrio://
- Load the image from Containers Storage location
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.
JSON Report Output
This feature is in Technical Preview status.
You can use the --output-json=/path/to/file.json
to write a JSON report of the scan result
Scan Logs (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.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.