Blackbox IP Reputation API

Project History

Blackbox is a modern replacement for the now-discontinued proxy checking APIs, http://proxy.mind-media.com/block/ and http://www.shroomery.org/ythan/proxycheck.php.

The free APIv1 is a direct continuation of the Shroomery.org project, providing a simple way to determine if an IP address is a likely proxy.

Features & Improvements

This service was built from the ground up with several key improvements over the original APIs:

• Fast: Optimized for high performance and low latency.
• Drop-in Replacement: APIv1 is fully compatible with the legacy proxycheck.php API.
• Modern Detection: Utilizes ASNs to identify entire networks of hosting providers, not just individual IPs.
• Comprehensive Lists: Includes TOR exit nodes in its detection capabilities.
• IPv6 Support: Fully supports lookups for both IPv4 and IPv6 addresses.
• Flexible Responses: Offers a detailed JSON format (APIv2) for richer data integration.

API v1

Returns a simple Y (Yes) or N (No) if the IP is detected as malicious or suspicious. This legacy endpoint is offered with unlimited free requests. Responses are cached for up to 30 days.

Endpoints:

• /api/v1/{ip}
• /lookup/{ip}

Example:

curl https://blackbox.ipinfo.app/api/v1/8.8.8.8

Response Types:

• Y - Yes, the IP was found on one or more of our detection lists.
• N - No, the IP was not found on any of our detection lists.
• E - Error, something went wrong (e.g., an invalid IP was provided).

Implementation Note:

When checking the response, it is important to explicitly check for Y. Avoid checking for "not N" (!= 'N'), as this could incorrectly treat an error response as a positive detection.

// Correct
if (response === 'Y') {
    // Handle proxy
}

// Incorrect
if (response !== 'N') {
    // This will incorrectly trigger on errors
}

API v2

Returns a detailed JSON object with information about the IP address. This modern endpoint is for those who need more specificity and control. API v2 is a subscription-only service, available at RapidAPI. Responses are cached for one day to ensure data is fresh while maintaining high performance.

Endpoint: /api/v2/{ip}

Example:

curl https://blackbox.ipinfo.app/api/v2/8.8.8.8

Example Response (IP is listed):

{
    "ip": "8.8.8.8",
    "error": null,
    "asn": {
        "name": "GOOGLE",
        "number": 15169,
        "network": "8.8.8.0",
        "cidr": 24
    },
    "detection": {
        "bogon": false,
        "cloud": true,
        "hosting": true,
        "proxy": false,
        "spamhaus": false,
        "tor": false
    },
    "suggestion": "block"
}

Example Response (IP is not listed):

{
    "ip": "72.49.1.1",
    "error": null,
    "asn": {
        "name": "FUSE-NET",
        "number": 6181,
        "network": "72.49.0.0",
        "cidr": 16
    },
    "detection": {
        "bogon": false,
        "cloud": false,
        "hosting": false,
        "proxy": false,
        "spamhaus": false,
        "tor": false
    },
    "suggestion": "allow"
}

Detections Explained

The detection object in the API v2 response contains the following boolean flags:

• Bogon: The IP address is not internet-routable (e.g., a local 192.168.x.x address). These requests should typically be blocked as they may indicate spoofing attempts.
• Cloud: The IP belongs to a major cloud provider like AWS or Google Cloud. For most user-facing applications, traffic from these IPs is more likely to be bots or scrapers than legitimate users.
• Hosting: The IP is part of a network primarily used for hosting servers (e.g., Digital Ocean). It's unlikely to be a regular user and may be a proxy, scraper, or other nefarious traffic.
• Proxy: The IP is a known proxy provider, an open proxy, or a compromised device acting as a proxy.
• Spamhaus: The IP is listed by Spamhaus as a source of continuous threats. We highly recommend blocking all traffic with this flag.
• Tor: The IP is a Tor exit node, commonly used to anonymize traffic and potentially exploit services.

The suggestion field will be block if any detection flag is true. You can use the detailed flags to implement your own blocking logic.

Health Check

Endpoint: /ping or /api/ping

Example:

curl https://blackbox.ipinfo.app/ping

Projects Using Blackbox

• IP-Lookup.org Proxy Checker - A free web-based tool to check if an IP address is a known proxy, VPN, or TOR node.
• my.ipinfo.app - Lists client details via web browser and provides a quick and easy way to find details on the client's IP.
• SourceMod Blacklist/Whitelist Plugin - A plugin for game server administrators to block players from specific countries or those using proxies and VPNs.
• IMC '21 Research Paper - "Residential Proxies: A Deep Dive into the Growing Anonymity Service," a paper that provides a comprehensive analysis of the residential proxy landscape, which Blackbox helps to detect.
• FoxGate - A modern server proxy and firewall for Minecraft servers that utilizes Blackbox for enhanced security and connection filtering.
• XenForo Proxy Check Add-on - A XenForo add-on to prevent user registrations from proxies and VPNs using the Blackbox API.