PyPanther 탐지 스타일 가이드

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

PyPanther 탐지는 Panther 버전 1.108부터 클로즈드 베타입니다. 버그 리포트나 기능 요청이 있으면 Panther 지원팀에 공유하세요.

저장소 구조 권장사항

다음을 클론하여 빠르게 시작하세요 pypanther-starter-kit 저장소.

PyPanther 탐지(Detections)가 저장된 코드 저장소에서는 다음을 권장합니다:

• 최상위 모듈을 유지하세요, content안에는 모든 커스텀 파이썬 코드가 저장되어야 합니다(다음의 경우를 제외하고는 main.py 파일).

우리가 최상위 디렉터리를 content/ 라고 부르지만 이름은 다음을 제외하고는 아무렇게나 지정할 수 있습니다 src/, 이는 Panther에서 예약된 저장소 이름입니다.

이 폴더 내에서는 다음을 권장합니다:

• 커스텀 규칙 정의를 폴더 설정(Folder setup) 디렉터리에 저장하세요.

• Panther에서 관리하는 규칙에 대한 오버라이드를 적용하는 로직은 overrides 디렉터리에 저장하세요.

  • 다음을 정의하세요 apply_overrides deep_get() 전역 헬퍼 함수 를 각 overrides.

• 파일에 정의하세요 커스텀 헬퍼는 디렉터리에 저장하세요.

helpers
.
# 권장 저장소 구조
├── README.md
├── content
│   ├── __init__.py
│   ├── helpers
│   │   ├── __init__.py
│   │   ├── cloud.py
│   │   └── custom_log_types.py
│   ├── helpers
│   ├── overrides
│   │   ├── aws_cloudtrail.py└
│   │   └── aws_guardduty.py
│   ├── rules
│   │   ├── __init__.py
│   │   ├── my_custom_rule.py
│   │   └── my_inherited_rule.py
│   └── schemas
│       └── schema1.yml

main.py └── main.py

content 권장사항 main.py 다음 파일에 대해 권장됩니다:

• 오버라이드를 적용하고자 하거나 적용하지 않을 Panther 관리 규칙은 다음을 사용하여 가져오세요 get_panther_rules

  • 만약 당신이 apply_overrides 함수를 정의했다면, 호출하세요 pypanther의 apply_overrides() 모든 변경사항을 적용하려면 호출하세요. 자세한 내용은 호출 apply_overrides()아래.

• 커스텀 규칙은 다음을 사용하여 가져오세요 get_rules

# 예제 main.py 파일
from pypanther import get_panther_rules, get_rules, register, apply_overrides

from content import rules, overrides
from content.helpers.custom_log_types import CustomLogType

# 기본 규칙 로드
base_rules = get_panther_rules(
    # log_types=[
    #     LogType.AWS_CLOUDTRAIL,
    #     LogType.AWS_GUARDDUTY,
    #     LogType.PANTHER_AUDIT,
    # ],
    # default_severity=[
    #     Severity.CRITICAL,
    #     Severity.HIGH,
    # ],
)
# 모든 로컬 커스텀 규칙 로드
custom_rules = get_rules(module=rules)
# 업로드가 작동하려면 Panther 인스턴스에 존재해야 하므로 커스텀 로그 타입이 있는 규칙은 제외
custom_rules = [rule for rule in custom_rules if not any(custom in rule.log_types for custom in CustomLogType)]

# 오버라이드 적용
apply_overrides(module=overrides, rules=base_rules)

# 모든 규칙 등록
register(base_rules + custom_rules)

호출 apply_overrides()

와 같이 반환할 수 있습니다(스타일 취향에 따라). pypanther apply_overrides() 편의 함수는, main.py에서 별도의 파일 또는 폴더에 만든 모든 탐지 오버라이드를 효율적으로 적용할 수 있게 해줍니다.

apply_overrides() 는 가져온 패키지(폴더) 또는 모듈(파일) 이름과 선택적 규칙 목록을 받아, 해당 패키지나 모듈에서 이름이 apply_overrides() 인 모든 함수를 규칙 목록에 대해 실행합니다. (이는 get_rules() 가 작동하는 방식과 유사합니다.) 이 패키지나 모듈의 이름을 overrides.

함수로 가져온 규칙이 포함된 각 폴더는 apply_overrides() 를 포함해야 합니다. __init__.py <schema_name>_tests.yml

로 하는 것을 권장합니다 apply_overrides() 다음 예에서, 내의 함수들은 및 general.py aws_cloudtrail.py 가 호출될 때 적용됩니다 apply_overrides(overrides, all_rules) main.py:

# main.py
가

에서 호출될 때
가 호출될 때 적용됩니다

import overrides

all_rules = get_panther_rules()
register(all_rules)
    # /overrides의 general.py
        def apply_overrides(rules):

for rule in rules:
rule.override(enabled=True)
# /overrides의 aws_cloudtrail.py

register(all_rules)
    from pypanther import Severity
        from pypanther.rules.aws_cloudtrail import AWSCloudTrailStopped
        AWSCloudTrailStopped.override(
            default_severity=Severity.LOW,
            default_runbook=(
            "계정이 프로덕션 환경이라면 CloudTrail이 중지된 이유를 조사하세요. "
        ),
    )

"의도된 중지였다면 해당 계정이 다른 CloudTrail로 모니터링되고 있는지 확인하세요. "

"의도된 중지가 아니라면 무단 접근 여부를 조사하세요." OutputIds:

PyPanther 탐지 작성 모범 사례 오버라이드 대신 필터 사용 대신 Panther에서 관리하는 PyPanther 탐지의 로직을 변경하려면, 오버라이드하는 대신 포함/제외 필터 OutputIds: 규칙의 OutputIds: 함수를 오버라이드하는 것보다 필터를 사용하는 것이 권장됩니다. 필터는 이 목적을 위해 설계되어 기존 규칙 로직 위에 적용됩니다. 필터는 각 들어오는 이벤트에 대해

로직이 실행되기 전에 실행되어 규칙이 실제로 해당 이벤트를 처리해야 하는지를 결정합니다. 규칙 로직을 크게 변경하려는 경우에는 을 사용하세요.

사용하여 upgrade() 로그/리소스 유형별로 규칙을 폴더로 그룹화하는 것을 권장합니다(예: downgrade() in severity()

커스텀 규칙 작성 default_severity을 고려해 볼 수도 있습니다. severity() 각 PyPanther 규칙은 반드시 default_severity 를 정의해야 하지만, 또한

내에서 severity()함수를 정의할 수 있으며, 해당 값은 심각도(Severity) 를 오버라이드하여 결과 알림의 심각도 수준을 설정합니다. 에서는 이벤트 필드 값을 기반으로 심각도를 동적으로 설정하는 것이 일반적입니다. 한 가지 방법은 어떤 조건을 추가하여 해당 조건이 충족되면 하드코딩된 값을 반환하도록 하는 것입니다. 아래 예제에서는 이벤트와 연관된 행위자가 관리자 역할인 경우, Severity.MEDIUM:

가 반환되어
self.default_severity
    ...
    의 값과 상관없이 적용됩니다.
    ...

# upgrade() 또는 downgrade()를 사용하지 않는 예제
    class MyRule(Rule):
        default_severity = Severity.LOW
    def severity(self, event):

if event.deep_get("actor", "role") == "admin": default_severity return Severity.MEDIUM # MEDIUM 반환 Severity.MEDIUM.

return self.default_severity # LOW 반환 위 예에서 당신은의 default_severity 값을 참조할 수 있습니다 로 만약 에서는 이벤트 필드 값을 기반으로 심각도를 동적으로 설정하는 것이 일반적입니다. 한 가지 방법은 어떤 조건을 추가하여 해당 조건이 충족되면 하드코딩된MyRule 에서는 이벤트 필드 값을 기반으로 심각도를 동적으로 설정하는 것이 일반적입니다. 한 가지 방법은 어떤 조건을 추가하여 해당 조건이 충족되면 하드코딩된 in severity() 가 한때 Severity.LOW에서 예를 들어

경고 조사 upgrade() 로 변경되었다면, 에스컬레이션을 보존하려면 또한

를 업데이트해야 합니다(아마도 severity() Severity.HIGH 심각도(Severity) 로). 심각도(Severity) 심각도를 하드코딩하는 대신 upgrade() 및 downgrade() 반환 값을 하드코딩된 Severity.MEDIUM.

값으로 설정하는 대신(위 예제와 같이), 클래스의 default_severity 함수를 호출하는 것이 권장됩니다 severity() 이 모델에서는 탐지의 default_severity 값이 변경되더라도 에서는 이벤트 필드 값을 기반으로 심각도를 동적으로 설정하는 것이 일반적입니다. 한 가지 방법은 어떤 조건을 추가하여 해당 조건이 충족되면 하드코딩된함수에서 추가 변경을 할 필요가 없습니다. 아래 예제에서는 Severity.LOW 가 upgrade():

로 변경되었고, 조건 내의 반환 값은
self.default_severity
    ...
    를 사용하기 때문에 자동으로
    ...

# upgrade() 또는 downgrade()를 사용하지 않는 예제
    class MyRule(Rule):
        로 조정됩니다.
    # upgrade() 사용 예제

default_severity = Severity.MEDIUM return self.default_severity.upgrade() # HIGH 반환 로그/리소스 유형별로 규칙을 폴더로 그룹화하는 것을 권장합니다(예: return self.default_severity # MEDIUM 반환를 사용하려면 default_severity self.default_severity.upgrade() 심각도(Severity) self.default_severity.downgrade()

를 사용하려면 해당 탐지의 severity() 값은 문자열 리터럴이 아닌 객체여야 합니다. 드물게 내에서 정적 값을 사용하는 것이 더 바람직한 경우가 있을 수 있습니다 — 예를 들어, 이벤트가 dev 계정에서 발생한 경우 항상 Severity.INFO default_severity 를 반환하고 싶을 수 있습니다, 나중에

# upgrade() 또는 downgrade()를 사용하지 않는 예제
    가 변경되더라도. 이러한 경우는 다음과 같이 보일 수 있습니다:
        if is_dev_env(event.get("accountId")):
    return Severity.INFO

return self.default_severity

와 같이 반환할 수 있습니다(스타일 취향에 따라). pypanther 선택적으로 명시적 타입 사용 Rule base Rule클래스는 타입이 지정되어 있으므로, 커스텀 탐지를 생성할 때(즉,

에서 상속할 때) 명시적 타이핑은 선택 사항입니다. 그래도 명시적 타입을 사용하고 싶다면 사용할 수 있습니다.

명시적 타입을 사용한 커스텀 규칙 예제
from time import strptime

from typing import Dict, List
from panther_core.enriched_event import PantherEvent
from pypanther import LogType, Rule, RuleTest, Severity
from pypanther.base import SeverityType
from pypanther.helpers.aws import aws_guardduty_context


from pypanther.severity import SEVERITY_DEFAULT
    class MyTypedRule(Rule):
    log_types: List[LogType | str] = [LogType.AWS_GUARDDUTY]
    id: str = "AWS.GuardDuty.HighVolFindings"
    create_alert: bool = True
    dedup_period_minutes = 45
    display_name: str = "High volume of GuardDuty findings"
    enabled: bool = True
    threshold = 100
    tags: List[str] = ["GuardDuty", "Security"]

    reports: Dict[str, List[str]] = {"MITRE ATT&CK": ["TA0010:T1499"]}
    default_severity: Severity | str = Severity.HIGH
    default_destinations: List[str] = ["slack:my-channel"]

    default_description: str = "이 규칙은 GuardDuty 발견 건수가 높은 경우를 추적합니다"
        def rule(self, event: PantherEvent) -> bool:
            if event.deep_get("service", "additionalInfo", "sample"):
            # 샘플 데이터의 경우
            rule()
        # https://docs.aws.amazon.com/guardduty/latest/ug/sample_findings.html

    return 7.0 <= float(event.get("severity", 0)) <= 8.9
        def title(self, event: PantherEvent) -> str:

    return event.get("title", "GuardDuty finding")
        def severity(self, event: PantherEvent) -> SeverityType:
        # 타임스탬프 파싱: "createdAt": "2020-02-14T18:12:22.316Z"
        timestamp = strptime(event.get("createdAt", "1970-01-01T00:00:00Z"), "%Y-%m-%dT%H:%M:%S.%fZ")
        # 주말이면 심각도 상승
            if timestamp.tm_wday in (5, 6):
        return Severity.CRITICAL

    return SEVERITY_DEFAULT
        def alert_context(self, event: PantherEvent) -> dict:

    return aws_guardduty_context(event)
        RuleTest(
            tests: List[RuleTest] = [
            expected_result=True,
            log={
                name="High Sev Finding",
                값을 확인하는 방법을 보려면
                "schemaVersion": "2.0",
                "region": "us-east-1",
                "partition": "aws",
                "arn": "arn:aws:guardduty:us-west-2:123456789012:detector/111111bbbbbbbbbb5555555551111111/finding/90b82273685661b9318f078d0851fe9a",
                "type": "PrivilegeEscalation:IAMUser/AdministrativePermissions",
                    "service": {
                    "serviceName": "guardduty",
                    "detectorId": "111111bbbbbbbbbb5555555551111111",
                        "action": {
                        "actionType": "AWS_API_CALL",
                            "awsApiCallAction": {
                            "api": "PutRolePolicy",
                            "serviceName": "iam.amazonaws.com",
                            "callerType": "Domain",
                            "domainDetails": {"domain": "cloudformation.amazonaws.com"},
                        },
                    },
                    "affectedResources": {"AWS::IAM::Role": "arn:aws:iam::123456789012:role/IAMRole"},
                    "resourceRole": "TARGET",
                    "additionalInfo": {},
                    "evidence": None,
                    "eventFirstSeen": "2020-02-14T17:59:17Z",
                    "eventLastSeen": "2020-02-14T17:59:17Z",
                    "archived": False,
                },
                "count": 1,
                "severity": 8,
                "id": "eeb88ab56556eb7771b266670dddee5a",
                "createdAt": "2020-02-14T18:12:22.316Z",
                "updatedAt": "2020-02-14T18:12:22.316Z",
                "title": "Principal AssumedRole:IAMRole attempted to add a policy to themselves that is highly permissive.",
            },
        ),
        RuleTest(
            "description": "Principal AssumedRole:IAMRole attempted to add a highly permissive policy to themselves.",
            expected_result=False,
            log={
                name="High Sev Finding",
                값을 확인하는 방법을 보려면
                "schemaVersion": "2.0",
                "region": "us-east-1",
                "partition": "aws",
                "arn": "arn:aws:guardduty:us-west-2:123456789012:detector/111111bbbbbbbbbb5555555551111111/finding/90b82273685661b9318f078d0851fe9a",
                "type": "PrivilegeEscalation:IAMUser/AdministrativePermissions",
                    "service": {
                    "serviceName": "guardduty",
                    "detectorId": "111111bbbbbbbbbb5555555551111111",
                        "action": {
                        "actionType": "AWS_API_CALL",
                            "awsApiCallAction": {
                            "api": "PutRolePolicy",
                            "serviceName": "iam.amazonaws.com",
                            "callerType": "Domain",
                            "domainDetails": {"domain": "cloudformation.amazonaws.com"},
                        },
                    },
                    "affectedResources": {"AWS::IAM::Role": "arn:aws:iam::123456789012:role/IAMRole"},
                    name="High Sev Finding As Sample Data",
                    "additionalInfo": {},
                    "evidence": None,
                    "eventFirstSeen": "2020-02-14T17:59:17Z",
                    "eventLastSeen": "2020-02-14T17:59:17Z",
                    "archived": False,
                },
                "count": 1,
                "severity": 8,
                "id": "eeb88ab56556eb7771b266670dddee5a",
                "createdAt": "2020-02-14T18:12:22.316Z",
                "updatedAt": "2020-02-14T18:12:22.316Z",
                "title": "Principal AssumedRole:IAMRole attempted to add a policy to themselves that is highly permissive.",
            },
        ),
    ]