# Panther API

## 개요

Panther는 [REST API](https://docs.panther.com/ko/panther/api/rest) 와 [GraphQL-over-HTTP API](https://docs.panther.com/ko/panther/api/graphql)를 제공합니다. 다음을 사용할 수 있습니다: [API Playground](https://docs.panther.com/ko/panther/api/api-playground) Panther Console에서 두 API를 모두 살펴볼 수 있습니다. API 호출을 하기 전에 다음을 해야 합니다: [API 토큰 생성](#how-to-create-a-panther-api-token).

다음을 확인하세요: [REST API 스키마는 여기에서](https://docs.panther.com/ko/panther/rest#discover-the-panther-rest-api-schema)와, [GraphQL 스키마는 여기에서](https://docs.panther.com/ko/panther/graphql#discover-the-panther-graphql-schema).

### 지원되는 작업

Panther API는 보안 워크플로를 구축할 수 있도록 지원하는, 계속 늘어나는 작업 집합을 제공합니다:

| <p><a href="api/rest">REST API</a></p><ul><li><a href="api/rest/alerts">알러트</a></li><li><a href="api/rest/alert-comments">알러트 댓글</a></li><li><a href="api/rest/api-tokens">API 토큰</a></li><li><a href="api/rest/data-models">데이터 모델</a></li><li><a href="api/rest/globals">글로벌</a></li><li><a href="api/rest/log-sources">로그 소스</a></li><li><a href="api/rest/queries">쿼리</a></li><li><a href="api/rest/roles">역할</a></li><li><a href="api/rest/rules">룰</a></li><li><a href="api/rest/scheduled-rules">예약된 룰</a></li><li><a href="api/rest/simple-rules">단순 룰</a></li><li><a href="api/rest/policies">정책</a></li><li><a href="api/rest/users">사용자</a></li></ul> | <p><a href="api/graphql">GraphQL API</a></p><ul><li><a href="api/graphql/alerts-and-errors">알러트 및 오류</a></li><li><a href="api/graphql/cloud-account">클라우드 계정 관리</a></li><li><a href="api/graphql/data-lake-queries">데이터 레이크 쿼리</a></li><li><a href="api/graphql/log-source">로그 소스 관리</a></li><li><a href="api/graphql/metrics">메트릭</a></li><li><a href="api/graphql/token-rotation">토큰 회전</a></li><li><a href="api/graphql/user-management">사용자 및 역할 관리</a></li></ul> |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

## Panther API 토큰을 만드는 방법

{% hint style="info" %}
API 토큰을 성공적으로 만든 후에는 주기적으로 회전하는 것을 잊지 마세요. 다음에서 토큰 회전에 대한 안내를 확인하세요: [API 토큰 회전](#rotating-api-tokens)아래.
{% endhint %}

1. Panther Console 오른쪽 상단에서 톱니바퀴 아이콘을 클릭한 다음, 드롭다운 메뉴에서 **API 토큰**.
2. 클릭하세요 **API 토큰 만들기**.\
   ![The image shows the API Tokens page in the Panther Console. The screen says "You haven't created any tokens yet" and there is a red circle around the "Create an API Token" button at the bottom.](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-6511f9015708889e31e3d89330e242c7add6f347%2Fcreate-api-token.png?alt=media)
   * 이미 토큰이 있다면, **새 토큰 만들기**.
3. 다음을 입력하세요: **이름**그런 다음 이 토큰에 부여할 권한을 선택하세요.
   * 각 [REST API](https://docs.panther.com/ko/panther/api/rest) 엔터티 페이지에서 각 작업에 필요한 권한을 찾을 수 있습니다. 자세한 내용은 다음을 참조하세요: [Console 및 API의 권한 이름](https://app.gitbook.com/s/-LgdiSWdyJcXPahGi9Rs-2910905616/system-configuration/rbac#permission-names-in-the-console-and-api) 추가 정보를 확인하세요.
   * 다음을 참조하세요: [각 Panther Analysis Tool(PAT) 명령에 필요한 권한은 여기에서 확인하세요](https://docs.panther.com/ko/detections-repo/pat/pat-commands#permissions-required-per-command).
4. 다음에서 **IP 제한** 섹션의 **CIDR 블록** 필드에, 필요하다면 토큰 사용을 제한할 하나 이상의 IP 주소를 입력하세요.
   * IP 주소를 CIDR 표기법으로 입력하세요. 예: `10.0.0.0/8` 또는 `8.8.8.8/32`.
   * IP 주소를 지정하지 않으면, 이 토큰은 모든 IP 주소에서 사용할 수 있습니다.
5. 클릭하세요 **API 토큰 만들기**.
   * API 토큰 값이 표시된 성공 화면이 나타납니다. API 토큰은 다시 표시되지 않으므로 복사해서 안전한 위치에 저장하세요.
   * 선택적으로 [새 API 토큰이 작동하는지 검증하세요](#validating-your-api-token).

<figure><img src="https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-4423f59a4073abef61f1299ccef13eb76908cf7e%2Fapi-token-success.png?alt=media" alt="The image shows the success screen after you create an API Key. At the top, it says &#x22;API Key Created&#x22;. There is a drawing of two people holding up a green checkmark. The API Key in this screen shot is blurred out. Beneath the key there is a blue button labeled &#x22;Done.&#x22;" width="375"><figcaption></figcaption></figure>

### API 토큰 검증

{% hint style="info" %}
API 토큰을 추가한 후 30\~60초 정도 전파 지연이 있을 수 있습니다.
{% endhint %}

API 토큰을 생성한 후에는 API Playground 또는 PAT를 사용하여 작동하는지 검증할 수 있습니다:

{% tabs %}
{% tab title="API Playground" %}
Panther Console의 API Playground에서 API 토큰을 테스트하려면:

1. API 토큰 생성 성공 화면에서 **Playground에서 직접 사용해 보기**.
2. Playground 화면의 왼쪽 하단에서 **REQUEST HEADERS** 탭을 찾으세요. 이 탭에서 `X-API-Key` 헤더의 기본값을 `<ENTER_YOUR_KEY_HERE>` 에서 API 토큰 값으로 변경하세요.
3. 왼쪽 상단에서 "재생" 아이콘을 눌러 테스트를 실행하세요.

<figure><img src="https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-582a7060d464c576c0aed9616742b86a09c434f0%2Fapi-playground-test.png?alt=media" alt="The image shows the API Playground from the Panther Console. At the top, a play icon button is circled. On the left, a code box contains an example query. Beneath that, the header &#x22;Request Header&#x22; is circled. On the right, there is a section labeled &#x22;Documentation Explorer&#x22;." width="563"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="PAT" %}
{% hint style="warning" %}
이 테스트를 수행하려면 [PAT가 설치되어 있어야 합니다](https://docs.panther.com/ko/panther/detections-repo/pat/install-configure-and-authenticate-with-pat) 를 사용하여 이 테스트를 수행하려면
{% endhint %}

CLI에서 API 토큰을 테스트하려면 [PAT](https://docs.panther.com/ko/panther/detections-repo/pat) 다음 명령을 실행하세요:

* 실행 `pipenv run pat check-connection --api-token <your-api-token> --api-host <your-api-host>`.
  {% endtab %}
  {% endtabs %}

### API 토큰 회전

API 토큰은 Panther의 공개 API에 대한 인증 및 접근 권한 부여에 사용됩니다. 사용자 이름과 비밀번호 자격 증명과 마찬가지로, 악의적인 행위자로부터 보호하기 위해 API 토큰을 안전하게 저장해야 합니다. 토큰을 주기적으로 회전하면 유출될 가능성을 줄일 수 있습니다. 인터넷 보안 센터(CIS)와 미국 국립표준기술연구소(NIST)는 API 토큰을 90일마다 회전할 것을 권장합니다.

Panther Console에서 또는 Panther의 API 자체를 호출하여 API 토큰을 회전할 수 있습니다. 토큰을 회전하면 이전 토큰은 더 이상 유효하지 않습니다.

{% tabs %}
{% tab title="Panther Console" %}
**Panther Console에서 API 토큰 회전**

Panther Console에서 API 토큰을 회전하려면:

1. Panther Console 오른쪽 상단에서 톱니바퀴 아이콘을 클릭한 다음 **API 토큰**.
2. 회전하려는 토큰을 찾으세요. 해당 타일의 오른쪽 상단에서 점 3개 아이콘을 클릭한 다음 **회전**.

   <figure><img src="https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-a17f7880972eb50956000279065985b90c4009fb%2FScreenshot%202023-03-20%20at%204.04.13%20PM.png?alt=media" alt="The API Tokens page in the Console shows a token called &#x22;Example Key.&#x22; It has info about who created and modified the token, as well as when it expires. The three dot menu is open, and three options are displayed: Edit, Rotate, and Delete."><figcaption></figcaption></figure>
3. 팝업되는 확인 모달에서 **계속**.\
   ![A modal titled "Rotate Example Key" asks the user if they're sure they want to refresh the key. There are Cancel and Continue buttons.](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-e7fe0900e45eccbd7a71179e4071eaee7c82302a%2FScreenshot%202023-03-20%20at%204.08.06%20PM.png?alt=media)
4. 모달에 새 API 토큰이 표시됩니다. 이 값은 한 번만 볼 수 있으므로 반드시 복사하여 안전한 위치에 저장하세요.\
   ![The key rotation modal displays the new API token. There is a note saying "Please copy it since we won't show it to you again."](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-67d6889800e340412502f08b6b1eca823fa12183%2FScreenshot%202023-03-20%20at%204.09.52%20PM.png?alt=media)
   {% endtab %}

{% tab title="REST API" %}
**Panther REST API를 사용하여 API 토큰 회전**

Panther REST API를 사용하여 API 토큰을 회전할 수 있습니다. API 토큰은 다음을 사용해 자체적으로 회전합니다: `POST api-tokens/self/rotate` 엔드포인트. 자세한 내용은 다음에서 확인하세요: [API 토큰](https://docs.panther.com/ko/panther/api/rest/api-tokens).
{% endtab %}

{% tab title="GraphQL API" %}
**Panther GraphQL API를 사용하여 API 토큰 회전**

Panther GraphQL API를 사용하여 API 토큰을 회전할 수 있으며, 다음을 사용합니다: `rotateAPIToken` 작업. 이 엔드포인트 사용 방법에 대해 자세히 알아보세요: [토큰 회전](https://docs.panther.com/ko/panther/api/graphql/token-rotation).
{% endtab %}
{% endtabs %}

## Panther API 문제 해결

Panther 지식 베이스를 방문하여 [Panther API에 대한 문서를 확인하세요](https://help.panther.com/Panther_Developer_Workflows/Panther_API) 자주 묻는 질문에 답하고 일반적인 오류와 문제를 해결하는 데 도움이 됩니다.