Evite el fraude en el intercambio de tarjetas SIM en Python con la API Identity Insights

El fraude por intercambio de SIM es una amenaza creciente en la seguridad móvil, en la que los atacantes secuestran el número de teléfono de la víctima transfiriéndolo a una nueva tarjeta SIM. Esto les permite interceptar llamadas, mensajes de texto e incluso códigos de autenticación de dos factores. ¡Qué miedo!

En este tutorial, usaremos la API Vonage Identity Insights en Python para detectar posibles intercambios de SIM y proteger a tus usuarios.

>> TL;DR: Obtenga el código completo en GitHub

Requisitos previos

Para seguirlo, necesitarás:

• Una cuenta de desarrollador de Vonage

• Python 3.8+

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Configuración del proyecto

Crear una aplicación de Vonage

Su script Python utilizará el Sandbox del Registro de Red. Para ello, crea una aplicación de Vonage en el Panel de Vonage con:

1. Capacidad de registro de red activada y seleccione "Playground".

2. Genere un private.keya la raíz de su directorio en la siguiente sección

Cree su proyecto e instale las dependencias

1. Crea tu carpeta de proyecto y archivos en tu terminal.

mkdir sim_swap_checker
cd sim_swap_checker
touch main.py .env

>> Ahora puede mover los archivos descargados private.key al directorio sim_swap_checker directorio

2. Configure un entorno virtual.

Esto asegura que tus dependencias permanezcan aisladas de tu sistema Python.

python3 -m venv venv

source venv/bin/activate

3. Instale los paquetes necesarios.

Utilizaremos requests para realizar peticiones HTTP a la API de Identity Insights, python-dotenv para cargar de forma segura nuestras credenciales API desde un archivo de entorno, y vonage-jwt para generar tokens JWT seguros para autenticar nuestras peticiones.

pip install requests python-dotenv vonage-jwt

Configure su archivo ENV

Agrega el ID de tu aplicación de Vonage y el número de teléfono predeterminado + el período en horas durante el cual la API realizará la verificación de intercambio de SIM.

Puede consultar en la Referencia de la API de Identity Insights que Sim Swap insight depende de un único parámetro llamado periodlo llamaremos hora y estableceremos el valor predeterminado en 240.

VONAGE_APPLICATION_ID=your_application_id
VONAGE_PRIVATE_KEY_PATH=./private.key
PHONE_NUMBER=+990123455
DEFAULT_HOURS=240

Escribe el script Python para comprobar si hay un Sim Swap

Paso 1: Configurar las importaciones y el entorno

En el archivo main.py vamos a construir el script principal que comprueba si se ha producido un intercambio de SIM en un plazo de tiempo definido por el usuario (por defecto 240 horas, o 10 días).

Empieza importando las librerías necesarias y cargando las variables de entorno desde el archivo .env. De este modo nos aseguramos de no codificar valores sensibles y facilitamos la actualización rápida del número de teléfono y el periodo de tiempo para probar diferentes valores.

# main.py
import requests
from dotenv import load_dotenv
import os
from vonage_jwt import JwtClient

load_dotenv()

API_URL = "https://api-eu.vonage.com/v0.1/identity-insights"
PHONE_NUMBER = os.getenv("PHONE_NUMBER")
DEFAULT_HOURS = int(os.getenv("DEFAULT_HOURS"))
application_id = os.getenv("VONAGE_APPLICATION_ID")
private_key_path = os.getenv("VONAGE_PRIVATE_KEY_PATH")

Paso 2: Autenticarse con JWT

Antes de poder realizar cualquier llamada a la API Identity Insights, necesitamos autenticarnos utilizando un token web JSON (JWT). Esto es necesario para todas las API de la red de Vonage.

Un JWT identifica de forma segura su aplicación utilizando su APPLICATION_ID y su clave privada, e incluye metadatos como cuándo se emitió ( iat ) y cuándo expira ( exp ). Estos tokens se firman utilizando el algoritmo RS256 y suelen ser válidos durante unos minutos, lo que los hace seguros y efímeros.

Debajo de tus variables de entorno, inicializa tu JwtClient. Utilizaremos este cliente para generar el JWT real al realizar la solicitud de API.

with open(private_key_path, "r") as f:
    private_key_str = f.read()

jwt_client = JwtClient(application_id, private_key_str)

Paso 3: Definir la función de comprobación de intercambio de SIM de núcleo

A continuación, continuaremos y definiremos una función check_sim_swap() que recibe un número de teléfono y un periodo en horas. Utiliza el cliente JWT para autenticar y envía una solicitud POST a la API Identity Insights.

# main.py

def check_sim_swap(phone_number, hours):

    jwt_token = jwt_client.generate_application_jwt()

    headers = {
        "Authorization": f"Bearer {jwt_token}",
        "Content-Type": "application/json"
    }

    payload = {
        "phone_number": phone_number,
        "purpose": "FraudPreventionAndDetection",
        "insights": {
            "format": {},
            "sim_swap": {
                "period": hours
            }
        }
    }

    print(f"\n🔍 Checking SIM swap status for {phone_number}...")
    res = requests.post(API_URL, headers=headers, json=payload)

    if res.status_code != 200:
        print("❌ Error:", res.status_code, res.text)
        return

    data = res.json()

Este código establece el propósito de "FraudPreventionAndDetection" un requisito para el uso de SIM swap insights. Si la API devuelve algo distinto de un 200 OKimprimimos el error en la consola y salimos.

Paso 4: Analizar y mostrar los resultados del intercambio de SIM

A continuación, extraemos los datos de SIM swap y comprobamos el estado de la respuesta. Si todo es correcto, mostramos si se ha detectado un intercambio durante el periodo de tiempo indicado y cuándo se produjo el último intercambio de SIM.

   sim_swap_info = data.get("insights", {}).get("sim_swap", {})
    status_code = sim_swap_info.get("status", {}).get("code")

    if status_code != "OK":
        print(f"\n⚠️ SIM Swap check failed. Status: {status_code}")
        print("   Message:", sim_swap_info.get("status", {}).get("message"))
        return

    swapped = sim_swap_info.get("swapped")
    swap_time = sim_swap_info.get("latest_sim_swap_at")

    print(f"\n🔒 SIM Swap Results:")
    print(f"   SIM Swapped: {'❌ Yes' if swapped else '✅ No'}")
    print(f"   Last SIM Swap: {swap_time if swap_time else 'None detected'}")

Paso 5: Añadir una envoltura CLI para la interactividad

Por último, añadimos un bloque main para que los usuarios puedan ejecutar el script interactivamente desde la línea de comandos. Pide el número de teléfono y el número de horas a comprobar, volviendo a los valores por defecto si no se introduce ninguno.

El sitio Operadora virtual dispone de 9 números de teléfono para la API Identity Insights que puede utilizar para realizar pruebas. La API devuelve respuestas deterministas de intercambio de SIM:

• Si hours > 500devuelve swapped = true

• Si hours < 500devuelve swapped = false

También puede probar con allowlist Numbers en Network Registry Playground.

if __name__ == "__main__":
    print("=== Vonage Identity Insights - SIM Swap Checker ===")
    phone = input(f"Enter phone number [Default: {PHONE_NUMBER}]: ").strip() or PHONE_NUMBER
    hours = input(f"How many hours ago to check for? [Default: {DEFAULT_HOURS}]: ").strip() or DEFAULT_HOURS
    hours = int(hours)
    check_sim_swap(phone, hours)

>> Asegúrese de que este código no está auto-indentado por su linter para estar dentro de la función check_sim_swap función.

Probar el script con el operador virtual

Ya puedes probar tu pequeña aplicación.

python3 main.py

En primer lugar, puede utilizar los valores por defecto y ver que el Sim no fue intercambiado:

(venv) ➜  sim_swap_checker python main.py
=== Vonage Identity Insights - SIM Swap Checker ===
Enter phone number [Default: +990123455]: 
How many hours ago to check for? [Default: 240]: 

🔍 Checking SIM swap status for +990123455...

🔒 SIM Swap Results:
   SIM Swapped: ✅ No
   Last SIM Swap: 2025-07-10T08:48:55.143Z

Y a continuación, puede utilizar un valor de horas superior a 500 para ver un Sim Swap:

(venv) ➜  sim_swap_checker python main.py
=== Vonage Identity Insights - SIM Swap Checker ===
Enter phone number [Default: +990123455]: 
How many hours ago to check for? [Default: 240]: 600

🔍 Checking SIM swap status for +990123455...

🔒 SIM Swap Results:
   SIM Swapped: ❌ Yes
   Last SIM Swap: 2025-07-10T08:50:16.733Z

Conclusión

Con solo unas líneas de Python y la API de Vonage Identity Insights, puedes identificar eventos de intercambio de SIM y marcar proactivamente escenarios de alto riesgo en tus aplicaciones. Si bien esta demostración utiliza el Operador virtual para realizar pruebas, la misma configuración funciona en producción una vez que tu aplicación se registra en el Registro de red.

¿Tienes preguntas o estás construyendo algo interesante? Únete a nosotros en el Slack de la comunidad de Vonageo sigue nuestro canal de YouTubeo suscríbete al Boletín para desarrolladores para recibir actualizaciones.