> ## 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.

# Codici di avviso per fingerprinting e rischio IP

> Tutti i codici di avviso dell'analisi dispositivo e IP di Didit: VPN/Tor, discrepanza paese, blocklist, IP duplicati e dispositivi recuperati.

## Panoramica

L'Analisi dispositivo e IP genera tag di avviso su `ip_analyses[].warnings[]` ogni volta che rileva comportamenti sospetti relativi a dispositivo, rete o posizione. Nove tag prevedono un'azione configurabile (Rifiuta / Revisione / Nessuna azione) per nodo del workflow; i due tag di blocklist forzano sempre `Declined`, mentre i due tag di allowlist sono sempre informativi. Il `log_type` di ciascun avviso rispecchia l'azione applicata: `error` (Rifiuta), `warning` (Revisione) o `information` (Nessuna azione). Ciascun rischio si attiva al massimo una volta per sessione.

Ogni rischio indicato di seguito viene verificato rispetto alla pipeline decisionale attiva; gli avvisi presentano il tag di funzionalità `LOCATION` e la struttura standard dell'[oggetto avviso](https://docs.didit.me/it/reference/data-models.md#oggetto-avviso).

Gli avvisi relativi al fingerprint del dispositivo sono intenzionalmente suddivisi in segnali esatti e recuperati:

* `DUPLICATED_DEVICE_FINGERPRINT` indica che la stessa identità deterministica del dispositivo (`match_source` `persistent_id` o `legacy_fp`) è stata riutilizzata tra sessioni con valori diversi di `vendor_data`.
* `DEVICE_RECOVERED_HIGH_CONFIDENCE` indica che il recupero del fingerprint v2 ha associato la sessione a un dispositivo rilevato in precedenza **dopo** la modifica dell'ID persistente (svuotamento della memoria, modalità di navigazione in incognito, reinstallazione dell'app). L'avviso compare solo quando la corrispondenza supera la soglia di somiglianza ad alta affidabilità e i controlli rigidi.

![Esempio di avviso di Analisi dispositivo e IP di Didit con alert relativi a dispositivo, VPN, proxy e discrepanza di posizione](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)

## Avvisi generati

| Rischio | Causa | `log_type` | Influisce sullo stato | Risoluzione consigliata |
| - | - | - | - | - |
| `PRIVATE_NETWORK_DETECTED` | `is_vpn_or_tor` era `true`: la sessione è stata aperta tramite VPN, proxy o nodo di uscita Tor. `additional_data` è `null`. | rispecchia l'azione configurata | Configurabile: Decline / Review / No action (valore predefinito: No action). | Decidi se la tua tolleranza al rischio consente il traffico mascherato. Se lo accetti, lascia l'impostazione su No action. |
| `COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP` | Il paese ISO del documento di identità differisce dal paese ricavato dall'indirizzo IP. `additional_data` contiene entrambi i codici ISO-3: `document_country_code`, `ip_country_code`. | rispecchia l'azione configurata | Configurabile: Decline / Review / No action (valore predefinito: No action). | Sottoponi a revisione quando l'utente è legittimamente in viaggio. Rifiuta se associato a segnali di VPN o dispositivo duplicato. |
| `EXPECTED_IP_ADDRESS_MISMATCH` | La sessione è stata creata con un indirizzo IP previsto e l'IP in tempo reale differisce. `additional_data` contiene `expected_ip_address` ed `actual_ip_address`. | rispecchia l'azione configurata | Configurabile: Decline / Review / No action (valore predefinito: No action). | Utilizzalo se associ preventivamente l'IP alla creazione della sessione. Rifiuta la sessione o richiedi un'autenticazione rafforzata in caso di mancata corrispondenza. |
| `IP_ADDRESS_IN_BLOCKLIST` | L'indirizzo IP della sessione corrisponde a una voce presente nella blocklist degli IP dell'applicazione. `additional_data`: `ip_address`. | sempre `error` | Forza `Declined`. | Rifiuta la sessione. Se necessario, verifica la fonte della blocklist per escludere falsi positivi. |
| `DEVICE_FINGERPRINT_IN_BLOCKLIST` | Il fingerprint del dispositivo della sessione corrisponde a una voce presente nella blocklist dei dispositivi. `additional_data`: `device_fingerprint`. | sempre `error` | Forza `Declined`. | Rifiuta la sessione. |
| `IP_ADDRESS_IN_ALLOWLIST` | L'IP della sessione presentava corrispondenze duplicate ma si trova nell'allowlist degli IP dell'applicazione, quindi l'avviso di IP duplicato è stato ignorato. `additional_data`: `ip_address`. | sempre `information` | Nessuno. | Utilizzalo per NAT aziendali affidabili, reti di QA o punti di accesso condivisi noti. |
| `DEVICE_FINGERPRINT_IN_ALLOWLIST` | Il fingerprint del dispositivo della sessione presentava corrispondenze duplicate deterministiche ma si trova nell'allowlist dei dispositivi, quindi l'avviso di dispositivo duplicato è stato ignorato. `additional_data`: `device_fingerprint`. | sempre `information` | Nessuno. | Utilizzalo solo per dispositivi condivisi affidabili. Le blocklist hanno comunque la priorità. |
| `DUPLICATED_IP_ADDRESS` | Lo stesso IP è stato utilizzato in un'altra sessione con un `vendor_data` diverso. `additional_data`: `duplicated_session_id`, `duplicated_session_number`, `api_service`. Viene ignorato se l'IP è presente nell'allowlist. | rispecchia l'azione configurata | Configurabile: Decline / Review / No action (valore predefinito: No action). | Frequente su NAT aziendali o condivisi. Combinalo con altri segnali (dispositivo duplicato, mancata corrispondenza del paese) prima di rifiutare. |
| `DUPLICATED_DEVICE_FINGERPRINT` | La stessa identità deterministica del dispositivo è stata riutilizzata in più sessioni con `vendor_data` diversi. `additional_data`: `duplicated_session_id`, `duplicated_session_number`, `api_service`, `match_source` (`persistent_id` o `legacy_fp`). Viene ignorato se il fingerprint è presente nell'allowlist. | rispecchia l'azione configurata | Configurabile: Decline / Review / No action (valore predefinito: No action). | Forte indicatore di abuso multi-account. Sottoponi a revisione o rifiuta a seconda della tolleranza alle frodi. |
| `DEVICE_RECOVERED_HIGH_CONFIDENCE` | Il modello di recupero del dispositivo v2 ha associato con elevata affidabilità la sessione a un dispositivo già rilevato in precedenza, anche dopo la modifica dell'ID persistente. `additional_data`: `duplicated_session_id`, `duplicated_session_number`, `api_service`, `match_source` (`recovered_high`), `recovery_similarity`, `recovery_match_device_uuid`. Non viene soppresso dall'allowlist dei dispositivi. | rispecchia l'azione configurata | Configurabile: Decline / Review / No action (valore predefinito: No action). | Inizia con Review, misura il tasso di falsi positivi e poi inasprisci l'azione. Forte indicatore di tentativi di ripristino dello storage o navigazione in incognito. |
| `DEVICE_LINKED_TO_LIVENESS_ATTACK` | Lo stesso dispositivo (abbinato in base al suo ID dispositivo persistente) è stato utilizzato in una precedente sessione di un altro utente la cui acquisizione per il rilevamento della vitalità è stata giudicata un attacco. Un dispositivo già utilizzato per attaccare il rilevamento della vitalità è un forte indicatore del fatto che questa acquisizione provenga dallo stesso aggressore. `additional_data`: `liveness_attack_session_id`, `liveness_attack_session_number`, `liveness_attack_sessions_count`, `match_source` (`persistent_id`). | rispecchia l'azione configurata | Configurabile: Decline / Review / No action (valore predefinito: No action). | Inizia con Review e misura il tasso di falsi positivi prima di passare a Decline. |
| `DEVICE_MODEL_INCONSISTENT` | Lo stesso dispositivo (abbinato in base al suo ID dispositivo persistente) è stato segnalato come un modello di dispositivo diverso in una sessione precedente. Un singolo dispositivo fisico non cambia modello, quindi il modello segnalato è probabilmente contraffatto oppure l'identificatore del dispositivo è stato copiato su un altro dispositivo. Le stringhe generiche del modello non vengono mai confrontate. `additional_data`: `device_model`, `earlier_device_model`, `earlier_session_id`, `earlier_session_number`, `match_source`. | rispecchia l'azione configurata | Configurabile: Decline / Review / No action (valore predefinito: No action). | Confronta i due modelli segnalati ed esamina la sessione precedente prima di intervenire. |
| `IP_LOCATION_NOT_ALLOWED` | Il geofencing IP è abilitato e l'IP della sessione si trova in un paese o stato/regione contrassegnato come non consentito. `additional_data`: `ip_country_code` (ISO-3), `ip_country`, `ip_state`, `restricted_by` (`country` o `state`). | rispecchia l'azione configurata | Configurabile: Decline / Review / No action (valore predefinito: Decline). | Utilizzalo per applicare le restrizioni giurisdizionali. Combinalo con `vpn_detection_action` in modo che il traffico mascherato non possa aggirare il geofence. |

Quando il dispositivo recuperato non ha ancora sessioni correlate idonee (quindi nessun elemento viene inserito in `matches[]`), `DEVICE_RECOVERED_HIGH_CONFIDENCE` viene comunque attivato con una struttura di `additional_data` di fallback: `recovery_match_device_uuid`, `recovery_match_similarity`, `recovery_match_band`, `recovery_gate_reason`.

`IP_LOCATION_NOT_ALLOWED` viene attivato quando il geofencing IP è abilitato (`is_ip_geofencing_enabled`) e l'IP della sessione si trova in un paese o in uno stato/regione contrassegnato come non consentito in `ip_geofencing_by_country`. `additional_data` include `ip_country_code` (ISO-3), `ip_country`, `ip_state` e `restricted_by` (`country` o `state`). Le voci relative a stato/regione prevalgono sul flag del paese e vengono verificate senza distinzione tra maiuscole e minuscole rispetto al nome della regione del provider IP (ad es. `"California"`); i paesi non elencati nella configurazione sono consentiti.

## Integrità del dispositivo e del runtime

Segnali segnalati dagli SDK nativi e dal client web che descrivono lo stato del dispositivo su cui è stata eseguita la verifica. Servono a rilevare attacchi di iniezione: un utente malintenzionato in grado di eseguire il root di un dispositivo o di fare l'hooking del processo dell'app può sostituire il flusso della fotocamera prima ancora che raggiunga i controlli biometrici.

Ciascuno di essi è configurabile per workflow e ha come impostazione predefinita **nessuna azione**, pertanto l'abilitazione della funzionalità non modifica alcuna decisione finché non si effettua l'attivazione.

| Rischio | Causa | Chiave di configurazione | Predefinito |
| - | - | - | - |
| `DEVICE_APP_TAMPERED` | L'attestazione della piattaforma non è riuscita a verificare che la richiesta provenisse da una build autentica e non modificata dell'applicazione su un dispositivo autentico. | `device_app_tampered_action` | `NO_ACTION` |
| `DEVICE_RUNTIME_HOOKING_DETECTED` | È stato rilevato un framework di strumentazione o hooking a runtime (Frida, Xposed, LSPosed, Substrate) nel processo dell'applicazione. | `device_hooking_action` | `NO_ACTION` |
| `DEVICE_ROOTED_OR_JAILBROKEN` | Il dispositivo mostra indicatori di root o jailbreak, che rimuovono le protezioni del sistema operativo che impediscono l'intercettazione della fotocamera. | `device_rooted_action` | `NO_ACTION` |
| `DEVICE_EMULATOR_DETECTED` | La sessione ha avuto origine da un emulatore o simulatore anziché da un dispositivo fisico. | `device_emulator_action` | `NO_ACTION` |
| `DEVICE_DEBUGGER_ATTACHED` | Un debugger o tracciatore di processi era collegato all'applicazione durante la verifica. | `device_debugger_action` | `NO_ACTION` |
| `AUTOMATION_FRAMEWORK_DETECTED` | La sessione è stata guidata da un framework di automazione del browser o da un browser headless anziché da una persona. | `automation_detected_action` | `NO_ACTION` |
| `DEVICE_INTEGRITY_SIGNALS_MISSING` | Il client ha segnalato una versione dell'SDK che supporta la segnalazione dell'integrità, ma non è arrivato alcun segnale di integrità: questo può indicare che i segnali sono stati rimossi durante il transito. | `device_integrity_missing_action` | `NO_ACTION` |

> [!NOTE]
>
> Ogni verifica viene eseguita per quanto possibile. Quando un controllo non può essere eseguito, restituisce **non determinato** anziché un risultato pulito, in modo che una verifica non riuscita non generi mai un falso positivo per un utente legittimo. I segnali vengono inviati a partire dalla versione **4.4.0** dell'SDK nativo; le sessioni provenienti da versioni precedenti dell'SDK legittimamente non inviano nulla e non attivano mai `DEVICE_INTEGRITY_SIGNALS_MISSING`.

> [!WARNING]
>
> I segnali di root ed emulatore sono frequenti tra gli utenti legittimi su dispositivi modificati ma non fraudolenti. Imposta inizialmente queste azioni su Revisione anziché Rifiuto e osserva il tuo tasso di rifiuto prima di renderle più restrittive.

## Impostazioni configurabili

Controlli del workflow per nodo (configurabili anche a livello globale nelle impostazioni di verifica dell'applicazione; ogni azione è impostata per impostazione predefinita su **Nessuna azione**, se non diversamente specificato):

| Impostazione | Determina | Predefinito |
| - | - | - |
| `vpn_detection_action` | `PRIVATE_NETWORK_DETECTED` | Nessuna azione |
| `ip_mismatch_action` | `COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP` | Nessuna azione |
| `expected_ip_mismatch_action` | `EXPECTED_IP_ADDRESS_MISMATCH` | Nessuna azione |
| `duplicated_ip_action` | `DUPLICATED_IP_ADDRESS` | Nessuna azione |
| `duplicated_device_action` | `DUPLICATED_DEVICE_FINGERPRINT` | Nessuna azione |
| `recovered_device_action` | `DEVICE_RECOVERED_HIGH_CONFIDENCE` | Nessuna azione |
| `device_liveness_attack_history_action` | `DEVICE_LINKED_TO_LIVENESS_ATTACK` | Nessuna azione |
| `device_model_inconsistency_action` | `DEVICE_MODEL_INCONSISTENT` | Nessuna azione |
| `ip_geofencing_action` | `IP_LOCATION_NOT_ALLOWED` | Rifiuto |

Le allowlist di IP e dispositivi sopprimono solo l'avviso di IP duplicato esatto o di dispositivo duplicato deterministico per il valore inserito nell'allowlist. Non eliminano gli avvisi relativi a VPN/proxy, mancata corrispondenza del paese, mancata corrispondenza dell'IP previsto, dispositivo recuperato o blocklist.

Gli avvisi di dispositivo recuperato sono utili per rilevare reti di frode che alternano account e sessioni dallo stesso hardware, ma Didit adotta un approccio prudente per progettazione: il sistema preferisce non rilevare alcuni utenti duplicati piuttosto che unire dispositivi non correlati quando le prove non sono sufficientemente solide. **Implementazione consigliata**: inizia con Revisione, monitora il volume per due settimane e poi rendi l'azione più restrittiva se il tasso di falsi positivi è basso.

## Dispositivo duplicato vs dispositivo recuperato

Tratta i due avvisi in modo diverso: si attivano in base a evidenze differenti:

| Avviso | Trigger | Significato tipico | Prima azione consigliata |
| - | - | - | - |
| `DUPLICATED_DEVICE_FINGERPRINT` | Corrispondenza esatta dell'identità persistente del dispositivo (`persistent_id`) o dell'hash dell'impronta legacy (`legacy_fp`). | Forte evidenza che lo stesso dispositivo compare tra utenti diversi. | Revisione o Rifiuto, a seconda della tua tolleranza alle frodi. |
| `DEVICE_RECOVERED_HIGH_CONFIDENCE` | Recupero v2 ad alta affidabilità (`recovered_high`) dopo la modifica dello storage, della sessione o dell'identità dell'app. | Forte segnale di tentativi di navigazione in incognito, reset dello storage o reinstallazione dell'app. Separato intenzionalmente in modo da poterlo monitorare in modo indipendente. | Inizia con Revisione, poi rendi l'azione più restrittiva dopo aver misurato il tasso di falsi positivi. |

## Corrispondenze tra sessioni

Quando lo stesso indirizzo IP, l'identità esatta del dispositivo o un dispositivo recuperato viene rilevato tra sessioni appartenenti a **utenti diversi**, Didit li registra come `matches[]` su `ip_analyses[]`. Le sessioni sono raggruppate per `vendor_data`: le sessioni con lo stesso `vendor_data` sono considerate come lo stesso utente ed escluse dalle corrispondenze. Senza `vendor_data`, ogni sessione viene trattata come un utente univoco e vengono mostrati tutti i potenziali duplicati — raccomandiamo vivamente di fornire sempre `vendor_data` per ridurre il rumore.

Ciascuna corrispondenza include:

* `session_id`, `session_number`, `vendor_data` e `verification_date` della sessione corrispondente, oltre al relativo `status` del ciclo di vita e `api_service` (`null` per le sessioni di workflow); `source` è sempre `session`
* `match_type` — `ip_address` o `device_fingerprint`
* `match_source` — `ip_address`, `persistent_id`, `legacy_fp` o `recovered_high`
* `matched_value` — l'IP condiviso, l'identificatore del dispositivo o (per le corrispondenze recuperate) l'UUID del dispositivo recuperato
* `confidence` (0–1, `1 - P(false positive)`) e `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`
* Dati aggiuntivi del dispositivo recuperato quando `match_source` è `recovered_high`: `recovery_similarity`, `tls_ja4_corroborated`, `recovery_gate_reason`

Le corrispondenze IP e le corrispondenze di dispositivo sono limitate a 5 ciascuna (al massimo 10 voci). Consulta la [pagina del report](https://docs.didit.me/it/core-technology/ip-analysis/report-ip-analysis.md#semantica-delle-corrispondenze) per lo schema completo delle corrispondenze e il modello di affidabilità.

## Esempi

### VPN + mancata corrispondenza del paese (configurato su In revisione)

```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"
    }
  ]
}
```

### Riscontro in blocklist (forza il rifiuto)

```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"
    }
  ]
}
```

### Dispositivo recuperato ad alta affidabilità (configurato su In revisione)

```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"
    }
  ]
}
```

## Correlati

* [Report di analisi dispositivo e IP](https://docs.didit.me/it/core-technology/ip-analysis/report-ip-analysis.md) — struttura completa della risposta e semantica dello stato
* [Panoramica sull'analisi dispositivo e IP](https://docs.didit.me/it/core-technology/ip-analysis/overview.md) — cosa misura ciascun blocco
* [Modelli di dati — Analisi IP](https://docs.didit.me/it/reference/data-models.md#analisi-ip) — schema canonico
* [Webhook](https://docs.didit.me/it/integration/webhooks.md) — `status.updated` trasmette gli avvisi di analisi IP

### Tipi di avviso


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