> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 이메일 피싱 로그

> /v1 보고 시뮬레이션 이벤트 및 엔터티에서 이전 공급업체의 이벤트 단위 피싱 로그를 재현합니다.

이 보고서는 이벤트 단위 피싱 로그입니다. 관찰된 시뮬레이션 상호작용마다 한 행이 생성되며(날짜, 작업, 수신자 이메일, 제목, 발신자, 난이도), 개인의 이력을 하나의 결과로 합치지 않고 긴 형식(long-form)으로 유지합니다.

쿼리는 최근 \*\*12개월(달력 기준)\*\*을 `occurred_after`에 반영합니다
(12개월 전 같은 일자의 UTC 자정이며, 365일 기간이 아닙니다).

<Note>
  원본 클라이언트 IP는 `/v1`에 절대 포함되지 않습니다. 이는 설계 단계부터 적용된 개인정보 보호 방침이며, 보류 중인 매핑이 아닙니다. 디바이스 유형은 이벤트 행에 있는 파생 분류이며, 원본
  `user_agent`는 비공개로 유지됩니다. 자세한 내용은
  [기존 내보내기와의 차이점](#%EA%B8%B0%EC%A1%B4-%EB%82%B4%EB%B3%B4%EB%82%B4%EA%B8%B0%EC%99%80%EC%9D%98-%EC%B0%A8%EC%9D%B4%EC%A0%90)을 참조하십시오.
</Note>

설정, 자격 증명, 페이지 매김, 속도 제한 재시도는
[Power BI / Excel 연결 가이드](/ko/developers/v1/powerbi)와 동일합니다. 공유
`Fn_FetchAll` 쿼리를 먼저 추가하십시오. 이 보고서는 해당 쿼리를 이름으로 호출합니다.

## 필요한 키 범위

| 범위 | 용도 |
| - | - |
| `reporting:read` | `GET /v1/reporting/simulation_events` |
| `entity:read` | `GET /v1/entities` (이메일 및 표시 이름 조인) |

`simulation:read`만 부여된 키로는 보고 이벤트 엔드포인트를 호출할 수 없습니다(API가 `403`를 반환합니다). [적합한 단위 선택](/ko/developers/v1/powerbi#%EC%A0%81%ED%95%A9%ED%95%9C-%EA%B7%B8%EB%A0%88%EC%9D%B8-%EC%84%A0%ED%83%9D)을 참조하십시오.

## 소스 엔드포인트

| 엔드포인트 | 역할 |
| - | - |
| `GET /v1/reporting/simulation_events` | 이벤트 단위 팩트입니다. 단위는 입력된 상호작용 하나입니다. `email_subject`, `sender_email`, `sender_domain`, `difficulty_tier`는 이 행에 포함되어 있으므로, 쿼리는 해당 필드를 위해 캠페인 단위 결과를 조인하지 않습니다. |
| `GET /v1/entities` | `entity_id`를 이메일 / 표시 이름으로 변환합니다. 보고 이벤트에는 수신자 이메일이 포함되지 않습니다(보고 리더에서 강제로 제외됨). 기존 "이메일" 열은 `/entities`를 순회하여 채웁니다. |

이벤트 목록에서 허용되는 필터(그 외는 `400`를 반환합니다):
`limit`, `page_token`, `simulation`, `entity`, `event_type`,
`occurred_after`.

이 보고 계열은 [미리 보기 데이터 세트](/ko/developers/v1/powerbi#%EB%B3%B4%EA%B3%A0%EC%9A%A9-%EB%AF%B8%EB%A6%AC-%EB%B3%B4%EA%B8%B0-%EB%8D%B0%EC%9D%B4%ED%84%B0%EC%85%8B-%EA%B0%9C%EC%9D%B8%EB%B3%84-%ED%94%BC%EC%8B%B1)입니다.
데이터 세트 스키마와 데이터 정책은
`GET /v1/reporting/datasets` 및
`GET /v1/reporting/datasets/simulation_events`에서 확인할 수 있습니다.

### 단위

보고 시뮬레이션 이벤트마다 한 행이 생성됩니다. 같은 메시지를 열고 클릭한 사용자는 두 개의 행을 생성합니다. `entity_id`가 null인 이벤트(행위자 / 수신자 / 대상 참가자 없음)도 그대로 표시되며, 이 경우 `email`는 null입니다.

API 기간은 1분 확장됩니다. 서버가 `occurred_after`를 포함으로 처리하든 제외로 처리하든 최근 1년 범위가 영향을 받지 않도록, 정확한
`occurred_at >= WindowStart` 경계는 로컬에서 다시 적용됩니다.

요청 예산: 해당 기간의 이벤트에 대한 페이지 매김 순회 1회와 엔터티 순회 1회입니다. 항상 `limit = "500"`를 설정하십시오.

## 열 매핑

기존 열 이름은 이전 공급업체의 내보내기 기준입니다. `/v1` 필드는
공개 API 이름이며, 쿼리는 보고서를 위해 일부 이름에 별칭을 사용합니다.

| 기존 열 | `/v1` 필드 또는 파생 | 보고서 열 |
| - | - | - |
| 날짜 | `Event.occurred_at` (날짜로 변환, 원본 `occurred_at`는 `datetimezone`로 유지) | `date` |
| 작업 | `Event.event_type` — 아래에 나열된 고정 토큰 | `action` |
| 이메일 | `Entity.email` (`entity_id` 기준 조인) | `email` |
| 제목 | `Event.email_subject` | `subject` |
| 발신자 | `Event.sender_email` | `from` |
| 난이도 | `Event.difficulty_tier` — 1\~5의 정수, 1이 가장 쉬움, 5가 가장 어려움 | `difficulty` |
| 원본 IP | `/v1`에 절대 포함되지 않음 | 생략됨(null 처리 아님) |
| 디바이스 유형 | `Event.device_type` — 파생 분류, 이벤트에 파생 분류가 없으면 null | `device_type` |

### 작업 토큰

`action`는 고정된 보고 토큰입니다. 기존 "Email Sent"는
`simulation.delivered`에 매핑됩니다(`delivered`는 공개 동사이고, 전송 토큰은
`simulation.delivered`입니다).

| `action` 값 |
| - |
| `simulation.delivered` |
| `simulation.opened` |
| `simulation.link_clicked` |
| `simulation.credentials_submitted` |
| `simulation.attachment_opened` |
| `simulation.reported` |
| `simulation.bounced` |
| `simulation.qr_scanned` |
| `simulation.replied` |

API에 존재하므로 유지되는 추가 필드: `sender_domain`, `full_name`,
`event_id`, `entity_id`, `simulation_id`, `occurred_at`, 그리고 엔터티 조인에서 가져오는
`entity_type` 및 `entity_status`.

## 기존 내보내기와의 차이점

* **원본 IP는 제공되지 않습니다.** `/v1`는 원본 클라이언트 IP를 노출하지 않습니다. 이는 설계 단계부터 적용된 개인정보 보호 방침이며, 보류 중인 매핑이 아닙니다. 쿼리는 자리 표시자 IP 열을 추가하지 않습니다.
* **디바이스 유형은 원본이 아닌 파생 값입니다.** `device_type`는 클릭, 제출, 신고 이벤트에 대한 파생 디바이스 분류입니다. 관찰된 토큰에는
  `desktop`, `mobile`, `tablet`, `unknown`가 있으나, 발행기는 자유 형식 문자열로 저장하므로 고정된 열거형이 아닌 열린 텍스트로 취급하십시오. 이벤트에 파생 분류가 없으면 null이며, 원본 `user_agent` 문자열은 비공개로 유지됩니다.
* **"Email Sent"는 `simulation.delivered`입니다.** 발송을 필터링하거나 집계할 때 이 토큰을 사용하십시오. 기존 `email_sent` 문자열을 찾지 마십시오.
* **수신자 이메일은 이벤트의 필드가 아니라 조인으로 얻습니다.** 보고 이벤트에는 이메일이 없으며, 쿼리가 `/entities`를 순회하여 채웁니다.
* \*\*최근 12개월(달력 기준)\*\*이며, 365일 기간이나 전체 이력이 아닙니다.
* **긴 형식이며 합치지 않습니다.** 사용자당 결과 하나가 아니라 상호작용마다 한 행입니다.

## 다음 단계

<CardGroup cols={2}>
  <Card title="Power BI 및 Excel 설정" href="/ko/developers/v1/powerbi">
    자격 증명, 페이지 매김, Power BI 또는 Excel에서 이러한 쿼리를 불러오는 방법.
  </Card>

  <Card title="가장 취약한 사용자" href="/ko/developers/v1/reports/most-susceptible-users">
    사용자별 12개월간 클릭, 자격 증명, 신고 집계.
  </Card>

  <Card title="사용자별 규정 준수" href="/ko/developers/v1/reports/per-person-compliance">
    사용자 × 할당 단위의 교육 등록 현황.
  </Card>

  <Card title="API 키" href="/ko/developers/developer-hub/api-keys">
    이 보고서를 새로 고치는 키에 `reporting:read` 및 `entity:read`를 부여하십시오.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.