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

# 기기 핑거프린팅 및 IP 위험 경고 코드

> Didit의 기기 및 IP 분석 경고 코드 안내: VPN/Tor, 국가 불일치, 차단 목록, 중복 IP/기기, 복구된 기기, 예상 IP 불일치 등 전체 목록.

## 개요

기기 및 IP 분석은 의심스러운 기기, 네트워크 또는 위치 관련 동작을 감지할 때마다 `ip_analyses[].warnings[]`에 경고 태그를 생성합니다. 9개 태그에는 워크플로 노드별로 구성 가능한 작업(거부/검토/작업 없음)이 설정되어 있습니다. 2개의 차단 목록 태그는 항상 `Declined`를 강제 적용하며, 2개의 허용 목록 태그는 항상 정보용입니다. 각 경고의 `log_type`은 적용된 작업을 반영합니다: `error`(거부), `warning`(검토), 또는 `information`(작업 없음). 각 위험은 세션당 최대 한 번만 발생합니다.

아래의 모든 위험은 라이브 결정 파이프라인과 대조하여 검증됩니다. 경고에는 `LOCATION` 기능 태그와 표준 [경고 객체](https://docs.didit.me/ko/reference/data-models.md#경고-객체) 형태가 포함됩니다.

기기 핑거프린트 경고는 의도적으로 정확한 신호와 복구된 신호로 분리되어 있습니다:

* `DUPLICATED_DEVICE_FINGERPRINT`는 동일한 결정론적 기기 식별자(`match_source`가 `persistent_id` 또는 `legacy_fp`인)가 다른 `vendor_data` 값을 가진 세션 간에 재사용되었음을 의미합니다.
* `DEVICE_RECOVERED_HIGH_CONFIDENCE`는 영구 ID가 변경(저장소 삭제, 시크릿 모드, 앱 재설치)된 **이후에** v2 핑거프린트 복구가 해당 세션을 이전에 확인된 기기와 일치시켰음을 의미합니다. 이 경고는 일치 항목이 높은 신뢰도 유사성 임계값 및 엄격한 게이트를 통과하는 경우에만 표시됩니다.

![기기, VPN, 프록시 및 위치 불일치 알림이 포함된 Didit 기기 및 IP 분석 경고 예시](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/ip-analysis-warning-example.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=370f87af45a6138ebd7454abe9131665)

## 생성되는 경고

| 위험 | 원인 | `log_type` | 상태에 미치는 영향 | 권장 조치 |
| - | - | - | - | - |
| `PRIVATE_NETWORK_DETECTED` | `is_vpn_or_tor` 값이 `true`였습니다. 즉, 세션이 VPN, 프록시 또는 Tor 출구 노드를 통해 열렸습니다. `additional_data`는 `null`입니다. | 설정된 작업을 반영 | 설정 가능: 거부 / 검토 / 조치 없음 (기본값: 조치 없음). | 위험 허용 수준이 마스킹된 트래픽을 허용하는지 판단하십시오. 허용하는 경우 조치 없음으로 유지하십시오. |
| `COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP` | 신분증 문서의 ISO 국가가 IP 주소에서 도출된 국가와 다릅니다. `additional_data`에는 두 ISO-3 코드인 `document_country_code`, `ip_country_code`가 포함됩니다. | 설정된 작업을 반영 | 설정 가능: 거부 / 검토 / 조치 없음 (기본값: 조치 없음). | 사용자가 정상적으로 여행 중인 경우 검토하십시오. VPN 또는 중복 기기 신호와 함께 감지되면 거부하십시오. |
| `EXPECTED_IP_ADDRESS_MISMATCH` | 세션 생성 시 예상 IP 주소가 지정되었으나 실제 접속 IP와 다릅니다. `additional_data`에는 `expected_ip_address` 및 `actual_ip_address`가 포함됩니다. | 설정된 작업을 반영 | 설정 가능: 거부 / 검토 / 조치 없음 (기본값: 조치 없음). | 세션 생성 시 IP를 미리 고정할 때 사용하십시오. 불일치 시 세션을 거부하거나 인증 단계를 상향하십시오. |
| `IP_ADDRESS_IN_BLOCKLIST` | 세션의 IP 주소가 애플리케이션의 IP 차단 목록에 있는 항목과 일치합니다. `additional_data`: `ip_address`. | 항상 `error` | 강제로 `Declined` 처리됩니다. | 세션을 거부하십시오. 필요한 경우 오탐 여부를 확인하기 위해 차단 목록 출처를 감사하십시오. |
| `DEVICE_FINGERPRINT_IN_BLOCKLIST` | 세션의 기기 핑거프린트가 기기 차단 목록의 항목과 일치합니다. `additional_data`: `device_fingerprint`. | 항상 `error` | 강제로 `Declined` 처리됩니다. | 세션을 거부하십시오. |
| `IP_ADDRESS_IN_ALLOWLIST` | 세션의 IP에 중복 일치 항목이 있었으나 애플리케이션의 IP 허용 목록에 포함되어 있어 중복 IP 경고를 건너뛰었습니다. `additional_data`: `ip_address`. | 항상 `information` | 없음. | 신뢰할 수 있는 회사 NAT, QA 네트워크 또는 알려진 공유 액세스 포인트에 사용하십시오. |
| `DEVICE_FINGERPRINT_IN_ALLOWLIST` | 세션의 기기 핑거프린트에 확정적 중복 일치가 있었으나 기기 허용 목록에 포함되어 있어 중복 기기 경고를 건너뛰었습니다. `additional_data`: `device_fingerprint`. | 항상 `information` | 없음. | 신뢰할 수 있는 공유 기기에만 사용하십시오. 차단 목록이 여전히 우선 적용됩니다. |
| `DUPLICATED_IP_ADDRESS` | 동일한 IP가 다른 `vendor_data`를 가진 다른 세션에서 사용되었습니다. `additional_data`: `duplicated_session_id`, `duplicated_session_number`, `api_service`. IP가 허용 목록에 있는 경우 건너뜁니다. | 설정된 작업을 반영 | 설정 가능: 거부 / 검토 / 조치 없음 (기본값: 조치 없음). | 회사 또는 공유 NAT에서 흔히 발생합니다. 거부하기 전에 다른 신호(중복 기기, 국가 불일치)와 함께 확인하십시오. |
| `DUPLICATED_DEVICE_FINGERPRINT` | 동일한 확정적 기기 식별자가 서로 다른 `vendor_data`를 가진 여러 세션에서 재사용되었습니다. `additional_data`: `duplicated_session_id`, `duplicated_session_number`, `api_service`, `match_source` (`persistent_id` 또는 `legacy_fp`). 핑거프린트가 허용 목록에 있는 경우 건너뜁니다. | 설정된 작업을 반영 | 설정 가능: 거부 / 검토 / 조치 없음 (기본값: 조치 없음). | 다중 계정 남용의 강력한 증거입니다. 사기 허용 범위에 따라 검토하거나 거부하십시오. |
| `DEVICE_RECOVERED_HIGH_CONFIDENCE` | 영구 ID가 변경된 후에도 v2 기기 복구 모델이 높은 신뢰도로 이전에 확인된 기기와 세션을 일치시켰습니다. `additional_data`: `duplicated_session_id`, `duplicated_session_number`, `api_service`, `match_source` (`recovered_high`), `recovery_similarity`, `recovery_match_device_uuid`. 기기 허용 목록에 의해 억제되지 않습니다. | 설정된 작업을 반영 | 설정 가능: 거부 / 검토 / 조치 없음 (기본값: 조치 없음). | 먼저 검토로 시작하여 오탐률을 측정한 후 작업을 강화하십시오. 스토리지 초기화 또는 시크릿 모드 시도에 대한 강력한 신호입니다. |
| `DEVICE_LINKED_TO_LIVENESS_ATTACK` | 동일한 기기(영구 기기 ID로 일치됨)가 라이브니스 캡처가 공격으로 판단된 다른 사용자의 이전 세션에서 사용되었습니다. 이미 라이브니스 검사를 공격하는 데 사용된 기기는 이 캡처 또한 동일한 공격자로부터 비롯되었음을 나타내는 강력한 지표입니다. `additional_data`: `liveness_attack_session_id`, `liveness_attack_session_number`, `liveness_attack_sessions_count`, `match_source` (`persistent_id`). | 설정된 작업을 반영 | 설정 가능: 거부 / 검토 / 조치 없음 (기본값: 조치 없음). | 거부로 강화하기 전에 먼저 검토로 시작하여 오탐률을 측정하십시오. |
| `DEVICE_MODEL_INCONSISTENT` | 동일한 기기(영구 기기 ID로 일치됨)가 이전 세션에서 다른 기기 모델로 보고되었습니다. 하나의 물리적 기기는 모델이 변경되지 않으므로, 보고된 모델이 스푸핑되었거나 기기 식별자가 다른 기기로 복사되었을 가능성이 높습니다. 일반적인 모델 문자열은 비교되지 않습니다. `additional_data`: `device_model`, `earlier_device_model`, `earlier_session_id`, `earlier_session_number`, `match_source`. | 설정된 작업을 반영 | 설정 가능: 거부 / 검토 / 조치 없음 (기본값: 조치 없음). | 조치를 취하기 전에 보고된 두 모델을 비교하고 이전 세션을 검토하십시오. |
| `IP_LOCATION_NOT_ALLOWED` | IP 지오펜싱이 활성화되어 있으며 세션 IP가 허용되지 않음으로 표시된 국가 또는 주/지역에 위치해 있습니다. `additional_data`: `ip_country_code` (ISO-3), `ip_country`, `ip_state`, `restricted_by` (`country` 또는 `state`). | 설정된 작업을 반영 | 설정 가능: 거부 / 검토 / 조치 없음 (기본값: 거부). | 관할권 제한을 적용하는 데 사용하십시오. 마스킹된 트래픽이 지오펜스를 우회할 수 없도록 `vpn_detection_action`과 함께 사용하십시오. |

복구된 기기에 적격한 형제 세션이 아직 없어 `matches[]`에 아무것도 포함되지 않은 경우에도, `DEVICE_RECOVERED_HIGH_CONFIDENCE`는 대체 `additional_data` 형태(`recovery_match_device_uuid`, `recovery_match_similarity`, `recovery_match_band`, `recovery_gate_reason`)로 트리거됩니다.

`IP_LOCATION_NOT_ALLOWED`는 IP 지오펜싱이 활성화되어 있고(`is_ip_geofencing_enabled`) 세션 IP가 `ip_geofencing_by_country`에서 허용되지 않음으로 표시된 국가 또는 주/지역에 위치할 때 트리거됩니다. `additional_data`에는 `ip_country_code` (ISO-3), `ip_country`, `ip_state` 및 `restricted_by` (`country` 또는 `state`)가 포함됩니다. 주/지역 항목은 국가 플래그보다 우선 적용되며 IP 제공업체의 지역 이름(예: `"California"`)과 대소문자를 구분하지 않고 일치시킵니다. 설정에 나열되지 않은 국가는 허용됩니다.

## 기기 및 런타임 무결성

네이티브 SDK와 웹 클라이언트가 보고하는 신호로, 인증이 실행된 기기의 상태를 나타냅니다. 이는 인젝션 공격을 감지하기 위해 존재합니다. 기기를 루팅하거나 앱 프로세스를 후킹할 수 있는 공격자는 카메라 피드가 생체 인식 검사에 도달하기 전에 이를 변조할 수 있습니다.

각 신호는 워크플로별로 구성할 수 있으며 기본값은 **작업 없음**이므로, 기능을 활성화하더라도 직접 옵트인하기 전까지는 결정이 변경되지 않습니다.

| 위험 | 원인 | 구성 키 | 기본값 |
| - | - | - | - |
| `DEVICE_APP_TAMPERED` | 플랫폼 증명을 통해 요청이 실제 기기에서 실행된 정품 및 수정되지 않은 애플리케이션 빌드에서 비롯되었음을 검증하지 못했습니다. | `device_app_tampered_action` | `NO_ACTION` |
| `DEVICE_RUNTIME_HOOKING_DETECTED` | 애플리케이션 프로세스에서 런타임 계측 또는 후킹 프레임워크(Frida, Xposed, LSPosed, Substrate)가 감지되었습니다. | `device_hooking_action` | `NO_ACTION` |
| `DEVICE_ROOTED_OR_JAILBROKEN` | 기기에서 루팅 또는 탈옥 지표가 확인되었습니다. 이는 카메라 가로채기를 방지하는 운영체제 보호 기능을 무력화합니다. | `device_rooted_action` | `NO_ACTION` |
| `DEVICE_EMULATOR_DETECTED` | 세션이 물리적 기기가 아닌 에뮬레이터 또는 시뮬레이터에서 발생했습니다. | `device_emulator_action` | `NO_ACTION` |
| `DEVICE_DEBUGGER_ATTACHED` | 인증 중에 애플리케이션에 디버거 또는 프로세스 추적기가 연결되었습니다. | `device_debugger_action` | `NO_ACTION` |
| `AUTOMATION_FRAMEWORK_DETECTED` | 세션이 사람이 아닌 브라우저 자동화 프레임워크 또는 헤드리스 브라우저에 의해 실행되었습니다. | `automation_detected_action` | `NO_ACTION` |
| `DEVICE_INTEGRITY_SIGNALS_MISSING` | 클라이언트가 무결성 보고를 지원하는 SDK 버전을 보고했으나 무결성 신호가 수신되지 않았습니다. 이는 전송 중에 신호가 제거되었음을 나타낼 수 있습니다. | `device_integrity_missing_action` | `NO_ACTION` |

> [!NOTE]
>
> 각 프로브는 가능한 범위에서 작동합니다. 검사를 실행할 수 없는 경우 정상 결과 대신 **판정 불가**를 보고하므로, 프로브 실패로 인해 정당한 사용자에게 오탐이 발생하지 않습니다. 신호는 네이티브 SDK **4.4.0** 버전부터 보고되며, 이전 버전 SDK의 세션은 정상적으로 아무것도 전송하지 않으므로 `DEVICE_INTEGRITY_SIGNALS_MISSING`이 발생하지 않습니다.

> [!WARNING]
>
> 루팅 및 에뮬레이터 신호는 수정되었으나 사기 목적이 아닌 기기를 사용하는 정상적인 사용자 사이에서도 흔히 발생할 수 있습니다. 거부(Decline) 대신 검토(Review)로 시작하고, 설정을 강화하기 전에 자체 거부율을 모니터링하십시오.

## 구성 가능한 설정

노드별 워크플로 제어(애플리케이션의 인증 설정에서 전역으로 구성할 수도 있으며, 별도로 명시되지 않는 한 모든 작업의 기본값은 **작업 없음**입니다):

| 설정 | 제어 대상 | 기본값 |
| - | - | - |
| `vpn_detection_action` | `PRIVATE_NETWORK_DETECTED` | 작업 없음 |
| `ip_mismatch_action` | `COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP` | 작업 없음 |
| `expected_ip_mismatch_action` | `EXPECTED_IP_ADDRESS_MISMATCH` | 작업 없음 |
| `duplicated_ip_action` | `DUPLICATED_IP_ADDRESS` | 작업 없음 |
| `duplicated_device_action` | `DUPLICATED_DEVICE_FINGERPRINT` | 작업 없음 |
| `recovered_device_action` | `DEVICE_RECOVERED_HIGH_CONFIDENCE` | 작업 없음 |
| `device_liveness_attack_history_action` | `DEVICE_LINKED_TO_LIVENESS_ATTACK` | 작업 없음 |
| `device_model_inconsistency_action` | `DEVICE_MODEL_INCONSISTENT` | 작업 없음 |
| `ip_geofencing_action` | `IP_LOCATION_NOT_ALLOWED` | 거부 |

IP 및 기기 허용 목록은 허용 목록에 등록된 값에 대해 정확히 일치하는 중복 IP 또는 결정론적 중복 기기 경고만 억제합니다. VPN/프록시, 국가 불일치, 예상 IP 불일치, 복구된 기기 또는 차단 목록 경고는 억제하지 않습니다.

복구된 기기 경고는 동일한 하드웨어에서 계정과 세션을 순환하는 사기 조직을 감지하는 데 유용하지만, Didit은 기본적으로 보수적으로 설계되었습니다. 즉, 증거가 충분하지 않을 때 관련 없는 기기를 병합하기보다는 일부 중복 사용자를 놓치는 방식을 택합니다. **권장 도입 단계**: 검토(Review)로 시작하여 2주 동안 발생량을 관찰한 다음, 오탐률이 낮다면 작업을 강화하십시오.

## 중복 기기 vs. 복구된 기기

두 경고는 서로 다른 증거를 바탕으로 트리거되므로 다르게 다루어야 합니다.

| 경고 | 트리거 조건 | 일반적인 의미 | 권장 초기 작업 |
| - | - | - | - |
| `DUPLICATED_DEVICE_FINGERPRINT` | 영구 기기 식별자(`persistent_id`) 또는 레거시 핑거프린트 해시(`legacy_fp`)의 정확한 일치. | 서로 다른 사용자 간에 동일한 기기가 나타났음을 나타내는 강력한 증거입니다. | 사기 허용 한도에 따라 검토(Review) 또는 거부(Decline). |
| `DEVICE_RECOVERED_HIGH_CONFIDENCE` | 스토리지, 세션 또는 앱 식별자가 변경된 후 높은 신뢰도의 v2 복구(`recovered_high`). | 시크릿 모드/스토리지 초기화/앱 재설치 시도를 나타내는 강력한 신호입니다. 독립적으로 모니터링할 수 있도록 의도적으로 분리되어 있습니다. | 먼저 검토(Review)로 시작한 후 오탐률을 측정한 뒤 작업을 강화하십시오. |

## 세션 간 일치

**서로 다른 사용자**에 속한 세션 전반에서 동일한 IP, 정확히 일치하는 기기 식별값 또는 복구된 기기가 감지되면 Didit은 이를 `ip_analyses[]`의 `matches[]`에 기록합니다. 세션은 `vendor_data`를 기준으로 그룹화됩니다. 동일한 `vendor_data`를 가진 세션은 동일한 사용자로 처리되어 일치 항목에서 제외됩니다. `vendor_data`가 없으면 모든 세션이 고유한 사용자로 처리되어 잠재적인 중복 항목이 모두 노출되므로, 노이즈를 줄이기 위해 항상 `vendor_data`를 제공하는 것을 강력히 권장합니다.

각 일치 항목에는 다음이 포함됩니다.

* 일치하는 세션의 `session_id`, `session_number`, `vendor_data`, `verification_date` 및 수명 주기 `status`, `api_service`(워크플로 세션의 경우 `null`). `source`는 항상 `session`입니다.
* `match_type` — `ip_address` 또는 `device_fingerprint`
* `match_source` — `ip_address`, `persistent_id`, `legacy_fp` 또는 `recovered_high`
* `matched_value` — 공유된 IP, 기기 식별자 또는(복구된 일치 항목의 경우) 복구된 기기 UUID
* `confidence`(0–1, `1 - P(false positive)`) 및 `match_mode`(`deterministic` / `probabilistic` / `co_occurrence`)
* `device_info` — `device_brand`, `device_model`, `browser_family`, `os_family`, `platform`, `device_fingerprint`
* `location_info` — `ip_address`, `ip_country`, `ip_country_code`, `ip_state`, `ip_city`, `is_vpn_or_tor`, `is_data_center`
* `match_source`가 `recovered_high`일 때의 복구된 기기 추가 정보: `recovery_similarity`, `tls_ja4_corroborated`, `recovery_gate_reason`

IP 일치 및 기기 일치는 각각 최대 5개로 제한됩니다(최대 10개 항목). 전체 일치 스키마 및 신뢰도 모델에 대한 자세한 내용은 [보고서 페이지](https://docs.didit.me/ko/core-technology/ip-analysis/report-ip-analysis.md#일치-의미)를 참조하세요.

## 예시

### VPN + 국가 불일치(검토로 설정됨)

```json theme={null}
{
  "warnings": [
    {
      "feature": "LOCATION",
      "risk": "PRIVATE_NETWORK_DETECTED",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "Private network (VPN/Tor) detected",
      "long_description": "The system detected that the user tried to use a private network (VPN/TOR) to complete the verification process.",
      "node_id": "ip-1"
    },
    {
      "feature": "LOCATION",
      "risk": "COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP",
      "additional_data": { "document_country_code": "ESP", "ip_country_code": "NLD" },
      "log_type": "warning",
      "short_description": "Document country does not match IP country",
      "long_description": "The country from the document does not match the country from the IP address, suggesting a potential mismatch between the document and the user's location.",
      "node_id": "ip-1"
    }
  ]
}
```

### 차단 목록 일치(강제 거부)

```json theme={null}
{
  "warnings": [
    {
      "feature": "LOCATION",
      "risk": "IP_ADDRESS_IN_BLOCKLIST",
      "additional_data": { "ip_address": "45.61.20.5" },
      "log_type": "error",
      "short_description": "IP address in blocklist",
      "long_description": "The IP address used for this session was found in the application's IP blocklist, indicating a known suspicious or forbidden origin.",
      "node_id": "ip-1"
    }
  ]
}
```

### 복구된 기기 높은 신뢰도(검토로 설정됨)

```json theme={null}
{
  "warnings": [
    {
      "feature": "LOCATION",
      "risk": "DEVICE_RECOVERED_HIGH_CONFIDENCE",
      "additional_data": {
        "duplicated_session_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "duplicated_session_number": 5101,
        "api_service": null,
        "match_source": "recovered_high",
        "recovery_similarity": 0.9874,
        "recovery_match_device_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      },
      "log_type": "warning",
      "short_description": "Device matches a previously seen device with high confidence",
      "long_description": "A previously seen device matched this session with high confidence through v2 fuzzy fingerprint recovery after passing strict hard gates, indicating the same physical device under a fresh persistent_id.",
      "node_id": "ip-1"
    }
  ]
}
```

## 관련 항목

* [기기 및 IP 분석 보고서](https://docs.didit.me/ko/core-technology/ip-analysis/report-ip-analysis.md) — 전체 응답 형태 및 상태 시맨틱
* [기기 및 IP 분석 개요](https://docs.didit.me/ko/core-technology/ip-analysis/overview.md) — 각 블록의 측정 대상
* [데이터 모델 — IP 분석](https://docs.didit.me/ko/reference/data-models.md#ip-분석) — 표준 스키마
* [webhook](https://docs.didit.me/ko/integration/webhooks.md) — IP 분석 경고를 전달하는 `status.updated`

### 경고 유형


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