Proxy Service Checker - IP Intel

Overview

HTTP API (FastAPI/uvicorn) that decides if an IP is hosting/proxy or residential using deterministic signals. It pulls RDAP/WHOIS/DNS, applies rules from config/, and returns a verdict, confidence, and reason codes. A small web UI at / lets you test quickly.

Features

• ASN/provider matches with reason codes
• Country name expansion
• JSON config in config/
• Health endpoint
• Conservative defaults (residential‑safe)

How It Works

1. Validate IP → 2) RDAP/WHOIS/DNS → 3) Apply rule sets (ASNs, providers, terms) → 4) Verdict + confidence + reasons.

Detection Rules (concise)

• High: ASN in list, strong provider match, strong hosting term, Tor exit
• Medium/Low: ≥2 weak PTR patterns (downgrade if residential terms)
• Bogon: private/reserved ranges flagged, not proxy

Quick Start

# 1) Create and activate venv
python -m venv venv
source venv/bin/activate

# 2) Install dependencies
pip install -r requirements.txt

# 3) Run the service (also activates venv inside)
./run.sh

# Service listens on port 5000 by default

Open http://127.0.0.1:5000

Requirements

• Python 3.10+ with pip and venv.
• System whois binary in PATH (used to enrich missing fields):
  • Debian/Ubuntu: sudo apt-get install whois
  • macOS (Homebrew): brew install whois
• Outbound network access for RDAP (HTTPS) and DNS (port 53).
• Linux/macOS recommended; Windows may need a WHOIS alternative or WSL.

Hosting & Runtime

• uvicorn app:app (dev via ./run.sh)
• UI at / (static/index.html)
• Prod: uvicorn or gunicorn (UvicornWorker) behind Nginx/systemd

Tech Stack

• FastAPI + uvicorn
• RDAP (ipwhois), WHOIS (whois), DNS (dnspython)
• JSON config + hot reload
• In‑memory cache + thread pool

API

Lookup an IP:

curl -X POST http://localhost:5000/api/lookup \
  -H "Content-Type: application/json" \
  -d '{"ip": "8.8.8.8"}'

Health:

curl http://localhost:5000/api/health

Also useful:

• GET /api/recent-lookups — last 100 queries
• POST /api/reload-config — reload config
• GET / — static UI

Example (short):

{
  "ip": "8.8.8.8",
  "asn": "15169",
  "asn_description": "GOOGLE",
  "country": "US",
  "verdict": "hosting_proxy",
  "confidence": "high",
  "reasons": ["ASN_MATCH", "PROVIDER_MATCH"]
}

Configuration

All rule sets live in config/ so you can tune behavior without code changes:

• hosting_asns.json: Critical ASN numbers considered hosting/proxy infra.
• strong_providers.json: Organization/provider names that indicate infrastructure (exact/strict matches recommended).
• hosting_terms.json: Explicit hosting terminology that, when present, should trigger a high‑confidence verdict.

Update these files to adjust detection posture. Commit them alongside code for auditability.

Notes

• Deterministic and conservative by design
• Keep lists fresh (ASNs/providers)
• Add rate limiting/logging at the edge

Limitations

• Ownership context only (no DPI)
• Residential proxies may evade unless strong signals appear
• Accuracy depends on data freshness