PyPanther 탐지 생성하기

개요

다음 사용을 권장합니다 Python(v1) 탐지 대신 PyPanther를 사용합니다. PyPanther의 향후 지원은 평가 중이며 기능 개발은 일시 중단되었습니다.

PyPanther 탐지는 Panther 버전 1.108부터 클로즈드 베타로 제공됩니다. 버그 보고 및 기능 요청은 Panther 지원팀에 공유해 주세요.

Panther가 관리하는 PyPanther 탐지를 가져와서 수정하거나 자체 맞춤 탐지를 만들 수 있습니다. 탐지를 만든 후에는 등록, 테스트 및 업로드할 수 있습니다.

PyPanther 탐지를 작성하기 전에 환경을 설정해야 합니다. 자세한 내용은 PyPanther 탐지 사용 시작하기.

이 페이지에서는 CLI 워크플로우에서 PyPanther 탐지를 만드는 방법을 설명합니다. 콘솔에서 PyPanther 탐지를 만들고 싶다면 Panther 콘솔에서 PyPanther 탐지 관리하기.

PyPanther 탐지 작성에 대한 고수준 지침

CLI 워크플로우에서 PyPanther 탐지를 작업할 때:

• A main.py 파일은 어떤 규칙을 등록할지, 구성 재정의 또는 사용자 정의 규칙 정의를 개괄하는 전체 탐지 구성을 제어합니다. 다음 중 하나를 할 수 있습니다:

  • (권장) 다양한 다른 파일/폴더에 탐지를 정의한 다음 이를 main.py (자세한 내용은 PyPanther 탐지 스타일 가이드)

  • 에 가져오세요 main.py

• PyPanther 규칙은 단일 Python 파일에서 정의됩니다. 그 안에서 Panther가 관리하는(또는 자체 사용자 정의) PyPanther 규칙을 가져오고 재정의를 지정할 수 있습니다. 하나의 Python 파일은 여러 탐지를 정의할 수 있습니다.

• 모든 PyPanther 규칙은 pypanther 규칙 클래스 또는 규칙.

• 형의 상위 클래스를 서브클래싱합니다 규칙은 테스트 및 Panther 인스턴스에 업로드되려면 등록되어야 합니다.

• v1 탐지에서 현재 사용 가능한 모든 이벤트 객체 함수는 PyPanther 탐지에서도 사용할 수 있습니다. 여기에는 다음이 포함됩니다: get(), deep_get(), deep_walk()및 udm().

• 모든 Python(v1) 탐지에서 사용할 수 있는 경고(alert) 함수 는 PyPanther 탐지에서도 사용할 수 있으며, 예를 들어 title() 와 DynamicSeverities입니다. 자세한 내용은 규칙 보조/알림 함수 참조.

• 다음을 사용하세요 pypanther IDE의 자동완성 힌트(예: 사용 가능한 규칙 검색 또는 클래스 속성 보기)를 제공합니다.

맞춤 PyPanther 탐지 작성하기

“맞춤” PyPanther 규칙은 완전히 처음부터 직접 작성한 규칙—즉,에서 빌드되지 않은 규칙입니다 Panther 관리 규칙입니다. 맞춤 PyPanther 규칙은 pypanther 규칙 클래스를 서브클래싱하는 Python 클래스에서 정의됩니다. 이 클래스에서는 다음을 해야 합니다:

• 다음을 정의해야 합니다 rule() function

  • (선택 사항) 다음 중 아무거나 정의하세요: 다른 알림 함수와 같은, title() 또는 destinations()

• 특정 속성를 정의하세요, 예를 들어 log_types

  • (선택 사항) 다음과 같은 추가 속성을 정의하세요: threshold 또는 dedup_period_minutes

설정은 id 속성은 규칙을 등록 하려는 경우에만 필요합니다.

환경에서 Fluentd 시작에 대한 정보는 규칙 속성 참조 전체 필수 및 선택 필드 목록은 섹션을 참조하세요.

from pypanther import Rule, Severity, LogType

# Panther가 지원하는 로그 유형에 대한 맞춤 규칙
class MyCloudTrailRule(Rule):
    id = "MyCloudTrailRule"
    tests = True
    log_types = [LogType.AWS_CLOUDTRAIL]
    default_severity = Severity.MEDIUM
    threshold = 50
    dedup_period_minutes = 1

    def rule(self, event) -> bool:
        return (
	    event.get("eventType") == "AssumeRole" and 
	        400 <= int(event.get("errorCode", 0)) <= 413
	)

Panther가 관리하는 규칙 가져오기

Panther가 관리하는 규칙은 직접 가져오거나 get_panther_rules() 함수에 대해 정의되어야 합니다.

를 사용하여 가져올 수 있습니다. Panther가 관리하는 규칙은 현재 모두 -프로토타입 접미사를 가지고 있습니다(예:AWS.Root.Activity-prototype

). 이는 임시이며 향후 제거될 예정입니다. main.py Panther가 관리하는 규칙을 가져와서(에 등록 또는 다른 파일로) 개별적으로 있는 그대로 사용하거나, overrides 해당 규칙에 대해 서브클래싱 할 수 있습니다. Panther 관리 규칙은 pypanther.rules 모듈에서 직접 가져오거나 get_panther_rules() 함수에 대해 정의되어야 합니다.

를 사용하여 가져올 수 있습니다. rules 모듈을 사용해 Panther가 관리하는 규칙을 직접 가져오려면 다음과 같은 문을 사용합니다:

from pypanther.rules.github import GitHubAdvancedSecurityChange

설정은 get_panther_rules() 함수는 규칙 default_severity 와 같은 클래스 속성에서 필터링할 수 있습니다., log_types, 또는 tag필터링할 때 키는 AND 로직을 사용하고 값은 { "ip": "10.0.0.1", "un": "[email protected]", "country": "France" }{ "ip": "10.0.0.2", "un": "[email protected]", "country": "France" }{ "ip": "10.0.0.3", "un": "[email protected]", "country": "France" } 데이터 모델 테스트

를 사용합니다. 모든 Panther 관리 규칙을 가져오려면 get_panther_rules():

from pypanther import get_panther_rules

all_rules = get_panther_rules()

특정 심각도를 가진 Panther 관리 규칙을 가져오려면 get_panther_rules():

from pypanther import get_panther_rules, Severity

important_rules = get_panther_rules(
    default_severity=[
        Severity.HIGH,
        Severity.CRITICAL,
    ]
)

특정 로그 유형에 대한 Panther 관리 규칙을 가져오려면 get_panther_rules():

from pypanther import get_panther_rules, LogType

cloudtrail_okta_rules = get_panther_rules(
    log_types=[
        LogType.AWS_CLOUDTRAIL,
        LogType.OKTA_SYSTEM_LOG
    ]
)

여러 기준을 충족하는 Panther 관리 규칙을 가져오려면 get_panther_rules():

from pypanther import get_panther_rules, Severity

rules_i_care_about = get_panther_rules(
    enabled=True,
    default_severity=[Severity.CRITICAL, Severity.HIGH],
    tags=["Configuration Required"],
)

참조 리스트 내포 사용 는 고급 Python과 함께 사용하는 방법의 예입니다. get_panther_rules() 보다 자세한 사용 예시는

Panther 관리 규칙을 가져온 후에는 overrides 또는 상속.

을 사용하여 수정할 수 있습니다.

기존 규칙에 재정의를 적용하기 규칙의 로직을 수정하려는 경우에는 함수 자체를 재정의하는 대신 rule() 포함/제외 필터 를 사용하는 것이 권장됩니다. 자세한 내용은 rule().

재정의 대신 필터 사용

• Panther 관리 탐지에 재정의를 할 때는 다음을 권장합니다: main.py외부에 모든 재정의를 함수로 변환될 수 있습니다.

• 에 main.pyapply_overrides() pypanther에 저장하고, 모든 재정의를 의 모든 재정의를 함수로 변환될 수 있습니다.

Mappings 모든 재정의를 를 호출하여 각 PyPanther 탐지 스타일 가이드.

를 적용하세요.

단일 속성 재정의 override() 함수를 사용하여 한 줄로 단일 규칙 속성을 재정의할 수 있습니다:

from pypanther import Severity
from pypanther.rules.aws_cloudtrail import AWSCloudTrailCreated

# 규칙 심각도를 High로 설정
AWSCloudTrailCreated.override(default_severity=Severity.HIGH)

override 함수로 여러 속성 재정의하기

override override() 함수를 사용하여 한 줄로 단일 규칙 속성을 재정의할 수 있습니다:

from pypanther import Severity
from pypanther.rules.box import BoxContentWorkflowPolicyViolation

BoxContentWorkflowPolicyViolation.override(
    default_severity=Severity.HIGH,
    default_runbook="다른 내부 사용자가 동일한 위반을 겪었는지 확인하세요"
)

여러 PyPanther 규칙에 재정의 적용하기

여러 규칙에 한 번에 재정의를 적용하려면 컬렉션을 반복하는 for 루프를 사용하세요.

예를 들어 특정 속성을 특정 문자열의 단일 리스트 참고:.

에 연결된 모든 규칙에 대해 업데이트할 때 유용할 수 있습니다.

from pypanther import get_panther_rules, Severity, LogType
    enabled=True,
    default_severity=[Severity.CRITICAL, Severity.HIGH],
    tags=["Configuration Required"],
)

rules = get_panther_rules(
# 대상 [override](<https://docs.panther.com/detections/rules/python#destinations>) 정의
    def aws_cloudtrail_destinations(self, event):
        if event.get('recipientAccountId') == 112233445566:
        # 구성된 Slack 대상의 이름 또는 UUID
    return ['AWS Notifications']
    # 경보를 전송하지 않음

return []
# extend()를 사용하여 Panther 관리 규칙의 destinations 및 tags에 항목 추가하기
    for rule in rules:
        rule.extend(
        default_destinations=["Slack #security"],
    )
		
    tags=["Production"],
    # CloudTrail 규칙의 destinations 메서드 업데이트
        if LogType.AWS_CLOUDTRAIL in rule.log_types:

rule.destinations = aws_cloudtrail_destinations

기존 규칙의 리스트 속성 확장하기 tags, 기존 규칙을 수정할 때 리스트 유형의 규칙 속성(예:, tests, 또는 include_filtersexclude_filters

)에 항목을 추가하면서 기존 리스트를 보존하고 싶을 수 있습니다. 을 사용하여 수정할 수 있습니다.속성을 재정의하는 대신(에서 설명한 방법 중 하나를 사용하면) 기존 리스트 값을 대체하게 되므로, pypanther extend() 함수를 사용하여 리스트 속성에 새 값을 추가하세요.

from pypanther import Severity
from pypanther.rules.box_rules.box_policy_violation import BoxContentWorkflowPolicyViolation

BoxContentWorkflowPolicyViolation.extend(
    default_destinations=["Slack #security"],
    include_filters=[lambda event: event.get("env") == "prod"]
)

# BoxContentWorkflowPolicyViolation에는 이미 "Box" 태그가 있으므로 이제 
# "Production"과 "Box" 두 개의 태그를 갖게 됩니다

# BoxContentWorkflowPolicyViolation가 이미 include_filters를 정의하지 않았기 때문에, 
# 위의 단일 필터를 가지게 됩니다

포함 또는 제외 필터 생성하기

PyPanther 탐지 필터는 규칙이 평가하지 않도록 특정 이벤트를 제외하게 해 줍니다. 필터는 기존 규칙 로직(대개 가져오는 Panther 관리 PyPanther 탐지에 대해) 위에 적용되도록 설계되었습니다.

각 필터는 rule() 함수보다 먼저 실행되는 로직을 정의하며, 필터의 결과는 이벤트가 규칙에 의해 평가될지 여부를 결정합니다.

필터의 일반적인 사용 사례에는 다음이 포함됩니다:

• 예: 특정 환경(예: prod

• )만 대상으로 지정하려는 경우

잘못된 구성이나 기타 비악의적 시나리오로 인해 알려진 오탐 이벤트를 제외하려는 경우

• tests필터에는 두 가지 유형이 있습니다: 본문에서 : 필터가 이벤트에 대해 rule()

• include_filters필터에는 두 가지 유형이 있습니다: 본문에서 를 반환하면 이벤트는 rule())

설정은 규칙 에 의해 평가됩니다. 필터가 이벤트에 대해 를 반환하면 이벤트는 기각됩니다(즉, tests 와 include_filters 에 의해 평가되지 않음).

기본 클래스

from pypanther.rules.github import GitHubAdvancedSecurityChange

에는
속성이 있으며, 각각은 로그 이벤트에 대해 평가될 함수 목록을 포함합니다.
독립 함수 예시:
    # 프로덕션 repo만 포함
)

from pypanther.rules.box import BoxContentWorkflowPolicyViolation

prod_repos = ["prod_repo1", "prod_repo2"]
GitHubAdvancedSecurityChange.extend(
독립 함수 예시:
    include_filters=[lambda e: e.get("repo") in prod_repos]
)

# 개발용 계정 제외

dev_repos = ["dev_repo1", "dev_repo2"]
from pypanther.rules.github import GitHubAdvancedSecurityChange

exclude_filters=[lambda e: e.get("repo") in dev_repos]
    상속된 규칙 정의의 일부로서의 예시:
    from pypanther.wrap import include, exclude
    class GitHubAdvancedSecurityChangeOverride(GitHubAdvancedSecurityChange):
    id = "GitHubAdvancedSecurityChangeOverride"
    # 실제 시나리오에서는 아래 항목 중 아마 하나만 필요할 것입니다
    # 상위 규칙의 include_filters 확장
    ...

include_filters = super().include_filters.append(lambda e: e.get("repo") in prod_repos) for # 상위 규칙의 exclude_filters 재정의

exclude_filters = [lambda e: e.get("repo") in dev_repos]

필터는 또한
    루프와 함께 재사용되어 여러 규칙에 적용될 수 있습니다:
    ...
]

from pypanther.wrap import include
    rules = [
		
# extend()를 사용하여 Panther 관리 규칙의 destinations 및 tags에 항목 추가하기
    # Panther 관리 및 사용자 정의 규칙

def prod_filter(event):

return event.get("repo") in prod_repos rule.extend(include_filters=[prod_filter]) 구성 필수가 있는 규칙에 필요한 필드가 설정되었는지 확인하기 test Panther 환경에 업로드되기 전에 고객 구성이 필요한 Panther 관리 규칙에는

validate_config() rule.extend(include_filters=[prod_filter]) 함수가 포함될 수 있으며, 이 함수는 규칙이 rule.extend(include_filters=[prod_filter]) 명령을 통과(및 정상 동작)하기 위해 충족해야 하는 하나 이상의 조건을 정의합니다. pypanther test 가장 일반적으로, 규칙은).

예시:

는 허용 목록이나 차단 목록과 같은 클래스 변수가 값으로 할당되었는지 확인합니다. 만약
    에 포함된 요구 사항이 충족되지 않으면,
    명령이 실행될 때(규칙이
    인 경우) 예외가 발생합니다.

    class ValidateMyRule(Rule):

    id = "Validate.MyRule"
        log_types = [LogType.PANTHER_AUDIT]

    default_severity = Severity.HIGH 
    allowed_domains: list[str] = []
        def rule(self, event):
            return event.get("domain") not in self.allowed_domains
        @classmethod

def validate_config(cls): assert ( len(cls.allowed_domains) > 0 pypanther test.

), "규칙의 allowed_domains 필드는 채워져 있어야 합니다"

이 예에서,

allowed_domains

가 비어 있지 않은 리스트로 할당되지 않으면,

동안 AssertionError가 발생합니다. rule() 이 값을 설정하려면 다음과 같은 문을 사용할 수 있습니다:

ValidateMyRule.allowed_domains = ["example.com"] 문자열의 단일 리스트 참고:상속을 사용하여 PyPanther 규칙 생성하기 문자열의 단일 리스트 참고: 상속을 사용하여 다른 규칙(관리되거나 사용자 정의된 규칙)의 서브클래스로 규칙을 만들 수 있습니다.

여러 특성을 공유하는 규칙 모음을 만들 때는 상속을 사용하는 것이 권장됩니다. 예를 들어, 함수 로직, 속성 값, 클래스 변수 또는 헬퍼 함수 등이 그러합니다. 이 경우 관련 규칙들이 상속하는 기본 규칙을 만드는 것이 유용합니다.예를 들어, 각

에 대한 기본 규칙을 만들고, 그로부터 해당 등록 에 대한 모든 규칙을 확장하는 것이 유용할 수 있습니다. id 상속은 일반적으로

예시:

필터
와 함께 사용됩니다 — 즉, 서브클래싱된 규칙은 규칙이 처리되기 위해 이벤트가 충족해야 하는 추가 기준을 정의할 수 있습니다.
    기본 규칙을
    할 계획이 없다면, 해당 규칙에
    인 경우) 예외가 발생합니다.
    속성을 제공할 필요는 없습니다.
    # 사용자 정의 로그 유형에 대한 맞춤 규칙 — 부모 규칙

    def rule(self, event) -> bool:
        class HostIDSBaseRule(Rule):
    
    # 이 부모 규칙은 업로드하지 않으므로 id는 필요 없음
	log_types = ['Custom.HostIDS']
		
    threshold = 1
	dedup_period_minutes = 6 * 60 # 6시간
		
    return event.get('event_name') == 'confirmed_compromise'
	def host_user_lookup(self, hostname): 
	return {
	    return 'groot'
	    def title(self, event): -> str:
	    return f"Confirmed compromise from hostname {event.get('hostname')}"
	}

def alert_context(self, event):

user = self.host_user_lookup(event.get('hostName')
    'hostname': event['hostName'],
    'time': event['p_event_time'],
    
    'user': user,
    # 상속된 규칙 #1
    
    class IDSCommandAndControl(HostIDSBaseRule):
	id = 'IDSCommandAndControl'
	
    threshold = 19
    # 기본 규칙의 함수 외에 event_type으로 필터링

include_filters = [lambda e: e.get('event_type') == 'c2']

user = self.host_user_lookup(event.get('hostName')
    def title(self, event):
    return f"Confirmed c2 on host {event.get('hostname')}"
    # 부모 규칙에서 rule(), alert_context(), log_types, severity, dedup_period_minutes를 상속함
    
    'user': user,
    # pypanther Rule에서 다른 필드(예: Enabled)를 상속함

    class IDSCommandAndControl(HostIDSBaseRule):
	# 상속된 규칙 #2
    
    id = 'HostIDSMalware'
    threshold = 2

default_severity = Severity.CRITICAL

include_filters = [lambda e: e.get('event_type') == 'malware']

return f"Confirmed malware on host {event.get('hostname')}" # 부모 규칙에서 rule(), alert_context(), log_types, dedup_period_minutes를 상속함

# pypanther Rule에서 다른 필드(예: enabled)를 상속함

고급 Python 사용하기
PyPanther 규칙은 완전히 Python으로 정의되므로, 탐지를 사용자화할 때 Python의 모든 표현력을 활용할 수 있습니다.
    return event.get('event_name') == 'confirmed_compromise'
	super()
	부모 규칙이 정의한 함수의 로직을 보완할 수 있는 고급 사용 사례가 있습니다.
	# 상속된 규칙 생성하기
	class MyRule(AnExistingRule):
				
    # 부모 규칙의 alert_context를 보존하고 새 필드로 확장
	context = super().alert_context(event)
	context["new field"] = "new_value"
	    return context
	def severity(self, event):

리스트 내포 사용

# 조건에 따라 부모 규칙의 심각도를 증가시킴 get_panther_rules().

if event.get("env") == "prod":
return Severity.CRITICAL
					
return super().severity(event)
Python의 리스트 내포 기능을 사용하여 기존 리스트를 기반으로 축약된 문법으로 새 리스트를 만들 수 있습니다. 이는 get_panther_rules()로 가져온 탐지 목록을 필터링할 때 특히 유용할 수 있습니다.