Scan images with twistcli
Prisma Cloud ships a command-line scanner for scanning container images and serverless functions. It is supported on Linux, macOS, and Windows.
The twistcli command has several subcommands. Use the twistcli images scan subcommand to invoke the scanner.
When users from a tenant project run twistcli, they must set the --project option to specify the proper context for the command.
twistcli images scan — Scan an image for vulnerabilities and compliance issues. The image must reside on the system where twistcli runs. If not, retrieve the image with docker pull before scanning it. Twistcli does not pull images for you.
The twistcli images scan function collects information about the packages and binaries in the container image, and then sends it to Console for analysis.
Data collected by twistcli includes:
- Packages in the image.
- Files installed by each package.
- Hashes for files in the image.
After Console analyzes the image for vulnerabilities, twistcli:
- Outputs a summary report.
- Exits with a pass or fail return value.
When invoking twistcli, the last parameter should be the image to scan. If you list options after the image, they will be ignored.
- Complete URL for Console, including the protocol and port. Only the HTTPS protocol is supported. By default, Console listens to HTTPS on port 8083, although your administrator can configure Console to listen on a different port. Defaults to https://127.0.0.1:8083.Example: --address https://console.example.com:8083
- Username to access Console. If not provided, the TWISTLOCK_USER environment variable will be used if defined, or "admin" is used as the default.
- Password for the user specified with -u, --user. If not specified on the command-line, the TWISTLOCK_PASSWORD environment variable will be used if defined, or otherwise will prompt for the user’s password before the scan runs.
- Interface with a specific supervisor Console to retrieve policy and publish results.Example: --project "Tenant Console"
- 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.
- 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: true)
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 two 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 API section.