# Panther Analysis Tool 설치, 구성 및 인증하기

## 개요

Panther Analysis Tool(PAT)을 사용하여 Panther 자산을 관리하기 전에(예: 명령줄이나 CI/CD 파이프라인에서) 다음을 수행해야 합니다. [설치하기](#installing-pat), [구성 값 제공하기](#configuring-pat), 그리고 [인증용 API 토큰 생성하기](#authenticating-with-an-api-token). 이러한 단계를 완료한 후에는 다음을 실행하기 시작하세요. [PAT 명령어](https://docs.panther.com/ko/panther/detections-repo/pat/pat-commands).

PAT의 새 버전이 릴리스되면 다음을 수행할 수 있습니다. [PAT 업데이트](#updating-pat).

## PAT 설치

### 사전 요구 사항

PAT를 설치하려면 환경에 다음이 이미 설치되어 있어야 합니다:

* **Python 3.11**. 다음 방법 중 하나를 사용하여 Python을 설치하세요:
  * 다음의 다운로드 링크 [공식 릴리스 페이지](https://www.python.org/downloads/release/python-3119/)
  * 을 사용하여 [Homebrew](https://brew.sh/)에서 다음을 실행하여 `brew install python@3.11`
  * 을 사용하여 [pyenv](https://github.com/pyenv/pyenv) 를 사용하여 Python 버전을 관리합니다
* **Pipenv**. 다음을 설치하려면 [Pipenv](https://pipenv.pypa.io/en/latest/)다음을 실행하세요. `pip install --user pipenv`.

### pip를 사용한 설치

PAT를 설치하려면 다음 명령을 실행하세요:

Mac 및 Linux:

```bash
pip3 install panther_analysis_tool
```

Windows(Powershell):

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

<details>

<summary>Windows에서 PAT를 PATH에 추가하기</summary>

Windows에서는 PAT를 설치해도 자동으로 `PATH` 변수에 추가되지 않아 명령줄에서 PAT를 올바르게 사용할 수 없을 수 있습니다.

설치 시 다음 경고 메시지가 표시되면 PATH 환경 변수를 수동으로 수정해야 합니다.

{% code overflow="wrap" %}

```powershell
경고: 스크립트 panther_analysis_tool.exe 및 pat.exe가 'C:\Users\<USERNAME>\AppData\Local\Programs\Python\Python313\Scripts'에 설치되었지만, 이 위치가 PATH에 없습니다.
이 디렉터리를 PATH에 추가하거나, 이 경고를 표시하지 않으려면 --no-warn-script-location을 사용하세요.
```

{% endcode %}

이를 해결하려면 다음 명령을 실행하세요:

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

반드시 다음을 `<SCRIPT_PATH>` 오류 메시지에 언급된 경로로 바꾸세요. 오류 메시지를 읽을 수 없는 경우 다음 명령을 실행하여 이 경로를 얻을 수도 있습니다:

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

완료한 후에는 변경 사항이 적용되도록 터미널을 다시 시작하세요. 다음을 실행하여 성공했는지 확인할 수 있습니다. `pat --version`; 버전 번호가 반환되면 성공한 것입니다

</details>

### 소스에서 빌드

개발상의 이유로 소스에서 직접 실행하고 싶다면 먼저 환경을 설정하세요:

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

### 가상 환경 밖에서 PAT 사용하기

가상 환경 밖에서 PAT를 사용하고 싶다면, 직접 설치하세요:

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

### PAT CLI 별칭

PAT는 다음 별칭으로 설치됩니다. PAT 명령어에서는 둘 중 아무거나 사용할 수 있습니다:

* `panther_analysis_tool`
* `pat`

예시

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

## PAT 업데이트

다음을 사용 중인 경우 `pipenv` 를 사용해 종속성을 관리하고 있다면, 아래 단계에 따라 PAT를 업데이트하세요:

1. PAT를 최신 버전으로 업데이트하세요. `Pipfile`.
2. 다음 실행 `pipenv install --dev`.

또는 다음 명령을 실행하여 PAT를 업데이트할 수 있습니다:

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

## PAT 구성

PAT는 명령줄, 환경 변수 또는 구성 파일에서 구성 값을 읽을 수 있습니다.

### 구성 값 우선순위

플래그 값 소스의 우선순위는 다음과 같습니다(높음에서 낮음 순):

1. 명령어로 전달된 값
2. [환경 변수](#environment-variables)
3. [구성 파일](#pat-configuration-file)

### 환경 변수

모든 옵션은 변수 이름 앞에 다음을 붙여 환경 변수를 통해 전달할 수 있습니다. `PANTHER_.`

예를 들어 다음과 같습니다. `api_token` 및 `api_host` 인수는 다음과 같은 이름의 환경 변수를 통해 설정할 수 있습니다. `PANTHER_API_TOKEN` 및 `PANTHER_API_HOST`.

### PAT 구성 파일

PAT는 다음이라는 구성 파일에서 옵션을 읽습니다. `.panther_settings.yml` 작업 디렉터리에 위치합니다. 예제 구성 파일이 이 저장소에 포함되어 있습니다: [example\_panther\_config.yml](https://github.com/panther-labs/panther_analysis_tool/blob/master/example_panther_config.yml). 지원되는 옵션의 예제 구문이 들어 있습니다.

## API 토큰으로 인증하기

대부분의 PAT 명령어는 API 토큰을 사용해 Panther 인스턴스에 대한 인증이 필요합니다. 인증된 PAT 작업은 다음과 같이 기록됩니다. [Panther 감사 로그](https://docs.panther.com/ko/data-onboarding/supported-logs/panther-audit-logs).

1. 다음을 따르세요 [API 토큰을 생성하기 위한 이 지침](https://docs.panther.com/ko/api#how-to-create-a-panther-api-token).
   * 다음을 확인해 두세요. [PAT 명령어별 필수 권한](https://docs.panther.com/ko/panther/detections-repo/pat-commands#permissions-required-per-command).
2. 토큰을 검증하려면 다음을 실행하세요. `pipenv run pat check-connection --api-token <your-api-token> --api-host <your-api-host>`.
   * 다음을 참조하세요 [여기에서 토큰을 검증하는 추가 방법](https://docs.panther.com/ko/api#validating-your-api-token).
3. API 토큰이 필요한 PAT 명령어를 실행할 때는 API 토큰(및 [GraphQL 호스트](https://docs.panther.com/ko/api/graphql#step-1-identify-your-panther-graphql-api-url))가 다음 중 하나를 통해 PAT가 볼 수 있도록 설정되어 있는지 확인하세요. [구성 옵션](#configuring-pat).
   * API 토큰과 호스트 값을 전달하는 가장 간단한 방법은 명령어를 사용하는 것입니다. 즉, 다음을 사용합니다. `--api-token` 및 `--api-host`.

### API 토큰 순환

토큰은 만료되지 않습니다. 보안 모범 사례로서 API 토큰을 정기적으로 순환할 것을 권장합니다. 지침은 다음을 참조하세요. [API 토큰 회전](https://docs.panther.com/ko/api#rotating-api-tokens).

### 비밀로서 API 토큰 관리

CI/CD 작업에서 PAT를 사용하는 경우, CI/CD 제공업체의 지침에 따라 API 토큰을 비밀로 관리하는 방법을 반드시 따르세요. 자세한 내용은 다음을 참조하세요. [GitHub Actions를 통한 Panther 콘텐츠 관리](https://docs.panther.com/ko/panther/ci-cd/deployment-workflows/github-actions#prerequisites) 및 [CircleCI를 통한 Panther 콘텐츠 관리](https://docs.panther.com/ko/panther/ci-cd/deployment-workflows/circle-ci#automate-upload-in-circleci-workflow).