# Privacy & VPN detection

> How to use security and security_extensions to distinguish VPNs, Tor exits, proxies, and cloud hosting.

The `security` (`anonymity` family) and `security_extensions` blocks classify whether an IP address masks the user’s network identity and explain why.

```json security + security_extensions
{
  "security": {
    "is_vpn": true,
    "is_hosting": true,
    "is_tor_exit": false,
    "is_proxy": false,
    "anonymizer_type": "vpn",
    "confidence": 0.96,
    "reason_codes": [
      "vpn_handshake_confirmed",
      "datacenter_asn_range"
    ]
  },
  "security_extensions": {
    "abuse_velocity_score": 18,
    "is_known_scanner": false,
    "observation_recency_hours": 12,
    "anonymizer_reason": "vpn_handshake_confirmed",
    "threat_level": "medium",
    "abuse_velocity": "low",
    "confidence": 0.96
  }
}
```

## The four boolean flags in `security`

| Field | True when | Recommended policy action |
| --- | --- | --- |
| `is_vpn` | Confirmed commercial or self-hosted VPN exit node (`WireGuard`, `OpenVPN`, `IKEv2`). | Step-up MFA or CAPTCHA on sensitive account actions. |
| `is_tor_exit` | Active Tor exit relay in the hourly consensus. | Challenge or block high-risk checkout and signup flows. |
| `is_proxy` | Open HTTP/SOCKS proxy or residential proxy relay. | Require verification on login and payment endpoints. |
| `is_hosting` | Address belongs to a cloud, VPS, or colocation ASN. | Allow for webhook/API calls; challenge for consumer signups. |

## Deterministic reason codes (`anonymizer_reason`)

When your compliance or fraud audit log needs to record *why* an address was flagged, inspect `security_extensions.anonymizer_reason`:

- `vpn_handshake_confirmed`: active VPN protocol probe or verified exit enumeration matched this IP.
- `tor_consensus_exit`: present in the current Tor Project exit list.
- `datacenter_asn_range`: routed by a dedicated hosting or cloud provider ASN.
- `open_proxy_verified`: active proxy telemetry confirmed open relay behaviour.
- `clean_access_network`: residential, mobile, or enterprise access network with no anonymizer indicators.

> **Tip:** Avoid hard-blocking `is_vpn: true` on normal browsing. Stepping up to passkey/2FA or requiring email verification stops automated abuse without locking out privacy-conscious customers.