Scan Images with twistcli
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.
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]
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.
- Required. URL for Console, including the protocol and port. Only the HTTPS protocol is supported. To get the address for your Console, go toCompute > Manage > System > Utilities, and copy the string underPath 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
- Write the results of the scan to a file in JSON format.Example: --output-file scan-results.json
- Show all vulnerability details.
- Run the scan from inside the container.
- Include the image custom labels in the results.
- Docker daemon listening address (default: unix:///var/run/docker.sock). Can be specified with the DOCKER_CLIENT_ADDRESS environment variable.
- Path to Docker client CA certificate.
- Path to Docker client Client certificate.
- Path to Docker client Client private key.
- Immediately exit the scan if an error is encountered (not supported with the --containerized flag).
- Path to Prisma Cloud CA certificate file. If no CA certificate is specified, the connection to Console is insecure.
- Forces twistcli to use Podman. To use the default installation path, set as podman. Otherwise, provide the appropriate path.
- Evaluates packages listed only in manifests.
- Token to use for Prisma Cloud Console authentication. Tokens can be retrieved from the API endpoint api/v1/authenticate or from theManage > System > Utilitiespage in Console.
- Publishes scan results to the Console (default: --publish=true)
- Boolean flag that specifies the image to scan is a tar archive. The tarball scan requires enhanced privileges, and must be executed as sudo or as a root user. Prisma Cloud supports tar archives in the Docker Image Specification format, v1.1 and later.
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:
./twistcli images scan --tarball --user ted image.tar
./twistcli images scan --tarball image.tar --user ted
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.
To view scan reports in Console, go to
Monitor > Vulnerabilities > Images > CIor
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