# 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/~/changes/15ann7vKLltCCAGHtdQr/panther-developer-workflows/ci-cd/deployment-workflows/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.9
  * To install Python 3.9 using [Homebrew](https://brew.sh/), run `brew install python3.9`.
* [Pipenv](https://pipenv.pypa.io/en/latest/)
  * To install Pipenv, run `pip install --user pipenv`. 

### Installing with pip

To install PAT, run this command:

```bash
pip3 install panther_analysis_tool
```

### 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 .
```

## 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 `AWS_TOKEN` argument can be passed in through an environment variable named `PANTHER_AWS_TOKEN`.

### 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

PAT requires an API token to authenticate against your Panther instance. Follow [these instructions](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/api#step-2-create-an-api-token) to generate an API token, taking note of the [required permissions per PAT command](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/panther-developer-workflows/ci-cd/deployment-workflows/pat-commands#permissions-required-per-command).

When running PAT commands that require an API token, such as `upload` and `delete`, you will pass it with the `--api-token` option, in addition to the `--api-host` option with the [GraphQL host](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/api#prerequisites).

Using an API token to authenticate with PAT means your PAT actions will be captured as [Panther Audit Logs](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/system-configuration/panther-audit-logs).

### 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/~/changes/15ann7vKLltCCAGHtdQr/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/~/changes/15ann7vKLltCCAGHtdQr/panther-developer-workflows/ci-cd/github-actions#prerequisites) and [Managing Panther Content via CircleCI](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/panther-developer-workflows/ci-cd/circle-ci#automate-upload-in-circleci-workflow).