Previna fraudes de troca de SIM em Python com a API do Identity Insights

Fraude por troca de SIM é uma ameaça crescente à segurança móvel, na qual os invasores se apropriam do número de telefone da vítima transferindo-o para um novo cartão SIM. Isso lhes permite interceptar chamadas, mensagens de texto e até mesmo códigos de autenticação de dois fatores. Assustador!

Neste tutorial, usaremos a API do Vonage Identity Insights em Python para detectar possíveis trocas de cartão SIM e proteger seus usuários.

>> Resumo: Baixe o código funcional no GitHub

Pré-requisitos

Para acompanhar, você vai precisar de:

• Um account de desenvolvedor da Vonage

• Python 3.8 ou superior

Configuração do projeto

Criar uma aplicação da Vonage

Seu script em Python utilizará o Sandbox do Registro de Rede. Para isso, crie um aplicativo Vonage no Painel da Vonage com: 

1. Ative o recurso “Registro de rede” e selecione “Playground”

2. Gere um private.key, você precisará movê-lo para a raiz do seu diretório na seção a seguir

Crie seu projeto e instale as dependências

1. Crie a pasta e os arquivos do seu projeto no terminal.

mkdir sim_swap_checker
cd sim_swap_checker
touch main.py .env

>> Agora você pode mover o arquivo baixado private.key para o sim_swap_checker diretório

2. Configure um ambiente virtual.

Isso garante que suas dependências permaneçam isoladas do Python do seu sistema.

python3 -m venv venv

source venv/bin/activate

3. Instale os pacotes necessários.

Vamos usar requests para fazer solicitações HTTP à API do Identity Insights, python-dotenv para carregar com segurança nossas credenciais da API a partir de um arquivo de ambiente e vonage-jwt para gerar tokens JWT seguros para autenticar nossas solicitações.

pip install requests python-dotenv vonage-jwt

Configure seu arquivo ENV

Adicione o ID of your Vonage Application and the default phone number + the period, in hours, during which the API will perform the SIM Swap check.

Você pode conferir na Referência da API do Identity Insights que o insight “Sim Swap” depende de um único parâmetro chamado period; vamos chamá-lo de “hour” e definir o valor padrão como 240.

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

Escreva o script em Python para verificar se houve troca de chip

Etapa 1: Configurar as importações e o ambiente

No main.py arquivo, vamos criar o script principal que verifica se ocorreu uma troca de SIM dentro de um intervalo de tempo definido pelo usuário (padrão: 240 horas, ou 10 dias).

Comece importando as bibliotecas necessárias e carregando as variáveis de ambiente do arquivo .env. Isso garante que não codifiquemos valores confidenciais de forma estática e facilita a atualização rápida do número de telefone e do período de tempo para testar valores diferentes.

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

Etapa 2: Autenticar-se com JWT

Antes de podermos fazer qualquer chamada à API do Identity Insights, precisamos nos autenticar usando um JSON Web Token (JWT). Isso é obrigatório para todas as APIs da Rede Vonage.

Um JWT identifica com segurança seu aplicativo usando sua APPLICATION_ID e sua chave privada, além de incluir metadados como a data de emissão ( iat ) e quando expira ( exp ). Esses tokens são assinados usando o RS256 algoritmo e, normalmente, permanecem válidos por apenas alguns minutos, o que os torna seguros e de curta duração.

Abaixo das variáveis de ambiente, inicialize seu JwtClient. Usaremos esse cliente para gerar o JWT propriamente dito ao fazer a solicitação à API.

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

jwt_client = JwtClient(application_id, private_key_str)

Etapa 3: Definir a função principal de verificação de troca de SIM

A seguir, continuaremos abaixo e definiremos uma check_sim_swap() função que recebe um número de telefone e um período em horas. Ela usa o cliente JWT para autenticar e envia uma solicitação POST à API do 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 define a finalidade como "FraudPreventionAndDetection" , um requisito para utilizar o SIM Swap Insights. Se a API retornar qualquer coisa diferente de um 200 OK, exibimos o erro no console e encerramos o programa.

Etapa 4: Analisar e exibir os resultados da troca de SIM

Em seguida, extraímos os dados de troca de SIM e verificamos o status da resposta. Se tudo estiver em ordem, informamos se foi detectada alguma troca de SIM durante o período especificado e quando ocorreu a última troca 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'}")

Etapa 5: Adicionar um wrapper de CLI para interatividade

Por fim, adicionamos um main bloco para que os usuários possam executar o script de forma interativa a partir da linha de comando. Ele solicita o número de telefone e o número de horas a serem verificadas, recorrendo aos valores padrão caso nenhum seja inserido.

A Operadora Virtual dispõe de 9 números de telefone para a Number Insight API que você pode usar para testes. A API retorna respostas determinísticas para troca de SIM:

• Se hours > 500, ele retorna swapped = true

• Se hours < 500, ele retorna swapped = false

Você também pode tentar fazer um teste com números da lista de permissões no 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)

>> Certifique-se de que esse código não seja recuado automaticamente pelo seu linter para ficar dentro da check_sim_swap função.

Teste o script com o operador virtual

Agora você pode testar seu aplicativo!

python3 main.py

Primeiro, você pode usar os valores padrão e verificar se o Sim não foi trocado:

(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

E então você pode usar um valor para “horas” superior a 500 para ver uma troca 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

Conclusão

Com apenas algumas linhas de Python e a API do Vonage Identity Insights, você pode identificar eventos de troca de SIM e sinalizar proativamente cenários de alto risco em seus aplicativos. Embora esta demonstração utilize o Virtual Operator para testes, a mesma configuração funciona em produção assim que seu aplicativo for registrado no Registro de Rede.

Tem dúvidas ou está criando algo legal? Junte-se a nós na Slack da Comunidade Vonage, siga nosso canal no YouTubeou inscreva-se no Boletim Informativo para Desenvolvedores para ficar por dentro das novidades.