Managing Detections via CI/CD
Automate your detection pipeline and improve security with Panther Developer Workflows: CI/CD

Overview

This guide walks you through managing Panther's built-in detections and your custom detections with a Continuous Integration and Continuous Deployment (CI/CD) workflow.
The process outlined in this guide will use Github, Github Actions, and CircleCI, but can be adapted to your desired toolset. This guide explains how to:
  • Create a CI workflow that runs the Python Black linter on your codebase and executes all unit tests defined for rules.
  • Maintain a fork of the Panther-Analysis repository, where all of Panther’s built-in detections are stored, maintained, and updated.

Prerequisites

  • Before getting started, generate an API token from your Panther Console.

Migrating to a CI/CD workflow

If you are migrating from managing detections in the Panther Console to managing them via a CI/CD workflow, download any detections you created in the Console by following these steps:
  1. 1.
    Log in to the Panther Console.
  2. 2.
    Navigate to Build > Detections.
  3. 3.
    Click Filters in the upper right. Filter for Created by: then select Created by team.
  4. 4.
    Download each page of detections.
    1. 1.
      Check the bulk select box in the upper left corner of the list.
    2. 2.
      In the upper right side of the list, click the "Mass Action" dropdown menu, click Download, then click Apply.
The detections will be downloaded in a zip that you can now incorporate into your source control.
Optionally, you can also mark your users as read-only in the Panther Console to ensure that they only manage detections via CI/CD:
  1. 1.
    Navigate to Settings > Users.
  2. 2.
    In the user list, locate your developers who are using a CI/CD workflow.
  3. 3.
    Click ... on the right side of a user tile. In the dropdown menu that appears, click Edit.
  4. 4.
    Change the user's role to Read Only.
  5. 5.
    Click Update.
  6. 6.
    Repeat these steps for each developer who is using a CI/CD workflow.
Using GitHub Actions? If so, there is a more convenient way to grant upload access to your Panther Console via GitHub Actions Secrets. For more information on using Secrets with GitHub Actions, see our GitHub Actions Onboarding Guide.

Setting up CircleCI

Creating Account and Repository

  1. 1.
    Create a repository in CircleCI to contain the detections that you have created.
    • If you do not currently use CircleCI for other projects, you can create a free account. The "Sign Up with Github" option will authorize CircleCI to your Github account.
    • This guide focuses on using a fork of the panther-analysis repo.
  2. 2.
    In CircleCI's sidebar menu on the left, click Projects. Locate the project containing your repository and click Set Up Project.
  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.
    • If you already have .circleci/config.yml in your repo, select the branch it's on to start building
      • Select this option if you already have the 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.
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.

Uploading Detections to Panther

After changes have been merged to your detections repo, the recommended way to upload new detections is with panther_analysis_tool (PAT).
To upload detections via PAT:
  1. 1.
    Generate an API token from your Panther Console.
  2. 2.
    Run panther_analysis_tool test to ensure your unit tests are passing.
  3. 3.
    Run panther_analysis_tool upload to upload new detections to your Panther instance.
    • The environment variables PANTHER_API_TOKEN and PANTHER_API_HOST are required for these commands to execute successfully.
      • The PANTHER_API_TOKEN is the value of the API token you obtained in step 1.
      • The PANTHER_API_HOST is the API URL of your Panther Instance. For example, if your Panther domain is https://acme.runpanther.net, then your GraphQL API URL is https://api.acme.runpanther.net/public/graphql.
It is also possible to add this step to your CircleCI workflow to automate the upload of new rules when merging into master. 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.
For more information on PAT, please see the documentation: Panther Developer Workflows: Detections.

Configuring CircleCI to Upload to Panther

  1. 1.
    In your CircleCI projects list, locate the panther-analysis repository Click ... on the right side of the project then click Project Settings.
  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.
  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

Keeping up to date with Panther Built-in Detections

This section of the guide explains how to create of a fork of the Panther Analysis repo for the purpose of keeping the built-in detections in Panther up to date.

Creating a Fork

  1. 1.
    Log in to Github and navigate to panther-labs/panther-analysis.
  2. 2.
    In the upper right corner of the repository’s main page click Fork.
    • This will create a fork of the panther-analysis repo in your organization. This will serve as your working copy of panther-analysis, and any changes required by your organization can be made here and will undergo any configured CI checks that you define. Note that as mentioned in the previous section, a CircleCI config file is already present in this repository and can be used if desired; you will need to enable this new forked project in your instance of CircleCI.
  3. 3.
    (Optionally) Unzip any of your custom detections (created in by following these steps) into the same directory as your forked version of panther-analysis.

Keeping the Fork Up to Date

There are two methods for keeping your fork up to date with Panther Analysis: Manual or Automated updates.
NOTE: It is important to upload or create new branches from a release branch rather than “Master” if you wish to make changes to the Panther Analysis repo. Master may contain detections that rely on not-yet-implemented features.

Method 1: “Manual” Updates

Please see Github's documentation to learn more about the process of manually updating the fork from its source, in this case panther-labs/panther-analysis.
It is recommended to always using the “compare” option detailed in these documents to ensure you are pulling in changes that make sense for your organization. This will display the updates as a pull request, and changes and comments can be made.

Method 2: Automated Updates

Using Github Actions, you can automate the process for pulling in changes and creating pull requests. For this example we will use the action Fork Sync.
To automate updates, you will need to create a Github Personal Access Token as a repository secret:
  1. 1.
    In Github, click your avatar in the upper right corner and click Settings.
  2. 2.
    In the settings menu, click Developer Settings.
  3. 3.
    In the Developer Settings menu, click Personal Access Token. Fill in the fields to configure the token:
    1. 1.
      Note: Enter a descriptive name.
    2. 2.
      Expiration: Enter an expiration date for the token. Note that this token should be treated as a password, and as such, you should adhere to any password policies your organization has defined.
    3. 3.
      Select scopes: Check the boxes next to repo and workflow.
  4. 4.
    At the bottom of the page, click Generate Token.
  5. 5.
    Copy the token value and temporarily store it in a secure location. It will only be displayed once, and you will need it in the next steps.
  6. 6.
    Navigate to the fork of panther-analysis in your GitHub org.
  7. 7.
    Click Settings > Secrets then click New Repository Secret. Fill in the fields to configure the secret:
    • Name: Enter the name you used while creating the personal access token.
    • Value: Enter the personal access token you generated in the previous steps.
  8. 8.
    Click Add Secret.
  9. 9.
    Create the file .github/workflows/fork-sync.yml and configure the action as desired.
    • Examples and options can be found on the Fork Sync homepage and more in-depth options for GitHub Actions can be found in the Github Actions documentation.
    • This will allow for automated fork updates and pull request creation, although the pull request should still be reviewed and merged by a human to ensure the changes being made are acceptable for your use cases.
Congrats! You did it!
Copy link
Outline
Overview
Prerequisites
Setting up CircleCI
Creating Account and Repository
Uploading Detections to Panther
Configuring CircleCI to Upload to Panther
Keeping up to date with Panther Built-in Detections
Creating a Fork
Keeping the Fork Up to Date