> ## 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 个标签支持在每个工作流节点配置操作（Decline / Review / No action）；两个黑名单标签始终强制判定为 `Declined`，而两个白名单标签始终为信息提示。每个警告的 `log_type` 均对应所应用的操作：`error`（Decline）、`warning`（Review）或 `information`（No action）。每种风险在每次会话中最多触发一次。

以下列出的每种风险均经过生产决策流水线的核验；警告带有功能标签 `LOCATION` 以及标准[警告对象](https://docs.didit.me/zh/reference/data-models.md#警告对象)结构。

设备指纹警告特意细分为精确匹配与恢复匹配两类信号：

* `DUPLICATED_DEVICE_FINGERPRINT` 表示在具有不同 `vendor_data` 值的多个会话之间，复用了相同的确定性设备身份（`match_source` 为 `persistent_id` 或 `legacy_fp`）。
* `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`。 | 与配置的操作一致 | 可配置：Decline / Review / No action（默认：No action）。 | 评估您的风险承受能力是否允许经伪装的流量。如果接受，请将其设置为 No action。 |
| `COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP` | 身份证件的 ISO 国家/地区与从 IP 地址推导的国家/地区不一致。`additional_data` 包含这两个 ISO-3 代码：`document_country_code`、`ip_country_code`。 | 与配置的操作一致 | 可配置：Decline / Review / No action（默认：No action）。 | 当用户进行正当出行时进行审核。若同时伴有 VPN 或重复设备信号，则予以拒绝。 |
| `EXPECTED_IP_ADDRESS_MISMATCH` | 创建会话时指定了预期 IP 地址，而实际 IP 不符。`additional_data` 包含 `expected_ip_address` 和 `actual_ip_address`。 | 与配置的操作一致 | 可配置：Decline / Review / No action（默认：No action）。 | 适用于在创建会话时预先绑定 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 在白名单中时跳过。 | 与配置的操作一致 | 可配置：Decline / Review / No action（默认：No action）。 | 在企业或共享 NAT 环境下很常见。在拒绝之前，请结合其他信号（重复设备、国家/地区不匹配）综合判断。 |
| `DUPLICATED_DEVICE_FINGERPRINT` | 相同的确定性设备身份在具有不同 `vendor_data` 的多个会话间被重复使用。`additional_data`：`duplicated_session_id`、`duplicated_session_number`、`api_service`、`match_source`（`persistent_id` 或 `legacy_fp`）。当指纹在白名单中时跳过。 | 与配置的操作一致 | 可配置：Decline / Review / No action（默认：No action）。 | 属于多账号滥用的有力证据。根据欺诈容忍度进行审核或拒绝。 |
| `DEVICE_RECOVERED_HIGH_CONFIDENCE` | v2 设备恢复模型以高置信度将该会话与之前出现过的设备进行匹配，即使持久化 ID 已更改也是如此。`additional_data`：`duplicated_session_id`、`duplicated_session_number`、`api_service`、`match_source`（`recovered_high`）、`recovery_similarity`、`recovery_match_device_uuid`。不会因设备白名单而被抑制。 | 与配置的操作一致 | 可配置：Decline / Review / No action（默认：No action）。 | 建议先从 Review 开始，评估误报率，然后再收紧操作。这是针对重置存储或无痕模式尝试的强信号。 |
| `DEVICE_LINKED_TO_LIVENESS_ATTACK` | 相同设备（基于其持久化设备 ID 匹配）曾用于另一位用户的早期会话，且该用户的活体采集被判定为攻击。一台已被用于攻击活体检测的设备，是当前采集来自同一攻击者的有力指标。`additional_data`：`liveness_attack_session_id`、`liveness_attack_session_number`、`liveness_attack_sessions_count`、`match_source`（`persistent_id`）。 | 与配置的操作一致 | 可配置：Decline / Review / No action（默认：No action）。 | 建议先从 Review 开始并评估误报率，然后再收紧为 Decline。 |
| `DEVICE_MODEL_INCONSISTENT` | 相同设备（基于其持久化设备 ID 匹配）在早期会话中报告了不同的设备型号。一台物理设备不会改变型号，因此报告的型号可能是伪造的，或者该设备标识符被复制到了另一台设备上。通用型号字符串绝不会进行比对。`additional_data`：`device_model`、`earlier_device_model`、`earlier_session_id`、`earlier_session_number`、`match_source`。 | 与配置的操作一致 | 可配置：Decline / Review / No action（默认：No action）。 | 在采取行动之前，比对这两个报告的型号并审核先前的会话。 |
| `IP_LOCATION_NOT_ALLOWED` | 已启用 IP 地理围栏，且会话 IP 位于标记为不允许的国家/地区或州/地区。`additional_data`：`ip_country_code`（ISO-3）、`ip_country`、`ip_state`、`restricted_by`（`country` 或 `state`）。 | 与配置的操作一致 | 可配置：Decline / Review / No action（默认：Decline）。 | 用于实施管辖区限制。结合 `vpn_detection_action` 使用，以防经伪装的流量绕过地理围栏。 |

当恢复的设备尚无符合条件的关联会话时（因此没有任何内容进入 `matches[]`），`DEVICE_RECOVERED_HIGH_CONFIDENCE` 仍会触发备用 `additional_data` 结构：`recovery_match_device_uuid`、`recovery_match_similarity`、`recovery_match_band`、`recovery_gate_reason`。

当启用 IP 地理围栏（`is_ip_geofencing_enabled`）且会话 IP 位于 `ip_geofencing_by_country` 中标记为不允许的国家/地区或州/地区时，将触发 `IP_LOCATION_NOT_ALLOWED`。`additional_data` 包含 `ip_country_code`（ISO-3）、`ip_country`、`ip_state` 和 `restricted_by`（`country` 或 `state`）。州/地区条目会覆盖国家/地区标志，并与 IP 提供商的地区名称（例如 `"California"`）进行不区分大小写的匹配；配置中未列出的国家/地区均属于允许范围。

## 设备与运行时完整性

原生 SDK 和 Web 客户端上报的信号描述了运行验证的设备状态。它们用于检测注入攻击：能够获取设备 root 权限或挂钩应用进程的攻击者，可以在视频流进入生物识别检查之前将其替换。

每一项都可以按工作流配置，且默认值为**无操作**，因此在您主动选择启用之前，开启该功能不会改变任何决策。

| 风险 | 原因 | 配置键 | 默认值 |
| - | - | - | - |
| `DEVICE_APP_TAMPERED` | 平台证明未能验证该请求是否来自真实设备上真实且未经修改的应用版本。 | `device_app_tampered_action` | `NO_ACTION` |
| `DEVICE_RUNTIME_HOOKING_DETECTED` | 在应用进程中检测到运行时插桩或 Hook 框架（Frida、Xposed、LSPosed、Substrate）。 | `device_hooking_action` | `NO_ACTION` |
| `DEVICE_ROOTED_OR_JAILBROKEN` | 设备显示 Root 或越狱迹象，这破坏了防止摄像头拦截的操作系统保护机制。 | `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]
>
> Root 和模拟器信号在合法用户使用修改过但非欺诈性的设备时也较为常见。建议先将这些操作设置为“审核”而非“拒绝”，并在收紧策略之前观察自身的拒绝率。

## 可配置设置

每个节点的工作流控制项（也可在应用的验证设置中进行全局配置；除非另有说明，否则每个操作的默认值均为**无操作**）：

| 设置 | 控制的警告 | 默认值 |
| - | - | - |
| `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 在设计上保持审慎：在证据不够充分时，系统宁可漏掉部分重复用户，也不会将无关设备进行归并。**建议上线流程**：先从“审核”开始，观察两周的触发量，如果您的误报率较低，再收紧操作。

## 重复设备与恢复设备

请区别对待这两项警告，它们的触发依据不同：

| 警告 | 触发条件 | 典型含义 | 建议初始操作 |
| - | - | - | - |
| `DUPLICATED_DEVICE_FINGERPRINT` | 完全匹配的持久化设备标识（`persistent_id`）或旧版指纹哈希（`legacy_fp`）。 | 强力证据表明同一设备出现在不同用户之间。 | 根据您的欺诈容忍度，选择“审核”或“拒绝”。 |
| `DEVICE_RECOVERED_HIGH_CONFIDENCE` | 在存储、会话或应用标识发生变更后，进行高置信度 v2 恢复（`recovered_high`）。 | 针对无痕模式 / 存储重置 / 重新安装应用等企图的强信号。特意分开以便您可以独立监控。 | 先设置为“审核”，在评估误报率后再进行收紧。 |

## 跨会话匹配

当在属于**不同用户**的会话之间检测到相同的 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 条）。有关完整的匹配架构（schema）和置信度模型，请参阅[报告页面](https://docs.didit.me/zh/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/zh/core-technology/ip-analysis/report-ip-analysis.md) — 完整响应结构和状态语义
* [设备与 IP 分析概述](https://docs.didit.me/zh/core-technology/ip-analysis/overview.md) — 各模块测量的内容
* [数据模型 — IP 分析](https://docs.didit.me/zh/reference/data-models.md#ip-分析) — 规范数据结构（schema）
* [Webhooks](https://docs.didit.me/zh/integration/webhooks.md) — `status.updated` 携带 IP 分析警告

### 警告类型


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