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

Configure GitHub Actions for Panther

Prerequisites

Before finalizing GitHub Actions with Panther, please reach out to Panther's Support team to get your Panther Console set up with the PantherAnalysisFederatedCDRole needed to assume the role directly using the GitHub OIDC provider.

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 the button that says 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
      1
      name: GitHub Actions CI/CD workflow
      2
      3
      permissions:
      4
      id-token: write
      5
      contents: read
      Copied!
    • Replace the default on section with the following:
      1
      on:
      2
      push:
      3
      paths:
      4
      - 'detections/**'
      Copied!
      • 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:
        1
        jobs:
        2
        download_pantherlog_tool:
        3
        runs-on: ubuntu-latest
        4
        name: Downloading the pantherlog tool
        5
        steps:
        6
        - name: Download pantherlog & unzip
        7
        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
        8
        - name: Create a pantherlog artifact
        9
        uses: actions/[email protected]
        10
        with:
        11
        name: pantherlog
        12
        path: pantherlog
        13
        retention-days: 1
        Copied!
      • Add a job that runs schema tests using the pantherlog tool:
        1
        run_schema_tests:
        2
        runs-on: ubuntu-latest
        3
        name: Run schema tests with pantherlog
        4
        needs: [download_pantherlog_tool]
        5
        steps:
        6
        - name: Check out the repo
        7
        uses: actions/[email protected]
        8
        - name: Download Pantherlog tool from artifacts
        9
        uses: actions/[email protected]
        10
        with:
        11
        name: pantherlog
        12
        - name: Make pantherlog executable
        13
        run: sudo chmod +x pantherlog
        14
        - name: Perform schema tests with pantherlog
        15
        run: ./pantherlog test detections/schemas
        Copied!
      • Add a job to run unit tests using the panther_analysis_tool:
        1
        run_unit_tests:
        2
        runs-on: ubuntu-latest
        3
        name: Unit Testing with panther_analysis_tool
        4
        needs: [download_pantherlog_tool, run_schema_tests]
        5
        steps:
        6
        - name: Check out the repo
        7
        uses: actions/[email protected]
        8
        - name: Download the panther_analysis_tool
        9
        run: pip3 install panther_analysis_tool
        10
        - name: Run unit tests within the Detections folder
        11
        run: |
        12
        for dir in detections/*; do
        13
        if [[ "$dir" =~ .*_rules.* ]]; then
        14
        panther_analysis_tool test
        15
        fi
        16
        done
        Copied!
      • Add the last job to upload detections and custom schemas to the Panther Console. This leverages a pre-built action called [email protected] to assume a role directly using GitHub OIDC provider.
        • Note: Make sure you replace the AWS Account ID as well as the AWS Region with the values matching your instance of Panther.
          1
          panther_analysis_tool_upload:
          2
          runs-on: ubuntu-latest
          3
          name: panther_analysis_tool upload to panther console
          4
          needs: [download_pantherlog_tool, run_schema_tests, run_unit_tests]
          5
          steps:
          6
          - name: Checkout the repo
          7
          uses: actions/[email protected]
          8
          - name: Configure AWS credentials leveraging OIDC to make the connection
          9
          uses: aws-actions/[email protected] # https://github.com/aws-actions/configure-aws-credentials
          10
          with:
          11
          role-to-assume: arn:aws:iam::1234567891012:role/PantherAnalysisFederatedCDRole # Replace with your Panther AWS Account ID
          12
          aws-region: us-west-2 # Replace with AWS region your Panther instance is in
          13
          - name: Download panther_analysis_tool
          14
          run: pip3 install panther_analysis_tool
          15
          - name: Loop through folders ending in _rules and upload to papaya-oarfish
          16
          run: |
          17
          for dir in detections/*; do
          18
          if [[ "$dir" =~ .*_rules.* ]]; then
          19
          panther_analysis_tool upload --path "$dir" --skip-tests
          20
          fi
          21
          done
          22
          - name: Upload custom schemas to Panther Console
          23
          run: panther_analysis_tool update-custom-schemas --path schemas/
          Copied!

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.