# Managing Panther Content via 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](https://docs.panther.com/~/changes/Cd1BxbxeaFl8dlynhNpt/panther-developer-workflows/ci-cd) 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](https://docs.panther.com/~/changes/Cd1BxbxeaFl8dlynhNpt/api#how-to-create-a-panther-api-token).
* If you do not already have a CircleCI account, [create a free one](https://circleci.com/signup).

### 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](https://docs.panther.com/~/changes/Cd1BxbxeaFl8dlynhNpt/panther-developer-workflows/ci-cd/detections-repo/private-cloned-repo) or [publicly fork](https://docs.panther.com/~/changes/Cd1BxbxeaFl8dlynhNpt/panther-developer-workflows/ci-cd/detections-repo/public-fork) Panther's [panther-analysis repository](https://github.com/panther-labs/panther-analysis). 

### 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:

   ```yaml
   version: 2.1
   jobs:
     upload:
       docker:
         - image: 'cimg/python:3.11'
       steps:
         - checkout
         - run:
             name: Setup the Virtual Environment and install dependencies
             command: make venv
         - run:
             name: Run unit tests
             command: pipenv run panther_analysis_tool test
         - 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 Enabled=true
   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](https://circleci.com/vcs-authorize/) 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**.<br>

   <figure><img src="https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FFsrEFjXaNYSSPsbmUS2i%2Fcircleci-project-settings.jpeg?alt=media&#x26;token=78ca99d2-cd00-4123-b8d0-82d8fc537cbb" alt="In the CircleCI console, the Projects screen is shown. The three dots icon has been selected on the panther-analysis project."><figcaption></figcaption></figure>
4. In the left-hand navigation menu, click **Environment Variables**.&#x20;
5. Click **Add Environment Variable**, and add `INTERNAL_API_TOKEN` and `INTERNAL_API_HOST`.

   <figure><img src="https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FTyIj0WOhi49NQGIPMCho%2Fimage.png?alt=media&#x26;token=c9b15a01-0b1b-4caf-94a5-e3b3e1bd1347" alt="In the CircleCI console, the Project Settings screen is shown. There is a button to &#x22;Add Environment Variable&#x22;"><figcaption></figcaption></figure>

   * See the CircleCI documentation on [Using Environment Variables](https://circleci.com/docs/env-vars) for more information.

Check out [Panther Analysis Tool Commands](https://docs.panther.com/panther-developer-workflows/ci-cd/deployment-workflows/pat/pat-commands) for more information on the Panther Analysis tool.