Knowledge BaseRelease NotesRequest Demo

Panther Analysis Tool Commands

Use PAT to manage your Panther content

Overview

You can manage your Panther detection content using the Panther Analysis Tool (PAT). PAT lets you upload, test, and delete assets, among other actions.

Each of the PAT commands accepts certain options. For example, you can use --filter with several of the commands to narrow the scope of the action.

PAT commands

See the full list of available PAT commands in the following codeblock. Beneath it, find additional information about several of the commands.

To understand which Panther permissions you need to execute each PAT command, see Permissions required per command.

% panther_analysis_tool -h
usage: panther_analysis_tool [-h] [--version] [--debug] {release,test,publish,upload,delete,update-custom-schemas,test-lookup-table,validate,zip,check-connection,sdk} ...

Panther Analysis Tool: A command line tool for managing Panther policies and rules.

positional arguments:
  {release,test,publish,upload,delete,update-custom-schemas,test-lookup-table,validate,zip,check-connection,sdk}
    release             Create release assets for repository containing panther detections. Generates a file called panther-analysis-all.zip and optionally generates
                        panther-analysis-all.sig
    test                Validate analysis specifications and run policy and rule tests.
    publish             Publishes a new release, generates the release assets, and uploads them. Generates a file called panther-analysis-all.zip and optionally generates
                        panther-analysis-all.sig
    upload              Upload specified policies and rules to a Panther deployment.
    delete              Delete policies, rules, or saved queries from a Panther deployment
    update-custom-schemas
                        Update or create custom schemas on a Panther deployment.
    test-lookup-table   Validate a Lookup Table spec file.
    validate            Validate your bulk uploads against your panther instance
    zip                 Create an archive of local policies and rules for uploading to Panther.
    check-connection    Check your Panther API connection
    sdk                 Perform operations using the Panther SDK exclusively (pass sdk --help for more)

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --debug

test: Running tests with PAT

Use PAT to load the defined specification files and evaluate unit tests locally:

To filter rules or policies based on certain attributes:

validate: Ensuring detection content is ready to be uploaded

The validate command verifies your detection content is ready to be uploaded to your Panther instance by running the same checks that happen during the upload process. Because some of these checks require configuration information in your Panther instance, validate makes an API call.

To validate your detections against your Panther instance using PAT:

  1. If you have not already, generate an API token in your Panther Console.

  2. Run the following command:

    • You may exclude the --api-token and --api-host options if you are setting configuration values another way, i.e., by using environment variables or a configuration file.

zip: Creating a package to upload to the Panther Console

To create a package for uploading manually to the Panther Console, run the following command:

Uploading content in the Panther Console

  1. In the lefthand side of the Panther Console, click Build > Bulk Uploader.

  2. Drag and drop your .zip file onto the page, or click Select file.

In the Panther Console's Bulk Uploader, you can drag and drop a zip file or select a file.

upload: Uploading packages to Panther directly

Starting with PAT version 0.22.0, if you have authenticated with an API token and execute the upload command, an asynchronous bulk upload will automatically be performed, to prevent timeout issues.

If you did not use an API token to authenticate, you can use the --batch option. The --batch option is only available in versions of PAT after 0.19.0.

To upload detections to your Panther instance using PAT:

  1. If you have not already, generate an API token in your Panther Console.

  2. Run panther_analysis_tool test to ensure your unit tests are passing.

  3. Run the following command: panther_analysis_tool upload --path <path-to-your-detections> --api-token <your-api-token> --api-host https://api.<your-panther-instance-name>.runpanther.net/public/graphql

    • You may exclude the --api-token and --api-host options if you are setting configuration values another way, i.e., by using environment variables or a configuration file.

When using upload, detections and Lookup Tables with existing IDs are overwritten. Locally deleted detections will not automatically be deleted in your Panther instance, and must be removed with the delete command (or by manually deleting them in your Panther Console). For CLI-driven workflows, it's recommended to set a detection's Enabled property to false, instead of deleting.

delete: Deleting Rules, Policies, or Saved Queries with PAT

While panther_analysis_tool upload --path <directory> will upload everything from <directory>, it will not delete anything in your Panther instance if you simply remove a local file from <directory>. Instead, you can use the panther_analysis_tool delete command to explicitly delete detections from your Panther instance. To delete a specific detection, you can run the following command:

This will interactively ask you for a confirmation before it deletes the detection. If you would like to delete without confirming, you can use the following command:

You can delete up to 1000 detections at once with PAT.

Permissions required per command

Below is a mapping of permissions required for each command.

Command
Required permission(s)

check-connection

Read Panther Settings Info

upload

Bulk Upload

delete

Manage Policies Manage Rules Manage Saved Queries

update-custom-schemas

View Log Sources Manage Log Sources

PAT command options (sub commands)

See the options for each of the PAT commands in the codeblock below.

--filter: Filtering PAT commands

The test, zip, upload, and release commands all support filtering. Filtering works by passing the --filter argument with a list of filters specified in the format KEY=VALUE1,VALUE2. The keys can be any valid field in a policy or rule. When using a filter, only analysis that matches each filter specified will be considered.

For example, the following command will test only items with the AnalysisType of policy AND the severity of High:

The following command will test items with the AnalysisType policy OR rule, AND the severity High:

When writing policies or rules that refer to the global analysis types, be sure to include them in your filter. You can include an empty string as a value in a filter, and it will mean the filter is only applied if the field exists.

The following command will return an error, because the policy in question imports a global but the global does not have a severity so it is excluded by the filter:

For this query to work as expected, you need to allow for the severity field to be absent:

Filters work for the zip, upload, and release commands in the same way they work for the test command.

In addition to filtering, you can set a minimum number of unit tests with the --minimum-tests flag. Detections that don't have the minimum number of tests will be considered failing, and if --minimum-tests is set to 2 or greater it will also enforce that at least one test must return True and one must return False.

In the example below, even though the rules passed all their tests, they're still considered failing because they do not have the correct test coverage:

PreviousInstall, Configure, and Authenticate with the Panther Analysis ToolNextManaging Lookup Tables and Enrichment Providers with the Panther Analysis Tool

Last updated

Was this helpful?