Managing Panther Content via CircleCI

Manage detection content in Panther with a CI/CD workflow using CircleCI

Overview

You can configure CircleCI to automate testing and upload your detection pipeline from your source repository to your Panther Console.

This guide explains how to:

• Configure your repository to support CircleCI.

• Configure CircleCI to automatically upload detection content you commit to your repository to your Panther instance.

See CI/CD for Panther Content for information on starting your CI/CD workflow with Panther.

Setting up CircleCI

To use CircleCI to upload detection content to your Panther instance, you'll create a CircleCI job on your repository, then configure environment variables for Panther API credentials.

Prerequisites

• Generate an API token from your Panther Console.

  • See these instructions on generating an API token.

• If you do not already have a CircleCI account, create a free one.

Step 1: Set up your detections repository

• If you do not already have a repository set up for your Panther detection content, create one. It is recommended to either privately clone or publicly fork Panther's panther-analysis repository.

Step 2: Add a CircleCI job to your repository

In order for CircleCI to test and upload the detection content you commit to the main branch of your panther-analysis repository, you need to create a CircleCI job.

1. On the command line, navigate to the root of your private local repository: cd path/to/your/repository

2. Create a new directory for the CircleCI configuration, as well as a new configuration file:

   mkdir .circleci && touch .circleci/config.yml

3. Open config.yml and paste the following:

   version: 2.1
   jobs:
     upload:
       docker:
         - image: 'cimg/python:3.11'
       steps:
         - checkout
         - run:
             name: Set up the virtual environment and install dependencies
             command: make venv
         - run:
             name: Run unit tests
             command: pipenv run panther_analysis_tool test
         - run:
             name: Upload detection content
             # (Optional) Add `--filter Enabled=true` to command below to only upload Enabled detections
             command:  |
               PANTHER_API_HOST=$INTERNAL_API_HOST \
               PANTHER_API_TOKEN=$INTERNAL_API_TOKEN \
               pipenv run -- panther_analysis_tool upload
   workflows:
     panther:
       jobs:
         - upload:
             filters:
               branches:
                 only:
                   - main

4. Add, commit, and push the changes to your repository:

   git add . && git commit -m 'adding initial circleci configuration' && git push

Step 3: Add Panther API credentials as environment variables

Ensure that the environment variables PANTHER_API_TOKEN and PANTHER_API_HOST are set to allow for correct authentication.

1. Sign in to CircleCI and select the organization your project is in.

2. In the left-hand navigation menu, click Projects.

3. In your projects list, locate the panther-analysis repository. On the right side of the project, click ... then Project Settings.

   
4. In the left-hand navigation menu, click Environment Variables.

5. Click Add Environment Variable, and add INTERNAL_API_TOKEN and INTERNAL_API_HOST.

   

   • See the CircleCI documentation on Using Environment Variables for more information.

Check out Panther Analysis Tool Commands for more information on the Panther Analysis tool.