1. Home
    2. Prisma
    3. Prisma Cloud
    4. Prisma Cloud Administrator’s Guide (Compute)
    5. Tools
    6. Scan Images with twistcli

    Scan Images with twistcli

    You can use the Prisma Cloud twistcli command-line tool to scan container images and serverless functions. Scanning with twistcli is supported on Linux, macOS, and Windows.

    Command

    The twistcli command-line tool has several subcommands. To scan, use the following subcommand.
    twistcli images scan
    The command scans an image for vulnerabilities and compliance issues. The image must be on the system running the twistcli command-line tool. If not and if you are using Docker, you can retrieve the image with the docker pull before scanning it. The twistcli tool does not pull images.

    Syntax

    When using twistcli images scan, the image or tarball to scan must be the last parameter. If you specify options after the image or tarball, they are ignored. If scanning a tarball, use the --tarball option.
    twistcli images scan [OPTIONS] [IMAGE]

    Description

    The twistcli images scan tool collects information about the packages and binaries in the container image, and sends the information to the Prisma Cloud Console for analysis.
    The twistcli tool collects data including the following items.
    • Packages in the image.
    • Files installed by each package.
    • Hashes for files in the image.
    After the Prisma Cloud Console analyzes the image for vulnerabilities, twistcli performs the following tasks.
    • Outputs a summary report.
    • Exits with a pass or fail return value.
    To specify an image to scan, use either the image ID, or repository name and tag. If you are using Windows with containerd, provide a full image ID because short IDs aren’t supported. Get the full image ID using the following command.
    ctr -n <namespace> images ls
    The image should be present on the system, having either been built or pulled there. If a repository is specified without a tag, twistcli looks for an image tagged latest.

    Options

    • Required. URL for Console, including the protocol and port. Only the HTTPS protocol is supported. To get the address for your Console, go to
      Compute > Manage > System > Utilities
      , and copy the string under
      Path to Console
      .
      Example: --address https://us-west1.cloud.twistlock.com/us-3-123456789
    • Access Key ID to access Prisma Cloud. If not provided, the TWISTLOCK_USER environment variable is used, if defined. Othewise, "admin" is used as the default.
    • Secret Key for the above Access Key ID specified with -u, --user. If not specified on the command-line, the TWISTLOCK_PASSWORD environment variable is used, if defined. Otherwise, you will be prompted for the user’s password before the scan runs.
    Access Key ID and Secret Key are generated from the Prisma Cloud user interface. For more information, see access keys
    The tarball option is supported on Linux only; macOS and Windows versions of twistcli do not support it.
    The last parameter in the twistcli command should always be the path to the tarball. The --tarball option is simply a boolean flag. It doesn’t accept a corresponding value (e.g. a path to a tarball). For clarity, see the following examples:
    Correct usage:
      ./twistcli images scan --tarball --user ted image.tar
    Incorrect usage:
      ./twistcli images scan --tarball image.tar --user ted

    Return value

    The exit code is 0 if twistcli images scan finds no vulnerabilities or compliance issues. Otherwise, the exit code is 1.
    The criteria for passing or failing a scan is determined by the CI vulnerability and compliance policies set in Console. The default CI vulnerability policy alerts on all CVEs detected. The default CI compliance policy alerts on all critical and high compliance issues.
    There are a couple of reasons why twistcli images scan might return an exit code of 1.
    • The scan failed because the scanner found issues that violate your CI policy.
    • Twistcli failed to run due to an error.
    Although the return value is ambiguous — you cannot determine the exact reason for the failure by just examining the return value — this setup supports automation. From an automation process perspective, you expect that the entire flow will work. If you scan an image, with or without a threshold, either it works or it does not work. If it fails, for whatever reason, you want to fail everything because there is a problem.

    Scan Results

    To view scan reports in Console, go to
    Monitor > Vulnerabilities > Images > CI
     or
    Monitor > Compliance > Images > CI
    .
    The scan reports includes the image vulnerabilities, compliance issues, layers, process info, package info, and labels.
    When scanning images in the CI pipeline with twistcli or the Jenkins plugin, Prisma Cloud collects the environment variable JOB_NAME from the machine the scan ran on, and adds it as a label to the scan report.
    You can also retrieve scan reports in JSON format using the Prisma Cloud API, see the