> For the complete documentation index, see [llms.txt](https://docs.panther.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.panther.com/ko/detections/rules/python/data-models.md). # 데이터 모델 ## 개요 모든 로그 유형 전반에서 통합된 필드 집합을 구성하려면 Data Models를 생성하여 [매핑](#datamodel-mappings) 다양한 로그 유형의 이벤트 필드와 통합 Data Model 이름 간에. [Panther-managed Data Models](#panther-managed-data-models), 그리고 [사용자 지정 항목을 만들기](#how-to-create-custom-data-models). {% hint style="warning" %} Data Models는 다음과 함께 사용할 수 없습니다: [예약된 룰 또는 예약된 쿼리](https://docs.panther.com/ko/detections/rules/python/pages/03a99462193d3cb6f09cb46a6d9fa32a7a6035d0#rules-vs.-scheduled-rules). Data Models는 로그 유형별로 키가 지정되지만, 예약된 룰은 연결된 예약된 쿼리의 출력에 대해 동작하며 원시 로그 유형 이벤트에 대해서는 동작하지 않으므로, 실행 시에는 어떤 Data Model도 적용되지 않습니다. 예약된 룰의 Python이 [`event.udm()`](/ko/detections/rules/python.md#udm). 참고하세요 [아래의 Data Models 테스트](#testing-data-models) 예약된 룰을 단위 테스트할 때 관련된 함정에 대해. {% endhint %} ### Data Models 사용 사례 네트워크 트래픽 로그에서 특정 출발지 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-managed Data Models 기본적으로 Panther에는 다음과 같은 여러 로그 유형에 대한 내장 Data Models가 포함되어 있습니다: `AWS.S3ServerAccess`, `AWS.VPCFlow`, 그리고 `Okta.SystemLog`. 현재 지원되는 모든 data models는 다음에서 찾을 수 있습니다: [panther-analysis 저장소, 여기에서](https://github.com/panther-labs/panther-analysis/tree/main/data_models). 지원되는 Data Model 매핑의 이름은 다음에 나열되어 있습니다: [아래의 Panther-managed Data Model mapping names 표](#panther-managed-data-model-mapping-names). ## 사용자 지정 Data Models를 만드는 방법 사용자 지정 Data Models는 몇 가지 방법으로 만들 수 있습니다. Panther Console에서 다음을 사용하여 [Panther Analysis Tool (PAT)](/ko/panther/detections-repo/pat.md), 또는 다음에서 [Panther API](/ko/panther/api.md). 각 방법에 대한 생성 지침은 아래 탭을 참조하세요. 사용자 지정 Data Model 매핑에는 다음을 사용할 수 있습니다: [Panther-managed Data Models에서 참조되는 이름](#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의 왼쪽 탐색 막대에서 다음을 클릭하세요: **디택션**. 2. 다음을 클릭하세요: **Data Models** 탭**.**\ .![The list of Data Models in the Panther Console is displayed](/files/393c2b90705220d1aecee1b5c6ce0c59e72f3ee9) 3. 오른쪽 상단에서 다음을 클릭하세요: **새로 만들기**. 4. 다음에서 **설정**, 양식 필드를 채우세요. * **표시 이름**: 이 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. 오른쪽 상단에서 다음을 클릭하세요: **저장**. * 이제 이 Data Model을 룰에서 참조할 수 있습니다. 자세한 내용은 [룰에서 Data Models 참조](#referencing-data-models-in-a-rule). {% endtab %} {% tab title="CLI(PAT)" %} **CLI 워크플로에서 Data Model을 만드는 방법** **폴더 설정** 사용자 지정 Data Models와 관련된 모든 파일은 이름에 다음을 포함하는 폴더에 저장해야 합니다: `data_models` (이는 최상위 `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 - Name: event_type Method: get_event_type - Name: source_ip Path: sourceIPAddress - Name: user_agent Path: userAgent ``` * 설정 `AnalysisType` 로 `datamodel`. * 다음의 `LogTypes`, 로그 유형 중 하나의 이름을 제공하세요. 이 필드는 목록을 받지만, Data Model당 로그 유형은 하나만 지원됩니다. * 다음의 값을 입력하세요: `DataModelID` 필드. * 다음에서 `Mappings`, 생성하여 `Name` / `Path` 또는 `Name` / `Method` 쌍. * 자세히 알아보기 `Mappings` 구문 [아래의 DataModel에서 `Mappings`](#datamodel-mappings). * 참조하세요 [Data Model 사양 참조](#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': "failed_login" if event.get('responseElements', {}).get('ConsoleLogin') == 'Success': "successful_login" return None ``` 3. 다음을 사용하여 Data Model을 Panther 인스턴스에 업로드하세요: [PAT `업로드` 명령](/ko/panther/detections-repo/pat/pat-commands.md#upload-uploading-packages-to-panther-directly). * 이제 이 Data Model을 룰에서 참조할 수 있습니다. 자세한 내용은 [룰에서 Data Models 참조](#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-managed `gsuite_data_model.yml`](https://github.com/panther-labs/panther-analysis/blob/main/data_models/gsuite_data_model.yml): ```yaml - Name: assigned_admin_role Path: $.events[*].parameters[?(@.name == 'ROLE_NAME')].value ``` ## Data Models 사용 ### 룰에서 Data Models 참조 룰에서 Data Model 필드를 참조하려면: 1. 룰의 YAML 파일에서 다음을 확인하세요: `LogTypes` 필드에 적용하려는 Data Model의 로그 유형이 포함되어 있습니다: ```yaml AnalysisType: 룰 DedupPeriodMinutes: 60 DisplayName: DataModel Example 룰 Enabled: true Filename: my_new_룰.py RuleID: DataModel.Example.룰 Severity: High LogTypes: # 이 룰이 적용되는 LogTypes를 추가하세요 # 그리고 해당 LogType에 대한 Data Model이 존재해야 합니다 - AWS.CloudTrail Tags: - 태그 Description: > 이 룰은 Panther CLI의 CLI 워크플로를 검증하기 위해 존재합니다 Runbook: > 먼저 이 spec format을 누가 작성했는지 알아낸 다음, 피드백을 보내 알려주세요. Tests: - Name: test 룰 ExpectedResult: true # 테스트 사양의 'p_log_type' 필드에 LogType을 추가하세요 Log: { "p_log_type": "AWS.CloudTrail" } ``` 2. 룰의 모든 `테스트` 케이스에 다음을 추가하세요: `p_log_type` 필드. 3. 사용 [다음 `event.udm()` 메서드](/ko/detections/rules/python.md#udm) 룰의 Python 로직에서: ```python def 룰(event): # 통합 data model 필드에서 이벤트를 필터링 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')) ``` ### 보강이 포함된 데이터 모델 사용 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')) return {'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`.
The screen shot shows a passing test in the Panther Console including the alert context with the data key and data value
### 데이터 모델 테스트 데이터 모델을 테스트하려면 작성 [단위 테스트](/ko/detections/testing.md) 데이터 모델 매핑을 참조하는 디택션에 대해 사용하여 [`event.udm()`](/ko/detections/rules/python.md#udm) 그 안의 `룰()` 로직. {% hint style="warning" %} 단위 테스트를 할 때 **예약된 룰** (Panther Console 또는 [PAT](/ko/panther/detections-repo/pat.md)), 테스트 이벤트에 다음이 포함되어 있다면 `p_log_type` 필드가 포함되어 있으면 Panther는 해당 로그 유형의 Data Model을 테스트 이벤트에 적용합니다—프로덕션에서는 예약된 룰에 Data Model이 적용되지 않더라도 마찬가지입니다. 이로 인해 예약된 룰의 테스트가 런타임에는 채워지지 않을 Data Model이 적용된 필드를 기준으로 통과할 수 있어, 룰의 로직에 대해 잘못된 확신을 줄 수 있습니다. 따라서 [Data Models는 예약된 룰과 함께 사용할 수 없습니다](#overview), 의존하지 마십시오 `event.udm()` 예약된 룰 로직에서 {% endhint %} ## DataModel 사양 참조 DataModel 사양 필드의 전체 목록:
필드 이름필수설명예상 값
필드 이름필수설명예상 값
AnalysisType예이 사양이 룰, 정책, 데이터 모델 또는 전역을 정의하는지 여부를 나타냅니다datamodel
DataModelID예데이터 모델의 고유 식별자문자열
표시 이름아니오UI와 경고에 표시할 이름입니다. 그 DataModelID 이 필드가 설정되지 않으면 표시됩니다.문자열
활성화됨예이 Data Model이 활성화되어 있는지 여부불리언
파일 이름아니오Python Data Model 본문의 경로(파일 확장자 포함)문자열
LogTypes예이 Data Model이 적용될 로그 유형문자열의 단일 항목 목록
참고: 비록 LogTypes 문자열 목록을 허용하지만, Data Model당 로그 유형은 하나만 지정할 수 있습니다
Mappings예소스 필드 이름 또는 메서드에서 통합 데이터 모델 필드 이름으로의 매핑목록 Mappings
### 데이터 모델 `Mappings` 매핑은 `로그 유형` 필드를 통합 데이터 모델 필드로 변환합니다. 각 `Mappings` 항목은 다음을 정의해야 합니다: * `Name`: 탐지에서 이 데이터 모델을 참조하는 방법. * 다음 중 하나: * `Path`: 원래 로그 유형의 스키마에서 해당 필드로 가는 경로입니다. 이 값은 단순한 필드 이름이거나 JSON 경로일 수 있습니다. jsonpath-ng에 대한 자세한 내용은 [pypi.org의 설명서를 참조하세요](https://pypi.org/project/jsonpath-ng/). * `Method`: 메서드의 이름입니다. 메서드는 데이터 모델 사양에 나열된 파일에 정의되어 있어야 합니다 `Filename` 필드. 예: ```yaml Mappings: - Name: source_ip 경로: srcIp - 이름: user 경로: $.events[*].parameters[?(@.name == 'USER_EMAIL')].value - Name: event_type Method: get_event_type ``` 그 `Path` 값은 `사용자` 데이터 모델에는 로직이 있습니다. 해당 `USER_EMAIL` 이벤트 필드가 존재하는지 확인하는 로직이 있습니다. 자세한 내용은 [필드가 다음에 존재하는지 평가하기 `Path`](#evaluating-whether-a-field-exists-in-path). ## Panther에서 관리하는 Data Model 매핑 이름 그 [Panther에서 관리하는 Data Model](https://github.com/panther-labs/panther-analysis/tree/main/data_models) 매핑 이름은 아래에 설명되어 있습니다. 이때 [자체 Data Model 매핑을 만들 때](#how-to-create-custom-data-models), 아래의 이름은 사용자 정의 이름과 함께 사용할 수 있습니다.
통합 데이터 모델 필드 이름설명
데이터 모델 매핑 이름설명
actor_user이벤트를 트리거한 동작의 주체인 사용자의 ID 또는 사용자 이름.
assigned_admin_role이벤트에서 사용자에게 할당된 관리자 역할의 ID 또는 이름.
destination_ip트래픽의 대상 IP
destination_port트래픽의 대상 포트
event_type이벤트 유형에 대한 사용자 지정 설명입니다. 이벤트 유형에 대한 기본 제공 지원은 global, 에서 찾을 수 있습니다. panther_event_type_helpers.py.
http_status트래픽의 숫자 HTTP 상태 코드
source_ip트래픽의 출발지 IP
source_port트래픽의 출발지 포트
user_agent이벤트의 클라이언트와 연결된 사용자 에이전트.
사용자이벤트를 트리거하기 위해 조치를 받은 사용자의 ID 또는 사용자 이름.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.panther.com/ko/detections/rules/python/data-models.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.