# Install, Configure, and Authenticate with the Panther Analysis Tool

## Overview

Before using the Panther Analysis Tool (PAT) to manage your Panther assets (on your command line or in a CI/CD pipeline, for example), you'll need to [install it](#installing-pat), [provide configuration values](#configuring-pat), and [generate an API token to authenticate](#authenticating-with-an-api-token). Once you've completed these steps, start running [PAT Commands](https://docs.panther.com/panther-developer-workflows/detections-repo/pat/pat-commands).

When new versions of PAT are released, you can [update PAT](#updating-pat).

## Installing PAT

### Prerequisites

To install PAT, your environment must have the following already installed:

* **Python 3.11**. Install Python using one of the following methods:
  * The download links on the [official release page](https://www.python.org/downloads/release/python-3119/)
  * Using [Homebrew](https://brew.sh/), by running `brew install python@3.11`
  * Using [pyenv](https://github.com/pyenv/pyenv) to manage Python versions
* **Pipenv**. To install [Pipenv](https://pipenv.pypa.io/en/latest/), run `pip install --user pipenv`.

### Installing with pip

To install PAT, run this command:

Mac and Linux:

```bash
pip3 install panther_analysis_tool
```

Windows (Powershell):

```powershell
py -m pip install panther_analysis_tool
```

<details>

<summary>Adding PAT to your PATH in Windows</summary>

On Windows, it's possible that installing PAT doesn't automatically add it to your `PATH` variable, meaning you can't use PAT properly on the command line.

If your installation gives you the following warning message, then you'll need to manually correct your PATH environment variable.

{% code overflow="wrap" %}

```powershell
WARNING: The scripts panther_analysis_tool.exe and pat.exe are installed in 'C:\Users\<USERNAME>\AppData\Local\Programs\Python\Python313\Scripts' which is not on PATH.
Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
```

{% endcode %}

To resolve this, run the following command:

```powershell
[System.Environment]::SetEnvironmentVariable("Path", $env:Path + ";<SCRIPT_PATH>", [System.EnvironmentVariableTarget]::User)
```

Be sure to replace `<SCRIPT_PATH>` with the path mentioned in the error message. If you cannot read the error message, you can also get this path by running the following command:

```powershell
py -c "import sysconfig; print(sysconfig.get_path('scripts'))"
```

Once finished, restart your terminal to let the changes take place. You can confirm if you were successful by running `pat --version`; if a version number is returned, then it worked

</details>

### Building from source

If you'd prefer instead to run from source for development reasons, first set up your environment:

```
$ make install
$ pipenv run -- pip3 install -e .
```

### Using PAT outside of the virtual environment

If you would rather use PAT outside of the virtual environment, install it directly:

```
$ make deps
$ pip3 install -e .
```

### PAT CLI aliases

PAT will be installed under the following aliases—either can be used with PAT commands:

* `panther_analysis_tool`
* `pat`

Examples

```
$ pipenv run panther_analysis_tool test
...
$ pipenv run pat upload
...
```

## Updating PAT

If you are using `pipenv` to manage dependencies, follow the below steps to update PAT:

1. Update PAT to the latest version in your `Pipfile`.
2. Run `pipenv install --dev`.

Alternatively, you can update PAT by running the following command:

```
$ pip3 install panther_analysis_tool --upgrade
```

## Configuring PAT

PAT can read configuration values from the command line, environment variables, or a configuration file.

### Configuration value precedence

The precedence for flag value sources is as follows (highest to lowest):

1. Values passed with the command
2. [Environment variables](#environment-variables)
3. [Configuration file](#pat-configuration-file)

### Environment variables

All options can be passed in through environment variables by prepending the variable name with `PANTHER_.`

For example, the `api_token` and `api_host` arguments can be set through environment variables named `PANTHER_API_TOKEN` and `PANTHER_API_HOST`.

### PAT configuration file

PAT will read options from a configuration file called `.panther_settings.yml` located in your working directory. An example configuration file is included in this repo: [example\_panther\_config.yml](https://github.com/panther-labs/panther_analysis_tool/blob/master/example_panther_config.yml). It contains example syntax for supported options.

## Authenticating with an API token

Most PAT commands require authentication against your Panther instance using an API token. Authenticated PAT actions are captured as [Panther Audit Logs](https://docs.panther.com/data-onboarding/supported-logs/panther-audit-logs).

1. Follow [these instructions to generate an API token](https://docs.panther.com/api#how-to-create-a-panther-api-token).
   * Take note of the [required permissions per PAT command](https://docs.panther.com/panther-developer-workflows/detections-repo/pat-commands#permissions-required-per-command).
2. To validate your token, run `pipenv run pat check-connection --api-token <your-api-token> --api-host <your-api-host>`.
   * See [an additional way to validate your token here](https://docs.panther.com/api#validating-your-api-token).
3. When running PAT commands that require an API token, be sure your API token (and [GraphQL host](https://docs.panther.com/api/graphql#step-1-identify-your-panther-graphql-api-url)) are visible to PAT via one of the [configuration options](#configuring-pat).
   * The simplest way to pass API token and host values is with the command, i.e., using `--api-token` and `--api-host`.

### Rotating the API token

The token does not expire. As a security best practice, we recommend regularly rotating your API token. For instructions, see [Rotating API tokens](https://docs.panther.com/api#rotating-api-tokens).

### Managing your API token as a secret

If you are using PAT in CI/CD jobs, be sure to follow your CI/CD provider's instructions on how to manage your API token as a secret—as described on [Managing Panther Content via GitHub Actions](https://docs.panther.com/panther-developer-workflows/ci-cd/deployment-workflows/github-actions#prerequisites) and [Managing Panther Content via CircleCI](https://docs.panther.com/panther-developer-workflows/ci-cd/deployment-workflows/circle-ci#automate-upload-in-circleci-workflow).