Using panther-analysis

Leverage Panther-managed security content

Overview

panther-analysis is a public, open-source repository of Panther-managed security content, including detections, Saved Searches, global helpers, Lookup Tables, and more.

To interact with your Panther detections repository on the command line, use the Panther Analysis Tool (PAT). Add your own custom detection content, and receive updates as Panther's Threat Intelligence team releases new versions.

For general information and best practices for Panther detections, and for information on managing your detections in the Panther Console, see the Detections documentation.

After you have your own copy of panther-analysis, you can configure CI/CD workflows and set up GitHub sync.

Recommended Workflow

Starting in Panther Analysis Tool (PAT) v1.4.0 Panther content can be used to intelligently track versions, provide automated merging, and keep your content up to date.

• Tracks which version of a Panther detection your customizations are based on (BaseVersion field)

• Automatically pulls the latest Panther content

• Intelligently merges updates and allows handling of conflicts when you're ready

• Provides an interactive merge process for conflicts

• Requires only the content you are interested in

Virtual environment and package manager

It's recommended to use a virtual environment and package manager when interacting with panther-analysis or using PAT, as managing Python dependencies can get messy.

uv is recommended for its speed and reliability, but poetry, pipenv, and venv work too.

Staying up to date with panther-analysis releases

When new content is released, running pat explore or pat clone will allow you to use brand new content. pat pull will allow you to update your content. You can also choose to run pat clone --filter LogTypes=Okta.SystemLog --filter Severity=High within a GitHub Action or other scheduler to continually pull in new content matching the criteria supplied.

Experimental detections

Panther typically releases new detections in an "experimental" stage, which means they are still undergoing refinement and may not be suitable for production environments.

Detections in the experimental phase:

• Will have Status: Experimental

• Will not generate alerts

• Are not visible in the Panther Console (but can be viewed in the panther-analysis repository)

• Collect aggregate performance metrics (not your log data) to validate expected alert volume

You can choose to use experimental detections, however they may result in higher-than-average alert volume because they are still being tuned. To use an experimental detection before it is officially released, remove the Status field's Experimental value and upload the rule.

The duration of the experimental stage varies by detection, but typically lasts several weeks. When a detection exits the experimental phase, its Status value is changed from Experimental to Stable. After being promoted to stable, detections may still be updated, though with reduced frequency.

Removing deprecated Panther-managed detections

Panther occasionally deprecates and deletes Panther-managed detection content that has become obsolete. This means a new version of panther-analysis no longer contains the detections (or Saved/Scheduled Searches). When this happens, if you'd like to stop using the removed content, you must manually delete it from your Panther instance—simply removing the content from your repository is not enough, since the Panther Analysis Tool (PAT) does not delete content during upload to Panther.

To help you identify and remove deprecated content, Panther provides a Makefile command, make remove-deprecated, which removes deprecated detection content from your Panther instance.

This command works by comparing the content of your repository with deprecated.txt, a file in panther-analysis containing the IDs of all removed items. It's recommended to run make remove-deprecated at least once per month to clear out any deprecated detections from your instance.

Note that make remove-deprecated requires your API host and token be set as environment variables. See the instructions on configuring PAT with environment variables for more details.