API de detecção de VPN e proxy: sinaliza abuso sem bloquear usuários

Seu aplicativo SaaS oferece uma avaliação gratuita por usuário. Os usuários se inscrevem, ativam uma VPN e se inscrevem novamente. O abuso de promoções custa receita e distorce suas métricas de conversão. Você precisa sinalizar VPN e proxy conexões no ponto de inscrição.

Este guia cobre o botoi POST /v1/vpn-detect endpoint: o que ele retorna, como integrá-lo aos aplicativos Next.js e Express, como combiná-lo com outros sinais de fraude e onde fica aquém.

O ponto final

Uma solicitação POST com um endereço IP no corpo. Nenhum cabeçalho especial, nenhuma chave de API necessária para acesso anônimo.

curl -X POST https://api.botoi.com/v1/vpn-detect \\
  -H "Content-Type: application/json" \\
  -d '{ "ip": "185.220.101.1" }'

Resposta para um nó de saída Tor conhecido:

{
  "success": true,
  "data": {
    "ip": "185.220.101.1",
    "is_vpn": true,
    "is_proxy": false,
    "is_tor": true,
    "is_datacenter": false,
    "provider": null,
    "risk_score": 90,
    "checks": {
      "tor": true,
      "datacenter": false,
      "suspicious_hostname": false
    }
  }
}

Resposta para um IP residencial limpo:

{
  "success": true,
  "data": {
    "ip": "73.162.45.118",
    "is_vpn": false,
    "is_proxy": false,
    "is_tor": false,
    "is_datacenter": false,
    "provider": null,
    "risk_score": 0,
    "checks": {
      "tor": false,
      "datacenter": false,
      "suspicious_hostname": false
    }
  }
}

Campos de resposta

• is_vpn (booleano): Verdadeiro se o IP pertencer a um intervalo de datacenter conhecido ou tiver um nome de host DNS reverso suspeito contendo palavras-chave relacionadas à VPN.
• é_proxy (booleano): Verdadeiro se o nome do host DNS reverso sugerir um servidor proxy.
• is_tor (booleano): Verdadeiro se o IP corresponder a um nó de saída Tor conhecido.
• is_datacenter (booleano): Verdadeiro se o IP estiver dentro dos intervalos CIDR AWS, Google Cloud, Azure, DigitalOcean ou Linode.
• provedor (string ou null): O nome do provedor de nuvem quando is_datacenter é verdade. Nulo para IPs residenciais e Tor.
• pontuação_de_risco (número, 0-100): Conexões Tor pontuam 90, IPs de datacenter pontuam 60, nomes de host suspeitos pontuam 40. IPs residenciais limpos pontuam 0.
• cheques (objeto): Detalhamento de quais métodos de detecção foram acionados, para depuração.

Sinalize usuários VPN na inscrição com middleware Next.js

Este middleware intercepta solicitações POST para sua rota de inscrição, verifica o IP do chamador em relação ao API de detecção de VPN e anexa um cabeçalho à solicitação quando uma VPN é detectada. Seu gerenciador de inscrição lê o cabeçalho e decide o que fazer: exigir verificação de e-mail, adicionar um sinalizador de revisão manual ou reduzir o período de teste.

import { NextRequest, NextResponse } from 'next/server';

const VPN_DETECT_URL = 'https://api.botoi.com/v1/vpn-detect';

export async function middleware(req: NextRequest) {
  if (req.method !== 'POST') {
    return NextResponse.next();
  }

  const ip = req.headers.get('x-forwarded-for')?.split(',')[0]?.trim()
    || req.ip
    || '127.0.0.1';

  try {
    const res = await fetch(VPN_DETECT_URL, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ ip }),
      signal: AbortSignal.timeout(3000),
    });

    const { data } = await res.json();

    if (data.is_vpn || data.is_tor || data.is_proxy) {
      // Add a header so your signup handler can flag the account
      const response = NextResponse.next();
      response.headers.set('x-vpn-detected', 'true');
      response.headers.set('x-vpn-risk-score', String(data.risk_score));
      return response;
    }
  } catch {
    // Fail open: if the API is unreachable, let the request through
    console.warn('VPN detection check failed, allowing request');
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/api/auth/signup', '/api/auth/register'],
};

O middleware não bloqueia a inscrição. Ele passa um sinal para o seu manipulador. Este é o certo abordagem porque o tráfego VPN não é prova de fraude. Um usuário em uma VPN corporativa ou viajando através de uma rede restritiva é um cliente legítimo.

Limites de taxa mais rígidos para IPs VPN no Express

Se você executar uma API, poderá aplicar limites de taxa mais rígidos a conexões VPN e proxy sem bloquear eles abertamente. Este middleware oferece aos usuários padrão 100 solicitações por hora e aos usuários VPN 20.

import type { Request, Response, NextFunction } from 'express';

const VPN_DETECT_URL = 'https://api.botoi.com/v1/vpn-detect';
const BOTOI_API_KEY = process.env.BOTOI_API_KEY;

// Standard limits
const STANDARD_LIMIT = 100; // requests per hour
const VPN_LIMIT = 20;       // requests per hour for VPN users

const requestCounts = new Map<string, { count: number; resetAt: number }>();

export async function vpnAwareRateLimit(
  req: Request,
  res: Response,
  next: NextFunction
) {
  const ip = req.headers['x-forwarded-for']?.toString().split(',')[0]?.trim()
    || req.socket.remoteAddress
    || 'unknown';

  let isVpn = false;

  try {
    const vpnRes = await fetch(VPN_DETECT_URL, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': \`Bearer \${BOTOI_API_KEY}\`,
      },
      body: JSON.stringify({ ip }),
      signal: AbortSignal.timeout(2000),
    });

    const { data } = await vpnRes.json();
    isVpn = data.is_vpn || data.is_tor || data.is_proxy;
  } catch {
    // Fail open: use standard limits if detection fails
  }

  const limit = isVpn ? VPN_LIMIT : STANDARD_LIMIT;
  const now = Date.now();
  const entry = requestCounts.get(ip);

  if (!entry || entry.resetAt < now) {
    requestCounts.set(ip, { count: 1, resetAt: now + 3600_000 });
    res.setHeader('X-RateLimit-Limit', limit);
    return next();
  }

  entry.count++;

  if (entry.count > limit) {
    return res.status(429).json({
      error: 'Rate limit exceeded',
      retryAfter: Math.ceil((entry.resetAt - now) / 1000),
    });
  }

  res.setHeader('X-RateLimit-Limit', limit);
  res.setHeader('X-RateLimit-Remaining', limit - entry.count);
  next();
}

A proporção de 5:1 entre os limites padrão e VPN é um ponto de partida. Ajuste-o com base no seu abuso padrões. Se sua API lida com pagamentos ou modificações de conta, limites de VPN mais rígidos fazem sentido. Para endpoints somente leitura, talvez você não precise de limites diferenciais.

Pontuação de fraude: combine a detecção de VPN com outros sinais

A detecção de VPN por si só é um sinal fraco de fraude. Uma VPN + e-mail descartável + nova conta + falha tentativas de pagamento é um sinal forte. Esta função combina múltiplas entradas em uma única fraude pontuação.

interface FraudSignals {
  vpnDetected: boolean;
  riskScore: number;
  disposableEmail: boolean;
  accountAge: number; // days
  failedPayments: number;
}

function calculateFraudScore(signals: FraudSignals): number {
  let score = 0;

  // VPN/proxy risk contributes up to 30 points
  if (signals.vpnDetected) {
    score += Math.round(signals.riskScore * 0.3);
  }

  // Disposable email: strong signal
  if (signals.disposableEmail) {
    score += 35;
  }

  // New account + VPN is a red flag
  if (signals.accountAge < 1 && signals.vpnDetected) {
    score += 20;
  }

  // Failed payment history
  score += Math.min(signals.failedPayments * 10, 30);

  return Math.min(score, 100);
}

async function assessSignupRisk(ip: string, email: string) {
  const [vpnRes, emailRes] = await Promise.all([
    fetch('https://api.botoi.com/v1/vpn-detect', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ ip }),
    }),
    fetch('https://api.botoi.com/v1/disposable-email/check', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email }),
    }),
  ]);

  const vpnData = (await vpnRes.json()).data;
  const emailData = (await emailRes.json()).data;

  const fraudScore = calculateFraudScore({
    vpnDetected: vpnData.is_vpn || vpnData.is_tor,
    riskScore: vpnData.risk_score,
    disposableEmail: emailData.is_disposable,
    accountAge: 0, // new signup
    failedPayments: 0,
  });

  return {
    fraudScore,
    action: fraudScore > 70 ? 'block' : fraudScore > 40 ? 'review' : 'allow',
    details: {
      vpn: vpnData.is_vpn,
      tor: vpnData.is_tor,
      proxy: vpnData.is_proxy,
      disposableEmail: emailData.is_disposable,
    },
  };
}

Ambas as chamadas de API são executadas em paralelo, portanto a latência total é a mais lenta das duas (normalmente abaixo 100ms). O action O campo oferece três níveis: permitir, revisar ou bloquear. Para pontuações entre 40 e 70, encaminhe a inscrição para uma fila de revisão manual em vez de rejeitá-la automaticamente.

Cache para reduzir chamadas de API

Um endereço IP não altera seu status de VPN a cada solicitação. Armazene o resultado em cache por 10 minutos para reduza o uso da API sem perder alterações de status.

const vpnCache = new Map<string, { result: VpnResult; expiresAt: number }>();
const CACHE_TTL = 10 * 60 * 1000; // 10 minutes

interface VpnResult {
  isVpn: boolean;
  isTor: boolean;
  isProxy: boolean;
  riskScore: number;
}

async function checkVpn(ip: string): Promise<VpnResult> {
  const cached = vpnCache.get(ip);
  if (cached && cached.expiresAt > Date.now()) {
    return cached.result;
  }

  try {
    const res = await fetch('https://api.botoi.com/v1/vpn-detect', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ ip }),
      signal: AbortSignal.timeout(3000),
    });

    const { data } = await res.json();
    const result: VpnResult = {
      isVpn: data.is_vpn,
      isTor: data.is_tor,
      isProxy: data.is_proxy,
      riskScore: data.risk_score,
    };

    vpnCache.set(ip, { result, expiresAt: Date.now() + CACHE_TTL });
    return result;
  } catch {
    return { isVpn: false, isTor: false, isProxy: false, riskScore: 0 };
  }
}

Para implantações de vários servidores, troque o mapa na memória por Redis ou Upstash. A mesma chave de cache (endereço IP) e padrão TTL se aplicam.

O que esta API não consegue detectar

A honestidade sobre as limitações é mais importante do que um discurso de vendas sofisticado. Here's where VPN detection fica aquém.

• VPNs residenciais. Serviços como iCloud Private Relay e algumas configurações do tráfego de rota Mullvad através de endereços IP residenciais. Esses IPs parecem idênticos a conexões domésticas regulares de Internet. Nenhum DNS reverso ou detecção baseada em CIDR os detecta.
• NAT da operadora móvel. As operadoras de celular usam NAT de nível de operadora, o que significa milhares de usuários compartilham um único endereço IP. A sinalização desses IPs afeta usuários legítimos. A API pode retornar is_datacenter: false e risk_score: 0 para estes IPs mesmo quando um usuário VPN está por trás deles.
• Proxies SOCKS5 privados. Proxies hospedados em servidores pessoais com residência Os ISPs não aparecem nos intervalos CIDR do datacenter e não têm nomes de host suspeitos. Eles são invisível à detecção automatizada.
• Conexões somente IPv6. O endpoint atual oferece suporte apenas a endereços IPv4. A detecção de VPN IPv6 não está disponível.
• Falsos positivos em hospedagem compartilhada. Um desenvolvedor executando um projeto paralelo em um A gota DigitalOcean será acionada is_datacenter: true. Isso não significa que eles estão escondendo sua identidade.

A detecção funciona bem para provedores comerciais de VPN (NordVPN, ExpressVPN, Surfshark, CyberGhost) e tráfego Tor. Ele captura a maioria dos proxies hospedados em datacenters. Ele não captura VPNs residenciais ou procuradores privados. Espere 80-90% de detecção para os casos comuns e quase zero para casos extremos.

Sinalize, não bloqueie

Bloquear completamente os usuários VPN é um erro para a maioria dos aplicativos. Aqui está o porquê:

• Usuários preocupados com a privacidade, sem intenção de abusar do seu serviço, executam VPNs como padrão.
• Os funcionários em VPNs corporativas encaminham todo o seu tráfego através da infraestrutura da empresa.
• Os usuários em países com restrições de Internet dependem de VPNs para acessar seu produto.
• Jornalistas, ativistas e pesquisadores de segurança usam o Tor por motivos legítimos.

A abordagem correta: adicionar um sinalizador de risco à conta, exigir verificação adicional (e-mail confirmação, número de telefone, forma de pagamento) ou encaminhar a inscrição para uma fila de revisão. Deixe os humanos tomar a decisão final em casos ambíguos.

Pontos-chave

• POST /v1/vpn-detect retorna is_vpn, is_proxy, is_tor, is_datacenter, provider, e risk_score para qualquer endereço IPv4.
• Nenhuma chave de API é necessária para acesso anônimo (5 solicitações por minuto). Chaves gratuitas desbloqueiam 500 solicitações por dia.
• A detecção abrange provedores comerciais de VPN, nós de saída Tor conhecidos e os principais provedores de nuvem Intervalos de IP. VPNs residenciais e proxies privados escapam.
• Combine a detecção de VPN com verificações de e-mail descartáveis, idade da conta e histórico de pagamentos para uma pontuação de fraude significativa. O status da VPN por si só não é suficiente para agir.
• Sinalize conexões VPN para revisão. Não os bloqueie. Usuários legítimos utilizam VPNs para privacidade, política corporativa e acesso em regiões restritas.