Using the pypanther Command Line Tool

View, test, and upload V2 detections

Overview

The pypanther CLI tool is in closed beta starting with Panther version 1.108. Please share any bug reports and feature requests with your Panther support team.

Use the pypanther command line interface (CLI) tool to:

• View, test, and upload PyPanther Detections.

• Convert v1 detections to PyPanther Detections.

• View and upload schemas.

To get started using pypanther, follow the instructions in the pypanther-starter-kit's README. See the list of available CLI commands below, and note that some require authentication.

pypanther CLI command reference

Find out more about each command by passing the --help argument (or -h).

Command	How it works	Required API permission(s)
list	Lists locally defined detections and schemas.	None
get	Gets the attributes of locally defined detections and schemas.	None
test	Runs detection tests locally. Learn more in Running tests.	None
upload	Uploads local detections and schemas to Panther. Learn more in Uploading PyPanther Detections to Panther and Uploading schemas to Panther The default schemas path is content/schemas Warning: In order to use the pypanther upload functionality, it must first be enabled for you. If you would like to upload detections, please reach out to your Panther Support team.	Bulk Upload Manage Log Sources (if uploading schemas)
convert	Converts v1 rules and helpers into PyPanther format. Learn more in Using convert, below.	None

Authenticating CLI commands

Certain pypanther CLI commands, like upload, require authentication with your Panther instance. This means they require a valid Panther API host URL and API token. After you locate/generate these values, you will make them visible to pypanther.

Step 1: Locate/generate your Panther API host URL and token

• Panther API host URL: Follow these instructions to locate your GraphQL API URL.

• Panther API token: Follow these instructions to generate an API token, being sure to attach any permissions required by the pypanther commands you'd like to use. See the Required API permission(s) column in the table above.

Step 2: Make API host and token values visible to pypanther

Once you have API host and token values, you can choose how to expose them to pypanther when you are executing a CLI command. The following methods are in order of precedence, meaning option one overrides option two:

1. Pass the host and token on the command line using --api-token and --api-host.

2. Set the host and token as environment variables using PANTHER_API_TOKEN and PANTHER_API_HOST.

Uploading schemas to Panther

In addition to using pypanther upload to upload PyPanther Detections to Panther, you can also upload custom data schemas (used for custom log types and Lookup Tables). When you run the upload command, pypanther looks in /content/schemas for schemas to upload.

pypanther supports uploading YAML schemas defined according to the How to define a custom schema instructions.

Using convert

The pypanther convert command converts v1 rules and helpers into PyPanther format.

The convert command does not output a main.py file. You must create this yourself. Learn more about what to include in main.py content recommendations.

When converting a v1 rule, convert first checks whether it is custom or Panther-managed (by looking at its RuleId). If it's a custom rule, convert creates a straightforward translation of the rule.

If it's a Panther-managed rule, convert attempts to make as minimal of an override as possible. This means:

• If there have only been modifications to the Panther-managed rule's attributes (i.e., the fields stored in the YAML file in v1), and not to its alert functions, the Panther-managed rule is overridden using override to make the same customization(s) in PyPanther.

  • The overrides are made in an apply_overrides function inside a log type-specific file that is stored in an overrides directory.

• If there have been modifications made to any of the Panther-managed rule's alert functions, a rule is created that subclasses the Panther-managed rule. The subclassed rule defines all alert functions that were modified in v1 (in addition to any modified attributes).

  • The subclassed rule is created in a new file inside the rules directory.