Prévenir la fraude par échange de cartes SIM en Python avec l'API Identity Insights

La fraude par échange de cartes SIM est une menace croissante dans le domaine de la sécurité mobile, où les attaquants détournent le numéro de téléphone d'une victime en le transférant sur une nouvelle carte SIM. Cela leur permet d'intercepter les appels, les textes et même les codes d'authentification à deux facteurs. Effrayant !

Dans ce tutoriel, nous utiliserons l'API Identity Insights de Vonage en Python pour détecter les échanges potentiels de cartes SIM et protéger vos utilisateurs.

>> TL;DR: Obtenir le code complet code complet sur GitHub

Conditions préalables

Pour suivre, vous aurez besoin de

• Un compte de développeur 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.

Configuration du projet

Créer une application Vonage

Votre script Python utilisera le Environnement de test du registre du réseau. Pour ce faire, créez une application Vonage dans la section Tableau de bord Vonage avec :

1. Activez la fonction Registre du réseau et sélectionnez "Terrain de jeu".

2. Générer un private.keyvous devrez le déplacer à la racine de votre répertoire dans la section suivante

Créez votre projet et installez les dépendances

1. Créez le dossier et les fichiers de votre projet dans votre terminal.

mkdir sim_swap_checker
cd sim_swap_checker
touch main.py .env

>> Vous pouvez maintenant déplacer votre fichier téléchargé private.key dans le répertoire sim_swap_checker répertoire

2. Mettre en place un environnement virtuel.

Cela garantit que vos dépendances restent isolées de votre système Python.

python3 -m venv venv

source venv/bin/activate

3. Installez les paquets nécessaires.

Nous utiliserons requests pour effectuer des requêtes HTTP à l'API Identity Insights, python-dotenv pour charger en toute sécurité nos identifiants API à partir d'un fichier d'environnement, et vonage-jwt pour générer des jetons JWT sécurisés afin d'authentifier nos demandes.

pip install requests python-dotenv vonage-jwt

Configurez votre fichier ENV

Ajoutez le numéro de téléphone de votre application Vonage et le numéro de téléphone par défaut ID de votre Applications Vonage et le numéro de téléphone par défaut + la période en heures pendant laquelle l'API effectuera la vérification de l'échange de cartes SIM.

Vous pouvez voir dans la Référence de l'API Identity Insights que l'aperçu Sim Swap repose sur un seul paramètre appelé periodNous l'appellerons heure, et la valeur par défaut est 240.

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

Écrire le script Python pour vérifier la permutation des simulations

Étape 1 : Mise en place des importations et de l'environnement

Dans le fichier main.py construisons le script principal qui vérifie si un échange de cartes SIM a eu lieu dans un délai défini par l'utilisateur (240 heures, ou 10 jours, par défaut).

Commencez par importer les bibliothèques nécessaires et par charger les variables d'environnement à partir du fichier .env. Cela permet de s'assurer que les valeurs sensibles ne sont pas codées en dur et facilite la mise à jour rapide du numéro de téléphone et de la période de temps pour tester différentes valeurs.

# 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")

Étape 2 : Authentification avec JWT

Avant de pouvoir effectuer des appels à l'API Identity Insights, nous devons nous authentifier à l'aide d'un jeton Web JSON (JWT). jeton Web JSON (JWT). Cela est nécessaire pour toutes les API du réseau Vonage.

Un JWT identifie votre application de manière sécurisée à l'aide de votre clé privée et de votre clé d'identification. APPLICATION_ID et de votre clé privée, et inclut des métadonnées telles que la date d'émission ( iat ) et sa date d'expiration ( exp ). Ces jetons sont signés à l'aide de l'algorithme RS256 et ne restent généralement valides que quelques minutes, ce qui les rend sûrs et de courte durée.

Sous vos variables d'environnement, initialisez votre JwtClient. Nous utiliserons ce client pour générer le JWT lors de la demande d'API.

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

jwt_client = JwtClient(application_id, private_key_str)

Étape 3 : Définir la fonction de contrôle de la permutation des cartes SIM de base

Ensuite, nous allons continuer ci-dessous et définir une fonction check_sim_swap() qui prend en compte un numéro de téléphone et une période en heures. Elle utilise le client JWT pour s'authentifier et envoie une requête POST à l'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()

Ce code fixe l'objectif de "FraudPreventionAndDetection" une exigence pour l'utilisation de SIM swap insights. Si l'API renvoie autre chose qu'un 200 OKnous affichons l'erreur sur la console et sortons.

Étape 4 : Analyse et affichage des résultats de l'échange de cartes SIM

Ensuite, nous extrayons les données relatives à l'échange de cartes SIM et vérifions l'état de la réponse. Si tout est OK, nous indiquons si une permutation a été détectée au cours de la période donnée et quand la dernière permutation SIM a eu lieu.

   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'}")

Étape 5 : Ajouter un wrapper CLI pour l'interactivité

Enfin, nous ajoutons un bloc main afin que les utilisateurs puissent exécuter le script de manière interactive à partir de la ligne de commande. Il demande le numéro de téléphone et le nombre d'heures à vérifier, et revient aux valeurs par défaut si aucune n'est saisie.

L'opérateur virtuel Opérateur virtuel dispose de 9 numéros de téléphone pour l'API Identity Insights que vous pouvez utiliser à des fins de test. L'API renvoie des réponses déterministes d'échange de cartes SIM :

• Si hours > 500, il renvoie swapped = true

• Si hours < 500, il renvoie swapped = false

Vous pouvez également essayer de tester avec numéros de listes d'autorisation dans l'aire de jeu du registre du réseau.

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)

>> Assurez-vous que ce code n'est pas auto-indenté par votre linter pour être à l'intérieur de la fonction check_sim_swap fonction.

Tester le script avec l'opérateur virtuel

Vous pouvez maintenant tester votre petite application !

python3 main.py

Tout d'abord, vous pouvez utiliser les valeurs par défaut et constater que la Sim n'a pas été échangée :

(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

Vous pouvez ensuite utiliser une valeur d'heures supérieure à 500 pour voir un échange de Sim :

(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

Conclusion

Avec seulement quelques lignes de Python et l'API Vonage Identity Insights, vous pouvez identifier les événements d'échange de SIM et signaler de manière proactive les scénarios à haut risque dans vos Applications. Bien que cette démo utilise l'opérateur virtuel pour les tests, la même configuration fonctionne en production une fois que votre application est enregistrée dans le Registre du réseau.

Vous avez des questions ou vous construisez quelque chose de cool ? Rejoignez-nous dans le Communauté Vonage Slackou suivez notre chaîne YouTubeou abonnez-vous à la Bulletin des développeurs pour les mises à jour.