Links

Managing Panther Content via CircleCI

Manage detections and schemas 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 in CircleCI
  • Upload your detections to the Panther Console
Using GitHub Actions? If so, there is an option to grant upload access to your Panther Console via GitHub Actions Secrets. For more information on using Secrets with GitHub Actions, see Managing Panther Content via Github Actions.
See CI/CD for Panther Content for information on starting your CI/CD workflow with Panther.

Setting up CircleCI

Prerequisites

Step 1: Make use of the Panther-managed detections in the panther-analysis GitHub repo

Follow the documentation to make use of Panther-managed detections in the panther-analysis GitHub repo: Using the Panther detections repo.

Step 2: Configuring the repository

This section outlines how to link the CircleCI project to a forked version of panther-analysis.
  1. 1.
    Create a repository in CircleCI to contain the detections that you have created.
  2. 2.
    In CircleCI's sidebar menu on the left, click Projects. Locate the project containing your forked panther-analysis repository and click Set Up Project.
    The screen shot shows the CircleCI UI. The Projects title on the left sidebar is highlighted. On the right, a blue arrow points to a button labeled Set Up Project. The button applies to the Panther Analysis repo.
  3. 3.
    You will be prompted to select a config.yml file for your directory. Configuration for CircleCI jobs is found in the root directory of the repository under .circleci/config.yaml. Choose from the following options:
    • Write your own using our starter config.yml template.
      • You will be redirected to an in-browser editor to create a template. If you would prefer to create your own job from scratch, you can find more information in CircleCI's documentation.
    • Select the branch it's on to start building.
      • Select this option if you already have the .circleci/config.yml file in your repository. Select the branch where it is located.
Once the configuration is in place, the CI job should run automatically. You can return to the dashboard and see the status of your job.
The CircleCI Dashboard shows the status of the job. In this image, the status shows "Success" next to the pipeline called panther-analysis.
Going forward, this job will run every time a new pull request is created or a new commit pushed to a branch. You will see the status of the CI job at the bottom of your pull request. Next to the status, click Details to see detailed output from the job.
A message at the top says "All checks have passed." There is a list of tests. An arrow is pointing to the "Details" link on the right.

Step 3: Uploading detections to Panther

You can upload detections to Panther via automated upload in CircleCI using the Panther Analysis Tool command line utility. For more information on PAT, please see the Panther Analysis Tool documentation.

Automate upload in CircleCI workflow

In this section, you will add a step to your CircleCI workflow to automate the upload of new rules when merging into main.
Ensure that the environment variables PANTHER_API_TOKEN and PANTHER_API_HOST are passed into the job to allow for correct authentication. These can be stored encrypted as repository secrets. The process of adding repository secrets is covered in the next section.
  1. 1.
    In your CircleCI projects list, locate the panther-analysis repository Click ... on the right side of the project then click Project Settings.
    The image shows the Projects list in CircleCI. On the right side, a 3 dots icon is expanded to show a dropdown menu.
  2. 2.
    Create environment variables $INTERNAL_API_TOKEN and $INTERNAL_API_HOST within the Project Settings in CircleCI for your forked version of panther-analysis.
    • For instructions on creating environment variables in CircleCI, please see the CircleCI documentation: Using Environment Variables.
      The image shows the Project Settings console in CircleCI. On the left sidebar menu, "Environment Variables" is highlighted. In the center of the page, there is a blue button labeled "Add Environment Variable."
  3. 3.
    After the environment variables have been created, add the lines below to your CircleCI configuration in the panther-analysis repo:
deploy:
docker:
- image: 'circleci/python:3.7'
steps:
- checkout
- run:
name: Setup the Virtual Environment and install dependencies
command: make venv
- run:
name: upload to internal security
command: |
PANTHER_API_HOST=$INTERNAL_API_HOST \
PANTHER_API_TOKEN=$INTERNAL_API_TOKEN \
pipenv run -- panther_analysis_tool upload --filter Tags=internal