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.

If your repository includes scheduled prompts, the API token must hold the ManageScheduledPrompts permission (and AIRunAsModify if any prompt's RunAsUser differs from the token).

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.