Custom 로그

사용자 지정 스키마를 정의, 작성 및 관리

개요

Panther를 사용하면 사용자 지정 로그 스키마를 직접 정의할 수 있습니다. Panther로 사용자 지정 로그를 수집하려면 데이터 전송,을/를 통해 수행할 수 있으며, 그러면 사용자 지정 스키마가 데이터를 정규화하고 분류합니다.

이 페이지에서는 필요한 사용자 지정 스키마 수를 결정하고, 사용자 지정 스키마를 추론하고, 작성하고, 관리하는 방법과 Panther Analysis Tool (PAT)을/를 사용하여 스키마를 업로드하는 방법을 설명합니다. 사용 방법에 대한 정보는 pantherlog 을/를 사용해 사용자 지정 스키마로 작업하는 방법은 pantherlog CLI 도구.

사용자 지정 스키마는 Custom. 접두사가 이름에 포함되어 식별되며, 기본적으로 지원되는 로그 유형이 사용되는 모든 곳에서 사용할 수 있습니다:

• 로그 수집

  • 사용자 지정 로그는 데이터 전송 (예: HTTP 웹훅, S3, SQS, Google Cloud Storage, Azure Blob Storage)을 통해 온보딩할 수 있습니다

• 디택션

  • 사용자 지정 스키마에 대해 룰 및 예약된 룰 을/를 작성할 수 있습니다.

• 조사

  • 데이터를 검색 및 데이터 탐색기에서 쿼리할 수 있습니다. 해당 스키마를 사용하는 소스를 온보딩하면 Panther가 사용자 지정 스키마용 새 테이블을 생성합니다.

필요한 사용자 지정 스키마 수 결정하기

사용자 지정 소스에서 들어오는 데이터를 표현하는 데 몇 개의 스키마가 필요한지 결정하는 확정적인 룰은 없습니다. 이는 다양한 로그 이벤트의 의도와 그 사이의 필드 중복 정도에 따라 달라지기 때문입니다.

일반적으로는 각 로그 유형의 형태를 자체 스키마로 표현하는 데 필요한 최소 개수의 스키마를 만드는 것이 권장됩니다(동일한 스키마로 표현할 수 있도록 로그 유형 간 일부 필드 차이의 여지는 허용). 경험칙은 다음과 같습니다. 서로 다른 두 유형의 로그(예: 애플리케이션 감사 로그와 보안 경고)가 필수 필드에서 50% 미만만 겹친다면, 서로 다른 스키마를 사용해야 합니다.

아래 표에서 예시 시나리오와 그에 해당하는 스키마 권장 사항을 확인하세요:

시나리오	스키마 권장 사항
필드가 있는 한 가지 로그 유형이 있고 A, B, 및 C, 그리고 필드가 있는 다른 로그 유형이 있습니다 X, Y, 및 Z.	로그 유형별로 하나씩, 서로 다른 두 개의 스키마를 생성하세요. 기술적으로는 모든 필드(A, B, C, X, Y, Z)를 선택 사항으로 표시한 하나의 스키마를 만드는 것이 가능하지만(즉, required: false), 권장되지는 않습니다. 이후의 디택션 작성 및 검색 같은 작업이 더 어려워지기 때문입니다.
항상 필드가 있는 한 가지 로그 유형이 있고 A, B, 및 C, 그리고 항상 필드가 있는 다른 로그 유형이 있습니다 A, B, 및 Z.	필드를 포함한 하나의 스키마를 생성하고 A 및 B 는 필수로 표시하고 필드 C 및 Z 는 선택 사항으로 표시하세요.

필요한 스키마 수를 결정한 후에는 이를 정의할 수 있습니다.

스키마가 두 개 이상 필요하다고 판단했고 Panther의 스키마 추론 도구 를 사용해 이를 생성하려는 경우, 다음 중 하나를 수행하는 것이 좋습니다:

• 다음을 사용하세요. 샘플 로그에서 사용자 지정 스키마 추론하기 방법을 서로 다른 로그 유형의 샘플로 여러 번 사용

• 구조가 다른 데이터를 S3 버킷의 별도 폴더로 전송한 다음, 과거 S3 데이터에서 사용자 지정 스키마 추론하기 추론 방법을 사용

다음 중 하나인 Panther에서 수신한 S3 데이터로부터 사용자 지정 스키마 추론하기 또는 Panther에서 수신한 HTTP 데이터로부터 사용자 지정 스키마 추론하기 방법을 사용하면, Panther가 소스로 전송된 모든 로그 유형을 나타내는 단일 스키마를 생성할 위험이 있습니다.

사용자 지정 스키마 정의 방법

사용자 지정 로그 유형의 경우, Panther는 JSON, XML 또는 CSV(헤더 포함 또는 미포함) 형식으로 전송된 데이터 수집을 지원합니다. 스키마 추론의 경우 Panther는 헤더 없는 CSV를 지원하지 않습니다.

사용자 지정 스키마를 정의하는 방법은 여러 가지가 있습니다. 다음을 수행할 수 있습니다:

• 데이터에서 하나 이상의 스키마 추론: Panther에서 스키마 자동 추론.

• 수동으로 스키마 생성: 직접 스키마 생성.

Panther에서 스키마 자동 추론

스키마를 수동으로 작성하는 대신, Panther Console 또는 pantherlog CLI 도구를 사용해 데이터에서 스키마(또는 여러 스키마)를 추론할 수 있습니다.

Panther가 스키마를 추론할 때, 데이터 샘플에 다음이 있으면 유의하세요:

• 유형이 object 이며 필드가 200개를 초과하는 필드는 유형 json.

• 으로 분류됩니다. 데이터 유형이 혼합된 필드(즉, 여러 데이터 유형을 포함하는 배열이거나 필드 자체의 데이터 유형이 가변적인 경우)는 해당 필드가 유형 json.

스키마 추론 방법

Panther에서 스키마를 추론하는 방법은 여러 가지가 있습니다:

• Panther Console에서:

  • 업로드한 샘플 데이터에서 스키마를 추론하려면 아래의 샘플 로그에서 사용자 지정 스키마 추론하기 탭을 참조하세요.

  • Panther에서 수신한 S3 데이터에서 스키마를 추론하려면 Panther에서 수신한 S3 데이터로부터 사용자 지정 스키마 추론하기 탭을 참조하세요.

  • 을 참조하세요 과거 S3 데이터에서 사용자 지정 스키마 추론하기 탭을 참조하세요.

  • Panther에서 수신한 HTTP 데이터에서 스키마를 추론하려면 Panther에서 수신한 HTTP 데이터로부터 사용자 지정 스키마 추론하기 탭을 참조하세요.

• CLI 워크플로에서는:

  • 다음을 사용하세요. pantherlog infer 명령을 사용합니다.

샘플 로그

샘플 로그에서 사용자 지정 스키마 추론하기

Panther Console에 샘플 로그를 업로드하여 스키마를 생성할 수 있습니다. 대신 명령줄을 사용하려면 여기의 pantherlog CLI 도구 사용 지침.

을 따르세요. 시작하려면 다음 단계를 따르세요:

1. Panther Console에 로그인합니다.

2. 왼쪽 탐색 모음에서 Configure > Schemas를 클릭합니다.

3. 페이지 오른쪽 상단의 검색창 옆에서 새로 만들기.

4. 을 클릭합니다 Schema ID, 설명, 및 Reference URL.

   • Description은 테이블 관련 내용을 위한 것이며, Reference URL은 내부 리소스로 연결하는 데 사용할 수 있습니다.

5. 선택적으로 Field Discovery 를 토글을 클릭하여 활성화합니다 켜기. 자세한 내용은 Field Discovery.

6. 다음 Schema 섹션의 샘플 이벤트에서 스키마 추론 타일에서 Start.

7. 다음 Infer schema from sample logs 모달에서 라디오 버튼 중 하나를 클릭합니다:

   • 샘플 파일 업로드: 샘플 로그 세트를 업로드합니다: 시스템에서 파일을 팝업 모달로 끌어오거나 Select file 을 클릭하여 로그 파일을 선택합니다.

     • Panther는 스키마 추론 시 헤더 없는 CSV를 지원하지 않습니다. 단, Panther AI 가 활성화된 경우는 예외입니다.

   • 샘플 이벤트 붙여넣기: 편집기에 샘플 이벤트를 직접 붙여넣거나 입력합니다.

8. 파일을 업로드하면 Panther가 UI에 원시 로그를 표시합니다. 로그 줄을 확장해 전체 원시 로그를 볼 수 있습니다. 다른 샘플 세트를 추가하면 이전에 업로드한 샘플이 덮어써진다는 점에 유의하세요.

9. 적절한 스트림 유형 (각 유형의 예시는 여기에서 보기).

   • 자동: Panther가 적절한 스트림 유형을 자동으로 감지합니다.

   • 줄 단위: 이벤트는 줄 바꿈 문자로 구분됩니다.

   • JSON: 이벤트가 JSON 형식입니다.

   • JSON 배열: 이벤트가 JSON 객체 배열 안에 있습니다.

   • CloudWatch Logs: 이벤트가 CloudWatch Logs에서 왔습니다.

   • XML: 이벤트가 XML 형식.

10. JSON 로그를 업로드했다면 Infer Schema를 클릭합니다. (JSON이 아닌 로그를 업로드했고 Panther AI enabled, 이 활성화되어 있다면 Infer Schema with Panther AI를 클릭한 다음 Confirm).

    • 을 클릭합니다. Panther가 원시 샘플 로그에서 스키마 추론을 시작합니다.

    • Panther는 여러 타임스탬프 형식을 추론하려고 시도합니다.

    • 스키마가 생성되면 스키마 편집기 상자에 표시됩니다.

11. 업로드한 샘플 로그와 스키마에 가한 변경 사항에 대해 스키마가 제대로 작동하는지 확인하려면 테스트 실행.

    • 를 클릭합니다. 이 테스트는 스키마 구문이 올바른지, 그리고 Panther에 업로드한 로그 샘플이 스키마와 성공적으로 일치하는지를 검증합니다.

    • 테스트 결과를 보려면 View Events.

      • 를 클릭합니다. 성공적으로 일치한 모든 로그는 Matched아래에 표시되며, 각 로그에는 열, 필드 및 JSON 보기가 표시됩니다.

      • 일치하지 않은 모든 로그는 Unmatched아래에 표시되며, 각 로그에는 오류 메시지와 원시 로그가 표시됩니다.

12. 을 클릭한 다음 저장 를 클릭하여 스키마를 게시합니다.

Panther는 업로드된 모든 로그에서 추론하지만, 스키마 생성 시 빠른 응답 시간을 보장하기 위해 최대 100개의 로그만 표시합니다.

Panther에서 수신한 S3 데이터

과거 S3 데이터

Panther에서 수신한 HTTP 데이터

직접 스키마 생성

사용자 지정 스키마를 수동으로 생성하는 방법

사용자 지정 스키마를 수동으로 생성하려면:

1. Panther Console의 왼쪽 탐색 모음에서 구성하세요. > 스키마.

2. 오른쪽 상단 모서리에서 다음을 클릭합니다. 새로 만들기.

3. 을 클릭합니다 Schema ID, 설명, 및 Reference URL.

   • Description은 테이블 관련 내용을 위한 것이며, Reference URL은 내부 리소스로 연결하는 데 사용할 수 있습니다.

4. 선택적으로 자동 필드 검색 를 토글을 클릭하여 활성화합니다 켜기. 자세한 내용은 Field Discovery.

5. 다음 Schema 섹션의 처음부터 스키마 생성 타일에서 Start.

   • 그 Schema 섹션은 기본적으로 Separate Sections를 사용합니다. 전체 스키마를 하나의 편집기 창에 작성하려면 Single Editor.

6. 다음 를 클릭합니다. 스키마에 Parser 섹션에서 Default (JSON/XML)

   • 파서 외의 다른 파서가 필요하다면 이를 선택합니다. 다른 파서 옵션에 대한 자세한 내용은 다음 페이지를 참조하세요:

   • Script Log Parser

   • Fastmatch Log Parser

   • Regex Log Parser

7. 다음 CSV Log Parser Fields & Indicators 섹션에 YAML 로그 스키마 필드를 작성하거나 붙여넣습니다.

   • 참조하세요 스키마 작성 에서 스키마 구성에 대해 자세히 알아보세요.

   • Panther가 생성한 스키마 필드 제안.

8. 을 사용할 수 있습니다. (선택 사항) Universal Data Model 섹션에서 스키마에 대한 Core Field 매핑을 정의합니다.

   • 자세한 내용은 사용자 지정 로그 스키마에서 Core Field 매핑.

9. 을 참조하세요. 창 하단에서 테스트 실행 를 클릭하여 스키마에 오류가 없는지 확인합니다.

   • 구문 검사는 로그 스키마의 구문만 확인합니다. 이름 충돌로 인해 저장에 실패할 수 있다는 점에 유의하세요.

10. 을 클릭한 다음 저장.

이제 Configure > Log Sources 로 이동하여 새 소스를 추가하거나 기존 소스를 수정해 새로운 Custom.SampleAPI _Log Type을 사용하도록 설정할 수 있습니다. Panther가 이 소스에서 이벤트를 수신하면 로그를 처리하고 custom_sampleapi 테이블에 저장합니다.

이제 이러한 로그와 일치하도록 디택션 을 작성하고 이를 사용해 쿼리할 수도 있습니다. 검색 또는 데이터 탐색기.

스키마 작성

아래 탭에서 JSON, XML 및 텍스트 로그용 스키마 작성 방법을 자세히 알아보세요.

JSON 로그

JSON 로그용 스키마 작성

각 줄이 JSON인 로그 파일을 파싱하려면 각 로그 항목의 구조를 설명하는 로그 스키마를 정의해야 합니다.

YAML 사양은 Panther Console에서 직접 편집할 수도 있고 원하는 편집기/IDE에서 오프라인으로 준비할 수도 있습니다. Log Schema의 구조와 필드에 대한 자세한 내용은 Log Schema Reference.

를 참조하세요. 또한 starlark 파서를 사용하여 JSON 로그에 대해 Panther가 기본적으로 지원하는 변환 외의 처리를 수행할 수도 있습니다..

아래 예시 스키마에서 첫 번째 탭은 JSON 로그 구조를 표시하고 두 번째 탭은 Log Schema를 보여줍니다.

JSON 로그 예시

{
  "method": "GET",
  "path": "/-/metrics",
  "format": "html",
  "controller": "MetricsController",
  "action": "index",
  "status": 200,
  "params": [],
  "remote_ip": "1.1.1.1",
  "user_id": null,
  "username": null,
  "ua": null,
  "queue_duration_s": null,
  "correlation_id": "c01ce2c1-d9e3-4e69-bfa3-b27e50af0268",
  "cpu_s": 0.05,
  "db_duration_s": 0,
  "view_duration_s": 0.00039,
  "duration_s": 0.0459,
  "tag": "test",
  "time": "2019-11-14T13:12:46.156Z"
}

축소된 JSON 로그 예시:

이것을 활용하세요 축소된 JSON 로그 예시 를 사용할 때 pantherlog 도구를 사용하거나 Panther Console에서 스키마를 생성할 때.

{"method":"GET","path":"/-/metrics","format":"html","controller":"MetricsController","action":"index","status":200,"params":[],"remote_ip":"1.1.1.1","user_id":null,"username":null,"ua":null,"queue_duration_s":null,"correlation_id":"c01ce2c1-d9e3-4e69-bfa3-b27e50af0268","cpu_s":0.05,"db_duration_s":0,"view_duration_s":0.00039,"duration_s":0.0459,"tag":"test","time":"2019-11-14T13:12:46.156Z"}

로그 스키마 예시

XML 로그

텍스트 로그

스키마 필드 제안

사용자 지정 스키마를 만들거나 편집할 때 Panther가 생성한 필드 제안을 사용할 수 있습니다. 이 기능을 사용하려면:

1. Panther Console에서 YAML 스키마 편집기를 클릭합니다.

   • 기존 스키마를 편집하려면 구성하세요. > 스키마 > [편집하려는 스키마 이름] > 편집.

   • 새 스키마를 만들려면 구성하세요. > 스키마 > 새로 만들기.

2. 다음을 누르세요 Command+I macOS에서(또는 Control+I PC에서).

   • 스키마 편집기는 텍스트 커서 위치에 따라 사용 가능한 속성과 작업을 표시합니다.

     

     YAML 스키마 편집기가 표시됩니다. 커서 아래에는 concat, copy, description, indicators, mask 등 다양한 필드 제안이 있는 상자가 있습니다.

사용자 지정 스키마 관리

사용자 지정 스키마 편집

Panther에서는 사용자 지정 스키마를 편집할 수 있습니다. 구체적으로 다음 작업을 수행할 수 있습니다:

• 새 필드 추가.

• 기존 필드 이름 바꾸기 또는 삭제.

• 기존 필드의 모든 속성 편집, 추가 또는 제거.

• 다음을 수정하여 파서를 사용하여 JSON 로그에 대해 구성으로 버그를 수정하거나 새 패턴을 추가합니다.

• 스키마 보관 또는 보관 해제.

• 필드 탐지 활성화 또는 비활성화.

필드의 유형을 편집한 후 새로 수집되는 모든 데이터는 새 유형과 일치하고, 이전에 수집된 모든 데이터는 이전 유형을 유지합니다.

사용자 지정 스키마를 편집하려면:

1. Panther Console에서 사용자 지정 스키마의 세부 정보 페이지로 이동합니다.

2. 세부 정보 페이지의 오른쪽 상단에서 편집.

   
3. 원하는 대로 스키마를 수정합니다.

   • Panther가 생성한 스키마 필드 제안.

   • 변경 사항을 더 쉽게 보려면(또는 삭제된 줄을 복사하거나 되돌리려면) Single Editor, 을 클릭한 다음 Diff View.

     
4. 오른쪽 상단에서 Update.

을 클릭한 다음 테스트 실행 를 클릭하여 YAML의 구조적 적합성을 확인합니다. 규칙은 Update를 클릭한 후에만 검사된다는 점에 유의하세요. 규칙을 따르지 않으면 업데이트가 거부됩니다.

관련 탐지 및 저장된 쿼리 업데이트

스키마 필드를 편집하면 관련 탐지 및 저장된 쿼리를 업데이트해야 할 수 있습니다. Related Detections 를 스키마 편집기 위에 표시된 알러트 배너에서 클릭하면 영향을 받는 탐지 및 저장된 쿼리 목록을 보고, 업데이트하고, 테스트할 수 있습니다.

쿼리 관련 영향

쿼리는 Type 에 대한 변경 전반에서 동작합니다. 단, 쿼리가 Types.

• 좋은 예: Type 가 다음에서 편집됩니다 string 에서 int 로, 기존 값이 모두 숫자인 경우(즉, "1"). 함수 sum 을 사용하는 쿼리는 이전 값과 새 값을 함께 집계합니다.

• 나쁜 예: Type 가 다음에서 편집됩니다 string 에서 int 기존 값 중 일부가 숫자가 아닌 경우(즉, "apples"). 함수 sum ) 숫자가 아닌 값을 제외합니다.

쿼리 형변환 가능성 표

이 표는 쿼리를 실행할 때 각 Types 이 각 Type 으로 변환될 수 있는지 보여줍니다. 스키마 편집을 통해 모든 Type 를 다른 Type.

Type From -> To	boolean	string	int	bigint	float	timestamp
boolean	same	yes	yes	yes	no	no
string	yes	same	numbers only	numbers only	numbers only	numbers only
int	yes	yes	same	yes	yes	numbers only
bigint	yes	yes	yes	same	yes	numbers only
float	yes	yes	yes	yes	same	numbers only
timestamp	no	yes	no	no	no	same

사용자 지정 스키마 보관 및 보관 해제

Panther에서 사용자 지정 스키마를 보관하고 보관 해제할 수 있습니다. 데이터 수집에 더 이상 사용되지 않으며 Panther 전반의 다양한 드롭다운 선택기에 옵션으로 표시되지 않기를 원할 경우 스키마를 보관할 수 있습니다. 스키마를 보관하려면 어떤 로그 소스에도 사용 중이면 안 됩니다. 보관된 스키마는 계속 무기한 존재하며, 스키마를 영구적으로 삭제하는 것은 불가능합니다.

스키마를 보관해도 해당 스키마를 사용해 이미 수집되어 데이터 레이크에 저장된 데이터에는 영향을 주지 않습니다. 여전히 데이터 탐색기 및 검색을 사용하여 쿼리할 수 있습니다. 기본적으로 보관된 스키마는 스키마 목록 보기( 구성하세요. > 스키마에서 표시됨)에 표시되지 않지만 Status를 Filters의 오른쪽 상단에서 수정하여 표시할 수 있습니다. 데이터 탐색기에서는 보관된 스키마의 테이블이 Tables.

아래에 표시되지 않습니다. 보관된 스키마와 같은 이름으로 새 스키마를 만들려고 하면 이름 충돌이 발생하며, 대신 기존 스키마를 보관 해제하고 편집하라는 메시지가 표시됩니다.

사용자 지정 스키마를 보관하거나 보관 해제하려면:

1. Panther Console에서 구성하세요. > 스키마.

   • 보관하거나 보관 해제할 스키마를 찾습니다.

2. 스키마 행의 오른쪽에서 Archive 또는 Unarchive 아이콘을 클릭합니다.

   

   • 스키마를 보관 중이며 현재 하나 이상의 로그 소스와 연결되어 있는 경우 확인 모달에서 먼저 스키마 연결을 해제하라는 메시지가 표시됩니다. 그렇게 한 후 Refresh.

3. 를 클릭합니다. 확인 모달에서 계속.

사용자 지정 스키마 테스트

Panther Console의 Schema Edit 페이지에 있는 "샘플 로그에 대해 스키마 테스트" 기능은 Lines, CSV(헤더 포함 또는 미포함), JSON, JSON Array, XML, CloudWatch Logs, Auto를 지원합니다. Stream Types 의 예를 참조하세요.

또한 위의 로그 형식은 다음 형식으로 압축할 수 있습니다:

• gzip

• zstd(딕셔너리 없음)

여러 줄 로그는 JSON 및 JSONArray 형식에서 지원됩니다.

사용자 지정 스키마가 로그에 대해 작동하는지 검증하려면 샘플 로그로 테스트할 수 있습니다:

1. Panther Console의 왼쪽 탐색 모음에서 Configure > Schemas.

2. 사용자 지정 스키마 이름을 클릭합니다.

3. 스키마 세부 정보 페이지의 오른쪽 상단에서 스키마 테스트.

   

Panther Analysis Tool을 사용하여 로그 스키마 업로드

Panther Console 외부에서 로그 스키마를 관리하려는 경우, 예를 들어 버전 관리를 유지하고 업데이트 전에 변경 사항을 검토하기 위해, Panther Analysis Tool (PAT)을 사용하여 YAML 파일을 프로그래밍 방식으로 업로드할 수 있습니다.

업로더 명령은 인수로 기본 경로를 받고, 확장자가 .yml 및 .yaml.

인 모든 파일을 재귀적으로 찾습니다. 관련 없는 파일과는 별도로 스키마 파일을 저장하는 것이 좋습니다. 그렇지 않으면 잘못된 스키마 파일을 업로드하려다 업로드 중 오류가 발생할 수 있습니다.

panther_analysis_tool update-custom-schemas --path ./schemas

업로더는 기존 스키마가 있는지 확인하고 업데이트를 진행하거나, 일치하는 스키마 이름을 찾지 못하면 새 스키마를 생성합니다.

그 schema 필드는 항상 YAML 파일에 정의되어야 하며, 업데이트가 성공하려면 기존 스키마 이름과 일치해야 합니다. 사용 가능한 모든 CI/CD 필드 목록은 우리의 Log Schema Reference.

PAT를 통해 업로드된 스키마는 Panther Console에서 수행한 업데이트와 동일한 기준으로 검증됩니다.

사용자 지정 로그 문제 해결

Panther Knowledge Base를 방문하여 사용자 지정 로그 소스에 대한 문서 보기 자주 묻는 질문에 대한 답변과 일반적인 오류 및 문제 해결에 도움이 되는 문서입니다.