# 데이터 모델

## 개요

Data Model을 사용하여 [매핑](#datamodel-mappings) 을 생성함으로써 모든 로그 유형에 걸쳐 통합된 필드 집합을 구성합니다. 다양한 로그 유형의 이벤트 필드와 통합된 Data Model 이름 사이에. 다음을 활용할 수 있습니다. [Panther에서 관리하는 Data Model](#panther-managed-data-models)와 [사용자 지정 Data Model을 생성](#how-to-create-custom-data-models).

### Data Model 사용 사례

네트워크 트래픽 로그에서 특정 소스 IP 주소를 확인하는 디택션이 있고, 이를 여러 로그 유형에 사용하고 싶다고 가정해 보겠습니다. 이러한 로그 유형은 서로 다른 카테고리(예: DNS, Zeek, Apache)를 넘나들 뿐만 아니라 서로 다른 공급업체에 속할 수도 있습니다. 공통 로그 표준이 없으면, 이러한 각 로그 유형은 소스 IP를 `ipAddress`, `srcIP`또는 `ipaddr`와 같은 서로 다른 필드 이름으로 나타낼 수 있습니다. 모니터링하려는 로그 유형이 많아질수록 이 검사 로직은 더 복잡하고 다루기 어려워집니다. 예를 들어, 다음과 같이 보일 수 있습니다:

```python
(event.get('ipAddress') == '127.0.0.1' or 
event.get('srcIP') == '127.0.0.1' or 
event.get('ipaddr') == '127.0.0.1')
```

대신 이러한 각 로그 유형에 대해 Data Model을 정의하면, 이벤트의 필드 이름을 Data Model 이름으로 변환할 수 있으므로, 디택션은 단순히 Data Model 버전을 참조하면 됩니다. 그러면 위 로직은 다음과 같이 단순화됩니다:

```python
event.udm('source_ip') == '127.0.0.1'
```

## Panther에서 관리하는 Data Model

기본적으로 Panther에는 다음과 같은 여러 로그 유형에 대한 기본 제공 Data Model이 포함되어 있습니다. `AWS.S3ServerAccess`, `AWS.VPCFlow`와 `Okta.SystemLog`. 현재 지원되는 모든 data model은 다음에서 확인할 수 있습니다. [panther-analysis 저장소, 여기](https://github.com/panther-labs/panther-analysis/tree/main/data_models).

지원되는 Data Model 매핑의 이름은 아래의 [Panther에서 관리하는 Data Model 매핑 이름 표](#panther-managed-data-model-mapping-names).

## 사용자 지정 Data Model을 만드는 방법

사용자 지정 Data Model은 몇 가지 방법으로 만들 수 있습니다: Panther Console에서, [Panther Analysis Tool (PAT)](/ko/panther/detections-repo/pat.md)를 사용하거나, [Panther API](/ko/panther/api.md). 각 방법별 생성 지침은 아래 탭을 참조하세요.

사용자 지정 Data Model 매핑은 [Panther에서 관리하는 Data Model에서 참조되는 이름](#panther-managed-data-model-mapping-names)또는 자신만의 사용자 지정 이름을 사용할 수 있습니다. 각 매핑 `Name` 은(는) 이벤트 필드에 매핑할 수 있습니다( `Path` 또는 **Field Path**) 또는 직접 정의한 메서드에 매핑할 수 있습니다( `Field Method` 또는 **Method**). 메서드에 매핑하는 경우, 메서드는 별도의 Python 파일(CLI 워크플로를 사용하는 경우)에 정의해야 하며, YAML 파일에서는 `Filename`를 사용하거나, **Python Module** 필드를 사용해 참조됩니다. 콘솔에서는

각 로그 유형에는 하나의 활성화된 Data Model만 지정할 수 있습니다(단, 하나의 Data Model에는 여러 매핑이 포함될 수 있습니다). 기존 Data Model을 변경하거나 업데이트하려면 기존 항목을 비활성화한 다음 새 활성 항목을 생성하세요.

{% tabs %}
{% tab title="Panther Console" %}
Panther Console에서 새 Data Model을 생성하려면:

1. Panther Console의 왼쪽 탐색 표시줄에서 **Detections**.
2. 을 클릭합니다. **Data Models** 탭**.**\
   .![The list of Data Models in the Panther Console is displayed](/files/393c2b90705220d1aecee1b5c6ce0c59e72f3ee9)
3. 오른쪽 상단 모서리에서 **Create New**.
4. 아래에서 **Settings**을 클릭한 뒤, 양식 필드를 입력합니다.
   * **표시 이름**: 이 Data Model에 사용자 친화적인 표시 이름을 입력합니다.
   * **ID**: 이 Data Model에 대한 고유 ID를 입력합니다.
   * **로그 유형**: 이 Data Model을 적용할 로그 유형을 선택합니다. Data Model당 로그 유형은 하나만 허용됩니다.
   * **활성화됨**: 이 Data Model을 활성화할지 비활성화할지 선택합니다.\
     ![In the Panther Console, the New Data Model screen is displayed. It contains fields for Display Name, ID, and Log Type. Under "Data Model Mappings" there are fields are Name, Field Path, and Field Method.](/files/ba856293c3d3741351a726490bef4fea3af94d71)
5. 아래에서 **Data Model 매핑**, 생성합니다 **Name**/**Field Path** 또는 **Name**/**Field Method** 쌍을.
6. 만약 **Field Method** 필드를 사용했다면, **Python Module *****(선택 사항)*** 섹션에서 메서드를 정의합니다.
7. 오른쪽 상단 모서리에서 **Save**.
   * 이제 규칙에서 이 Data Model을 참조할 수 있습니다. 자세한 내용은 다음에서 알아보세요. [룰에서 Data Model 참조하기](#referencing-data-models-in-a-rule).
     {% endtab %}

{% tab title="CLI (PAT)" %}
**CLI 워크플로에서 Data Model을 생성하는 방법**

**폴더 설정**

사용자 지정 Data Model과 관련된 모든 파일은 이름에 `data_models` 이 포함된 폴더에 저장해야 합니다 `data_models` (이것은 최상위 `디렉터리일 수도 있고, 이름이`).

**파일 설정**

1. Data Model 사양 YAML 파일을 생성합니다(예: `data_models/aws_cloudtrail_datamodel.yml`):

   ```yaml
   AnalysisType: datamodel
   LogTypes: 
     - AWS.CloudTrail
   DataModelID: AWS.CloudTrail
   Filename: aws_cloudtrail_data_model.py
   Enabled: true
   Mappings:
     - Name: actor_user
       Path: $.userIdentity.userName
     - 이름: event_type
       메서드: get_event_type
     - 이름: source_ip
       경로: sourceIPAddress
     - 이름: user_agent
       경로: userAgent
   ```

   * 설정 `AnalysisType` 을 `datamodel`.
   * 다음에 대해 `LogTypes`, 로그 유형 중 하나의 이름을 제공하세요. 이 필드는 목록을 받지만, 데이터 모델당 하나의 로그 유형만 지원됩니다.
   * 다음에 대한 값을 제공하세요. `DataModelID` 필드.
   * 다음 내에서 `Mappings`, 생성합니다 `Name` / `Path` 또는 `Name` / `Method` 쌍을.
     * 에 대해 자세히 알아보세요 `Mappings` 구문 [아래의 DataModel에서 `Mappings`](#datamodel-mappings).
   * 참조 [Data Model Specification Reference](#datamodel-specification-reference) 필수 및 선택 필드의 전체 목록은 아래를 참조하세요.
2. 하나 이상의 항목을 포함한 경우 `Method` 필드가 다음 내에 `Mappings`, 연결된 Python 파일(`data_models/aws_cloudtrail_datamodel.py`)를 생성하고, 참조된 메서드를 정의하세요.
   * 이 경우 다음 항목도 추가해야 합니다 `Filename` 필드를 Data Model YAML 파일에 추가하세요. 만약 `Method` 필드가 존재하지 않으면, Python 파일/`Filename` 필드가 필요하지 않습니다.

     ```python
     from panther_base_helpers import deep_get
     def get_event_type(event):
         if event.get('eventName') == 'ConsoleLogin' and deep_get(event, 'userIdentity', 'type') == 'IAMUser':
             if event.get('responseElements', {}).get('ConsoleLogin') == 'Failure':
                 return "failed_login"
             if event.get('responseElements', {}).get('ConsoleLogin') == 'Success':
                 return "successful_login"
         return None
     ```
3. PAT를 사용하여 Panther 인스턴스에 Data Model을 업로드하세요 [PAT `업로드` 명령](/ko/panther/detections-repo/pat/pat-commands.md#upload-uploading-packages-to-panther-directly).
   * 이제 규칙에서 이 Data Model을 참조할 수 있습니다. 자세한 내용은 다음에서 알아보세요. [룰에서 Data Model 참조하기](#referencing-data-models-in-a-rule).
     {% endtab %}

{% tab title="API" %}
**Panther API를 사용하여 Data Model을 만드는 방법**

* 다음을 참조하세요 `POST` 에서의 작업 [Data Models](/ko/panther/api/rest/data-models.md).
  {% endtab %}
  {% endtabs %}

### 필드가 존재하는지 평가하기 `Path`

값 내부에서 `Path` 이벤트 필드가 특정 필드가 존재하는지 확인하는 로직을 포함할 수 있습니다. 존재하면 매핑이 적용되고, 존재하지 않으면 매핑이 적용되지 않습니다.

예를 들어, 다음 Path 값을 [Panther가 관리하는 `gsuite_data_model.yml`](https://github.com/panther-labs/panther-analysis/blob/main/data_models/gsuite_data_model.yml):

```yaml
  - 이름: assigned_admin_role
    경로: $.events[*].parameters[?(@.name == 'ROLE_NAME')].value
```

## 데이터 모델 사용하기

### 룰에서 Data Model 참조하기

룰에서 데이터 모델 필드를 참조하려면:

1. 룰의 YAML 파일에서 확인하세요 `LogTypes` 필드에는 적용하려는 데이터 모델의 로그 유형이 포함됩니다:

   ```yaml
   AnalysisType: 룰
   중복 제거 기간(분): 60
   DisplayName: DataModel 예제 룰
   Enabled: true
   파일 이름: my_new_룰.py
   룰ID: DataModel.Example.룰
   심각도: 높음
   LogTypes:
     # 이 룰이 적용되는 LogTypes를 추가하세요
     # 그리고 해당 LogType에 대한 데이터 모델이 존재합니다
     - AWS.CloudTrail
   태그:
     - 태그
   설명: >
     이 룰은 Panther CLI의 CLI 워크플로를 검증하기 위해 존재합니다
   런북: >
     먼저, 누가 이 사양 형식을 작성했는지 알아낸 다음, 피드백과 함께 그들에게 알리세요.
   테스트:
     - 이름: test 룰
       예상결과: true
       # 'p_log_type' 필드에 LogType을 테스트 사양에 추가합니다
       로그: {
         "p_log_type": "AWS.CloudTrail"
       }
   ```
2. 모든 룰의 `테스트` 사례에 로그 유형을 추가합니다, `p_log_type` 필드.
3. 사용 [the `event.udm()` 메서드](/ko/detections/rules/python.md#udm) 룰의 Python 로직에서:

   ```python
   def 룰(event):    
       # 통합 데이터 모델 필드에서 이벤트 필터링
       return event.udm('event_type') == 'failed_login'


   def title(event):
       # 제목에 통합 데이터 모델 필드 사용
       return '{}: IP [{}]의 사용자 [{}]가 실패한 로그인 임계값을 초과했습니다'.format(
           event.get('p_log_type'), event.udm('actor_user'),
           event.udm('source_ip'))
   ```

### Enrichment와 함께 데이터 모델 사용

Panther는 event 객체에 다음과 같은 내장 메서드를 제공합니다. `event.udm_path()`. 이는 데이터 모델에 사용된 원래 경로를 반환합니다.

#### AWS.VPCFlow 로그 예시

아래 예시에서, `event.udm_path('destination_ip')` 를 호출하면 다음을 반환합니다. `'dstAddr'`, 이는 해당 로그 유형의 데이터 모델에서 정의된 경로이기 때문입니다.

```python
from panther_base_helpers import deep_get

def 룰(event):
    True를 반환합니다

def title(event):
    event.udm_path('destination_ip')를 반환합니다

def 알러트_context(event):
    enriched_data = deep_get(event, 'p_enrichment', 'lookup_table_name', event.udm_path('destination_ip'))
    {'enriched_data':enriched_data}를 반환합니다
```

이를 테스트하기 위해, 다음 테스트 케이스를 사용할 수 있습니다:

```json
{   
  "p_log_type": "AWS.VPCFlow",
   "dstAddr": "1.1.1.1",
   "p_enrichment": {
      "lookup_table_name": {
        "dstAddr": {
          "datakey": "datavalue" }}}}
```

테스트 케이스는 다음 알러트를 반환하며, 알러트 컨텍스트에는 `dstAddr` (또는 `{"datakey": "datavalue"}`)가 다음의 값으로 포함됩니다. `enriched_data`.

<figure><img src="/files/20dd1c399dff09f7682f7a9306d5d279052a9c4e" alt="The screen shot shows a passing test in the Panther Console including the alert context with the data key and data value" width="375"><figcaption></figcaption></figure>

### 데이터 모델 테스트

데이터 모델을 테스트하려면, [단위 테스트](/ko/detections/testing.md) 데이터 모델 매핑을 참조하는 디택션에 대해 작성하세요. [`event.udm()`](/ko/detections/rules/python.md#udm) 의 `룰()` 로직에서.

## DataModel 사양 참조

DataModel 사양 필드의 전체 목록:

<table data-header-hidden><thead><tr><th width="172">필드 이름</th><th width="100.18672199170126">필수</th><th width="271">설명</th><th>예상 값</th></tr></thead><tbody><tr><td>필드 이름</td><td>필수</td><td>설명</td><td>예상 값</td></tr><tr><td><code>AnalysisType</code></td><td>예</td><td>이 사양이 룰, 정책, 데이터 모델 또는 전역을 정의하는지 여부를 나타냅니다</td><td><code>datamodel</code></td></tr><tr><td><code>DataModelID</code></td><td>예</td><td>데이터 모델의 고유 식별자</td><td>문자열</td></tr><tr><td><code>표시 이름</code></td><td>아니요</td><td>UI 및 알러트에 표시할 이름입니다. The <code>DataModelID</code> 이 필드가 설정되지 않은 경우 표시됩니다.</td><td>문자열</td></tr><tr><td><code>활성화됨</code></td><td>예</td><td>이 데이터 모델이 활성화되어 있는지 여부</td><td>불리언</td></tr><tr><td><code>파일 이름</code></td><td>아니요</td><td>Python 데이터 모델 본문으로의 경로(파일 확장자 포함)</td><td>문자열</td></tr><tr><td><code>LogTypes</code></td><td>예</td><td>이 데이터 모델이 적용될 로그 유형</td><td>문자열의 단일 항목 목록<br>참고: 비록 <code>LogTypes</code> 문자열 목록을 허용하지만, 데이터 모델당 로그 유형은 하나만 지정할 수 있습니다</td></tr><tr><td><code>Mappings</code></td><td>예</td><td>소스 필드 이름 또는 메서드에서 통합 데이터 모델 필드 이름으로의 매핑</td><td><a href="#datamodel-mappings">목록 <code>Mappings</code></a></td></tr></tbody></table>

### 데이터 모델 `Mappings`

매핑은 `로그 유형` 필드를 통합 데이터 모델 필드로 변환합니다. 각 `Mappings` 항목은 다음을 정의해야 합니다:

* `Name`: 탐지에서 이 데이터 모델을 참조하는 방법.
* 다음 중 하나:
  * `Path`: 원래 로그 유형의 스키마에서 필드로의 경로입니다. 이 값은 단순한 필드 이름일 수도 있고 JSON 경로일 수도 있습니다. jsonpath-ng에 대한 자세한 내용은 다음을 참조하세요. [여기에서 pypi.org 문서](https://pypi.org/project/jsonpath-ng/).
  * `Method`: 메서드 이름입니다. 이 메서드는 데이터 모델 사양에 나열된 파일에 정의되어 있어야 합니다 `Filename` 필드.

예시:

```yaml
Mappings:
  - 이름: source_ip
    경로: srcIp
  - 이름: user
    경로: $.events[*].parameters[?(@.name == 'USER_EMAIL')].value
  - 이름: event_type
    메서드: get_event_type
```

해당 `Path` 값은 `user` 데이터 모델에는 다음 항목이 있는지 확인하는 로직이 있습니다. `USER_EMAIL` 이벤트 필드가 존재합니다. 자세히 알아보기 [필드가 존재하는지 평가하기 `Path`](#evaluating-whether-a-field-exists-in-path).

## Panther에서 관리하는 데이터 모델 매핑 이름

해당 [Panther에서 관리하는 데이터 모델](https://github.com/panther-labs/panther-analysis/tree/main/data_models) 매핑 이름은 아래에 설명되어 있습니다. 다음을 수행할 때 [자체 데이터 모델 매핑을 생성할 때](#how-to-create-custom-data-models)아래 이름을 사용자 지정 이름과 함께 사용할 수 있습니다.

<table data-header-hidden><thead><tr><th width="252">통합 데이터 모델 필드 이름</th><th>설명</th></tr></thead><tbody><tr><td>데이터 모델 매핑 이름</td><td>설명</td></tr><tr><td><code>actor_user</code></td><td>이벤트를 트리거한 작업의 사용자 ID 또는 사용자 이름.</td></tr><tr><td><code>assigned_admin_role</code></td><td>이벤트에서 사용자에게 할당된 관리자 역할 ID 또는 이름.</td></tr><tr><td><code>destination_ip</code></td><td>트래픽의 대상 IP</td></tr><tr><td><code>destination_port</code></td><td>트래픽의 대상 포트</td></tr><tr><td><code>event_type</code></td><td>이벤트 유형에 대한 사용자 지정 설명. 이벤트 유형에 대한 기본 제공 지원은 전역에서 찾을 수 있습니다, <code>panther_event_type_helpers.py</code>.</td></tr><tr><td><code>http_status</code></td><td>트래픽의 숫자 HTTP 상태 코드</td></tr><tr><td><code>source_ip</code></td><td>트래픽의 출발지 IP</td></tr><tr><td><code>source_port</code></td><td>트래픽의 출발지 포트</td></tr><tr><td><code>user_agent</code></td><td>이벤트에서 클라이언트와 연관된 사용자 에이전트.</td></tr><tr><td><code>user</code></td><td>이벤트를 발생시키기 위해 작업 대상이 된 사용자의 ID 또는 사용자 이름.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.panther.com/ko/detections/rules/python/data-models.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.