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. You can also use it to convert v1 detections to PyPanther Detections. 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
pypanther
CLI command referencelist rules
By default, lists registered rules and their attributes in a table for easy viewing. If the optional --managed
flag is provided, lists Panther-managed rules
To see a full list of command options, run $ pypanther list rules --help
None
get rule $RULE_ID
Gets the attributes of a single rule. Can also retrieve the original class definition
To see a full list of command options, run $ pypanther get rule --help
None
test
Learn more in Running tests.
To see a full list of command options, run $ pypanther test --help
None
upload
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.
Learn more in Uploading PyPanther Detections to Panther.
To see a full list of command options, run $ pypanther upload --help
Bulk Upload
convert
Converts v1 rules and helpers into PyPanther format. Learn more in Using convert
, below.
To see a full list of command options, run $ pypanther convert --help
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
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:
Pass the host and token on the command line using
--api-token
and--api-host
.Set the host and token as environment variables using
PANTHER_API_TOKEN
andPANTHER_API_HOST
.
Using convert
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 anoverrides
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.
Last updated