This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.


    This doc applies only to the Vulnerability Management engine, released April 20, 2022. Make sure you are using the correct documentation: Which Scanning Engine to Use


    The sysdig-cli-scanner tools allow you to manually scan a container image, either locally or from a remote registry. You can also integrate the sysdig-cli-scanner as part of your CI/CD pipeline or automations to automatically scan any container image right after it is built and before pushing to the registry scanner.

    Development / CI/CD / Pipeline / Shift-Left / …: all of these terms refer to scanning performed on container images that are not (yet) executed in a runtime workload. You can scan these images using the sysdig-cli-scanner tool, and explore the results directly in the console or in the Sysdig UI.

    Optionally, you can create additional pipeline scanning policies and rules.

    The Pipeline section in Sysdig Secure will display the scan results for all images that are scanned using the sysdig-cli-scanner

    For Runtime workloads, see how they are automatically scanned by the Sysdig Runtime Scanner.

    Running the CLI Scanner

    The sysdig-cli-scanner is a binary you can download and execute locally in your computer or environment.

    Scanning Images

    1. Download latest version of sysdig-cli-scanner with:
    • Linux:

      Intel Processor (AMD64)

      curl -LO "$(curl -L -s"

      ARM Processor (ARM64)

      curl -LO "$(curl -L -s"
    • MacOS:

      Intel Processor (AMD64)

      curl -LO "$(curl -L -s"

      Apple Silicon (M1, M2) Processor (ARM64)

      curl -LO "$(curl -L -s"

    Optionally, you can check the sha256sum as:

    • Linux:

      Intel Processor (AMD64)

      sha256sum -c <(curl -sL "$(curl -L -s")

      ARM Processor (ARM64)

      sha256sum -c <(curl -sL "$(curl -L -s")
    • MacOS:

      Intel Processor (AMD64)

      shasum -a 256 -c <(curl -sL "$(curl -L -s")

      Apple Silicon (M1, M2) Processor (ARM64)

      shasum -a 256 -c <(curl -sL "$(curl -L -s")
    1. Set the executable flag on the file:

      chmod +x ./sysdig-cli-scanner

      You only need to download and set executable once. Then:

    2. 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.

    Integrating 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:

    About CI/CD 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.


    Basic usage of the sysdig-cli-scanner:

    sysdig-cli-scanner [OPTIONS] <ImageName>


    SECURE_API_TOKENProvide 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.
    ImageNameThe 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

    REGISTRY_USERProvide the registry username as environment variable REGISTRY_USER.
    REGISTRY_PASSWORDProvide the registry password as environment variable REGISTRY_PASSWORD.



    Additional Parameters

    Use the -h / --help flag to display a list of all available command line parameters:


      sysdig-cli-scanner [OPTIONS] [ImageName]
    Application Options:
      -a, --apiurl=                 Secure API base URL
      -t, --apitimeout=             Secure API timeout (seconds) (default: 120)
          --output-json=            Output path of the scan result report in json format
      -s, --skiptlsverify           Skip TLS certificate verification (default: false)
      -u, --skipupload              Skip the scan results upload (default: false)
      -d, --dbpath=                 Database full path. By default it uses main.db.gz from the same directory
          --policy=                 Identifier of policy to apply
      -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, used if --console-log not passed
          --console-log             Force logs to console, --logfile will be ignored
          --full-vulns-table        Show the entire list of packages found
          --detailed-policies-eval  Show a detailed view of the policies evaluation
      --no-cache config flag				Disable the cache layer during the scan
      --standalone config flag 			Disable communication towards the backend. This implies:  
      															skip upload of the scan-result; offline-analyze; no 
      															policies; no policy remediations; no risk-acceptances; no 
      															download of the mainDB (local path for an existing one 
      															needs to be provided with the dedicated parameter)      
    Help Options:
      -h, --help                    Show this help message
      ImageName:                    Image name

    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 file
    • docker:// - Load the image from the Docker daemon (honoring DOCKER_HOST environment variable or other Docker configuration files)
    • podman:// - Load the image from the Podman daemon
    • pull:// - Force pulling the image from a remote repository (ignoring local images with same name)
    • containerd:// - Load the image from Containerd daemon
    • crio:// - 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 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 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)
      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 Output

    You can use the --output-json=/path/to/file.json to write a JSON report of the scan result

    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.

    Review Pipeline Scans in the UI

    You can explore the details for every image that has been scanned by executing the sysdig-cli-scanner in Sysdig Secure UI.

    1. Navigate to Vulnerabilities > Pipeline.

    2. Filter the list by Pass | Fail if desired.

      • The Policy Evaluation column reflects the policy state at evaluation time for that image and the assigned policies
        • Failed: If any of the policies used to evaluate the image is failing, the image is considered “Failed”
        • Passed If there is no violation of any of the rules contained in any of the policies, the image is considered “Passed”

    From here you can drill down to the scan result details.

    Drill into Scan Result Details

    Select a result from the Pipeline list to see the details, parsed in different ways depending on your needs.

    Overview Tab

    Focuses on the package view and filters for those that are fixable. Clickable cells lead into the Vulnerabilities list (next).

    Vulnerabilities Tab

    Expanded filters and clickable list of CVEs that open the full CVE details, including source data and fix information.

    The same security finding (e.g. a particular vulnerability) can be present in more than one rule violation table if it happens to violate several rules.

    Content Tab

    Also organized by package view, with expanded filters and clickable CVE cells.

    Policies Tab

    Shows CVEs organized by the policy+rule that failed. Use the toggle to show or hide policies+rules that passed. Click CVE names for the details.

    Filter and Sort Results

    Within the Pipeline results tabs, there are ways to further refine your view:

    • Search by keyword or CVE name
    • Use filters: Severity (>=); CVSS Score (>=); Vuln Type; Has Fix; Exploitable.

    Accept Risk: Pipeline

    As of November, 2022, users can choose to accept the risk of a detected vulnerability or asset. The process for handling Accepted Risk is the same for Pipeline as for Runtime.

    Use the Runtime instructions, with the following difference:

    Accept Validity - Pipeline

    The pipeline scan results are point-in-time, so there is no automatic re-evaluation.

    To trigger a new evaluation containing the accept:

    • You must execute the pipeline process again over the same image
    • The N+1 scan will contain the accept