Setting Up Your Panther Content Repository

This updated panther_analysis_tool merge workflow is in open beta starting with Panther version 1.119, and is available to all customers. Please share any bug reports and feature requests with your Panther support team.

Creating a new Panther content repository

Prerequisite

• You have installed the Panther Analysis Tool (PAT).

Step 1: Prepare your Panther repository

• In an empty directory, run pat init.

Prepares your repository for later PAT commands.

The init command initializes an empty repository and pulls the latest content from panther-analysis to your cache.

Step 2 (Optional): Explore content from panther-analysis

• Run pat explore.

Step 3: Enable content from panther-analysis

To enable content from panther-analysis, like detections, run pat install, passing one or more content items. For example:

• pat install <id>

• pat install --filter LogTypes=AWS.CloudTrail

Step 4: Ensure new content passes tests

• Run pat test.

Step 5: Upload content to Panther

• Run pat upload.

Migrating from a legacy repository

If your existing Panther content repository was forked or cloned from panther-analysis, migrate to the new management workflow by following the steps below.

Step 1: Prepare your Panther repository

• In your Panther content directory, run pat init.

Step 2: Format existing content

Certain formatting changes to your YAML files are required (such as removing braces and brackets from nested JSON segments, like detection unit tests). To make these changes:

• Run pat fmt.

It's recommended to commit changes at this step, as pat fmt will generate large amounts of formatting changes that will be tedious to review.

Step 3: Update existing content

Migrate all analysis items that are based off panther-analysis content by adding a BaseVersion field and merging them with the most recent panther-analysis version. If your repo is still forked from panther-analysis after migrating, that will not break other PAT commands, but we recommend never syncing from upstream panther-analysis after migrating. Any automation doing that should be removed.

• Run pat migrate.

Note that pat migrate does not pull in any new panther-analysis content—it only migrates your existing content.

Step 4: Review migration_status.md and resolve individual merge conflicts

1. Run less migration_status.md.

2. (Optional) If migration_status.md indicates there are outstanding merge conflicts, for each item with a conflict, run pat migrate <ID> to resolve it.

   • You can optionally use --write-merge-conflicts to instruct PAT to instead write merge conflicts to the file, which may be useful if you're using AI to solve conflicts or use --auto-accept to auto resolve.

     This step is optional because it is not required to resolve merge conflicts before moving on (i.e., before testing and uploading the content that did not generate merge conflicts).

   • To resolve a conflict in a YAML file, you'll use the PAT CLI editor.

     • To resolve a conflict in a Python file, you can either use the PAT CLI editor or a code editor of your choice. To designate your code editor of choice (e.g., code (VS code), cursor, Poland, goland (Go), pycharm), either:

       • Use --editor with pat migrate

       • Set the EDITOR environment variable

It's also recommended to commit at this stage, before enabling new content.

Step 5 (Optional): Explore latest content from panther-analysis

• Run pat explore.

Step 6 (Optional): Enable new content from panther-analysis

To enable content from panther-analysis, like detections, run pat install, passing one or more content items. You do not need to run the migrate command in order to install content you have never had before. For example:

• pat install <id>

• pat install --filter LogTypes=AWS.CloudTrail

Step 7: Ensure content passes tests

• Run pat test.

Step 8: Upload content to Panther

• Run pat upload.

Step 9: Remove unused panther-analysis content

In the deprecated management workflows, you pulled in all content from panther-analysis, regardless of whether you enabled it or not. In the updated workflow, you only need to keep content you are actually using.

At this stage, you can remove any content that has no use in your environment. When removing content, be sure to run pat test frequently to validate that no dependencies have been removed, as detection content often depends on global helpers and data models.