Intelligent WHOIS, RDAP & DNS Lookup Engine
A fast, hybrid domain intelligence tool with IP geolocation, circuit breakers, and smart caching.

🚀 Live Demo: https://whoisdig.web.app

• PHP >= 7.4
• Extensions: curl, json, intl (for IDN support)
• Apache or Nginx with mod_rewrite (optional)

# Clone the repository
git clone https://github.com/mbahnizen/whoisdig.git
cd whoisdig

# Ensure storage directories are writable
chmod -R 755 storage/

# Point your web server document root to the public/ directory
# For quick local testing:
php -S localhost:8000 -t public/

Open http://localhost:8000 in your browser.

All endpoints are served from public/api.php.

GET /api.php?action=whois-single&domain=google.com

{
  "success": true,
  "domain": "google.com",
  "tld": "com",
  "registrar": "MarkMonitor Inc.",
  "whois_server": "whois.markmonitor.com",
  "created": "1997-09-15T04:00:00+0000",
  "updated": "2019-09-09T15:39:04+0000",
  "expires": "2028-09-13T07:00:00+0000",
  "status": ["clientDeleteProhibited", "clientTransferProhibited", "clientUpdateProhibited", "serverDeleteProhibited", "serverTransferProhibited", "serverUpdateProhibited"],
  "nameservers": ["ns1.google.com", "ns2.google.com", "ns3.google.com", "ns4.google.com"],
  "lifecycle": {
    "age_days": 10077,
    "days_until_expiry": 880
  },
  "raw": "<base64-encoded raw WHOIS output>"
}

GET /api.php?action=whois-single&domain=8.8.8.8

{
  "success": true,
  "is_ip": true,
  "domain": "8.8.8.8",
  "organization": "Google LLC",
  "country": "US",
  "network_name": "GOGL",
  "cidr": "8.8.8.0/24",
  "ip_version": "v4",
  "asn": "AS15169",
  "asn_name": "GOOGLE",
  "hostname": "dns.google",
  "geo": {
    "country_name": "United States",
    "region": "Virginia",
    "city": "Ashburn",
    "isp": "Google LLC",
    "is_proxy": false,
    "is_hosting": true,
    "is_mobile": false
  },
  "ip_decimal": "134744072",
  "ip_hex": "08.08.08.08"
}

POST /api.php?action=whois-bulk
Content-Type: application/json

{
  "domains": ["google.com", "github.com", "8.8.8.8"],
  "refresh": false
}

GET /api.php?action=dig&domain=google.com&type=MX

{
  "success": true,
  "domain": "google.com",
  "record_type": "MX",
  "results": ["10 smtp.google.com", "20 smtp2.google.com"]
}

GET /api.php?action=whois-single&domain=example.com&refresh=1

WHOISDIG is natively designed to be deployed in a high-performance serverless environment using Google Cloud Run (for dynamic PHP processing) and Firebase Hosting (as an edge CDN and proxy gateway).

To run the entire stack locally in a containerized environment:

# Start the containers
docker compose up --build

This starts the application at http://localhost:8080 with auto-reloading and persists your caching and metrics logging locally.

Google Cloud Run offers a generous free tier (2 million requests/month) and complete outbound TCP port 43 access required for legacy WHOIS lookups.

If you have the Google Cloud SDK installed, you can build and deploy directly:

# Configure gcloud active project
gcloud config set project whoisdig

# Enable dynamic APIs
gcloud services enable run.googleapis.com artifactregistry.googleapis.com

# Create the Artifact Registry repository
gcloud artifacts repositories create whoisdig-repo --repository-format=docker --location=asia-southeast2

# Build & Deploy to Cloud Run
gcloud run deploy whoisdig \
  --source . \
  --region asia-southeast2 \
  --allow-unauthenticated \
  --port 8080

Firebase Hosting acts as the front gateway to map your custom domain (like whoisdig.web.app) and automatically proxy dynamic requests to your Cloud Run service.

1. Log in to your Firebase account via the CLI:

   npx firebase login

2. Deploy the hosting configuration (defined in firebase.json):

   npx firebase deploy --only hosting --project=whoisdig

Every push to the main or master branch will trigger an automated deployment using .github/workflows/deploy-cloudrun.yml.

1. Under your GitHub Repository Settings -> Secrets and variables -> Actions, add the following repository secrets:
   • GCP_PROJECT_ID: Set to whoisdig.
   • GCP_SA_KEY: Set to the entire JSON private key of a Google IAM Service Account with least-privilege deployment roles (run.admin, artifactregistry.writer, iam.serviceAccountUser, and iam.serviceAccountTokenCreator).
2. Push to GitHub! The runner will build, tag, push your Docker container to Artifact Registry, and rollout a clean, zero-downtime revision to Cloud Run.

public/
├── index.html          # Frontend SPA
├── api.php             # API router (single entry point)
├── js/app.js           # Frontend logic (progressive loading)
└── css/app.css         # Styles (glassmorphism, dark/light)

config/
└── app.php             # Global config, autoloader, rate limiting

src/
├── Clients/
│   ├── WhoisClient.php     # Raw WHOIS (Port 43) with retry + circuit breaker
│   ├── RdapClient.php      # RDAP REST client with circuit breaker
│   └── GeoIpClient.php     # GeoIP enrichment (multi-provider fallback)
├── Parsers/
│   ├── WhoisParser.php     # Regex-based WHOIS response parser
│   ├── RdapParser.php      # Structured RDAP JSON parser
│   └── ReferralParser.php  # WHOIS referral server extractor
├── Resolvers/
│   ├── WhoisService.php    # Core orchestrator (hybrid resolution engine)
│   ├── WHOISChecker.php    # Public facade / entry point
│   ├── DigChecker.php      # DNS record resolver
│   ├── IanaResolver.php    # IANA WHOIS/RDAP server discovery
│   └── TldResolver.php     # TLD detection via Mozilla PSL
└── Utils/
    ├── Cache.php           # File-based SWR cache with flock()
    ├── CircuitBreaker.php  # Fault isolation for external services
    └── Metrics.php         # JSONL performance logging

storage/
├── cache/              # Cached WHOIS/RDAP/GeoIP results
└── logs/               # Activity logs, metrics, rate-limit data

Browser → api.php → WHOISChecker → WhoisService
                                       ├── Is IP? → RDAP /ip → GeoIP enrichment → merge
                                       └── Is Domain? → TLD resolve → IANA discover
                                              ├── WHOIS Port 43 → referral chain → parse
                                              └── Fallback → RDAP /domain → parse
                                       Cache ←→ (all steps)
                                       CircuitBreaker ←→ (all external calls)

Legacy WHOIS (Port 43) has the widest coverage, but modern TLDs (.dev, .app, .page) only support RDAP. WHOISDIG uses RDAP-first for modern TLDs and WHOIS-first for legacy TLDs, with automatic fallback in both directions.

WHOIS servers are slow (500ms–7s) and rate-limited. SWR ensures:

• Instant responses from cache for repeat queries
• Background revalidation when cache is stale
• No thundering herd — file locking prevents duplicate fetches

External WHOIS/RDAP servers can be unreliable. The circuit breaker:

• Tracks failures per server
• Temporarily blocks requests to failing servers (cooldown period)
• Automatically recovers when the server comes back online

• Input Sanitization — All input is cleaned before processing (trim + lowercase)
• Output Encoding — HTML escaping at the display layer prevents XSS
• Rate Limiting — Sliding window (120 req/hour per IP) with Retry-After support
• Storage Protection — .htaccess blocks direct access to cache/logs
• CORS — Configurable via WHOISDIG_CORS_ORIGIN environment variable
• Error Isolation — Internal errors are logged; clients receive generic messages

• IPv6 PTR lookup support
• WHOIS response diffing (track changes over time)
• Webhook notifications for domain expiry
• REST API authentication (API keys)
• Docker image & Container support (with local docker-compose and Cloud Run deployment)
• Export results (CSV / JSON)
• Batch upload via file (CSV/TXT)

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure your code:

• Follows the existing code structure
• Includes appropriate error handling
• Does not introduce new external dependencies without discussion

This project is licensed under the MIT License — see the LICENSE file for details.

Built with ❤️ for the domain intelligence community