# 사용자 지정 보강

## 개요

커스텀 엔리치먼트(“Lookup Tables”라고도 함)를 사용하면 Panther에 커스텀 엔리치먼트 데이터를 저장하고 참조할 수 있습니다. 즉, 이 추가된 컨텍스트를 디택션에서 참조하고 알러트로 전달할 수 있습니다. 특히 신원/자산 정보, 취약점 컨텍스트 또는 네트워크 맵을 포함하는 커스텀 엔리치먼트를 만드는 데 유용할 수 있습니다.

다음이 있습니다[ 네 가지 가져오기 방법 옵션](#how-to-configure-a-custom-enrichment): Scheduled Search, 정적 파일, S3 버킷 또는 Google Cloud Storage(GCS) 버킷입니다.

커스텀 엔리치먼트와 하나 이상의 로그 유형을 연결할 수 있으며, 그러면 해당 유형의 모든 수신 로그(엔리치먼트 테이블 값과 일치하는 로그)는 엔리치먼트 데이터를 포함하게 됩니다. 엔리치먼트 프로세스에 대해 자세히 알아보려면 [수신 로그가 엔리치되는 방식](#how-incoming-logs-are-enriched)을(를) 참조하세요. 또한 다음을 수행할 수도 있습니다 [Python 디택션에서 엔리치먼트 데이터를 동적으로 참조](#option-2-dynamically-using-lookup). 다음 방법을 알아보세요 [저장된 엔리치먼트 데이터 보기 여기](https://docs.panther.com/ko/enrichment/..#viewing-and-managing-enrichments), 그리고 다음을 [엔리치먼트 데이터가 있는 로그 이벤트 보기 여기](https://docs.panther.com/ko/enrichment/..#viewing-log-events-with-enrichment-data).

데이터가 몇 개의 특정 디택션에만 필요하고 자주 업데이트되지 않는다면, 엔리치먼트 대신 [Global helpers](https://docs.panther.com/writing-detections/globals) 를 사용하는 것을 고려하세요. 또한 다음을 사용할 수 있습니다 [Panther에서 관리하는 엔리치먼트](https://docs.panther.com/ko/enrichment/..#panther-managed-lookup-tables) IPinfo 및 Tor Exit Nodes와 같은 것.

커스텀 엔리치먼트 수 및/또는 엔리치먼트 테이블 크기 제한을 늘리려면 Panther 지원 팀에 문의하세요.

## 수신 로그가 엔리치되는 방식

Panther의 엔리치먼트는 전통적으로 다음 두 가지를 모두 정의합니다:

* 기본 키: 엔리치먼트 테이블 데이터의 필드.
  * 엔리치먼트가 CLI 워크플로에서 정의된 경우, 이는 다음으로 지정됩니다 `PrimaryKey` 필드 내의 [YAML 구성 파일](https://docs.panther.com/ko/enrichment/custom/lookup-table-specification-reference).
* 연결된 하나 이상의 로그 유형, 각각 하나 이상의 Selector 포함: Selector는 이벤트 필드로, 해당 값이 엔리치먼트 테이블의 기본 키 값과 비교되어 일치 항목을 찾습니다.
  * 엔리치먼트에 로그 유형/Selector를 설정하는 방법은 두 가지가 있습니다. 아래의 [엔리치먼트에 대해 로그 유형과 Selector가 설정되는 방식](#how-log-types-and-selectors-are-set-for-a-lookup-table)를 참조하세요.

로그가 Panther로 수집될 때, 해당 로그 유형이 엔리치먼트와 연결된 유형이라면 모든 Selector 필드 값이 엔리치먼트의 기본 키 값과 비교됩니다. Selector 필드의 값과 기본 키 값이 일치하면, 로그는 일치한 기본 키와 연결된 엔리치먼트 데이터로 다음의 형태로 엔리치됩니다 `p_enrichment` 필드. 자세한 내용은 아래의 `p_enrichment` 아래에서 [`p_enrichment` 구조](#p_enrichment-structure).

아래 이미지의 예에서 Selector 필드(수신 로그의 이벤트 내)는 `ip_address`입니다. 엔리치먼트 LUT1의 기본 키는 `bad_actor_ip`입니다. 오른쪽의 알러트 이벤트에서는 Selector 값( `bad_actor_name`)과 기본 키 값(`1.1.1.1` 사이에 일치가 있었기 때문에 로그가 엔리치먼트 데이터(포함)로 엔리치됩니다`1.1.1.1`).

<figure><img src="https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-10f2fd323cb1b5165c5ed62e15c39e04c711c920%2F6.21.23_Lookup-Tables-Diagram-23.png?alt=media" alt="A diagram showing how Lookup Tables work: On the left, there is a code box labeled &#x22;Incoming logs.&#x22; An arrow branches off the logs and points to a Lookup Table including &#x22;bad_actor_ip&#x22; and &#x22;bad_actor_name.&#x22; On the right, an arrow goes from the Lookup Table to an Alert Event, showing the alert you would receive based on the log example."><figcaption></figcaption></figure>

### 엔리치먼트에 대해 로그 유형과 Selector가 설정되는 방식

엔리치먼트를 만들 때 연결된 로그 유형과 Selector를 수동으로 설정할 수 있습니다([옵션 1](#option-1-manually-choose-log-types-and-selectors)), 그리고/또는 자동으로 매핑되도록 둘 수 있습니다([옵션 2](#option-2-let-log-types-and-selectors-be-automatically-mapped-by-indicator-fields)).

#### 옵션 1: 로그 유형과 Selector를 수동으로 선택

엔리치먼트를 만들 때, 엔리치먼트와 연결해야 할 하나 이상의 로그 유형을 선택할 수 있으며, 각 로그 유형에 대해 하나 이상의 Selector 필드를 선택할 수 있습니다.

{% hint style="info" %}
이렇게 로그 유형과 Selector를 수동으로 선택하더라도, [옵션 2](#option-2-let-log-types-and-selectors-be-automatically-mapped-by-indicator-fields) 에서 설명하는 자동 매핑은 계속 적용됩니다.
{% endhint %}

{% tabs %}
{% tab title="Panther Console" %}

* Panther Console에서 엔리치먼트를 만들 때 연결된 로그 유형과 Selector를 설정할 수 있습니다. 자세한 내용은 [커스텀 엔리치먼트 구성 방법](#how-to-configure-a-lookup-table)를 참조하세요.

<figure><img src="https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-9b670b91bf90f2be483a376cb65bedb05a1eb604%2FScreenshot%202024-08-15%20at%2010.22.48%20AM.png?alt=media" alt="Under an &#x22;Associated Log Types (Optional)&#x22; header is a form with fields for Log Type, Selectors, and Add Log Type. At the bottom is a Continue button."><figcaption></figcaption></figure>
{% endtab %}

{% tab title="CLI 워크플로" %}

* CLI 워크플로에서 엔리치먼트를 만들 때 YAML 구성 파일을 만들고 업로드합니다. `AssociatedLogTypes` 값은 다음 필드를 포함하는 객체 목록이 됩니다 `LogType` 및 `Selectors` 필드.
* 전체 필드 목록은 [Custom Enrichment Specification Reference](https://docs.panther.com/ko/enrichment/custom/lookup-table-specification-reference) 를 참조하세요.
  {% endtab %}
  {% endtabs %}

#### 옵션 2: 로그 유형과 selector를 자동으로 매핑

엔리치먼트의 기본 키는 다음과 함께 표시할 수 있습니다 [indicator](https://docs.panther.com/ko/search/panther-fields#indicator-fields) 또는 [CIDR 유효성 검사](https://docs.panther.com/data-onboarding/custom-log-types/reference#ip-and-cidr-format-validation).

indicator 예시:

```yaml
    - name: attack_ids           # 이것은 기본 키입니다
      description: 공격 필드
      type: array
      element:
        type: string
        indicators:
            - mitre_attack_technique
```

각 indicator 값에 대해 Panther는 자동으로 다음을 수행합니다:

1. 모든 **활성** 로그 유형을 찾아, 어떤 이벤트 필드라도 동일한 indicator로 지정된 유형을 찾습니다.
2. 해당 로그 유형들을 엔리치먼트와 연결합니다.
3. 각 로그 유형에 대해 indicator에 연결된 `p_any` 필드를 Selector로 설정합니다.

예를 들어, 엔리치먼트 데이터의 스키마가 위에 보인 것처럼 `attack_ids` 기본 키를 `mitre_attack_technique` indicator로 지정한다면, Panther 인스턴스에서 동일한 `mitre_attack_technique` indicator를 설정한 모든 로그 유형이 엔리치먼트와 연결되며, 각각 `p_any_mitre_attack_techniques` Selector를 갖게 됩니다.

CIDR 유효성 검사 예시:

```yaml
    - name: cidr           # 이것은 기본 키입니다
      description: CIDR 블록
      type: string
      validate:
        cidr: ipv4
```

이 경우 Panther는 자동으로 다음을 수행합니다:

* 모든 **활성** 어떤 이벤트 필드라도 `ip` indicator로 지정한 로그 유형.
* 해당 로그 유형들을 엔리치먼트와 연결합니다.
* 각 로그 유형에 대해 indicator에 연결된 `p_any_ip_addresses` 필드를 Selector로 설정합니다.

이 매핑은 엔리치먼트의 데이터가 새로 고쳐질 때마다 수행됩니다.

### `p_enrichment` 구조

로그 이벤트에 엔리치먼트 데이터가 주입되면, `p_enrichment` 필드가 이벤트에 추가되며 디택션 내에서 다음을 사용하여 접근합니다 `deep_get()` 또는 `DeepKey`. `p_enrichment` 필드에는 다음이 포함됩니다:

* 수신 로그 이벤트와 일치한 하나 이상의 엔리치먼트 이름
* 엔리치먼트와 일치한 수신 로그의 Selector 이름
* 엔리치먼트의 기본 키를 통해 일치한 엔리치먼트의 데이터(주입된 `p_match` 필드로 일치한 Selector 값을 포함)

다음은 `p_enrichment` 필드의 구조입니다:

```yaml
'p_enrichment': {
    <name of enrichment1>: {
        <name of selector>: {
            'p_match': <value of Selector>,
	          <enrichment key>: <enrichment value>,
	          ...
	      }
    }
}
```

참고로 `p_enrichment` 는 데이터 레이크의 로그 이벤트에 저장되지 않습니다. 자세한 내용은 [엔리치먼트 데이터가 있는 로그 이벤트 보기](https://docs.panther.com/ko/enrichment/..#viewing-log-events-with-enrichment-data) 를 참조하세요.

## 디택션에서 엔리치먼트 데이터에 접근하는 방법

### 옵션 1(로그가 엔리치된 경우): 다음을 사용 `deep_get()`

로그 이벤트가 수집 시 엔리치되었다면(의 [수신 로그가 엔리치되는 방식](#how-incoming-logs-are-enriched)), 다음 내의 데이터를 접근할 수 있습니다 `p_enrichment` 필드([위에서 설명한 구조의](#p_enrichment-structure)) 다음을 사용하여 `deep_get()` event 객체 함수. 자세한 내용은 다음을 참조하세요 `deep_get()` [Python 디택션 작성에서](https://docs.panther.com/ko/detections/rules/python#deep_get).

아래에서 이 방법의 전체 예시를 보세요, [커스텀 엔리치먼트 데이터를 사용한 디택션 작성](#writing-a-detection-using-lookup-table-data).

### 옵션 2: 다음을 사용하여 동적으로 `lookup()`

Python 디택션에서 다음을 사용하여 엔리치먼트 데이터에 동적으로 접근하는 것도 가능합니다 [the `event.lookup()` 함수](https://docs.panther.com/ko/detections/rules/python#lookup). 이 방식으로, 수신 이벤트에 주입하지 않고도 모든 엔리치먼트의 데이터를 가져올 수 있습니다(의 [수신 로그가 엔리치되는 방식](#how-incoming-logs-are-enriched).

## 커스텀 엔리치먼트 구성 전제 조건

엔리치먼트를 구성하기 전에 다음이 있는지 확인하세요:

* 엔리치먼트 데이터 전용 스키마
  * 이는 엔리치먼트 데이터의 형태를 설명합니다.
* 엔리치먼트 데이터의 기본 키
  * 이 기본 키는 엔리치먼트 스키마에서 정의한 필드 중 하나입니다. 기본 키 값은 수신 로그의 selector 값과 비교됩니다.
  * 아래의 [기본 키 데이터 유형](#primary-key-data-types) 섹션을 참조하여 기본 키 요구사항에 대해 자세히 알아보세요.
* (선택 사항) 수신 로그의 Selector
  * 이들 Selector의 값은 엔리치먼트 데이터에서 일치 항목을 찾는 데 사용됩니다.
* (CLI 워크플로): 엔리치먼트 구성 파일
  * 참조 [Custom Enrichment Specification Reference](https://docs.panther.com/ko/enrichment/custom/lookup-table-specification-reference) 를 참조하세요.
  * 우리는 다음을 권장합니다 [다음을 포크하여 `panther-analysis` 저장소를](https://docs.panther.com/ko/panther/detections-repo/setup/deprecated/public-fork) 그리고 다음을 설치하세요 [Panther Analysis Tool(PAT)](https://docs.panther.com/ko/panther/detections-repo/pat).
* 파일 업로드 또는 S3/GCS 버킷을 사용하는 경우:
  * JSON 또는 CSV 형식의 엔리치먼트 데이터
    * JSON 파일은 라인, 배열 또는 객체를 포함해 다양한 방식으로 이벤트를 형식화할 수 있습니다.
* Scheduled Search를 사용하는 경우:
  * 엔리치먼트에 사용할 데이터를 반환하는 SQL 쿼리
    * 다음을 통해 데이터 웨어하우스에 접근할 수 있는지 확인하세요 [Panther의 Data Explorer](https://docs.panther.com/ko/search/data-explorer).

### 기본 키 데이터 유형

엔리치먼트 테이블의 기본 키 열은 다음 데이터 유형 중 하나여야 합니다:

* String
* Number
* Array(문자열 또는 숫자)
  * 배열을 사용하면 엔리치먼트 테이블의 한 행을 여러 문자열 또는 숫자 기본 키 값과 연결할 수 있습니다. 이렇게 하면 여러 기본 키에 대해 특정 데이터 행을 복제할 필요가 없습니다.

<details>

<summary>예시: 문자열 배열 vs. 문자열 기본 키 유형</summary>

수신 로그 이벤트가 특정 사용자와 연결될 때 추가 개인 정보로 엔리치되도록 커스텀 엔리치먼트 테이블에 사용자 데이터를 저장하고 싶다고 가정해 보겠습니다. 사용자의 이메일 주소로 매칭하려고 하며, 이는 이메일 필드가 엔리치먼트 테이블의 기본 키이자 로그 이벤트의 Selector가 된다는 뜻입니다.

엔리치먼트 테이블의 기본 키 열 유형을 string 또는 string array 중 무엇으로 할지 결정하고 있습니다.

먼저, 로그 소스에서 수신될 것으로 예상할 수 있는 아래 두 이벤트를 검토해 보세요:

```json
# 수신 로그 이벤트 1
{
    "actor_email": "janedoeemailone@mail.com",
    "action": "LOGIN"
}

# 수신 로그 이벤트 2
{
    "actor_email": "janedoeemailtwo@mail.com",
    "action": "EXPORT_FILE"
}
```

두 이메일 주소(`janedoeemailone@mail.com` 및 `janedoeemailtwo@mail.com`)는 동일한 사용자 `Jane Doe`.

에게 속한다는 점에 유의하세요. Panther가 이러한 이벤트를 수신하면, 엔리치먼트 테이블을 사용해 각 이벤트를 Jane의 전체 이름과 역할로 엔리치하고 싶을 것입니다. 엔리치먼트 후 이러한 이벤트는 다음과 같이 보일 것입니다:

<pre class="language-json"><code class="lang-json"><strong># 엔리치먼트 후 로그 이벤트 1
</strong>{
    "actor_email": "janedoeemailone@mail.com",
    "action": "LOGIN",
    "p_enrichment": {
        "&#x3C;lookup_table_name>": {
            "actor_email": {
                "full_name": "Jane Doe",
                "p_match":  "janedoeemailone@mail.com",
                "role": "ADMIN"
            }
        }
    }
}

<strong># 엔리치먼트 후 로그 이벤트 2
</strong>{
    "actor_email": "janedoeemailtwo@mail.com",
    "action": "EXPORT_FILE",
    "p_enrichment": {
        "&#x3C;lookup_table_name>": {
            "actor_email": {
                "full_name": "Jane Doe",
                "p_match": "janedoeemailtwo@mail.com",
                "role": "ADMIN"
            }
        }
    }
}
</code></pre>

다음 중 하나를 정의하여 이 엔리치먼트를 구현할 수 있습니다:

* (권장) 문자열 배열 유형의 기본 키 열
* 문자열 유형의 기본 키 열

기본 키 열이 문자열 배열 유형인 엔리치먼트 테이블을 사용하면, Jane의 여러 이메일 주소를 하나의 기본 키 항목에 포함시켜 하나의 데이터 행과 연결할 수 있습니다. 다음과 같이 보일 수 있습니다:

또는 기본 키 열이 문자열 유형인 엔리치먼트 테이블을 정의할 수도 있습니다. 그러나 이벤트와 엔리치먼트 테이블 간의 매칭은 사용자의 이메일 주소를 기준으로 이루어지고, 사용자는 여러 이메일 주소를 가질 수 있으므로(Jane의 경우처럼), 각 이메일마다 엔리치먼트 테이블 행을 복제해야 합니다. 다음과 같이 보일 것입니다:

두 옵션 모두 동일한 결과(즉, 로그 이벤트가 동일한 방식으로 엔리치됨)를 제공하지만, 문자열 배열 기본 키로 엔리치먼트를 정의하는 것이 편리하고 유지보수 오류 가능성이 낮아 권장됩니다.

</details>

## 커스텀 엔리치먼트 구성 방법

다음 [전제 조건](#prerequisites-for-configuring-a-custom-enrichment)을 충족한 후, 커스텀 엔리치먼트는 다음 방법 중 하나를 사용하여 생성 및 구성할 수 있습니다:

* [옵션 1: Scheduled Search로 커스텀 엔리치먼트 데이터 가져오기](#option-1-import-custom-enrichment-data-with-a-scheduled-search)
  * 정기 일정에 따라 자동 업데이트를 통해 데이터 웨어하우스에서 직접 데이터를 가져오는 데 가장 적합합니다.
  * 예: 현재 환경을 기반으로 자동 새로 고침이 필요한 의심스러운 IP, 사용자 행동 패턴 또는 AWS 계정 매핑 추적.
* [옵션 2: ](#option-2-import-lookup-table-data-via-file-upload)[파일 업로드를 통해 커스텀 엔리치먼트 데이터 가져오기](https://docs.panther.com/enrichment/custom#option-1-import-lookup-table-data-via-file-upload)
  * AWS 계정 정보나 조직 서브넷과 같이 비교적 정적인 데이터에 가장 적합합니다.
  * 파일 업로드를 통해 채워진 커스텀 엔리치먼트 테이블의 최대 크기는 6 MB입니다(API 요청의 payload 크기 제한 때문).
  * 예: AWS CloudTrail 로그에서 개발 계정과 프로덕션 계정을 구분하기 위한 메타데이터 추가.
* [옵션 3: S3 버킷에서 커스텀 엔리치먼트 데이터 동기화](#option-3-sync-custom-enrichment-data-from-an-s3-bucket) 또는 [옵션 4: Google Cloud Storage(GCS) 버킷에서 커스텀 엔리치먼트 데이터 동기화](#option-4-sync-custom-enrichment-data-from-a-google-cloud-storage-gcs-bucket)
  * 상대적으로 자주 업데이트되는 많은 양의 데이터가 있을 때 가장 적합합니다. S3 또는 GCS 버킷의 모든 변경 사항은 Panther와 동기화됩니다.
  * S3 또는 GCS 버킷에서 동기화된 커스텀 엔리치먼트 테이블의 최대 크기는 10 GB입니다.
  * 예: 회사 직원에게 어떤 그룹과 권한 수준이 연결되어 있는지 알고 싶다고 가정해 보겠습니다. 이 시나리오에서 회사는 그룹과 권한 정보를 포함한 최신 Active Directory 목록 사본이 있는 S3 버킷을 보유하고 있을 수 있습니다.

이러한 방법 중 하나를 선택한 후에는 Panther Console 또는 다음을 사용하여 작업할 수 있습니다 [PAT](https://docs.panther.com/ko/panther/detections-repo/pat).

{% hint style="warning" %}
커스텀 엔리치먼트 테이블의 한 행 최대 크기는 65535바이트입니다.
{% endhint %}

### 옵션 1: Scheduled Search로 커스텀 엔리치먼트 데이터 가져오기

{% hint style="info" %}
Scheduled Search를 사용한 커스텀 엔리치먼트 데이터 가져오기는 Panther 버전 1.117부터 오픈 베타이며 모든 고객이 사용할 수 있습니다. 버그 보고 및 기능 요청은 Panther 지원 팀과 공유해 주세요.
{% endhint %}

커스텀 엔리치먼트 데이터는 다음 결과로 자동 채워질 수 있습니다 [Scheduled Search](https://docs.panther.com/ko/search/scheduled-searches). 이 방법은 외부 스크립트나 수동 CSV 내보내기가 필요 없게 하며, 정의된 일정에 따라 자동으로 업데이트되는 엔리치먼트 데이터를 유지할 수 있게 해줍니다.

{% hint style="warning" %}
**Scheduled Search로 커스텀 엔리치먼트 데이터를 가져올 때의 제한 사항**

* 커스텀 엔리치먼트는 다음만 처리할 수 있습니다 [Scheduled Search](https://docs.panther.com/ko/search/scheduled-searches) 최대 100 MB까지.
* CIDR 매칭은 사용할 수 없습니다.
* Scheduled Search는 최소 15분 간격으로 실행할 수 있습니다.
* 검색 타임아웃은 15분으로 고정되어 있으며 구성할 수 없습니다.
  {% endhint %}

<details>

<summary>Panther Console</summary>

**Panther Console을 통해 Scheduled Search로 데이터를 가져오기**

1. Panther Console의 왼쪽 탐색 바에서 다음을 클릭하세요 **Configure** > **Enrichments.**
2. 오른쪽 상단에서 다음을 클릭하세요 **Create New,** 그런 다음 다음을 선택하세요 **Custom Enrichment**.
   * 또는 다음에서 시작할 수 있습니다 **Investigate > Data Explorer** 페이지에서 쿼리를 입력한 후 다음을 클릭하세요 **Create Enrichment via query**.
3. 다음에서 **Enrichment Basic Information** 페이지에서 필드를 입력하세요:
   * **Enrichment Name**: 커스텀 엔리치먼트의 설명적인 이름.
   * **Enabled?**: 이 토글이 다음으로 설정되어 있는지 확인하세요 `YES`. 이 과정에서 나중에 데이터를 가져오려면 이것이 필요합니다.
   * **Description - Optional**: 테이블에 대한 추가 컨텍스트.
   * **Reference - Optional**: 일반적으로 내부 리소스의 하이퍼링크로 사용됩니다.
4. 클릭 **Continue**.
5. 다음에서 **Choose Import Method** 페이지의 **Import Data with a Query** 타일에서 다음을 클릭하세요 **Select**.
   * 가져오기 방법은 자동으로 선택되며, 다음에서 시작한 경우 이 페이지는 건너뜁니다 **Data Explorer** 페이지.
6. 다음에서 **Associated Log Types (Optional)** 페이지에서 로그 유형/Selector를 지정하세요:

   <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>이 단계는 기술적으로 선택 사항이지만(즉, 로그 유형/Selector를 지정하지 않고 이 페이지를 건너뛸 수 있음), 로그가 엔리치되려면 이러한 지정이 필요합니다. <a href="https://docs.panther.com/enrichment/custom#option-2-let-log-types-and-selectors-be-automatically-mapped">auto-mapping</a> 은 지원되지 않기 때문입니다.</p></div>

   1. 클릭 **Add Log Type**.
   2. 다음을 클릭하세요 **Log Type** 드롭다운을 선택한 다음 로그 유형을 선택하세요.
   3. 하나 이상의 **Selectors**를 선택하세요. 이는 커스텀 엔리치먼트로 엔리치할 로그 유형의 외래 키 필드입니다.
      * 또한 다음을 사용하여 중첩 객체의 속성을 참조할 수 있습니다 [JSON path 구문](https://goessner.net/articles/JsonPath/). 예를 들어, 맵의 필드를 참조하려면 다음을 입력할 수 있습니다 `$.field.subfield`.
   4. 클릭 **Add Log Type** 필요한 경우 하나를 더 추가하세요.
7. 클릭 **Continue**.
8. 다음에서 **쿼리 설정** 페이지에서 필드를 입력하세요:
   * **SQL Query**: 커스텀 엔리치먼트용 데이터를 반환하는 SQL 쿼리를 작성하세요. 다음을 클릭하여 Data Explorer에서 쿼리를 테스트할 수 있습니다 **Test in Data Explorer**.
     * 쿼리가 Panther에 의해 수집된 데이터를 가져오는 경우, 다음으로 시작하는 모든 [표준 필드](https://docs.panther.com/ko/search/panther-fields) 를 제외하거나 이름을 바꾸세요 `p_` 접두사, 이 이름들은 예약어이기 때문입니다.
     * 엔리치먼트 스키마는 SQL 쿼리를 기반으로 생성됩니다. 예를 들어 쿼리를 수정하여 스키마 필드와 타입을 변경할 수 있습니다. `SELECT AVG(total_events)::FLOAT AS mean_total_events` 다음 타입의 필드를 생성합니다 `float` 그리고 이름은 `mean_total_events`
   * **Schedule Type & Frequency**: 데이터가 얼마나 자주 새로 고쳐져야 하는지에 따라 스케줄 빈도를 구성하세요. 다음 중에서 선택하세요:
     * **Period**: 고정된 시간 간격으로 쿼리를 실행합니다(예: 2시간마다)
     * **Cron**: 다음을 사용하여 특정 날짜와 시간에 쿼리를 실행합니다 [Cron expressions](https://docs.panther.com/ko/search/scheduled-searches#how-to-use-the-scheduled-search-crontab)
9. 클릭 **Continue**. Panther는 SQL 쿼리에서 자동으로 스키마를 생성합니다.
10. 다음에서 **Table Schema** 페이지에서 자동 생성된 스키마를 검토하고 다음을 선택하세요 **Primary Key Name** 드롭다운에서.
    * 모든 `string` 필드에 대해 선택적으로 다음을 추가할 수 있습니다 [indicator fields](https://docs.panther.com/ko/search/panther-fields#indicator-fields) 다음을 클릭하여 **Add Indicators** 필드 옆. 드롭다운에서 하나 이상의 indicator 유형(예: IP Address, Domain Name, SHA256 Hash)을 선택하세요. indicator를 추가하면 [자동 로그 유형 및 Selector 매핑](#option-2-let-log-types-and-selectors-be-automatically-mapped) 이 엔리치먼트에 대해 활성화됩니다.
    * 필드가 indicator 대상이 될 수 있도록 하려면, SQL 쿼리에서 이를 다음으로 캐스팅하세요 `STRING` .
11. 클릭 **Create Enrichment**. 소스 설정 성공 페이지가 표시됩니다.
12. 선택적으로 다음을 설정하세요 **이 엔리치먼트가 데이터를 받지 못하면 알람을 설정하시겠습니까?**&#xB97C; 다음으로 토글하여 `YES` 알람을 활성화하세요.
    * 다음을 입력하세요 **Number** 및 **Period** 필드에 Panther가 이 알림을 보내는 빈도를 지정하세요.
    * 이 알람의 알러트 대상은 페이지 하단에 표시됩니다. 알림이 전송되는 위치를 구성하고 사용자 지정하려면 다음 문서를 참조하세요 [Panther Destinations](https://docs.panther.com/ko/alerts/destinations).
13. 클릭 **설정 완료**.

{% hint style="info" %}
Scheduled Search는 구성된 일정에 따라 실행되며 커스텀 엔리치먼트 데이터를 자동으로 업데이트합니다. 검색 기록은 다음에서 볼 수 있습니다 [Search History 페이지](https://docs.panther.com/ko/search/search-history).
{% endhint %}

</details>

### 옵션 2: 파일 업로드를 통해 커스텀 엔리치먼트 데이터 가져오기

Panther Console 또는 PAT를 통해 파일 업로드로 데이터를 가져올 수 있습니다:

<details>

<summary>Panther Console</summary>

**Panther Console을 통해 파일 업로드로 커스텀 엔리치먼트 데이터 가져오기**

1. Panther Console의 왼쪽 탐색 바에서 다음을 클릭하세요 **Configure** > **Enrichments**.
2. 오른쪽 상단에서 다음을 클릭하세요 **Create New**.
3. 다음에서 **Basic Information** 페이지:
   * **Enrichment Name**: 커스텀 엔리치먼트의 설명적인 이름.
   * **Enabled?**: 이 토글이 다음으로 설정되어 있는지 확인하세요 `YES`. 이 과정에서 나중에 데이터를 가져오려면 이것이 필요합니다.
   * **Description - Optional**: 테이블에 대한 추가 컨텍스트.
   * **Reference - Optional**: 일반적으로 내부 리소스의 하이퍼링크로 사용됩니다.\ <img src="https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-305b9013173d5e5ad60d7d98ca2eb6c24eccfcb8%2Fimage%20(1)%20(13).png?alt=media" alt="" data-size="original">
4. 클릭 **Continue**.
5. 다음에서 **Associated Log Types (Optional)** 페이지에서 필요하다면 로그 유형/Selector를 선택적으로 지정하세요:
   * 클릭 **Add Log Type**.
   * 다음을 클릭하세요 **Log Type** 드롭다운을 선택한 다음 로그 유형을 선택하세요.
   * 하나 이상의 **Selectors**를 선택하세요. 이는 커스텀 엔리치먼트로 엔리치할 로그 유형의 외래 키 필드입니다.
     * 또한 다음을 사용하여 중첩 객체의 속성을 참조할 수 있습니다 [JSON path 구문](https://goessner.net/articles/JsonPath/). 예를 들어, 맵의 필드를 참조하려면 다음을 입력할 수 있습니다 `$.field.subfield`.
   * 클릭 **Add Log Type** 필요하면 하나를 더 추가하세요.\
     ![](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-568dbf4e3ac50d527771a6b7dd5aa7cefc2ceffc%2Flookup-table-log-types.png?alt=media)\
     위의 예시 화면에서는 다음을 선택했습니다 **AWS.CloudTrail** 로그와 다음을 입력했습니다 `accountID` 및 `recipientAccountID` 를 사용하여 CloudTrail 로그의 키를 나타냈습니다.
6. 클릭 **Continue**.
7. 다음에서 **Table Schema** 페이지에서 Table Schema를 구성하세요:\
   \&#xNAN;*참고: 아직 새 스키마를 생성하지 않았다면 다음을 참조하세요* [*스키마 생성에 대한 문서*](https://docs.runpanther.io/data-onboarding/custom-log-types/example-csv)*. 또한 커스텀 엔리치먼트 데이터를 사용하여 스키마를 추론할 수도 있습니다. 스키마를 생성한 후에는 Enrichment를 구성하는 동안 Table Schema 페이지의 드롭다운에서 선택할 수 있습니다.*\
   \&#xNAN;*참고: CSV 스키마는 커스텀 엔리치먼트와 함께 작동하려면 열 헤더가 필요합니다*.
   * 다음을 선택하세요 **Schema Name** 드롭다운에서.
   * 다음을 선택하세요 **Primary Key Name** 드롭다운에서. 이는 다음과 같은 테이블의 고유한 열이어야 합니다 `accountID`.\
     ![The image shows the Table Schema form from the Panther Console. The Schema Name field is filled in with "Custom.AWSaccountIDs" and the Primary Key Name field is set to "awsacctid."](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-216b4f8d1528f292f1cef160b0daa36722779bc1%2Flookup-table-schema.png?alt=media)
8. 클릭 **Continue**.
9. 다음에서 **Choose Import Method** 페이지의 **Import via File Upload** 타일에서 다음을 클릭하세요 **Set Up**.
10. 다음에서 **Upload File** 페이지에서 파일을 드래그 앤 드롭하거나 다음을 클릭하세요 **Select file** 를 눌러 가져올 엔리치먼트 데이터 파일을 선택하세요. 파일은 다음 형식이어야 합니다 `.csv` 또는 `.json` 형식.
11. 클릭 **설정 완료**. 소스 설정 성공 페이지가 표시됩니다.
12. 선택적으로, 다음 옆에 ***S*****이 커스텀 엔리치먼트가 데이터를 받지 못하면 알람을 설정하시겠습니까?**&#xC124;정을 다음으로 토글하세요 **YES** 알람을 활성화하세요.

    * 다음을 입력하세요 **Number** 및 **Period** 필드에 Panther가 이 알림을 보내는 빈도를 지정하세요.
    * 이 알람의 알러트 대상은 페이지 하단에 표시됩니다. 알림이 전송되는 위치를 구성하고 사용자 지정하려면 다음 문서를 참조하세요 [Panther Destinations](https://docs.panther.com/ko/alerts/destinations).

    ​![The image shows a success page in the Panther Console after creating a Lookup Table. There is an option to set an  alarm in case this Lookup Table doesn't receive any data, and dropdown selectors to choose a time period when you receive the alerts. At the bottom, there is a section showing which destinations will receive the alert.](https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FoyqgS5R8TnNzpDRtl9e9%2Fimage.png?alt=media\&token=5d8c27d1-ac28-460c-a2f5-bd2c503a49f1)

{% hint style="info" %}
커스텀 엔리치먼트 업로드 실패에 대해 생성된 알림은 Panther Console의 **System Errors** 탭 내 **Alerts & Errors** 페이지에서 확인할 수 있습니다.
{% endhint %}

</details>

<details>

<summary>PAT</summary>

**PAT를 통해 파일 업로드로 커스텀 엔리치먼트 데이터 가져오기**

{% hint style="info" %}
데이터 파일이 1MB보다 크다면 대신 다음 방법을 사용하는 것이 좋습니다 [S3 동기화 업로드 방법](#option-2-sync-via-s3-source) 또는 [GCS 동기화 업로드 방법](#option-3-sync-via-google-cloud-storage-source).
{% endhint %}

**파일 및 폴더 설정**

커스텀 엔리치먼트에는 다음 파일이 필요합니다:

* 엔리치먼트 테이블용 YAML 구성 파일
  * 이 커스텀 엔리치먼트 구성 파일은 이름에 다음이 포함된 폴더에 저장되어야 합니다 `lookup_tables`*.* 이는 최상위 `lookup_tables` 디렉터리일 수도 있고, 이름이 다음과 일치하는 하위 디렉터리일 수도 있습니다 `*lookup_tables*`. 다음을 참조로 사용할 수 있습니다 [panther-analysis](https://github.com/panther-labs/panther-analysis) 저장소를.
* 테이블에 데이터를 로드할 때 사용할 스키마를 정의하는 YAML 파일
  * 이 데이터 스키마 파일은 다음 위치 외부의 디렉터리에 저장해야 합니다. `lookup_tables` 디렉터리. 다른 사용자 지정 로그 스키마와 함께 저장할 수 있으며, 예를 들어 `/schemas` 디렉터리를 panther-analysis 저장소의 루트에 둘 수 있습니다.
* 테이블에 로드할 데이터를 포함하는 JSON 또는 CSV 파일(선택 사항, 자세한 내용은 계속 읽어보세요).

**스키마 및 구성 파일 작성**

일반적으로 먼저 데이터 스키마를 작성하는 것이 좋습니다. 테이블 구성에서 그중 일부 값을 참조하기 때문입니다.

1. YAML 데이터 스키마 파일을 만드세요. 이 스키마는 테이블에 데이터를 업로드할 때 사용할 파일을 읽는 방법을 정의합니다. 데이터에 CSV 파일을 사용하는 경우, 스키마는 CSV를 파싱할 수 있어야 합니다.
   * 테이블 스키마의 형식은 로그 스키마와 동일합니다. 스키마 작성에 대한 자세한 내용은 다음에 관한 문서를 참조하세요. [Log Schemas 관리.](https://docs.panther.com/data-onboarding/custom-log-types#uploading-log-schemas-with-the-panther-analysis-tool)
2. YAML 구성 파일을 만드세요. 필요한 값과 허용되는 값의 전체 목록은 다음에서 확인하세요. [Custom Enrichment Specification Reference](https://docs.panther.com/ko/enrichment/custom/lookup-table-specification-reference).
   * 로컬 파일에 저장된 데이터를 사용하는 사용자 지정 enrichment의 예시 구성은 다음과 같습니다:

     ```yaml
     AnalysisType: lookup_table
     LookupName: my_lookup_table # 고유한 표시 이름
     Schema: Custom.MyTableSchema # 이전 단계에서 정의한 스키마
     Filename: ./my_lookup_table_data.csv # 데이터의 상대 경로
     Description: >
       이 테이블에 어떤 정보가 포함되어 있는지에 대한 유용한 설명.
       예를 들어, 이 테이블은 IP 주소를 호스트 이름으로 변환할 수 있습니다.
     Reference: >
       이 테이블에 대한 추가 문서의 URL
     Enabled: true # 테이블 사용을 중지하려면 false로 설정
     LogTypeMap:
       PrimaryKey: ip                # 테이블의 기본 키
       AssociatedLogTypes:           # 이 테이블과 일치시킬 로그 유형 목록
         - LogType: AWS.CloudTrail
           Selectors:
             - "sourceIPAddress"     # CloudTrail 로그의 필드
             - "p_any_ip_addresses"  # Panther가 생성한 필드도 사용할 수 있습니다.
         - LogType: Okta.SystemLog
           Selectors:
             - "$.client.ipAddress"  # JSON 값 경로도 허용됩니다.
     ```
3. 저장소 루트에서 다음을 실행하여 스키마 파일을 업로드하세요. [`panther_analysis_tool update-custom-schemas`](https://docs.panther.com/ko/panther/detections-repo/pat/pat-commands#update-custom-schemas-creating-or-updating-custom-schemas) `--path ./schemas`.
4. 저장소 루트에서 다음을 사용하여 사용자 지정 enrichment를 업로드하세요.\
   [`panther_analysis_tool upload`](https://docs.panther.com/ko/panther/detections-repo/pat/pat-commands#upload-uploading-packages-to-panther-directly).

**Panther Analysis Tool로 사용자 지정 enrichment 업데이트:**

1. 문제가 되는 사용자 지정 enrichment의 YAML 구성 파일을 찾습니다.
2. 파일을 열고 다음 필드를 찾습니다. `Filename`. 데이터 파일로 이어지는 파일 경로가 보일 것입니다.
3. 다음에 표시된 파일을 업데이트하거나 교체하세요. `Filename`. 허용되는 값은 다음에서 확인하세요. [Custom Enrichment Specification Reference](https://docs.panther.com/ko/enrichment/custom/lookup-table-specification-reference).
4. 구성 파일을 저장한 다음, 다음을 사용하여 변경 사항을 업로드하세요:

   ```yaml
   panther_analysis_tool upload
   ```

   선택적으로, 사용자 지정 enrichment만 업로드하도록 지정할 수 있습니다:

   ```yaml
   panther_analysis_tool upload --filter AnalysisType=lookup_table
   ```

</details>

### 옵션 3: S3 버킷에서 커스텀 엔리치먼트 데이터 동기화

Panther Console 또는 PAT를 통해 S3 버킷에서 데이터 동기화를 설정할 수 있습니다:

<details>

<summary>Panther Console</summary>

**Panther Console을 통해 S3 버킷에서 사용자 지정 enrichment 데이터 동기화**

1. Panther Console의 왼쪽 탐색 바에서 다음을 클릭하세요 **Configure > Enrichments**.
2. 오른쪽 상단에서 다음을 클릭하세요 **Create New**.
3. Add 클릭 **Custom Enrichment** 카드.
4. 다음에서 **Basic Information** 페이지에서 필드를 입력하세요:
   * **Enrichment Name**: 커스텀 엔리치먼트의 설명적인 이름.
   * **Enabled?**: 이 토글이 다음으로 설정되어 있는지 확인하세요 `YES`. 이 과정에서 나중에 데이터를 가져오려면 이것이 필요합니다.
   * **Description - Optional**: 테이블에 대한 추가 컨텍스트.
   * **Reference - Optional**: 일반적으로 내부 리소스의 하이퍼링크로 사용됩니다.
   * ![The image shows the Lookup Table Basic Information form from the Panther Console. The Lookup Name field is filled in with "Employee Directory." It is enabled. The description says "Directory with groups and permissions a specific user is associated with." There is a blue button labeled "Continue" at the bottom.](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-0245a979983a4fede303cdc48f4a6d78d93f1a52%2Flookup-table-basic-s3.png?alt=media)
5. 다음에서 **Associated Log Types** 페이지에서 필요하다면 로그 유형/Selector를 선택적으로 지정하세요:
   * 클릭 **Add Log Type**.
   * 다음을 클릭하세요 **Log Type** 드롭다운을 선택한 다음 로그 유형을 선택하세요.
   * 하나 이상의 **Selectors**, 외래 키 필드는 사용자 지정 enrichment 데이터로 enrichment하려는 로그 유형을 형성합니다.
     * 또한 다음을 사용하여 중첩 객체의 속성을 참조할 수 있습니다 [JSON path 구문](https://goessner.net/articles/JsonPath/). 예를 들어, 맵의 필드를 참조하려면 다음을 입력할 수 있습니다 `$.field.subfield`.

* 클릭 **Add Log Type** 필요하면 하나를 더 추가하세요.\
  ![The image shows the Associated Log Types form from the Panther Console. The Log Type field is set to AWS.VPCFlow. Selectors is set to "account."](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-baa85a56b3740e124717f110214bcb2a3965a4fa%2Flut-logtype-s3.png?alt=media)\
  위의 예시 화면에서는 다음을 선택했습니다 **AWS.VPCFlow** 로그와 다음을 입력했습니다 `account` 를 사용하여 VPC Flow 로그의 키를 나타냅니다.

6. 클릭 **Continue**.
7. 다음에서 **Table Schema** 페이지에서 Table Schema를 구성하세요.\
   \&#xNAN;*참고: 아직 새 스키마를 생성하지 않았다면 다음을 참조하세요* [*스키마 생성에 대한 문서*](https://docs.runpanther.io/data-onboarding/custom-log-types/example-csv)*. 스키마를 생성하면 사용자 지정 enrichment를 구성하는 동안 Table Schema 페이지의 드롭다운에서 선택할 수 있습니다.*
   1. 다음을 선택하세요 **Schema Name** 드롭다운에서.
   2. 다음을 선택하세요 **Primary Key Name** 드롭다운에서. 이는 다음과 같은 테이블의 고유한 열이어야 합니다 `accountID`.
8. 클릭 **Continue**.
9. 다음에서 **Choose Import Method** 페이지의 **S3 버킷에서 데이터 동기화** 타일에서 다음을 클릭하세요 **Set Up**.\
   ![The image shows the "Choose Import Method" page in the Panther Console. The options are Import via File Upload and Sync Data from an S3 Bucket. The Setup button is circled next to "Sync Data from an S3 Bucket."](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-1ef1630e6f723e42c0ba5ced3b2ff247a90b227b%2Flut-import-s3.png?alt=media)
10. S3 소스를 설정하세요. 데이터는 다음 형식이어야 합니다. `.csv` 또는 `.json` 형식.
    * 다음을 입력하세요. **Account ID**, S3 버킷이 있는 12자리 AWS 계정 ID입니다.
    * 다음을 입력하세요. **S3 URI**, 특정 S3 버킷을 식별하는 고유 경로입니다.
    * 선택적으로 다음을 입력하세요. **KMS Key** 데이터가 KMS-SSE로 암호화된 경우.
    * 다음을 입력하세요. **Update Period**, S3 소스가 업데이트되는 주기(기본값은 1시간).\
      ![The image shows the "Set up your S3 source" form from the Panther Console. There are fields for Account ID, S3 URI, KMS Key, and selectors to choose the Update Period.](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-c2cfc8478d221f30ffc971dd46db52331ce0c35e%2Flut-setup-s3.png?alt=media)
11. 클릭 **Continue**.
12. IAM 역할을 설정하세요.
    * 사용 가능한 세 가지 옵션에 대한 지침은 다음 섹션인 IAM 역할 생성에서 확인하세요.
13. 클릭 **설정 완료**. 소스 설정 성공 페이지가 표시됩니다.
14. 선택적으로, 다음 옆에 *S***이 커스텀 엔리치먼트가 데이터를 받지 못하면 알람을 설정하시겠습니까?**&#xC124;정을 다음으로 토글하세요 **YES** 알람을 활성화하세요.
    * 다음을 입력하세요 **Number** 및 **Period** 필드에 Panther가 이 알림을 보내는 빈도를 지정하세요.
    * 이 알람의 알러트 대상은 페이지 하단에 표시됩니다. 알림이 전송되는 위치를 구성하고 사용자 지정하려면 다음 문서를 참조하세요 [Panther Destinations](https://docs.panther.com/ko/alerts/destinations).

​![The image shows a success page in the Panther Console after creating a Lookup Table. There is an option to set an  alarm in case this Lookup Table doesn't receive any data, and dropdown selectors to choose a time period when you receive the alerts. At the bottom, there is a section showing which destinations will receive the alert.](https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FoyqgS5R8TnNzpDRtl9e9%2Fimage.png?alt=media\&token=5d8c27d1-ac28-460c-a2f5-bd2c503a49f1)​

{% hint style="info" %}
사용자 지정 enrichment 업로드 실패로 생성된 알림은 다음에서 확인할 수 있습니다. **System Errors** 탭 내 **Alerts & Errors** 페이지에서 확인할 수 있습니다.
{% endhint %}

**IAM 역할 생성**

S3 소스를 사용하는 Panther 사용자 지정 enrichment에 사용할 IAM 역할을 만드는 방법에는 세 가지 옵션이 있습니다:

* [AWS Console UI를 사용하여 IAM 역할 생성.](#create-an-iam-role-using-aws-console-ui)
* [CloudFormation 템플릿 파일을 사용하여 IAM 역할 생성](#create-an-iam-role-using-aws-console-ui).
* [수동으로 IAM 역할 생성](#create-an-iam-role-manually).

<img src="https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-078d0498ee3d122d2361683f131f70af713240dd%2Fnew-iam-role.png?alt=media" alt="" data-size="original">

**AWS Console UI를 사용하여 IAM 역할 생성**

1. S3 소스를 사용하는 사용자 지정 enrichment 생성 과정의 "Set Up an IAM role" 페이지에서 "Using the AWS Console UI"라고 표시된 타일을 찾습니다. 타일 오른쪽에서 다음을 클릭하세요. **Select**.
2. 클릭 **Launch Console UI**.\
   ![The image shows the screen after you choose to use AWS UI to set up your role. There is a green button in the center labeled "Launch Coonsole UI." At the bottom, there is a field to enter your Role ARN.](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-643baf573c6f0018c463d9792e61d584e75a5faa%2Faws-ui-role.png?alt=media)
   * 템플릿 URL이 미리 채워진 상태로 새 브라우저 탭에서 AWS 콘솔로 리디렉션됩니다.
   * CloudFormation 스택은 S3 버킷에서 객체를 읽는 데 필요한 최소 권한을 가진 AWS IAM 역할을 생성합니다.
   * AWS의 CloudFormation 스택에서 "Outputs" 탭을 클릭하고 Role ARN을 기록합니다.
3. Panther 계정으로 돌아갑니다.
4. "Use AWS UI to set up your role" 페이지에서 Role ARN을 입력합니다.
5. 클릭 **설정 완료**.

**CloudFormation 템플릿 파일을 사용하여 IAM 역할 생성**

1. S3 소스를 사용하는 사용자 지정 enrichment 생성 과정의 "Set Up an IAM role" 페이지에서 "CloudFormation Template File"이라고 표시된 타일을 찾습니다. 타일 오른쪽에서 다음을 클릭하세요. **Select**.
2. 클릭 **CloudFormation template**, 그러면 자체 파이프라인을 통해 적용할 수 있도록 템플릿이 다운로드됩니다.
3. AWS에서 템플릿 파일을 업로드하세요:
   1. AWS 콘솔을 열고 CloudFormation 제품으로 이동합니다.
   2. 클릭 **Create stack**.
   3. 클릭 **Upload a template file** 를 선택하고 다운로드한 CloudFormation 템플릿을 선택합니다.
4. Panther의 "CloudFormation Template" 페이지에서 Role ARN을 입력합니다.
5. 클릭 **설정 완료**.

**수동으로 IAM 역할 생성**

1. S3 소스를 사용하는 사용자 지정 enrichment 생성 과정의 "Set Up an IAM role" 페이지에서 다음과 같은 링크를 클릭하세요. **I want to set everything up on my own**.
2. 필요한 IAM 역할을 생성합니다. 필요한 IAM 역할은 수동으로 또는 자체 자동화를 통해 만들 수 있습니다. 역할 이름은 다음 형식을 사용해야 합니다. `PantherLUTsRole-${Suffix}`(예: `PantherLUTsRole-MyLookupTable`).
   * IAM 역할 정책에는 아래에 정의된 문이 포함되어야 합니다:

     ```
         "Version": "2012-10-17",
         "Statement": [
             {
                 "Action": "s3:GetBucketLocation",
                 "Resource": "arn:aws:s3:::<bucket-name>",
                 "Effect": "Allow"
             },
             {
                 "Action": "s3:GetObject",
                 "Resource": "arn:aws:s3:::<bucket-name>/<input-file-path>",
                 "Effect": "Allow"
             }
         ]
     }
     ```
   * S3 버킷이 AWS KMS를 사용한 서버 측 암호화로 구성된 경우, Panther API가 해당 KMS 키에 액세스할 수 있도록 추가 문을 포함해야 합니다. 이 경우 정책은 다음과 비슷해집니다:

     ```
         "Version": "2012-10-17",
         "Statement": [
             {
                 "Action": "s3:GetBucketLocation",
                 "Resource": "arn:aws:s3:::<bucket-name>",
                 "Effect": "Allow"
             },
             {
                 "Action": "s3:GetObject",
                 "Resource": "arn:aws:s3:::<bucket-name>/<input-file-path>",
                 "Effect": "Allow"
             },
             {
                 "Action": ["kms:Decrypt", "kms:DescribeKey"],
                 "Resource": "arn:aws:kms:<region>:<your-accound-id>:key/<kms-key-id>",
                 "Effect": "Allow"
             }
         ]
     }
     ```
3. Panther의 "Setting up role manually" 페이지에서 Role ARN을 입력합니다.
   * 이 값은 AWS 계정의 CloudFormation 스택 "Outputs" 탭에서 찾을 수 있습니다.
4. 클릭 **설정 완료**, 그러면 새 Employee Directory 테이블이 나열된 Enrichments 목록 페이지로 리디렉션됩니다.

</details>

<details>

<summary>PAT</summary>

**PAT를 통해 S3 버킷에서 사용자 지정 enrichment 데이터 동기화**

**파일 및 폴더 설정**

커스텀 엔리치먼트에는 다음 파일이 필요합니다:

* 엔리치먼트 테이블용 YAML 구성 파일
  * 이 커스텀 엔리치먼트 구성 파일은 이름에 다음이 포함된 폴더에 저장되어야 합니다 `lookup_tables`*.* 이는 최상위 `lookup_tables` 디렉터리일 수도 있고, 이름이 다음과 일치하는 하위 디렉터리일 수도 있습니다 `*lookup_tables*`. 다음을 참조로 사용할 수 있습니다 [panther-analysis](https://github.com/panther-labs/panther-analysis) 저장소를.
* 테이블에 데이터를 로드할 때 사용할 스키마를 정의하는 YAML 파일
  * 이 데이터 스키마 파일은 다음 위치 외부의 디렉터리에 저장해야 합니다. `lookup_tables` 디렉터리(예: `/schemas` panther analysis 저장소의 루트에). 다른 사용자 지정 로그 스키마와 함께 저장할 수 있습니다.
* 테이블에 로드할 데이터를 포함하는 JSON 또는 CSV 파일(선택 사항, 자세한 내용은 계속 읽어보세요).

**스키마 및 구성 파일 작성**

일반적으로 먼저 데이터 스키마를 작성하는 것이 좋습니다. 테이블 구성에서 그중 일부 값을 참조하기 때문입니다.

1. YAML 데이터 스키마 파일을 만드세요. 이 스키마는 테이블에 데이터를 업로드할 때 사용할 파일을 읽는 방법을 정의합니다. 데이터에 CSV 파일을 사용하는 경우, 스키마는 CSV를 파싱할 수 있어야 합니다.
   * 테이블 스키마의 형식은 로그 스키마와 동일합니다. 스키마 작성에 대한 자세한 내용은 다음에 관한 문서를 참조하세요. [Log Schemas 관리.](https://docs.panther.com/data-onboarding/custom-log-types#uploading-log-schemas-with-the-panther-analysis-tool)
2. 테이블 구성용 YAML 파일을 만드세요. S3의 파일에 저장된 데이터를 사용하는 사용자 지정 enrichment의 예시 구성은 다음과 같습니다:
   * 다음 사항에 유의하세요. `Refresh` 필드에는 `RoleARN`, `ObjectPath`, 그리고 `PeriodMinutes` 필드.
   * 필요한 값과 허용되는 값의 전체 목록은 다음에서 확인하세요. [Custom Enrichment Specification Reference](https://docs.panther.com/ko/enrichment/custom/lookup-table-specification-reference).

     ```yaml
     AnalysisType: lookup_table
     LookupName: my_lookup_table # 고유한 표시 이름
     Schema: Custom.MyTableSchema # 이전 단계에서 정의한 스키마
     Refresh:
       RoleArn: arn:aws:iam::123456789012:role/PantherLUTsRole-my_lookup_table # 조직의 AWS 계정에 있는 역할
       ObjectPath: s3://path/to/my_lookup_table_data.csv
       PeriodMinutes: 120 # 2시간마다 S3에서 동기화
     Description: >
       이 테이블에 어떤 정보가 포함되어 있는지에 대한 유용한 설명.
       예를 들어, 이 테이블은 IP 주소를 호스트 이름으로 변환할 수 있습니다.
     Reference: >
       이 테이블에 대한 추가 문서의 URL
     Enabled: true # 테이블 사용을 중지하려면 false로 설정
     LogTypeMap:
       PrimaryKey: ip                # 테이블의 기본 키
       AssociatedLogTypes:           # 이 테이블과 일치시킬 로그 유형 목록
         - LogType: AWS.CloudTrail
           Selectors:
             - "sourceIPAddress"     # CloudTrail 로그의 필드
             - "p_any_ip_addresses"  # Panther가 생성한 필드도 사용할 수 있습니다.
         - LogType: Okta.SystemLog
           Selectors:
             - "$.client.ipAddress"  # JSON 값 경로도 허용됩니다.
     ```
3. 저장소 루트에서 다음을 실행하여 스키마 파일을 업로드하세요. [`panther_analysis_tool update-custom-schemas`](https://docs.panther.com/ko/panther/detections-repo/pat/pat-commands#update-custom-schemas-creating-or-updating-custom-schemas) `--path ./schemas`.
4. 저장소 루트에서 다음을 사용하여 사용자 지정 enrichment를 업로드하세요.\
   [`panther_analysis_tool upload`](https://docs.panther.com/ko/panther/detections-repo/pat/pat-commands#upload-uploading-packages-to-panther-directly).

**사전 요구 사항**

사용자 지정 enrichment를 S3와 동기화하도록 구성하려면 먼저 다음을 준비해야 합니다:

1. Panther가 S3 버킷에 액세스하는 데 사용할 수 있는 AWS의 IAM 역할 ARN입니다. Panther용 IAM 역할 설정에 대한 자세한 내용은 다음 섹션을 참조하세요. [Creating an IAM Role.](#creating-an-iam-role)
2. 데이터를 저장할 파일의 경로입니다. 경로 형식은 다음과 같아야 합니다: `s3://bucket-name/path_to_file/file.csv`

</details>

### 옵션 4: Google Cloud Storage(GCS) 버킷에서 커스텀 엔리치먼트 데이터 동기화

Panther Console 또는 PAT를 통해 GCS 버킷에서 데이터 동기화를 설정할 수 있습니다:

<details>

<summary>Panther Console</summary>

**Panther Console을 통해 GCS 버킷에서 사용자 지정 enrichment 데이터 동기화**

1. Panther Console의 왼쪽 탐색 바에서 다음을 클릭하세요 **Configure > Enrichments**.
2. 오른쪽 상단에서 다음을 클릭하세요 **Create New**.
3. 다음을 클릭하세요 **Custom Enrichment** 카드.
4. 다음에서 **Basic Information** 페이지에서 필드를 입력하세요:

   * **Enrichment Name**: 커스텀 엔리치먼트의 설명적인 이름.
   * **Enabled?**: 이 토글이 다음으로 설정되어 있는지 확인하세요 `YES`. 이 과정에서 나중에 데이터를 가져오려면 이것이 필요합니다.
   * **Description - Optional**: 테이블에 대한 추가 컨텍스트.
   * **Reference - Optional**: 일반적으로 내부 리소스의 하이퍼링크로 사용됩니다.

   ![](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-305b9013173d5e5ad60d7d98ca2eb6c24eccfcb8%2Fimage%20\(1\)%20\(13\).png?alt=media)
5. 클릭 **Continue**.
6. 다음에서 **Associated Log Types (Optional)** 페이지에서 필요하다면 로그 유형/Selector를 선택적으로 지정하세요:
   * 클릭 **Add Log Type**.
   * 다음을 클릭하세요 **Log Type** 드롭다운을 선택한 다음 로그 유형을 선택하세요.
   * 하나 이상의 **Selectors**, 외래 키 필드는 사용자 지정 enrichment 데이터로 enrichment하려는 로그 유형을 형성합니다.
     * 또한 다음을 사용하여 중첩 객체의 속성을 참조할 수 있습니다 [JSON path 구문](https://goessner.net/articles/JsonPath/). 예를 들어, 맵의 필드를 참조하려면 다음을 입력할 수 있습니다 `$.field.subfield`.
   * 클릭 **Add Log Type** 필요하면 하나를 더 추가하세요.\
     ![The image shows the Associated Log Types form from the Panther Console. The Log Type field is set to AWS.VPCFlow. Selectors is set to "account."](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-baa85a56b3740e124717f110214bcb2a3965a4fa%2Flut-logtype-s3.png?alt=media)\
     위의 예시 화면에서는 다음을 선택했습니다 **AWS.VPCFlow** 로그와 다음을 입력했습니다 `account` 를 사용하여 VPC Flow 로그의 키를 나타냅니다.
7. 클릭 **Continue**.
8. 다음에서 **Table Schema** 페이지에서 Table Schema를 구성하세요:\
   \&#xNAN;***참고:** 아직 새 스키마를 생성하지 않았다면 다음을 참조하세요.* [*스키마 생성에 대한 문서*](https://docs.runpanther.io/data-onboarding/custom-log-types/example-csv)*. 스키마를 생성하면 사용자 지정 enrichment를 구성하는 동안 Table Schema 페이지의 드롭다운에서 선택할 수 있습니다.*
   1. 다음을 선택하세요 **Schema Name** 드롭다운에서.
   2. 다음을 선택하세요 **Primary Key Name** 드롭다운에서. 이는 다음과 같은 테이블의 고유한 열이어야 합니다 `accountID`.
9. 클릭 **Continue**.
10. 다음에서 **Choose Import Method** 페이지의 **Google Cloud Storage 버킷에서 데이터 동기화** 타일에서 다음을 클릭하세요 **Set Up**.\
    ![](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-792562953908721ea527434e39a0100dfce7bc1d%2FScreenshot%202025-06-23%20at%2015.59.31.png?alt=media)
11. Google Cloud Storage 소스를 설정하세요. 데이터는 다음 형식이어야 합니다. `.csv` 또는 `.json` 형식.
    * 다음을 입력하세요. **Google Cloud Storage URI**, 특정 객체를 식별하는 고유 경로입니다.
    * 다음을 입력하세요. **Update Period**, S3 소스가 업데이트되는 주기(기본값은 1시간).\
      ![](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-f6ab127d030dbdf1cf6bf2524d73fe716b6e3e8c%2FScreenshot%202025-06-23%20at%2016.03.39.png?alt=media)
12. 클릭 **Continue**.
13. ID를 설정하세요.
    * 이를 수행하는 방법은 다음 섹션인 ID 설정을 참조하세요.
14. 클릭 **설정 완료**. 소스 설정 성공 페이지가 표시됩니다.
15. 선택적으로, 다음 옆에 **이 사용자 지정 enrichment가 데이터를 전혀 받지 못할 경우 알러트를 설정하시겠습니까?**&#xC124;정을 다음으로 토글하세요 **YES** 알람을 활성화하세요.

    * 다음을 입력하세요 **Number** 및 **Period** 필드에 Panther가 이 알림을 보내는 빈도를 지정하세요.
    * 이 알람의 알러트 대상은 페이지 하단에 표시됩니다. 알림이 전송되는 위치를 구성하고 사용자 지정하려면 다음 문서를 참조하세요 [Panther Destinations](https://docs.panther.com/ko/alerts/destinations).

    ![](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-6895ea89e9a54421ed762f5a5e756d492189144b%2FScreenshot%202025-06-23%20at%2016.08.09.png?alt=media)​

{% hint style="info" %}
사용자 지정 enrichment 업로드 실패로 생성된 알림은 다음에서 확인할 수 있습니다. **System Errors** 탭 내 **Alerts & Errors** 페이지에서 확인할 수 있습니다.
{% endhint %}

**ID 설정**

지원되는 ID 방법은 다음과 같습니다. [Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation). GCS 소스를 사용하는 Panther 사용자 지정 enrichment에 사용할 Workflow Identity Federation을 설정하는 방법에는 세 가지 옵션이 있습니다:

* Terraform 템플릿 파일을 사용하여 Workload Identity Federation 설정
* GCP 콘솔에서 수동으로 Workload Identity Federation 설정

![](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-d2551e2407e97e12a9cbf4c6e3dbb27df8548086%2FScreenshot%202025-06-23%20at%2016.18.06.png?alt=media)

**Terraform 템플릿 파일을 사용하여 Workload Identity Federation 설정**

1. 다음에서 **ID 설정** 페이지에서 GCS 소스를 사용하는 사용자 지정 enrichment 생성 과정 중 "Terraform Template File"이라고 표시된 타일을 찾습니다. 타일 오른쪽에서 다음을 클릭하세요. **Select**.
2. 클릭 **Terraform template**, 그러면 자체 파이프라인을 통해 적용할 수 있도록 템플릿이 다운로드됩니다.
3. 다음의 필드를 입력하세요. `panther.tfvars` 파일에 구성 값을 입력합니다.
   * 다음 값에 대한 값을 제공하세요. `panther_workload_identity_pool_id`, `panther_workload_identity_pool_provider_id`**,** 및 `panther_aws_account_id`.
   * 나머지 리소스와 함께 버킷을 생성할지, 아니면 이미 버킷이 있는지에 대한 파일의 지침을 따르세요.
4. Terraform 구성 파일이 포함된 작업 디렉터리를 초기화하고 다음을 실행하세요. `terraform init`.
5. 해당 **Terraform Command** 를 복사하여 CLI에서 실행합니다.
6. 다음을 복사하여 풀에 대한 자격 증명 구성 파일을 생성하세요. **gcloud Command** 를 복사하고 프로젝트 번호, 풀 ID, 공급자 ID 값을 바꾼 다음 CLI에서 실행합니다.
   * 프로젝트 번호, 풀 ID, 공급자 ID는 다음의 출력에서 찾을 수 있습니다. **Terraform Command**.
7. 다음 아래에서 **Provide JSON file**, 자격 증명 구성 파일을 업로드합니다.
8. 클릭 **설정 완료**

**GCP 콘솔에서 수동으로 Workload Identity Federation 설정**

1. Google Cloud 콘솔에서 Panther가 로그를 가져올 버킷을 확인합니다.
   * 아직 버킷을 생성하지 않았다면 다음을 참조하세요. [버킷 생성에 관한 Google 문서](https://cloud.google.com/storage/docs/creating-buckets).

{% hint style="warning" %}
[Uniform bucket-level access](https://cloud.google.com/storage/docs/uniform-bucket-level-access) 는 Workload Identity Federation 엔터티가 클라우드 스토리지 리소스에 액세스할 수 있도록 하려면 대상 버킷에서 활성화되어 있어야 합니다.
{% endhint %}

2. [IAM API 활성화](https://console.cloud.google.com/apis/library/iam.googleapis.com).
3. 다음을 따라 AWS와 함께 Workload Identity Federation을 구성하세요. [Configure Workload Identity Federation with AWS or Azure](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds) 문서.
   1. 다음을 수행하는 동안 [속성 매핑 및 조건을 정의할 때](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#mappings-and-conditions), 다음 예시를 참고하세요:
      * 예시 [속성 매핑](https://cloud.google.com/iam/docs/workload-identity-federation#mapping):

        <table><thead><tr><th width="195.8271484375">Google</th><th width="523.1220703125">AWS</th></tr></thead><tbody><tr><td><code>google.subject</code></td><td><code>assertion.arn.extract('arn:aws:sts::{account_id}:')+":"+assertion.arn.extract('assumed-role/{role_and_session}').extract('/{session}')</code></td></tr><tr><td><code>attribute.account</code></td><td><code>assertion.account</code></td></tr></tbody></table>
      * 예시 [속성 조건](https://cloud.google.com/iam/docs/workload-identity-federation#conditions):\
        `attribute.account=="<PANTHER_AWS_ACCOUNT_ID>"`
   2. 다음을 수행할 때 [ID 풀에 공급자를 추가하는](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds#aws), 다음을 선택하세요. **AWS**.

{% hint style="warning" %}
의 값은 `google.subject` 속성 [127자를 초과할 수 없습니다](https://cloud.google.com/iam/docs/workload-identity-federation#mapping). 다음을 사용할 수 있습니다. [Common Expression Language (CEL) 표현식](https://cloud.google.com/iam/docs/workload-identity-federation#mapping) AWS가 발급한 토큰의 속성을 변환하거나 결합하는 데 사용할 수 있습니다. 위 표에 제안된 식은 이 제한을 고려하며, ARN을 Panther 엔터티를 고유하게 식별하는 값으로 변환하려는 시도입니다. AWS 속성에 대한 자세한 내용은 다음의 "Example 2 - Called by user created with AssumeRole"를 참조하세요. [이 AWS 문서 페이지](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html).
{% endhint %}

4. 필요한 IAM 역할을 계정에 할당합니다.

* Pub/Sub 구독과 토픽이 있는 프로젝트에는 다음 권한이 필요합니다:

  <table data-header-hidden><thead><tr><th width="327.374982940047" align="center">필요한 권한</th><th width="294.15662026309724" align="center">역할</th><th width="208" align="center">조건</th></tr></thead><tbody><tr><td align="center"><strong>필수 권한</strong></td><td align="center"><strong>역할</strong></td><td align="center"><strong>범위</strong></td></tr><tr><td align="center"><p><code>storage.objects.get</code></p><p><code>storage.objects.list</code></p></td><td align="center"><code>roles/storage.objectViewer</code></td><td align="center"><em>bucket-name</em></td></tr></tbody></table>

  * **참고:** 특정 리소스의 권한에 대해 조건 또는 IAM 정책을 설정할 수 있습니다. 이는 GCP의 IAM 섹션(아래 예시 스크린샷 참조) 또는 특정 리소스 페이지에서 수행할 수 있습니다.\
    ![In the Google Cloud console, the "IAM" navigation bar item is circled. In a slide-out panel, sections titled "Add principals" and "Assign roles" are circled.](https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-fde2bbdd808d22e67b3f2409a908d7a63596593b%2FScreenshot%202025-03-05%20at%2015.20.04.png?alt=media)
  * **참고:** 다음을 사용하여 권한을 만들 수 있습니다. `gcloud` CLI 도구에서 `$PRINCIPAL_ID` 는 다음과 같을 수 있습니다:\
    `principalSet://iam.googleapis.com/projects/<THE_ACTUAL_GOOGLE_PROJECT_NUMBER>/locations/global/workloadIdentityPools/<THE_ACTUAL_POOL_ID>/attribute.account/<THE_ACTUAL_PANTHER_AWS_ACCOUNT_ID>`
    * `gcloud projects add-iam-policy-binding $PROJECT_ID --member="$PRINCIPAL_ID" --role="roles/storage.objectViewer"`

5. [자격 증명 구성 파일 다운로드](https://cloud.google.com/iam/docs/workload-download-cred-and-grant-access), Panther에서 GCP 인프라에 인증할 때 사용됩니다.

* gcloud CLI 도구를 사용하여 자격 증명 구성 파일을 생성하려면 다음 명령 형식을 사용하세요:\
  `gcloud iam workload-identity-pools create-cred-config projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID --aws --output-file=config.json`

</details>

<details>

<summary>PAT</summary>

**PAT를 통해 GCS 버킷에서 사용자 지정 enrichment 데이터 동기화**

**파일 및 폴더 설정**

커스텀 엔리치먼트에는 다음 파일이 필요합니다:

* 엔리치먼트 테이블용 YAML 구성 파일
  * 이 커스텀 엔리치먼트 구성 파일은 이름에 다음이 포함된 폴더에 저장되어야 합니다 `lookup_tables`*.* 이는 최상위 `lookup_tables` 디렉터리일 수도 있고, 이름이 다음과 일치하는 하위 디렉터리일 수도 있습니다 `*lookup_tables*`. 다음을 참조로 사용할 수 있습니다 [panther-analysis](https://github.com/panther-labs/panther-analysis) 저장소를.
* 테이블에 데이터를 로드할 때 사용할 스키마를 정의하는 YAML 파일
  * 이 데이터 스키마 파일은 다음 위치 외부의 디렉터리에 저장해야 합니다. `lookup_tables` 디렉터리. 다른 사용자 지정 로그 스키마와 함께 저장할 수 있으며, 예를 들어 `/schemas` 디렉터리를 panther-analysis 저장소의 루트에 둘 수 있습니다.
* 테이블에 로드할 데이터를 포함하는 JSON 또는 CSV 파일(선택 사항, 자세한 내용은 계속 읽어보세요).

**스키마 및 구성 파일 작성**

일반적으로 먼저 데이터 스키마를 작성하는 것이 좋습니다. 테이블 구성에서 그중 일부 값을 참조하기 때문입니다.

1. YAML 데이터 스키마 파일을 만드세요. 이 스키마는 테이블에 데이터를 업로드할 때 사용할 파일을 읽는 방법을 정의합니다. 데이터에 CSV 파일을 사용하는 경우, 스키마는 CSV를 파싱할 수 있어야 합니다.
   * 테이블 스키마의 형식은 로그 스키마와 동일합니다. 스키마 작성에 대한 자세한 내용은 다음에 관한 문서를 참조하세요. [Log Schemas 관리.](https://docs.panther.com/data-onboarding/custom-log-types#uploading-log-schemas-with-the-panther-analysis-tool)
2. 테이블 구성용 YAML 파일을 만드세요. GCS의 파일에 저장된 데이터를 사용하는 사용자 지정 enrichment의 예시는 아래 파일을 참조하세요.
   * 다음 사항에 유의하세요. `Refresh` 필드에는 `GCSCredentials`, `StorageProvider`, `ObjectPath`, 그리고 `PeriodMinutes` 필드.
   * 필요한 값과 허용되는 값의 전체 목록은 다음에서 확인하세요. [Custom Enrichment Specification Reference](https://docs.panther.com/ko/enrichment/custom/lookup-table-specification-reference).

     ```yaml
     AnalysisType: lookup_table
     LookupName: my_lookup_table # 고유한 표시 이름
     Schema: Custom.MyTableSchema # 이전 단계에서 정의한 스키마
     Refresh:
       ObjectPath: gs://path/to/my_lookup_table_data.csv
       GCSCredentials: '{"universe_domain":"googleapis.com","type":"external_account","audience":"//iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/mypool/providers/myprovider","subject_token_type":"urn:ietf:params:aws:token-type:aws4_request","token_url":"https://sts.googleapis.com/v1/token","credential_source":{"environment_id":"aws1","region_url":"http://169.254.169.254/latest/meta-data/placement/availability-zone","url":"http://169.254.169.254/latest/meta-data/iam/security-credentials","regional_cred_verification_url":"https://sts.{region}.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15"},"token_info_url":"https://sts.googleapis.com/v1/introspect"}'
       StorageProvider: GCS
       PeriodMinutes: 120 # 2시간마다 GCS에서 동기화
     Description: >
       이 테이블에 어떤 정보가 포함되어 있는지에 대한 유용한 설명.
       예를 들어, 이 테이블은 IP 주소를 호스트 이름으로 변환할 수 있습니다.
     Reference: >
       이 테이블에 대한 추가 문서의 URL
     Enabled: true # 테이블 사용을 중지하려면 false로 설정
     LogTypeMap:
       PrimaryKey: ip                # 테이블의 기본 키
       AssociatedLogTypes:           # 이 테이블과 일치시킬 로그 유형 목록
         - LogType: AWS.CloudTrail
           Selectors:
             - "sourceIPAddress"     # CloudTrail 로그의 필드
             - "p_any_ip_addresses"  # Panther가 생성한 필드도 사용할 수 있습니다.
         - LogType: Okta.SystemLog
           Selectors:
             - "$.client.ipAddress"  # JSON 값 경로도 허용됩니다.
     ```
3. 저장소 루트에서 다음을 실행하여 스키마 파일을 업로드하세요. [`panther_analysis_tool update-custom-schemas`](https://docs.panther.com/ko/panther/detections-repo/pat/pat-commands#update-custom-schemas-creating-or-updating-custom-schemas) `--path ./schemas`.
4. 저장소 루트에서 다음을 사용하여 사용자 지정 enrichment를 업로드하세요.\
   [`panther_analysis_tool upload`](https://docs.panther.com/ko/panther/detections-repo/pat/pat-commands#upload-uploading-packages-to-panther-directly).

**사전 요구 사항**

GGS 버킷과 동기화하도록 사용자 지정 enrichment를 구성하기 전에 다음을 준비해야 합니다:

* Panther가 Google Cloud Storage 객체에 액세스하는 데 사용할 수 있는 workload identity pool의 JSON 자격 증명 구성입니다. Panther용 Workload Identity Federation 설정에 대한 자세한 내용은 다음을 참조하세요. **ID 설정** 다음의 섹션 **Panther Console** 위의 지침.
* 데이터를 저장할 파일의 경로입니다. 경로 형식은 다음과 같아야 합니다: `gs://bucket-name/path_to_file/file.csv`

</details>

## 커스텀 엔리치먼트 데이터를 사용한 디택션 작성

사용자 지정 enrichment를 구성한 후에는 추가 컨텍스트를 기반으로 디텍션을 작성할 수 있습니다.

예를 들어, AWS CloudTrail 로그에서 개발자 계정과 프로덕션 계정을 구분하도록 사용자 지정 enrichment를 구성한 경우, 다음 조건이 모두 참일 때만 알러트를 받고 싶을 수 있습니다.

* MFA가 활성화되지 않은 사용자가 로그인했습니다.
* AWS 계정이 프로덕션 계정(개발자 계정이 아님)입니다.

아래에서 enrichment 데이터를 사용하여 디텍션을 만드는 방법을 확인하세요:

{% tabs %}
{% tab title="Python" %}
**이벤트가 자동으로 enrichment된 enrichment 데이터 접근**

Python에서 다음을 사용할 수 있습니다. [`deep_get()` 헬퍼 함수](https://docs.panther.com/ko/detections/rules/python/globals#deep_get) 를 사용하여 다음에서 조회된 필드를 검색할 수 있습니다. `p_enrichment` 로그의 외래 키 필드를 사용합니다. 패턴은 다음과 같습니다:

```python
deep_get(event, 'p_enrichment', <Enrichment name>, <foreign key in log>, <field in Enrichment>)
```

{% hint style="info" %}
사용자 지정 enrichment 이름, 외래 키, 필드 이름은 모두 선택적 매개변수입니다. 지정하지 않으면 `deep_get()` 모든 enrichment 데이터가 포함된 계층형 딕셔너리를 반환합니다. 매개변수를 지정하면 관심 있는 데이터만 반환됩니다.
{% endhint %}

룰은 다음과 같이 됩니다:

```python
from panther_base_helpers import deep_get
 def rule(event):
   is_production = deep_get(event, 'p_enrichment', 'account_metadata',
'recipientAccountId', 'isProduction') # 접근하는 필드가 목록 안에 저장되어 있으면 대신 deep_walk()를 사용하세요
   return not event.get('mfaEnabled') and is_production
```

***

**동적으로 enrichment 데이터 접근**

또한 다음을 사용할 수 있습니다. [event 객체의 `lookup()` 함수](https://docs.panther.com/ko/detections/rules/python#lookup) 를 사용하여 디텍션에서 enrichment 데이터에 동적으로 접근할 수 있습니다. 이는 이벤트에 enrichment의 기본 키 열 값과 정확히 일치하는 값이 없는 경우 유용할 수 있습니다.
{% endtab %}

{% tab title="간단한 디텍션" %}
다음의 경우 [간단한 디텍션](https://docs.panther.com/ko/detections/rules/writing-simple-detections), 당신은 다음을 만들 수 있습니다. [Enrichment 일치 표현식](https://docs.panther.com/ko/detections/rules/writing-simple-detections/match-expression#enrichment-match-expressions).

```yaml
디텍션:
  - Enrichment:
      Table: account_metadata
      Selector: recipientAccountId
      FieldPath: isProduction
    Condition: Equals
    Value: true
  - KeyPath: mfaEnabled
    Condition: Equals
    Value: false
```

{% endtab %}
{% endtabs %}

Panther 룰 엔진은 조회된 일치를 가져와 다음 키를 사용하여 해당 데이터를 이벤트에 추가합니다. `p_enrichment` 다음 JSON 구조에서:

```json
{ 
    "p_enrichment": {
        <enrichment table name>: { 
            <일치한 로그의 키>: <조회된 일치 행>,
            ...
	    <일치한 로그의 키>: <조회된 일치 행>,
	}    
    }
} 
```

예시:

```json
 {
  "p_enrichment": {
      "account_metadata": {
          "recipientAccountId": {
              "accountID": "90123456", 
              "isProduction": false, 
              "email": "dev.account@example.com",
              "p_match": "90123456"
              }
          }
      }
}

```

일치하는 로그 키의 값이 배열인 경우(예: `p_any_aws_accout_ids`), 조회 데이터는 일치하는 레코드를 포함하는 배열입니다.

```json
{ 
    "p_enrichment": {
        <enrichment table name>: { 
            <배열인 일치한 로그의 키>: [
                <조회된 일치 행>,
                <조회된 일치 행>,
                <조회된 일치 행>
            ]
	}
     }
} 
```

예시:

```json
 {
  "p_enrichment": {
      "account_metadata": {
          "p_any_aws_account_ids": [
             {
              "accountID": "90123456", 
              "isProduction": false, 
              "email": "dev.account@example.com",
              "p_match": "90123456"
              },
              {
              "accountID": "12345678", 
              "isProduction": true, 
              "email": "prod.account@example.com",
              "p_match": "12345678"
              }
          ]
      }
  }
}
```

### enrichment를 사용하는 디텍션 테스트

다음을 사용하는 룰의 경우 `p_enrichment`, 다음을 클릭하세요. **Enrich Test Data** JSON 코드 편집기 오른쪽 상단에서 이를 사용하여 Enrichment 데이터로 채웁니다. 이를 통해 다음을 포함하는 이벤트로 Python 함수를 테스트할 수 있습니다. `p_enrichment`.

{% hint style="info" %}
단위 테스트가 올바르게 enrichment되려면 이벤트에 다음 두 필드가 지정되어야 합니다:

* `p_log_type`: 어떤 Enrichment를 사용할지 결정합니다.
* 선택자 필드: 일치시킬 값을 제공합니다
  {% endhint %}

<figure><img src="https://2400888838-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-313f3e4ff14db84cfcdb889dea2b17b72d4213c8%2Funit-test-enrichment-example?alt=media" alt="A &#x22;Unit Test&#x22; header is above a code block with JSON. The JSON includes various key/value pairs—for example, &#x22;p_log_type&#x22;: &#x22;My.Log.Type&#x22;"><figcaption></figcaption></figure>
