# 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:**

```bash
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

```json
{
  "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`)

```json
{
  "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`)

```json
{
  "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`)

```json
{
  "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`)

```json
{
  "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`)

```json
{
  "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`)

```json
{
  "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`)

```json
{
  "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`)

```json
{
  "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`)

```json
{
  "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)

```bash
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)

```bash
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

```python
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

```javascript
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

```json
{
  "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 |