search
Knowledge BaseRelease NotesRequest Demo

Panther Analysis Tool Commands

Use PAT to manage your Panther content

hashtag
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.

hashtag
PAT commands

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

PAT commands can be run using panther_analysis_tool or pat. Learn more about these aliases here.

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] [--skip-version-check] {release,test,publish,upload,delete,update-custom-schemas,test-lookup-table,validate,zip,check-connection,benchmark,enrich-test-data} ...

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,benchmark,enrich-test-data}
    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.
    debug               Run a single rule test in a debug environment, which allows you to see print statements and use breakpoints.
    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
    benchmark           Performance test one rule against one of its log types. The rule must be the only item in the working directory or specified by --path, --ignore-files, and --filter. This feature is an extension
                        of Data Replay and is subject to the same limitations.
    enrich-test-data    Enrich test data with additional enrichments from the Panther API.

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --debug
  --skip-version-check

hashtag
test: Running unit tests

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

To filter rules or policies based on certain attributes:

circle-info

Running pat test for correlation rules and Simple Detections requires an API token. See Authenticating with an API token for more information.

hashtag
debug: Debug a test using print statements and breakpoints

Use debug to run a specific unit test in debug mode:

See print statements:

See your errors with traceback info:

hashtag
benchmark: Evaluating rule performance

You can use benchmark to test the performance of an existing or draft rule against one hour of data, for one log type. It can be particularly useful to iterate on a rule that is timing out. This is a long-running command intended to be used manually, as needed—not in a regular CI/CD workflow.

The API token used with this command must be granted the "Read Panther Metrics" (also known as SummaryRead) and "Manage Rules" (also known as RuleModify) permissions. Because benchmark is an extension of Data Replay, it is subject to the same limitations.

You must provide a single rule to benchmark, either by having just one rule in the working directory (./ or --path), or through the use of --ignore-files or --filter.

If you do not specify a certain hour of data, the system will select the historical hour with the highest volume of data. To specify a specific hour to run against, use --hour. (Most common time formats are supported, e.g., 2023-07-31T09:00:00-7:00—minutes, seconds, etc. will be truncated). For example:

For a rule with multiple log types, one must be specified using --log-type. For example:

The output of benchmark will be written to both stdout, and to the directory indicated by the --out option.

hashtag
enrich-test-data: Enriching test data with Enrichment content

Use enrich-test-data to enrich the test content of your Rules and Scheduled Rules with data from connected Enrichment providers and custom Lookup Tables. This allows you to build more sophisticated test cases for detections that rely on enrichment content.

enrich-test-data is simple to use, but may introduce substantial changes to your analysis YAML files. The command will modify files based on the following criteria:

  • If the Rule or Scheduled Rule does not have test cases, the YAML file will not be modified.

  • If the log type does not support enrichment, the YAML file will not be modified.

  • If the log type supports enrichment and there are test cases:

    • Test cases represented as inline JSON content will be reformatted into YAML.

    • The YAML file will be formatted according to common YAML conventions, using two spaces for indentation.

Similar to other commands, enrich-test-data works from the current directory, recursively. If you run the command at the root directory of your panther-analysis copy, it will attempt to enrich all Rules and Scheduled Rules. To enrich content in a single directory, navigate to that directory before running the command.

You can run enrich-test-data in PAT versions 0.26 and beyond using the following command:

The output of the command will be written to stdout, including a list of any Rules or Scheduled Rules that were enriched.

hashtag
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:

    {% code fullWidth="false" %}

    {% endcode %}

    • 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.

hashtag
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:

hashtag
Uploading content in the Panther Console

  1. In the lefthand side of the Panther Console, click Detections.

  2. Click the Upload button in the upper right corner.

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

hashtag
upload: Uploading packages to Panther directly

circle-info

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.

The upload command uploads your detection content to your Panther instance.

To use upload:

  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 on upload—they must be removed with the delete command (or manually deleted in your Panther Console). When using the CLI workflow, it's recommended to set a detection's Enabled property to false, instead of deleting.

If you update the ID of an entity (i.e., the value of RuleId or PolicyId) and use upload—but do not also use delete to manually remove the old entity, both versions will exist in your Panther instance. If you intend to update the ID without creating a duplicate detection, use delete with the old ID.

hashtag
The CreatedBy detection field

By default, detections uploaded in the CLI workflow (i.e., with PAT or via the REST API) are shown on the Detections list page in the Panther Console as created by Panther:

A table with headers and one row is shown. A header/row value pair (Created By / Panther) is circled.

If you'd like to customize the Created By value for a detection uploaded in the CLI workflow, you can add a CreatedBy key to your detection's YAML file. The value of CreatedBy can be:

  • A Panther user's email address: in the Console, the Created By field will show the associated user.

  • A Panther user's unique ID: in the Console, the Created By field will show the associated user.

  • An arbitrary text value: in the Panther Console, the provided value will be displayed with (External) appended to it.

    A table with headers and four row values is shown. A "Created By" column with the values in the first three rows is circled.

The CreatedBy key can be used in definitions for Python rules, scheduled rules, correlation rules, simple detections, and policies.

If you download a detection from the Panther Console:

  • If it was created in the Panther Console, it will not contain CreatedBy.

  • If it was uploaded in the CLI workflow:

    • With CreatedBy, it will contain CreatedBy.

    • Without CreatedBy, it will not contain CreatedBy.

hashtag
delete: Deleting Rules, Policies, or Saved Queries

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.

hashtag
update-custom-schemas: Creating or updating custom schemas

Use update-custom-schemas to create or update custom schemas.

circle-exclamation

After using this command to create a schema, wait at least 15 minutes before using upload to upload detections that reference the new schema.

hashtag
Permissions required per command

Below is a mapping of permissions required for each command.

Command
Required permission(s)

check-connection

Read Panther Settings Info

test (when testing detections that use Inline Filtersarrow-up-right)

Bulk Upload OR Bulk Upload Validate OR View Rules

benchmark

Read Panther Metrics

validate

Bulk Upload Validate OR Bulk Upload

upload

Bulk Upload

delete

Manage Policies Manage Rules Manage Saved Searches

update-custom-schemas

View Log Sources Manage Log Sources

hashtag
PAT command options

Each PAT command has options (also known as flags), which you can view by running $ pat <command> -h.

chevron-rightExample output of pat test -hhashtag

If an option takes multiple arguments, you must pass each value individually with the option. For example, to pass two arguments to --valid-table-names:

  • Correct: --valid-table-names table1 --valid-table-names table2

  • Incorrect: --valid-table-names table1 table2

If a multi-argument option accepts values in the format KEY=VALUE1,VALUE2 (like --filter), each one must be passed to the flag separately (though the argument's value can still be represented as a comma-separated array). For example:

  • Correct: --filter AnalysisType=policy,rule --filter Severity=High

  • Incorrect: --filter AnalysisType=policy,rule Severity=High

hashtag
--filter: Filtering PAT commands

The test, zip, upload, and release commands all support filtering. Filtering works by passing the --filter flag 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 types 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 type, 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, we 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.

hashtag
--minimum-tests: Requiring a certain number of unit tests

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. 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 each of the rule tests passed, they're still considered failing because they do not have the correct test coverage:

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

Last updated

Was this helpful?