> 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/testing.md).
# 테스트
## 개요
디택션을 테스트하면 배포 후 디택션이 예상대로 동작하고 알러트가 생성되는지 [시그널](/ko/detections/signals.md) 적절하게 보장할 수 있습니다. 테스트는 또한 신뢰성을 높이고 시간이 지나 코드가 발전할 때 발생할 수 있는 회귀를 방지합니다.
테스트는 특정 디택션에 대한 테스트 로그 이벤트를 정의하고, 해당 테스트 이벤트가 그 디택션에 의해 처리될 때 알러트가 생성될 것으로 예상하는지 여부를 지정하는 방식으로 동작합니다. Panther는 각 디택션에 대해 필요한 최소 테스트 수를 강제하지 않지만, 최소 두 개—거짓 양성 하나와 참 양성 하나—를 구성하는 것을 권장합니다.
사용자 정의 디택션(즉, 다음이 아닌 것들)에 대한 테스트를 생성, 편집 및 삭제할 수 있습니다 [Panther에서 관리하는](/ko/detections/panther-managed.md)). 테스트는 [Panther에서 관리하는](/ko/detections/panther-managed.md) 디택션은 Panther가 관리하며 읽기 전용입니다.
Panther의 [데이터 리플레이](/ko/detections/testing/data-replay.md), 이는 예측 결과를 미리 보기 위해 히스토리컬 로그 데이터를 룰을 통해 실행할 수 있게 해 주며, 테스트할 때도 유용합니다.
## 테스트 사용
### 테스트를 만드는 방법
Panther Console에서 관리되지 않는 디택션에 대한 테스트를 만들 수 있습니다 [Panther에서 관리하는](/ko/detections/panther-managed.md) 또는 CLI 워크플로에서 [Panther Analysis Tool](/ko/panther/detections-repo/pat.md) (PAT).
{% tabs %}
{% tab title="콘솔: 디택션 페이지" %}
1. Panther 콘솔의 왼쪽 탐색 표시줄에서 다음을 클릭합니다: **디택션**.
2. 기존 디택션의 이름을 클릭하거나 [새 디택션을 만듭니다](/ko/detections.md#how-to-write-detections).
3. 아래로 스크롤하여 **테스트** 섹션.
4. 오른쪽 **단위 테스트** 타일에서 다음을 클릭합니다: **새로 추가**.\
* 디택션이 [Panther에서 관리하는](/ko/detections/panther-managed.md), **새로 추가** 새 테스트를 만들 수 없으므로 비활성화됩니다.
5. 새로 생성된 테스트에는 자리 표시자 이름이 부여됩니다. 오른쪽에서 점 세 개 아이콘을 클릭하고 **이름 바꾸기**.\
6. 테스트에 의미 있는 이름을 입력하고 enter 또는 return 키를 눌러 저장합니다.
7. 다음을 설정하세요 **디택션은 예시 이벤트를 기준으로 트리거되어야 합니다** 토글을`YES` 또는 `아니요`.
8. 텍스트 편집기에서 테스트 JSON 이벤트를 작성합니다.
9. 테스트가 통과하는지 확인하려면 **테스트 실행**.
10. 작업을 마쳤으면 페이지 오른쪽 상단에서 **업데이트** 또는 **저장**.
{% endtab %}
{% tab title="콘솔: 알러트 이벤트" %}
Panther Console에서 알러트와 연결된 실제 이벤트를 사용하여 알러트에서 바로 새 단위 테스트를 만들 수 있습니다. 다음의 지침을 따르세요: [알러트 이벤트에서 필터 추가](/ko/detections/rules/inline-filters.md#add-filters-from-an-alert-event), 9단계와 10단계를 참고하세요.
이 기능은 룰에만 사용할 수 있습니다.
{% endtab %}
{% tab title="CLI" %}
**CLI 워크플로에서 테스트를 만드는 방법**
**룰과 예약된 룰**
YAML 파일에서(둘 다 [Python](/ko/detections/rules/python.md) 그리고 [Simple 디택션](/ko/detections/rules/writing-simple-detections.md)), 다음이 있는 `Tests` 키를 다음 필드와 함께 추가합니다:
```yaml
테스트:
-
Name: 첫 번째 테스트를 설명하는 이름
LogType: LogType.GoesHere
ExpectedResult: true 또는 false
Log:
{
"hostName": "test-01.prod.acme.io",
"user": "martin_smith",
"eventTime": "June 22 5:50:52 PM"
}
```
**정책**
YAML 파일에 다음 `Tests` 키를 추가합니다. 의 값은 `리소스` 를 **정책** > **리소스** 탐색기에서 직접 복사한 JSON 객체일 수 있습니다.
```yaml
테스트:
-
Name: 첫 번째 테스트를 설명하는 이름.
ResourceType: AWS.S3.Bucket
예상 결과: true
Resource:
{
"PublicAccessBlockConfiguration": null,
"Region": "us-east-1",
"Policy": null,
"AccountId": "123456789012",
"LoggingPolicy": {
"TargetBucket": "access-logs-us-east-1-100",
"TargetGrants": null,
"TargetPrefix": "acmecorp-fiancial-data/"
},
"EncryptionRules": [
{
"ApplyServerSideEncryptionByDefault": {
"SSEAlgorithm": "AES256",
"KMSMasterKeyID": null
}
}
],
"Arn": "arn:aws:s3:::acmecorp-fiancial-data",
"Name": "acmecorp-fiancial-data",
"LifecycleRules": null,
"ResourceType": "AWS.S3.Bucket",
"Grants": [
{
"Permission": "FULL_CONTROL",
"Grantee": {
"URI": null,
"EmailAddress": null,
"DisplayName": "admins",
"Type": "CanonicalUser",
"ID": "013ae1034i130431431"
}
}
],
"Versioning": "Enabled",
"ResourceId": "arn:aws:s3:::acmecorp-fiancial-data",
"Tags": {
"aws:cloudformation:logical-id": "FinancialDataBucket"
},
"Owner": {
"ID": "013ae1034i130431431",
"DisplayName": "admins"
},
"TimeCreated": "2020-06-13T17:16:36.000Z",
"ObjectLockConfiguration": null,
"MFADelete": null
}
```
{% endtab %}
{% endtabs %}
### Panther Console에서 테스트 이름을 바꾸거나 삭제하는 방법
관리되지 않는 디택션에 대한 테스트의 이름을 바꾸거나 삭제할 수 있습니다 [Panther에서 관리하는](/ko/detections/panther-managed.md).
1. Panther 콘솔의 왼쪽 탐색 표시줄에서 다음을 클릭합니다: **디택션**.
2. 디택션의 이름을 클릭합니다.
3. 아래로 스크롤하여 **테스트** 섹션.
4. 다음 안에서 **단위 테스트** 타일에서 이름을 바꾸거나 삭제할 테스트를 찾습니다.
5. 테스트 이름 오른쪽에서 점 세 개 아이콘을 클릭합니다.
* 디택션이 [Panther에서 관리하는](/ko/detections/panther-managed.md), 그 테스트의 이름은 바꾸거나 삭제할 수 없습니다. 각 테스트 이름 옆의 점 세 개 아이콘 대신 Panther 아이콘이 표시됩니다.
6. 다음을 클릭합니다: **이름 바꾸기** 또는 **삭제**.
* 이름을 바꾸는 경우 새 이름을 입력하고 enter 또는 return 키를 눌러 저장합니다.
* 삭제하는 경우 **테스트 삭제** 확인 모달이 표시됩니다.
* 선택 **확인**.
### 테스트 예시
* 다음을 클릭합니다: **편집** 페이지 오른쪽 상단에서.
* 아래로 스크롤하여 **룰 함수** 텍스트 편집기 아래의 **단위 테스트** 텍스트 편집기.
이전 예시에서와 같이( [룰](/ko/detections/rules.md)), 이 디택션에 대해 두 개의 테스트를 작성해 보겠습니다:
{% tabs %}
{% tab title="Python" %}
```python
def 룰(event):
return event.get('status') == 200 and 'admin-panel' in event.get('request')
def title(event):
return f"{event.get('remoteAddr')}에서 성공적인 관리자 패널 로그인이 감지되었습니다"
def dedup(event):
return event.get('remoteAddr')
```
{% endtab %}
{% tab title="Simple 디택션" %}
```yaml
디택션:
- 키 경로: status
조건: 같음
값: 200
- 키 경로: request
조건: 포함
값: 'admin-panel'
알러트 제목: "{remoteAddr}에서 성공적인 관리자 패널 로그인이 감지됨"
그룹화 기준:
- 키 경로: remoteAddr
```
{% endtab %}
{% endtabs %}
`이름`: 성공적인 관리자 패널 로그인
`테스트 이벤트는 알러트를 트리거해야 합니다`: 예
```javascript
{
"httpReferer": "https://domain1.com/?p=1",
"httpUserAgent": "Chrome/80.0.3987.132 Safari/537.36",
"remoteAddr": "180.76.15.143",
"request": "GET /admin-panel/ HTTP/1.1",
"status": 200,
"time": "2019-02-06 00:00:38 +0000 UTC"
}
```
`이름`: 오류가 발생한 access-policy 페이지 요청
`테스트 이벤트는 알러트를 트리거해야 합니다`: 아니요
```javascript
{
"httpReferer": "https://domain1.com/?p=1",
"httpUserAgent": "Chrome/80.0.3987.132 Safari/537.36",
"remoteAddr": "180.76.15.143",
"request": "GET /access-policy/ HTTP/1.1",
"status": 500,
"time": "2019-02-06 00:00:38 +0000 UTC"
}
```
{% hint style="info" %}
디택션의 신뢰성을 최대한 높이기 위해 원하는 만큼 다양한 조합을 사용하세요.
{% endhint %}
## 모크
{% hint style="warning" %}
Panther에서 디택션 내부에서 외부 API 요청을 하는 것은 매우 권장되지 않습니다. 일반적으로 디택션은 매우 대규모로 처리되므로 API 요청을 하면 수신 시스템에 과부하가 걸리고 룰이 다음을 초과할 수 있습니다 [15초 실행 시간 제한](/ko/detections/rules.md#rule-errors-and-scheduled-rule-errors).
{% endhint %}
Panther의 테스트 프레임워크는 Python 함수 호출의 기본적인 모킹을 지원합니다.
외부 API 호출을 수행하는 디택션에 대한 단위 테스트를 작성할 때, 실제로 API 호출을 실행하지 않고도 테스트에서 모크를 사용해 서버 응답을 모방할 수 있습니다.
모크는 다음으로 정의됩니다: **모크 이름** 그리고 **반환 값** (또는 `objectName` 그리고 `returnValue`, (CLI 워크플로에서는) 각각 모킹할 함수 이름과 반환할 모크 값을 나타냅니다(이는 반드시 a `문자열`).
모크는 단위 테스트 수준에서 정의되므로, 각 단위 테스트마다 다른 모크를 정의할 수 있습니다.
### 모크 사용 방법
콘솔과 CLI 워크플로 모두에서 테스트용 모크를 구성할 수 있습니다.
모크는 `문자열` 값만 반환할 수 있습니다. 모킹되는 함수가 다른 데이터 형식을 반환하더라도 마찬가지입니다. 이는 모크 기능의 알려진 제한 사항입니다.
{% hint style="info" %}
모크 반환 값이 type `문자열`이어야 한다는 제한 때문에, string 이외의 데이터 형식을 반환하는 함수를 모킹하는 경우 테스트가 모크 값을 성공적으로 사용하도록 함수의 반환 값을 이미 그 데이터 형식으로 캐스팅하는 것이 권장됩니다.
예를 들어, 여러분의 `룰()` 함수 `get_counter()` 가 정수를 반환한다면 `int(get_counter())`.
{% endhint %}
{% tabs %}
{% tab title="콘솔" %}
콘솔에서 단위 테스트에 모크를 추가하려면:
1. 다음 안에서 **단위 테스트** 타일에서 **모크 테스트** 섹션을 테스트 이벤트 편집기 아래에서 찾습니다.
2. 다음에 대한 값을 추가합니다 **모크 이름** 그리고 **반환 값**.
3. 모크가 예상대로 동작하는지 테스트하려면 **테스트 실행**.
{% endtab %}
{% tab title="CLI" %}
CLI 워크플로에서 단위 테스트에 모크를 추가하려면:
테스트 케이스에 다음을 추가합니다 `모크` 키를 추가하여 모킹할 함수 목록과 해당 모크 반환 값을 정의합니다. 단일 테스트에서 여러 함수를 모킹할 수 있습니다.
다음의 값은 `returnValue` 이어야 합니다 `문자열`, 실제로 디택션 코드의 함수가 다른 데이터 형식을 반환하더라도 마찬가지입니다. 이는 [`pat test`](/ko/panther/detections-repo/pat/pat-commands.md#test-running-unit-tests).
예를 들어, 우리가 함수 `get_counter` 를 항상 반환하도록 모킹하고 싶고 `"1"` 및 함수 `geoinfo_from_ip` 를 특정 geo IP 정보 집합을 항상 반환하도록 모킹하고 싶다면, 다음과 같이 단위 테스트를 작성할 수 있습니다:
```yaml
테스트:
-
Name: 모크와 함께하는 테스트
LogType: LogType.Custom
예상 결과: true
Mocks:
- objectName: get_counter
returnValue: "1"
- objectName: geoinfo_from_ip
returnValue: |
{
"region": "UnitTestRegion",
"city": "UnitTestCityNew",
"country": "UnitTestCountry"
}
Log:
{
"hostName": "test-01.prod.acme.io",
"user": "martin_smith",
"eventTime": "June 22 5:50:52 PM"
}
```
모킹을 사용하면 API 키나 네트워크 접근 없이 CI/CD 파이프라인에서 네트워크 호출을 에뮬레이션할 수 있고, 외부 추적 시스템(예: panther KV store)의 상태를 흐트러뜨리지 않을 수 있습니다.
다음 사용에 대한 자세한 내용은 관련 문서를 참조하세요: [Panther Analysis Tool (PAT)](/ko/panther/detections-repo/pat.md) 그리고 [CI/CD 워크플로](/ko/panther/detections-repo/ci-cd/deployment-workflows/circle-ci.md).
{% endtab %}
{% endtabs %}
모크는 다음에서 사용할 수 있습니다 **전역** 그리고 **내장** Python 네임스페이스에는 다음이 포함됩니다:
* 가져온 모듈과 함수
* [전역 헬퍼](/ko/detections/rules/python/globals.md), Panther가 관리하는 것과 사용자 정의
Python은 두 가지 가져오기 형식을 제공하며, 이는 다음과 같이 모킹할 수 있습니다:
* `import package`
* 모크 이름: `패키지`
* `from package import module`
* 모크 이름: `모듈`
### 모크 예시
이 예시는 [AWS Config 글로벌 리소스](https://github.com/panther-labs/panther-analysis/blob/main/policies/aws_config_policies/aws_config_global_resources.py) 디택션.
디택션은 전역 헬퍼 함수 `resource_lookup` 를 사용합니다 `panther_aws_helpers` 에서 `resources-api` 를 조회하고 리소스 속성을 반환합니다. 그러나 단위 테스트는 외부 API 호출 없이 수행할 수 있어야 합니다.
이 테스트는 일반 예시 데이터에 대응하는 리소스 매핑이 없기 때문에 실패합니다.
#### 디택션 자세히 들여다보기
```python
# --- Snipped ---
from panther_aws_helpers import resource_lookup
# --- Snipped ---
def policy(resource):
# --- Snipped ---
for recorder_name in resource.get("Recorders", []):
recorder = resource_lookup(recorder_name)
resource_records_global_resources = bool(
deep_get(recorder, "RecordingGroup", "IncludeGlobalResourceTypes")
and deep_get(recorder, "Status", "Recording")
)
if resource_records_global_resources:
return True
return False
# --- Snipped ---
```
디택션은 `from panther_aws_helpers import resource_lookup` 관례를 사용하므로 모크는 `resource_lookup` 함수에 대해 정의되어야 합니다.
모크는 실제 데이터를 활용해 디택션 로직을 테스트할 수 있는 방법을 제공합니다.
**사용된 반환 값**:
```
{ "AccountId": "012345678910", "Name": "Default", "RecordingGroup": { "AllSupported": true, "IncludeGlobalResourceTypes": true, "ResourceTypes": null }, "Region": "us-east-1", "ResourceId": "012345678910:us-east-1:AWS.Config.Recorder", "ResourceType": "AWS.Config.Recorder", "RoleARN": "arn:aws:iam::012345678910:role/PantherAWSConfig", "Status": { "LastErrorCode": null, "LastErrorMessage": null, "LastStartTime": "2018-10-05T22:45:01.838Z", "LastStatus": "SUCCESS", "LastStatusChangeTime": "2021-05-28T17:45:14.916Z", "LastStopTime": null, "Name": "Default", "Recording": true }, "Tags": null, "TimeCreated": null }
```
이 리소스는 준수해야 하지만, 단위 테스트는 실패합니다.\
반환을 기대하지 않는 디택션은 `문자열` 모크에 약간의 조정이 필요합니다.
이 단위 테스트를 예상대로 작동하게 하려면 다음 수정이 필요합니다:
```python
# --- Snipped ---
import json
# Another option is to use: from ast import literal_eval
# --- Snipped ---
def policy(resource):
# --- Snipped ---
recorder = resource_lookup(recorder_name)
if isinstance(recorder, str):
recorder = json.loads(recorder)
# --- Snipped ---
```
이 수정이 추가되면 이제 실제 데이터로 디택션 로직을 테스트할 수 있습니다!
#### CLI의 모크
단위 테스트 모킹은 디택션 작성용 CLI 기반 워크플로에서도 지원됩니다. CLI 기반 디택션에 단위 테스트 모크를 추가하는 자세한 내용은 [단위 테스트 모킹](#how-to-use-mocks) PAT 문서의 섹션을 참조하세요.
## 테스트 데이터 보강
테스트 이벤트를 다음으로 보강할 수 있습니다 `p_enrichment` Panther Console과 CLI 워크플로 모두에서.
{% hint style="info" %}
다음을 사용하고 있다면 `lookup()` 함수를 디택션에서 사용 중이라면, 대신 다음 지침을 따르세요 [를 사용하는 디택션의 단위 테스트 `lookup()`](/ko/detections/rules/python.md#unit-testing-detections-that-use-lookup).
{% endhint %}
{% tabs %}
{% tab title="콘솔" %}
다음이 있다면 [Lookup Table(s)](/ko/enrichment/custom.md) 를 구성하고 이를 활용하는 디택션을 만든 뒤 **테스트 데이터 보강** JSON 이벤트 편집기의 오른쪽 상단에서 `p_enrichment` 가 올바르게 채워졌는지 확인합니다.
{% endtab %}
{% tab title="CLI" %}
* PAT의 `enrich-test-data` 명령을 사용합니다. [자세한 내용은 `enrich-test-data` 여기에서](/ko/panther/detections-repo/pat/pat-commands.md#enrich-test-data-enriching-test-data-with-enrichment-content).
{% endtab %}
{% endtabs %}
---
# 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/testing.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.