GitHub Actions Onboarding Guide
Manage detections and schemas in Panther with a CI/CD workflow using GitHub Actions

Overview

You can configure GitHub Actions to automate testing, customize detections, and upload your detection pipeline from your GitHub repository to your Panther Console. This guide will walk you through the following:
  • Creating a custom workflow via GitHub Actions
  • Testing your custom schemas and detections
  • Uploading the schemas and detections to your Panther Console
  • Customizing your GitHub Actions workflow to fit your organization's needs

Prerequisites

To get started with managing your Panther detections and schemas using GitHub Actions, you will need:
  • A Panther API Key
  • Your Panther API Host Name
    • Your Panther API hostname will look like this: https://api.<your-panther-instance-name>.runpanther.net/public/graphql
To use your API token securely, we recommend using GitHub Actions Secrets. To add the token to Secrets, follow Github's documentation: Creating encrypted secrets for a repository. This secret is shown later in this document as secrets.PantherApiToken.
This guide explains how to upload to your Panther Console via GitHub Actions using Panther API keys and Github secrets. This is the recommended method if you are using GitHub Actions. You can also upload to your Panther Console directly via the panther_analysis_tool.
For more information, see our CI/CD Onboarding Guide.

Configure GitHub Actions for Panther

Build a GitHub workflow to test schemas, detections, and upload to Panther

  1. 1.
    Navigate to the GitHub repository where you would like to set up automation.
  2. 2.
    Within the GitHub repository, navigate to Actions.
  3. 3.
    Click New Workflow.
  4. 4.
    Click Set up a workflow yourself →.
  5. 5.
    On the next page, replace the default filename (main.yml) with a memorable name, e.g., panther-workflow.yml.
  6. 6.
    Customize your workflow as follows:
    • Name: Create a memorable name.
    • Permissions: Add a permissions field to the workflow that mirrors the below: name: GitHub Actions CI/CD workflow
      name: GitHub Actions CI/CD workflow
      permissions:
      id-token: write
      contents: read
    • Replace the default on section with the following:
      on:
      push:
      paths:
      - 'detections/**'
      • This defines how to control the workflow to trigger when users perform a git push to the specific folder path detections/**.
      • For other ways to trigger a workflow, please see GitHub's documentation on using filters.
    • Jobs: modify the jobs sections as follows:
      • Modify the first job downloads, aka the pantherlog tool we use to perform schema tests:
        jobs:
        download_pantherlog_tool:
        runs-on: ubuntu-latest
        name: Downloading the pantherlog tool
        steps:
        - name: Download pantherlog & unzip
        run: curl -sSO "https://panther-community-us-east-1.s3.amazonaws.com/v1.32.4/tools/linux-amd64-pantherlog.zip" && unzip linux-amd64-pantherlog.zip
        - name: Create a pantherlog artifact
        uses: actions/[email protected]
        with:
        name: pantherlog
        path: pantherlog
        retention-days: 1
      • Add a job that runs schema tests using the pantherlog tool:
        run_schema_tests:
        runs-on: ubuntu-latest
        name: Run schema tests with pantherlog
        needs: [download_pantherlog_tool]
        steps:
        - name: Check out the repo
        uses: actions/[email protected]
        - name: Download Pantherlog tool from artifacts
        uses: actions/[email protected]
        with:
        name: pantherlog
        - name: Make pantherlog executable
        run: sudo chmod +x pantherlog
        - name: Perform schema tests with pantherlog
        run: ./pantherlog test detections/schemas
      • Add a job to run unit tests using the panther_analysis_tool:
        run_unit_tests:
        runs-on: ubuntu-latest
        name: Unit Testing with panther_analysis_tool
        needs: [download_pantherlog_tool, run_schema_tests]
        steps:
        - name: Check out the repo
        uses: actions/[email protected]
        - name: Set python version
        uses: actions/[email protected]
        with:
        python-version: '3.9'
        - name: Install pipenv
        run: pip install pipenv
        - name: Install python dependencies and panther_analysis_tool
        run: make install
        - name: Run unit tests within the Detections folder
        run: pipenv run panther_analysis_tool test --path detections
      • Add the last job to upload detections and custom schemas to the Panther Console.
        panther_analysis_tool_upload:
        runs-on: ubuntu-latest
        name: panther_analysis_tool upload to panther console
        needs: [download_pantherlog_tool, run_schema_tests, run_unit_tests]
        env: |
        PANTHER_API_TOKEN: ${{ secrets.PantherApiToken }}
        PANTHER_API_HOST: "https://api.<your-panther>.runpanther.net/public/graphql"
        steps:
        - name: Checkout the repo
        uses: actions/[email protected]
        - name: Set python version
        uses: actions/[email protected]
        with:
        python-version: '3.9'
        - name: Install pipenv
        run: pip install pipenv
        - name: Install python dependencies and panther_analysis_tool
        run: make install
        - name: Upload all AnalysisType=rule in the detections folder to your Panther instance
        run: pipenv run panther_analysis_tool upload --path detections --skip-tests --filter AnalysisType=rule
        - name: Upload custom schemas to Panther Console
        run: pipenv run panther_analysis_tool update-custom-schemas --path schemas/

Pushing detections via GitHub Actions

Now that the GitHub Actions workflow is complete, the following will occur the next time you use git push to make changes within the detections/ folder:
  • Custom log schemas are tested with pantherlog.
  • Custom detections are tested with panther_analysis_tool.
  • Upon success, schema and detections are uploaded to your Panther Console.
For reference, the full GitHub CI/CD GitHub Actions workflow schema is aggregated below:
Complete GitHub CI/CD workflow in one schema

Customize your GitHub Actions workflow in Panther

Optionally, you can extend or customize this workflow to better fit your organization. The following are common workflow customizations with Panther:
  • Perform Python Linting against .py files.
  • Trigger from an approved Pull Request (PR) instead of a Push to a specific folder.
  • If you fork the panther-analysis repository by the latest tag, learn how syncing a fork can help keep Panther Detections up-to-date. We recommend syncing weekly by tag.
Additional GitHub Actions documentation can be found here.
Copy link
Outline
Overview
Prerequisites
Configure GitHub Actions for Panther
Build a GitHub workflow to test schemas, detections, and upload to Panther
Pushing detections via GitHub Actions
Customize your GitHub Actions workflow in Panther