clossers/didi-lot1-ai
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
didi-lot1-ai/ai_platform/modules/domain_check/use_api.md

13 KiB
Raw Permalink Blame History

Domain Check API - Developer Documentation

Base URL: http://domain-check-api:11000

API Version: v1

Authentication

Currently no authentication required (internal use only).

Endpoints

POST /api/v1/check/check

Perform comprehensive domain verification.

Request:

curl -X POST "http://domain-check-api:11000/api/v1/check/check" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "check_options": {
      "whois": true,
      "dns": true,
      "ssl": true,
      "ip_intelligence": true,
      "http_analysis": true,
      "blacklist": true,
      "port_scan": true,
      "subdomains": true
    }
  }'

Check Options:

Option Type Default Description
whois bool true WHOIS lookup (registrar, dates, nameservers)
dns bool true DNS records (A, AAAA, MX, TXT, NS, CNAME, SOA)
ssl bool true SSL certificate validation
ip_intelligence bool true IP geolocation, ASN, reverse DNS
http_analysis bool true HTTP headers, security, technologies
blacklist bool true DNSBL spam/malware blacklist check
port_scan bool false TCP port scanning (slower)
subdomains bool false Subdomain enumeration (slower)
force_refresh bool false Bypass cache

Response Structure

{
  "success": true,
  "data": {
    "domain": "example.com",
    "check_id": "uuid-v4",
    "timestamp": "2026-02-04T09:32:18.459703Z",
    "whois": { ... },
    "dns": { ... },
    "ssl": { ... },
    "ip_intelligence": { ... },
    "http_analysis": { ... },
    "blacklist": { ... },
    "port_scan": { ... },
    "subdomains": { ... },
    "risk_score": { ... }
  },
  "metadata": {
    "cached": false,
    "processing_time_ms": 40315,
    "api_version": "v1",
    "checks_performed": ["whois", "dns", "ssl", ...]
  }
}

Data Sections

1. WHOIS (data.whois)

{
  "creation_date": "2017-10-13T07:59:48Z",
  "expiration_date": "2026-10-13T07:59:48Z",
  "updated_date": "2025-01-15T06:24:03Z",
  "registrar": "Vautron Rechenzentrum AG",
  "age_days": 3036,
  "status": "ok https://icann.org/epp#ok",
  "name_servers": ["NS1.CONTABO.NET", "NS2.CONTABO.NET"],
  "dnssec": null,
  "registrant_org": null,
  "registrant_country": "RO",
  "data_source": "whois"
}

2. DNS (data.dns)

{
  "a_records": ["84.54.23.135"],
  "aaaa_records": [],
  "mx_records": [{"priority": 10, "host": "mail.example.com"}],
  "txt_records": ["v=spf1 include:_spf.google.com ~all"],
  "ns_records": ["ns1.example.com", "ns2.example.com"],
  "cname_records": [],
  "soa_record": {
    "mname": "ns1.example.com",
    "rname": "hostmaster.example.com",
    "serial": 1770195563,
    "refresh": 10800,
    "retry": 3600,
    "expire": 604800,
    "minimum": 3600
  },
  "has_spf": true,
  "has_dkim": false,
  "has_dmarc": true,
  "spf_record": null,
  "dmarc_record": null
}

3. SSL (data.ssl)

{
  "has_ssl": true,
  "is_valid": true,
  "is_self_signed": false,
  "is_expired": false,
  "is_wildcard": false,
  "issuer": "CN=R13, O=Let's Encrypt, C=US",
  "subject": "CN=example.com",
  "valid_from": "2025-12-22T12:48:47Z",
  "valid_until": "2026-03-22T12:48:46Z",
  "days_until_expiry": 46,
  "key_size": 2048,
  "signature_algorithm": "sha256WithRSAEncryption",
  "san": ["example.com", "www.example.com", "mail.example.com"]
}

4. IP Intelligence (data.ip_intelligence)

{
  "ip": "84.54.23.135",
  "reverse_dns": "server.provider.net",
  "geolocation": null,
  "asn": "AS51167",
  "isp": "Contabo GmbH",
  "organization": "Contabo GmbH",
  "is_datacenter": true,
  "is_residential": false,
  "hostname": "server.provider.net",
  "city": "Lauterbourg",
  "region": "Grand Est",
  "country": "France",
  "country_code": "FR",
  "coordinates": {"latitude": 48.9751, "longitude": 8.1785},
  "timezone": "Europe/Paris",
  "postal": "67630",
  "data_source": "ipinfo.io",
  "hosting_score": {
    "score": 50,
    "reasons": [],
    "is_trusted": false,
    "is_suspicious": false
  }
}

5. HTTP Analysis (data.http_analysis)

{
  "domain": "example.com",
  "http_status": 200,
  "https_status": 200,
  "has_https": true,
  "http_to_https_redirect": true,
  "final_url": "https://example.com/",
  "redirect_chain": [],
  "response_time_ms": 3351,
  "server": "Apache",
  "powered_by": null,
  "security_headers": {},
  "missing_security_headers": [
    {
      "header": "Strict-Transport-Security",
      "description": "HSTS - Forces HTTPS",
      "severity": "CRITICAL"
    },
    {
      "header": "X-Frame-Options",
      "description": "Prevents clickjacking",
      "severity": "HIGH"
    }
  ],
  "cookies": [],
  "technologies": ["WordPress", "jQuery", "Apache"],
  "cms": "WordPress",
  "frameworks": ["jQuery"],
  "has_robots_txt": true,
  "has_sitemap": true,
  "has_favicon": true,
  "error": null
}

6. Blacklist (data.blacklist)

{
  "domain": "example.com",
  "ip": "84.54.23.135",
  "is_blacklisted": false,
  "ip_blacklisted": false,
  "domain_blacklisted": false,
  "total_listings": 0,
  "ip_check": {
    "ip": "84.54.23.135",
    "is_blacklisted": false,
    "blacklist_count": 0,
    "clean_count": 4,
    "total_checked": 4,
    "listings": [],
    "clean_lists": ["Spamhaus ZEN", "SpamCop", "Barracuda", "SORBS"],
    "check_errors": []
  },
  "domain_check": {
    "domain": "example.com",
    "is_blacklisted": false,
    "blacklist_count": 0,
    "clean_count": 4,
    "total_checked": 4,
    "listings": [],
    "clean_lists": ["Spamhaus DBL", "URIBL", "URIBL Black", "SURBL"],
    "check_errors": []
  },
  "reputation_score": 100,
  "risk_level": "LOW"
}

Blacklists Checked:

List Type Description
Spamhaus ZEN IP Combined spam blocklist
SpamCop IP User-reported spam sources
Barracuda IP Barracuda reputation
SORBS IP Spam and relay blocking
Spamhaus DBL Domain Domain blocklist
URIBL Domain URI blocklist
URIBL Black Domain High-confidence spam URIs
SURBL Domain Spam URI realtime blocklist

7. Port Scan (data.port_scan)

{
  "ip": "84.54.23.135",
  "total_scanned": 9,
  "open_ports": [
    {
      "port": 443,
      "service": "HTTPS",
      "category": "web",
      "risk_level": "low",
      "banner": null
    },
    {
      "port": 22,
      "service": "SSH",
      "category": "remote_access",
      "risk_level": "low",
      "banner": "SSH-2.0-OpenSSH_8.7"
    }
  ],
  "closed_ports": [8080, 23, 21, 3389],
  "filtered_ports": [],
  "dangerous_open": [
    {
      "port": 3306,
      "service": "MySQL",
      "category": "database",
      "risk_level": "critical",
      "banner": "Host not allowed to connect"
    }
  ],
  "services_detected": ["HTTPS", "HTTP", "SSH", "MySQL"],
  "categories": {
    "web": [443, 80],
    "remote_access": [22],
    "database": [3306]
  },
  "security_issues": [
    {
      "severity": "CRITICAL",
      "port": 3306,
      "service": "MySQL",
      "issue": "Dangerous service MySQL exposed on port 3306"
    }
  ],
  "scan_summary": {
    "open_count": 5,
    "closed_count": 4,
    "filtered_count": 0,
    "dangerous_count": 1,
    "has_web": true,
    "has_email": true,
    "has_database": true,
    "has_remote_access": true
  }
}

Ports Scanned (Quick Scan):

Port Service Risk Level
21 FTP Medium
22 SSH Low
23 Telnet Critical
25 SMTP Low
80 HTTP Low
443 HTTPS Low
3306 MySQL Critical
3389 RDP High
8080 HTTP Proxy Medium

8. Subdomains (data.subdomains)

{
  "domain": "example.com",
  "subdomains": [
    "admin.example.com",
    "api.example.com",
    "mail.example.com",
    "www.example.com"
  ],
  "total_found": 93,
  "sources": {
    "certificate_transparency": ["mail.example.com", "www.example.com"],
    "dns_bruteforce": ["admin.example.com", "api.example.com"],
    "dns_records": ["mail.example.com"]
  },
  "live_subdomains": [
    {
      "subdomain": "www.example.com",
      "ip": "84.54.23.135",
      "http": 301,
      "https": 200
    }
  ],
  "error": null
}

Subdomain Sources:

  1. Certificate Transparency - crt.sh logs
  2. DNS Bruteforce - Common subdomain prefixes
  3. DNS Records - MX, NS, SOA records

9. Risk Score (data.risk_score)

{
  "total": 13,
  "level": "LOW",
  "factors": [
    {
      "factor": "domain_age",
      "score": 0,
      "weight": 0.2,
      "weighted_score": 0,
      "reason": "TRUSTED: Mature domain (3036 days, 8+ years)",
      "details": {"creation_date": "2017-10-13", "age_days": 3036}
    }
  ],
  "formula_breakdown": [
    {
      "category": "Domain Age",
      "raw_score": 0,
      "weight": 0.2,
      "weighted_score": 0,
      "formula": "0 × 0.2 = 0.0"
    }
  ],
  "formula_string": "Total = (0 × 0.2) + (0 × 0.15) + ... = 13",
  "thresholds": {
    "low": "0-25",
    "medium": "26-50",
    "high": "51-75",
    "critical": "76-100"
  },
  "is_new_domain": false,
  "is_suspicious": false,
  "is_blacklisted": false,
  "requires_manual_review": false
}

Risk Score Formula:

Category Weight Description
Domain Age 20% New domains = higher risk
SSL/TLS 15% Certificate validity
DNS Configuration 10% Complete DNS setup
Email Security 10% SPF, DKIM, DMARC
WHOIS Privacy 5% Registration info
IP Reputation 10% Datacenter/residential
HTTP Security 10% Security headers
Blacklist Status 15% DNSBL listings
Port Security 5% Exposed dangerous ports

Risk Levels:

Level Score Range Color
LOW 0-25 Green
MEDIUM 26-50 Yellow
HIGH 51-75 Orange
CRITICAL 76-100 Red

Examples

Quick Check (Basic)

curl -X POST "http://domain-check-api:11000/api/v1/check/check" \
  -H "Content-Type: application/json" \
  -d '{"domain": "google.com"}'

Full Check (All Options)

curl -X POST "http://domain-check-api:11000/api/v1/check/check" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "check_options": {
      "whois": true,
      "dns": true,
      "ssl": true,
      "ip_intelligence": true,
      "http_analysis": true,
      "blacklist": true,
      "port_scan": true,
      "subdomains": true
    }
  }'

Python Example

import requests

response = requests.post(
    "http://domain-check-api:11000/api/v1/check/check",
    json={
        "domain": "example.com",
        "check_options": {
            "whois": True,
            "dns": True,
            "ssl": True,
            "ip_intelligence": True,
            "http_analysis": True,
            "blacklist": True,
            "port_scan": True,
            "subdomains": True
        }
    }
)

data = response.json()
print(f"Risk Score: {data['data']['risk_score']['total']}")
print(f"Risk Level: {data['data']['risk_score']['level']}")
print(f"Is Blacklisted: {data['data']['blacklist']['is_blacklisted']}")

JavaScript Example

const response = await fetch('http://domain-check-api:11000/api/v1/check/check', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    domain: 'example.com',
    check_options: {
      whois: true,
      dns: true,
      ssl: true,
      ip_intelligence: true,
      http_analysis: true,
      blacklist: true,
      port_scan: true,
      subdomains: true
    }
  })
});

const data = await response.json();
console.log(`Risk Score: ${data.data.risk_score.total}`);
console.log(`Risk Level: ${data.data.risk_score.level}`);

Error Responses

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Domain parameter is required",
    "status": 400
  }
}

Error Codes:

Code Status Description
INVALID_REQUEST 400 Missing or invalid parameters
INVALID_DOMAIN 400 Domain format invalid
NOT_FOUND 404 Resource not found
INTERNAL_ERROR 500 Server error

Rate Limits

No rate limits currently (internal use).

Dashboard

Web interface available at: http://domain-check-api:11000/

Network Info

  • Host: domain-check-api
  • IP: 10.11.10.200
  • Port: 11000 (x1xxx = API/Gateway per Port Schema v2)
  • Protocol: HTTP (internal network)

Port Allocation (Production Environment - 1xxxx)

Service Port Category
API 11000 x1xxx = API/Gateway
PostgreSQL 12000 x20xx = Databases/PostgreSQL
Redis 12300 x23xx = Cache/Redis