기기 및 IP 분석 보고서: 필드 및 일치 항목

개요

기기 및 IP 분석은 IP 지리적 위치, 기기 핑거프린트, 브라우저/OS, 네트워크 유형별로 모든 세션을 프로파일링합니다. 사용자가 인증을 완료하는 동안 지리적 위치 파악, 네트워크 위험 정보 보강, 기기 매칭 및 원격 기기 무결성 검사가 비동기적으로 실행됩니다. 분석이 보류 중인 동안에도 기기 및 IP 관측 데이터는 계속 사용할 수 있습니다. 결과가 도착하기 전이거나 주소가 공용 주소가 아닌 경우 지리적 위치 필드는 비어 있을 수 있습니다. 워크플로에서 이러한 검사를 사용하여 결과를 결정하거나 후속 단계를 선택하는 경우, 필요한 결과를 사용할 수 있을 때까지 세션은 In Progress 상태로 유지됩니다. 제한된 재시도 후에도 필요한 분석 결과를 여전히 사용할 수 없는 경우, 세션은 수동 결정을 위해 In Review로 이동합니다. 선택적 정보 보강 실패가 완료를 방해하지는 않으며, 수동 결정이 최종적인 효력을 갖습니다. 다음과 같은 항목이 생성됩니다:

공용 IP에서 파생된 IP 지리적 위치 블록(국가, 주/도, 도시, 위도/경도, 시간대).
마스킹 시도(VPN, Tor 출구 노드, 호스팅 제공업체, 익명화 도구)를 감지하는 네트워크 위험 플래그(is_vpn_or_tor 및 is_data_center).
IP 위치, 신분증 문서 위치, 주소 증명 문서 위치 간의 직선 거리(km)를 나타내는 문서 간 거리 계산.
서로 다른 사용자(vendor_data 기준 그룹화)에게 속한 세션 전반에서 동일한 IP 주소 또는 기기 식별 정보가 나타날 때의 세션 간 일치 항목.
사용자가 저장소를 지우거나 시크릿 모드로 전환하거나 앱을 재설치한 후에도 세션을 연결하는 높은 신뢰도의 복구 신호인 기기 핑거프린트 복구.

지리적 위치, 기기 핑거프린트 및 위험 플래그가 포함된 Didit 기기 및 IP 분석 보고서 스크린샷

API 응답에서의 표시 위치

결정 endpoint는 GET /v3/session/{sessionId}/decision/에서 기기 및 IP 분석을 복수형 배열인 ip_analyses[]로 반환합니다. 항목은 (node_id, ip_address, device_fingerprint)를 키로 하여 중복 제거된 Location 관측값입니다. 세션 중간에 사용자의 IP 또는 기기가 변경되면 단일 노드에서 여러 항목이 생성될 수 있습니다.

GET /v3/session/{sessionId}/decision/
  ──▶ { "ip_analyses": [ { status, node_id, ip_address, ip, id_document, poa_document, warnings, matches, … }, … ] }

아래 형태는 표준 스키마를 반영합니다. 데이터 모델을 참조하세요.

스키마

표준 스키마는 데이터 모델 참조의 기기 및 IP 분석을 참조하세요.

interface IPAnalysisV3 {
  status: 'Not Finished' | 'Approved' | 'Declined' | 'In Review' | 'Resub Requested';
  node_id: string | null;

  // Device
  device_brand: string | null;
  device_model: string | null;
  browser_family: string | null;
  os_family: string | null;
  platform: 'mobile' | 'tablet' | 'desktop' | null;
  device_fingerprint: string | null;

  // IP geolocation
  ip_country: string | null;
  ip_country_code: string | null;           // ISO 3166-1 alpha-2
  ip_state: string | null;
  ip_city: string | null;
  latitude: number | null;
  longitude: number | null;
  ip_address: string;
  isp: string | null;
  organization: string | null;
  is_vpn_or_tor: boolean;
  is_data_center: boolean;
  time_zone: string | null;
  time_zone_offset: string | null;

  // Distance blocks — each carries its own location + distances to the other two
  ip: {
    location: { latitude: number; longitude: number } | null;
    distance_from_id_document: number | null;   // km
    distance_from_poa_document: number | null;  // km
  };
  id_document: {
    location: { latitude: number; longitude: number } | null;
    distance_from_ip: number | null;
    distance_from_poa_document: number | null;
  };
  poa_document: {
    location: { latitude: number; longitude: number } | null;
    distance_from_ip: number | null;
    distance_from_id_document: number | null;
  };

  warnings: Warning[];          // see Data Models — Warning object

  // Cross-session matches — up to 5 IP matches + 5 device matches
  matches: IPAnalysisMatch[];
}

interface IPAnalysisMatch {
  session_id: string;                       // matching session UUID
  session_number: number;
  vendor_data: string | null;
  verification_date: string | null;         // "YYYY-MM-DDTHH:MM:SSZ"
  match_type: 'ip_address' | 'device_fingerprint';
  match_source: 'ip_address' | 'persistent_id' | 'legacy_fp' | 'recovered_high';
  matched_value: string | null;             // shared IP, device identifier, or recovered device UUID
  status: string;                           // lifecycle status of the matching session
  is_blocklisted: boolean;                  // currently always false
  api_service: string | null;               // standalone API service; null for workflow sessions
  source: 'session';
  device_info: {
    device_brand: string | null;
    device_model: string | null;
    browser_family: string | null;
    os_family: string | null;
    platform: string | null;
    device_fingerprint: string | null;
  };
  location_info: {
    ip_address: string | null;
    ip_country: string | null;
    ip_country_code: string | null;
    ip_state: string | null;
    ip_city: string | null;
    is_vpn_or_tor: boolean;
    is_data_center: boolean;
  };
  confidence: number;                       // 0–1, = 1 - P(false positive)
  match_mode: 'deterministic' | 'probabilistic' | 'co_occurrence';

  // Present only when match_source = 'recovered_high'
  recovery_similarity?: number;             // cosine similarity, 4 decimals
  tls_ja4_corroborated?: boolean;           // TLS JA4 fingerprints of both observations agree
  recovery_gate_reason?: string;            // e.g. 'hardware_root_match'
}

일치 의미

match_source는 일치에 도달한 방식을 알려주며, confidence는 해당 결과가 오탐일 가능성을 점수화합니다(confidence = 1 - P(false positive)):

`match_source`	의미	`confidence`	`match_mode`
`ip_address`	공유 IP — 네트워크상 동일 위치 공유이며 기기 식별 정보 주장이 아님.	`0.0`	`co_occurrence`
`persistent_id`	저장된 정확한 영구 기기 식별자.	`1.0`	`deterministic`
`legacy_fp`	레거시 `didit-fp-*` 기기 핑거프린트 해시.	`0.5`	`probabilistic`
`recovered_high`	엄격한 하드 게이트 이후의 높은 신뢰도 퍼지 핑거프린트 복구 결과.	하드웨어 기반인 경우 `1.0`, 그렇지 않은 경우 `< 1.0`, TLS JA4 및 IP 국가가 독립적으로 일치할 때 가산됨	`deterministic` 또는 `probabilistic`

신뢰도가 낮은 복구 후보는 위험 경고로만 표시되며, matches[]에는 절대 포함되지 않습니다. IP 일치 및 기기 일치는 각각 최대 5개로 제한되므로 배열에는 최대 10개의 항목이 포함됩니다.

상태 값

상태는 기능 수준의 FeatureStatusChoices 값입니다. 발생한 각 경고는 워크플로 노드에 설정된 해당 작업에 매핑되며, 가장 강력한 작업이 우선 적용됩니다.

값	의미
`Not Finished`	이 세션에 대해 IP 분석 노드가 아직 완료되지 않음(기본값).
`Approved`	경고가 발생하지 않았거나, 발생한 모든 경고가 작업 없음으로 구성됨.
`In Review`	발생한 경고 중 하나 이상이 검토로 구성됨(경고 참조).
`Declined`	차단 목록 경고가 발생했거나(`IP_ADDRESS_IN_BLOCKLIST` 또는 `DEVICE_FINGERPRINT_IN_BLOCKLIST` — 항상 거부됨), 설정 가능한 경고가 워크플로에서 거부로 설정됨.
`Resub Requested`	검토자가 이 단계의 재제출을 요청함.

IP 분석 노드에 구성된 맞춤 상태 규칙에 따라 결과 상태가 추가로 조정될 수 있습니다.

VPN, 프록시 및 Tor 감지

is_vpn_or_tor 및 is_data_center는 모든 세션에 대해 반환되는 독립적인 불리언 플래그입니다. is_vpn_or_tor가 true인 경우 Didit은 PRIVATE_NETWORK_DETECTED 경고도 함께 생성하므로 팀에서 워크플로 구성을 통해 이에 조치를 취할 수 있습니다. 데이터 센터 전용 트래픽(VPN/Tor 제외)은 is_data_center=true로 설정되지만 자동으로 경고를 발생시키지는 않으므로 자체 점수 산정에서 추가 신호로 활용할 수 있습니다.

예시

승인됨

{
  "ip_analyses": [
    {
      "status": "Approved",
      "node_id": "ip-1",
      "device_brand": "Apple",
      "device_model": "iPhone",
      "browser_family": "Mobile Safari",
      "os_family": "iOS",
      "platform": "mobile",
      "device_fingerprint": "didit-fp-8d2c7a91f4b3e042",
      "ip_country": "Spain",
      "ip_country_code": "ES",
      "ip_state": "Barcelona",
      "ip_city": "Barcelona",
      "latitude": 41.4022,
      "longitude": 2.1407,
      "ip_address": "83.50.226.71",
      "isp": "Telefonica",
      "organization": "Telefonica de Espana",
      "is_vpn_or_tor": false,
      "is_data_center": false,
      "time_zone": "Europe/Madrid",
      "time_zone_offset": "+0100",
      "ip": {
        "location": { "latitude": 41.4022, "longitude": 2.1407 },
        "distance_from_id_document": 23.4,
        "distance_from_poa_document": 12.3
      },
      "id_document": {
        "location": { "latitude": 41.2706, "longitude": 1.9770 },
        "distance_from_ip": 23.4,
        "distance_from_poa_document": 18.7
      },
      "poa_document": {
        "location": { "latitude": 41.3128, "longitude": 2.0540 },
        "distance_from_ip": 12.3,
        "distance_from_id_document": 18.7
      },
      "warnings": [],
      "matches": []
    }
  ]
}

거부됨 — IP 차단 목록 일치 + VPN + 중복 기기

{
  "ip_analyses": [
    {
      "status": "Declined",
      "node_id": "ip-1",
      "device_brand": null,
      "device_model": null,
      "browser_family": "Chrome",
      "os_family": "Linux",
      "platform": "desktop",
      "device_fingerprint": "didit-fp-a13c0d22e8b94471",
      "ip_country": "Netherlands",
      "ip_country_code": "NL",
      "ip_state": "North Holland",
      "ip_city": "Amsterdam",
      "latitude": 52.3676,
      "longitude": 4.9041,
      "ip_address": "45.61.20.5",
      "isp": "Example Hosting",
      "organization": "Example Hosting BV",
      "is_vpn_or_tor": true,
      "is_data_center": true,
      "time_zone": "Europe/Amsterdam",
      "time_zone_offset": "+0100",
      "ip": {
        "location": { "latitude": 52.3676, "longitude": 4.9041 },
        "distance_from_id_document": 1834.2,
        "distance_from_poa_document": 1822.5
      },
      "id_document": {
        "location": { "latitude": 40.4168, "longitude": -3.7038 },
        "distance_from_ip": 1834.2,
        "distance_from_poa_document": 14.0
      },
      "poa_document": {
        "location": { "latitude": 40.5070, "longitude": -3.6720 },
        "distance_from_ip": 1822.5,
        "distance_from_id_document": 14.0
      },
      "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"
        },
        {
          "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"
        },
        {
          "feature": "LOCATION",
          "risk": "DUPLICATED_DEVICE_FINGERPRINT",
          "additional_data": {
            "duplicated_session_id": "11111111-2222-3333-4444-555555555555",
            "duplicated_session_number": 1042,
            "api_service": null,
            "match_source": "persistent_id"
          },
          "log_type": "warning",
          "short_description": "Duplicated device fingerprint from another session",
          "long_description": "The same device fingerprint was detected in another session with a different vendor_data, which may indicate multiple identities verified from the same device.",
          "node_id": "ip-1"
        }
      ],
      "matches": [
        {
          "session_id": "11111111-2222-3333-4444-555555555555",
          "session_number": 1042,
          "vendor_data": "user-other",
          "verification_date": "2026-05-28T14:03:21Z",
          "match_type": "device_fingerprint",
          "match_source": "persistent_id",
          "matched_value": "pid_9f1c2b7a8d3e4f50",
          "status": "Declined",
          "is_blocklisted": false,
          "api_service": null,
          "source": "session",
          "device_info": {
            "device_brand": null,
            "device_model": null,
            "browser_family": "Chrome",
            "os_family": "Linux",
            "platform": "desktop",
            "device_fingerprint": "didit-fp-a13c0d22e8b94471"
          },
          "location_info": {
            "ip_address": "45.61.23.99",
            "ip_country": "Netherlands",
            "ip_country_code": "NL",
            "ip_state": "North Holland",
            "ip_city": "Amsterdam",
            "is_vpn_or_tor": true,
            "is_data_center": true
          },
          "confidence": 1.0,
          "match_mode": "deterministic"
        }
      ]
    }
  ]
}

인증

인증

모니터링

플랫폼

기기 및 IP 분석 보고서: 필드 및 일치 항목

개요

API 응답에서의 표시 위치

스키마

일치 의미

상태 값

VPN, 프록시 및 Tor 감지

예시

승인됨

거부됨 — IP 차단 목록 일치 + VPN + 중복 기기

관련 문서

​개요

​API 응답에서의 표시 위치

​스키마

​일치 의미

​상태 값

​VPN, 프록시 및 Tor 감지

​예시

​승인됨

​거부됨 — IP 차단 목록 일치 + VPN + 중복 기기

​관련 문서

개요

API 응답에서의 표시 위치

스키마

일치 의미

상태 값

VPN, 프록시 및 Tor 감지

예시

승인됨

거부됨 — IP 차단 목록 일치 + VPN + 중복 기기

관련 문서