CI/CD CLI v1.5.1

Integrating the Panoptica CI/CD CLI tool into the development workflow enables you to scan container images and IAC directories for potential security vulnerabilities. Panoptica's CI/CD CLI tool can detect and block security issues pre-production, before they are merged into the main codebase and deployed to the production environment.

Version 1.5.1 of Panoptica's CI/CD CLI adds the ability to scan your Infrastructure as Code (IaC) definitions and scripts to ensure the resulting resources are secure.

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.5.1/artifacts/darwin-amd64/panoptica-cicd && chmod +x ./panoptica-cicd

curl -O https://download.panoptica.app/panoptica-cicd/1.5.1/artifacts/darwin-arm64/panoptica-cicd && chmod +x ./panoptica-cicd

curl -O https://download.panoptica.app/panoptica-cicd/1.5.1/artifacts/linux-amd64/panoptica-cicd && chmod +x ./panoptica-cicd

curl -O https://download.panoptica.app/panoptica-cicd/1.5.1/artifacts/linux-arm64/panoptica-cicd && chmod +x ./panoptica-cicd

curl -O https://download.panoptica.app/panoptica-cicd/1.5.1/artifacts/windows-amd64/panoptica-cicd && chmod +x ./panoptica-cicd

Configuration

Global Flags

You can invoke Global flags for each command to customize the CLI behavior. Global flags can be set using command-line arguments, environment variables, or a configuration file.

📘

Argument priorities

The CLI prioritizes configuration options in the following order (highest to lowest):

1. command-line arguments
2. environment variables
3. configuration file entries

Endpoints and Region

The --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--regionflag 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
  

Commands

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

Use the image command to 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.

Usage

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

The command line flags for the image command are detailed in this table:

Infrastructure as Code (IaC)

Use the iac command to scan your Infrastructure as Code (IaC) definitions and scripts, to ensure the resulting resources are secure.

Usage

./panoptica-cicd [global flags] iac DIRECTORY_PATH [--exit-on-severity <level>]

Flags

The command line flags for the iac command are detailed in this table:

Results

The CI/CD CLI outputs detailed information on detected vulnerabilities and other security issues. You can view scan results in the CLI, or in the Panoptica console UI.

Image Scanning - CLI output

The image command outputs detailed information on detected vulnerabilities, including package names, current and fixed versions, CVE IDs, and severity levels. It also covers configuration assessments, such as policy enforcement and severity threshold results.

IAC Scanning - CLI output

The iac command outputs information on detected findings, including file name, finding name, file link and severity levels. It also covers configuration assessments, such as policy enforcement and severity threshold results.

Scan Results in the Console UI

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.

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
• GitHub Run ID - GITHUB_RUN_ID: A unique identifier representing the workflow run in which the CLI was executed.

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.5.1/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.