CI/CD CLI v1.4
Integrating the Panoptica CI/CD CLI tool into the development workflow enables you to scan container images for potential security vulnerabilities. Panoptica CI/CD CLI tool can detect and block security issues pre-production, before they are merged into the main codebase and deployed to production environment.
Version 1.4 of Panoptica's CI/CD CLI adds the ability to specify a region (US or EU) and enhanced error handling.
In order to view scan results in the Panoptica console UI, you need an API Key. See CI/CD CLI Tool for instructions on generating a Panoptica API Key and promoting its role to an Ops user.
Installation
To download the Panoptica CI/CD CLI tool, and configure permissions, select the tab that matches your OS and platform architecture, and run the relevant command:
curl -O https://download.panoptica.app/panoptica-cicd/1.4.0/artifacts/darwin-amd64/panoptica-cicd && chmod +x ./panoptica-cicd
curl -O https://download.panoptica.app/panoptica-cicd/1.4.0/artifacts/darwin-arm64/panoptica-cicd && chmod +x ./panoptica-cicd
curl -O https://download.panoptica.app/panoptica-cicd/1.4.0/artifacts/linux-amd64/panoptica-cicd && chmod +x ./panoptica-cicd
curl -O https://download.panoptica.app/panoptica-cicd/1.4.0/artifacts/linux-arm64/panoptica-cicd && chmod +x ./panoptica-cicd
curl -O https://download.panoptica.app/panoptica-cicd/1.4.0/artifacts/windows-amd64/panoptica-cicd && chmod +x ./panoptica-cicd
Usage
Help command
Combine the --help
flag with any command to see usage instructions and available flags.
./panoptica-cicd --help
CLI Version
Use the version
command to view the version of the CLI tool you have installed.
./panoptica-cicd version
Image Scanning
Integrate the Panoptica CI/CD CLI tool into your CI/CD pipeline โ after the image build phase but before it is pushed to a registry โ to block vulnerable images from ever reaching production.
Run the panoptica-cicd
command to scan container images for vulnerabilities and configuration issues.
./panoptica-cicd [global flags] image IMAGE_NAME:TAG [--local] [--exit-on-severity <level>]
Flags
Flag | Environment Variables | Config File Entry | Arguments | Description | Default |
---|---|---|---|---|---|
--local | PANOPTICA_IMAGE_LOCAL | image_local | None | Whether to pull the image from a local Docker daemon | False. Pulls the image from the Dockerhub registry |
--exit-on-severity | PANOPTICA_IMAGE_EXIT_ON_SEVERITY | image_exit-on-severity | Critical / High / Medium / Low / Information | If a vulnerability severity is found at or above the given severity, the scan will exit with code 1 | None. The scan will not exit when a severity of any level is found. |
Global Flags
Global flags can be set for each command to customize the CLI behavior. Flags can be set using command-line arguments, environment variables, or a configuration file.
Flag | Environment Variable | Config File Entry | Arguments | Description | Default |
---|---|---|---|---|---|
--config | N/A | N/A | <local-file-path> | Path to the configuration file to use. | None |
--api-key | PANOPTICA_API_KEY | api-key | <api-key> | API Key to authenticate to the Panoptica platform. | None |
--region | PANOPTICA_REGION | region | <region> (us, eu) | Panoptica userโs region. | us |
--report | PANOPTICA_REPORT | report | None | Whether to send a scan report to the Panoptica console UI. | False - Does not send a scan report. |
--report-endpoint | PANOPTICA_REPORT_ENDPOINT | PANOPTICA_REPORT_ENDPOINT | <url> | API endpoint to which to send the scan reports. It can be used to send scan reports to the EU backend. | None. The report endpoint API shall be determined by the region. |
--policies | PANOPTICA_POLICIES | policies | <policy-list> | Policy names to enforce, as defined in the Panoptica platform. | None. No policies will be enforced. |
--policy-rules-endpoint | PANOPTICA_POLICY_RULES_ENDPOINT | policy-rules-endpoint | f<url> | API endpoint from which to fetch policy data. It can be used to fetch policies from the EU backend. | None. The policy endpoint API shall be determined by the region. |
Argument priorities
The CLI prioritizes configuration options in the following order (highest to lowest):
- command-line arguments
- environment variables
- configuration file entries
Endpoints and Region
The new --region
flag enables you to specify your region, and avoid the need to pass arguments for --report-endpoint
and --policy-rules-endpoint
. Possible values for the--region
flag areus
(default) andeu
. This flag determines the designated endpoints API for policies and reports. Setting a value for any of the report or policy flags will override the endpoint determined by the region
.
Usage Examples โ Region
-
Using command-line arguments โ EU API endpoints
./panoptica-cicd image alpine:latest --report --api-key="api-key" --region eu
-
Using environment variables โ EU API endpoints
export PANOPTICA_REPORT="true" export PANOPTICA_API_KEY="api-key" export PANOPTICA_REGION="eu"
./panoptica-cicd image alpine:latest
-
Using a configuration file โ EU API endpoints
# /path/to/config.yaml # Global flags report: true api-key: "api-key" region: "eu"
./panoptica-cicd image alpine:latest --config=/path/to/config.yaml
Error Handling
Exit Codes
- 0 - Succesfully terminated.
- 1 - Terminated with a failure.
- 124 - Timeout error.
Policy Enforcement
The CI/CD CLI can enforce policy rules configured on the Policies screen in the Panoptica platform, using the CI/CD engine option.
To apply specific policies, use the --policies
flag followed by the list of policy names you wish to enforce. Format the <policy-list> argument as a comma-separated string (e.g., "policy1, policy2") for command line arguments and environment variables, or as a YAML list for configuration files.
When a policy's conditions are satisfied, the corresponding action is initiated by the CLI, as defined in the policy's "Action" setting:
- Detect: The CLI issues a warning for any policy violations but will continue without exiting.
- Block: On policy violation, the CLI reports an error and exits immediately with a status code of 1.
Usage Examples - Policy
-
Using command-line arguments
./panoptica-cicd image alpine:latest --report --api-key="api-key" --policies="policy1,policy2" --exit-on-severity="critical
-
Using environment variables
export PANOPTICA_REPORT="true" export PANOPTICA_API_KEY="api-key" export PANOPTICA_POLICIES="policy1,policy2" export PANOPTICA_IMAGE_EXIT_ON_SEVERITY="critical"
./panoptica-cicd image alpine:latest
-
Using a configuration file
# /path/to/config.yaml # Global flags report: true api-key: "api-key" policies: - policy1 - policy2 # Image flags image_exit-on-severity: "critical"
./panoptica-cicd image alpine:latest --config=/path/to/config.yaml
Environment Context
The CLI tool collects metadata from selected CI/CD Environments. The following environment variables values are collected:
GitHub
- Username -
GITHUB_ACTOR
- Branch Name -
GITHUB_REF_NAME
- Repository Name -
GITHUB_REPOSITORY
- Commit Hash -
GITHUB_SHA
- Server URL -
GITHUB_SERVER_URL
Results
The CLI outputs detailed information on detected vulnerabilities, including package names, current and fixed versions, CVE IDs, and severity levels. It also returns configuration assessments, such as policy enforcement and severity threshold results. You can view the results of the image scan in the CLI, or in the Panoptica console UI.
CLI output
This sample of output from the Panoptica CI/CD CLI tool displays a detailed list of vulnerabilities found, along with a configuration assessment.
CI/CD Scan Results
If the --report
flag is set to true
, you will be able to view scan reports in the Panoptica console UI, on the CI/CD Scans tab under Build and Applications . Note that you'll need to generate an API Key to assign to the --api-key
flag.
Click any scan record in the table to view a detailed report of the scan results.
Integration example: GitHub Actions
The Panoptica CI/CD CLI tool can be employed with any build system. Integration is straightforward, and is no different from running the tool locally.
Sample workflow:
name: Image Scan
on:
pull_request:
branches:
- main
jobs:
panoptica-cicd-scan:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Build Docker image
uses: docker/build-push-action@v5
with:
context: .
load: true
tags: my-image:latest
- name: Install Panoptica CICD CLI
run: |
curl -O https://download.panoptica.app/panoptica-cicd/1.4.0/artifacts/linux-amd64/panoptica-cicd && chmod +x ./panoptica-cicd
- name: Run image scan
run: |
./panoptica-cicd image my-image:latest --local --exit-on-severity high
Local image scanning
For local image scanning, the Docker daemon must be running, and have access to the scanned image.
Updated 3 months ago