DNS Provider Auto-Detection

Status: ✅ Production Ready Version: 1.0.0 Last Updated: January 4, 2026

Overview

DNS Provider Auto-Detection is an intelligent system that automatically identifies which DNS provider manages your domain's nameservers. When configuring wildcard SSL certificates in Charon, you no longer need to manually select your DNS provider—Charon detects it for you in less than a second.

Who Benefits:

Managed Service Providers (MSPs): Managing multiple customer domains across different DNS providers
System Administrators: Setting up wildcard certificates for multiple domains
DevOps Teams: Automating certificate provisioning workflows
Small Businesses: Simplifying SSL certificate setup without technical expertise

Key Benefits:

⚡ Instant Detection: Identifies your DNS provider in 100-200ms
🎯 High Accuracy: Supports 10+ major DNS providers with confidence scoring
⏱️ Time Savings: Reduces setup time from 5-10 minutes to under 30 seconds
🛡️ Error Prevention: Eliminates misconfiguration from incorrect provider selection
🔄 Smart Caching: Remembers detection results for 1 hour to improve performance

How It Works

DNS auto-detection uses a simple but powerful process:

Domain Entry: You enter a wildcard domain like *.example.com
Nameserver Lookup: Charon queries DNS for your domain's nameservers
Pattern Matching: System matches nameservers against 10+ known provider patterns
Confidence Scoring: Calculates confidence level based on match strength
Auto-Selection: Automatically selects provider if confidence is high (≥80%)
Manual Override: You can always override the auto-detected provider

Technical Details:

Uses standard DNS NS (nameserver) record lookups
Matches nameserver hostnames against built-in pattern database
Case-insensitive pattern matching for reliability
Results cached in-memory for 1 hour
DNS lookup timeout: 10 seconds maximum
Typical detection time: 100-200ms
Cache hit time: <1ms

Example Detection Flow:

User enters: *.example.com
↓
DNS Lookup: example.com NS records
↓
Returns: ns1.cloudflare.com, ns2.cloudflare.com
↓
Pattern Match: "cloudflare.com" → Cloudflare
↓
Confidence: High (100% match)
↓
Result: ✓ Cloudflare detected (High confidence)

Supported DNS Providers

Charon has built-in detection for these major DNS providers:

Provider	Detection Pattern	Example Nameserver
Cloudflare	`cloudflare.com`	ns1.cloudflare.com
Amazon Route 53	`awsdns`	ns-123.awsdns-45.com
DigitalOcean	`digitalocean.com`	ns1.digitalocean.com
Google Cloud DNS	`googledomains.com`, `ns-cloud`	ns-cloud-a1.googledomains.com
Microsoft Azure DNS	`azure-dns`	ns1-01.azure-dns.com
Namecheap	`registrar-servers.com`	dns1.registrar-servers.com
GoDaddy	`domaincontrol.com`	ns01.domaincontrol.com
Hetzner	`hetzner.com`, `hetzner.de`	ns1.hetzner.com
Vultr	`vultr.com`	ns1.vultr.com
DNSimple	`dnsimple.com`	ns1.dnsimple.com

Note: If your DNS provider isn't automatically detected, you can still select it manually from the dropdown. Detection is a convenience feature, not a requirement.

Using Auto-Detection

In the Web UI

Step-by-Step: Creating a Wildcard Proxy Host

Navigate to Proxy Hosts
- Click Proxy Hosts in the sidebar
- Click Add Proxy Host button
Enter Domain Information
- Domain Name: Enter your domain (e.g., app.example.com)
- Check Force SSL checkbox
- Check Use Wildcard Domain checkbox
- Domain automatically changes to *.example.com
Auto-Detection Triggers
- Detection starts automatically (500ms after typing stops)
- Loading spinner appears: "Detecting DNS provider..."
- Detection completes in 100-200ms

Review Detection Result

High Confidence Example:

✓ Cloudflare detected (High confidence)

Nameservers:
• ns1.cloudflare.com
• ns2.cloudflare.com

[✓ Use Cloudflare]  [Select Manually]

Medium/Low Confidence Example:

⚠ DigitalOcean detected (Medium confidence)

Nameservers:
• ns1.digitalocean.com

We detected DigitalOcean, but confidence is medium.
Please verify this is correct.

[Use DigitalOcean]  [Select Manually]

No Detection Example:

✗ DNS provider not detected

Nameservers:
• ns1.customdns.example.com
• ns2.customdns.example.com

Please select your DNS provider manually.

[Select Manually]

Choose Action
- Use [Provider]: Auto-selects detected provider (recommended for high confidence)
- Select Manually: Opens provider dropdown for manual selection
Complete Configuration
- Select DNS credentials (or add new ones)
- Configure other proxy settings
- Click Save

Tips:

Detection works best with production domains already using their final nameservers
If detection fails, check that your domain's DNS is properly configured
Manual selection is always available as a fallback

Via API

Detect DNS Provider Endpoint

Manually trigger DNS provider detection for any domain.

curl -X POST https://your-charon-instance/api/v1/dns-providers/detect \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com"
  }'

Successful Detection Response:

{
  "domain": "example.com",
  "detected": true,
  "provider_type": "cloudflare",
  "nameservers": [
    "ns1.cloudflare.com",
    "ns2.cloudflare.com"
  ],
  "confidence": "high",
  "suggested_provider": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Cloudflare Account",
    "provider_type": "cloudflare",
    "is_default": true
  }
}

Failed Detection Response:

{
  "domain": "example.com",
  "detected": false,
  "nameservers": [
    "ns1.custom-dns.example.com"
  ],
  "confidence": "none",
  "suggested_provider": null
}

Error Response:

{
  "domain": "example.com",
  "detected": false,
  "nameservers": [],
  "confidence": "none",
  "error": "DNS lookup timeout: no nameservers found"
}

Request Parameters:

domain (string, required): Domain to detect (with or without wildcard *)

Response Fields:

domain (string): The base domain that was checked
detected (boolean): Whether a provider was successfully identified
provider_type (string): Type identifier for the detected provider
nameservers (array): List of nameserver hostnames found
confidence (string): Confidence level - "high", "medium", "low", or "none"
suggested_provider (object): Matching configured DNS provider (if any)
error (string): Error message if detection failed

Get Detection Patterns Endpoint

Retrieve the current built-in nameserver pattern database.

curl https://your-charon-instance/api/v1/dns-providers/detection-patterns \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "patterns": {
    "cloudflare.com": "cloudflare",
    "awsdns": "route53",
    "digitalocean.com": "digitalocean",
    "googledomains.com": "googleclouddns",
    "ns-cloud": "googleclouddns",
    "azure-dns": "azure",
    "registrar-servers.com": "namecheap",
    "domaincontrol.com": "godaddy",
    "hetzner.com": "hetzner",
    "hetzner.de": "hetzner",
    "vultr.com": "vultr",
    "dnsimple.com": "dnsimple"
  }
}

Response Format:

patterns (object): Map of nameserver patterns to provider type identifiers
Pattern keys are substring matches (case-insensitive)
Provider type values match Charon's DNS provider types

Use Cases

1. Quick Wildcard Certificate Setup

Scenario: MSP managing 50+ customer domains across multiple DNS providers

Before Auto-Detection:

Manually research DNS provider for each customer domain
Look up nameservers using external tools (dig, nslookup)
Risk of selecting wrong provider → certificate issuance fails
Time per domain: 5-10 minutes
Total time for 50 domains: 4-8 hours

With Auto-Detection:

Enter customer's wildcard domain
Provider detected automatically in <200ms
One-click to use detected provider
Time per domain: 30 seconds
Total time for 50 domains: 25 minutes

Time Savings: 90%+ reduction in configuration time

2. Multi-Customer Management

Scenario: Service provider managing customers using different DNS providers

Customer Portfolio:

*.customer1.com → Cloudflare (High confidence)
*.customer2.com → Route53 (High confidence)
*.customer3.com → DigitalOcean (High confidence)
*.customer4.com → Azure DNS (High confidence)
*.customer5.com → Namecheap (Medium confidence - verify)

Benefits:

No need to remember which customer uses which provider
Automatic correct provider suggestion
Confidence levels flag domains needing verification
Standardized workflow for all customers

3. Mixed Environment

Scenario: Company with domains split across multiple DNS providers

Infrastructure:

Production domains (*.prod.company.com) → Cloudflare
Development domains (*.dev.company.com) → DigitalOcean
Legacy domains (*.legacy.company.com) → Namecheap
Marketing domains (*.marketing.company.com) → Google Cloud DNS

Challenge: Developers frequently set up new wildcard proxies and forget which DNS provider manages each environment.

Solution: Auto-detection eliminates guesswork:

Developers enter domain
Correct provider automatically detected
Zero configuration errors
Faster deployments

4. Automation and CI/CD Integration

Scenario: Automated certificate provisioning in deployment pipelines

API Integration Example:

#!/bin/bash
# Automated wildcard certificate setup

DOMAIN="*.newcustomer.com"

# Detect DNS provider
DETECTION=$(curl -s -X POST \
  https://charon.company.internal/api/v1/dns-providers/detect \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"domain\": \"$DOMAIN\"}")

PROVIDER_TYPE=$(echo "$DETECTION" | jq -r '.provider_type')
CONFIDENCE=$(echo "$DETECTION" | jq -r '.confidence')

if [ "$CONFIDENCE" = "high" ]; then
  echo "✓ Detected $PROVIDER_TYPE with high confidence"
  # Proceed with automatic certificate issuance
  # ... create proxy host with detected provider ...
else
  echo "⚠ Low confidence detection, manual verification required"
  exit 1
fi

Benefits:

Fully automated provisioning
Self-documenting configuration
Confidence checks prevent misconfiguration
Error handling built-in

Troubleshooting

Detection Failed

Symptom: "Could not detect DNS provider" or "DNS provider not detected"

Possible Causes:

Domain Not Using Production Nameservers
- Domain recently registered
- DNS not yet pointed to production provider
- Still using registrar's default nameservers
DNS Provider Not in Built-in Database
- Using a custom or niche DNS provider
- Using self-hosted DNS servers
- Using a regional provider not in the pattern list
DNS Lookup Timeout or Network Issue
- DNS server not responding
- Network connectivity problem
- Firewall blocking DNS queries
Domain Doesn't Exist
- Typo in domain name
- Domain not yet registered
- Domain expired

Solutions:

Check Domain's Nameservers:

# Linux/Mac
dig NS example.com +short

# Windows
nslookup -type=NS example.com

Expected output:

ns1.cloudflare.com.
ns2.cloudflare.com.

Verify Nameserver Propagation:

# Check multiple DNS servers
dig @8.8.8.8 NS example.com +short
dig @1.1.1.1 NS example.com +short

Wait for DNS Propagation:

Initial DNS setup: Up to 48 hours
DNS changes: Up to 24 hours
Check again after propagation completes

Use Manual Provider Selection:

Click Select Manually button
Choose provider from dropdown
Detection is optional—manual selection always works

Check Network Connectivity:

# Test DNS connectivity
dig cloudflare.com +short

Wrong Provider Detected

Symptom: Detection suggests incorrect or unexpected provider

Possible Causes:

Domain Recently Migrated
- Domain moved from old provider to new provider
- DNS caching showing old records
- Propagation incomplete
Cached Detection Result
- Previous detection cached for 1 hour
- Domain's DNS changed since last detection
- Cache showing outdated information
Shared Nameserver Pattern
- Some hosting providers use shared nameserver pools
- Pattern match may be ambiguous
- Multiple providers with similar nameserver naming

Solutions:

Verify Current Nameservers:

dig NS example.com +short

Compare with detected nameservers in Charon's result.

Clear Charon's Detection Cache:

Cache expires automatically after 1 hour
Wait 60 minutes and try detection again
Or restart Charon to clear in-memory cache

Check DNS Provider Account:

Log into your DNS provider's control panel
Verify the nameservers listed there
Compare with Charon's detection result

Use Manual Override:

If detection is consistently wrong
Click Select Manually
Choose correct provider
Report issue via GitHub if pattern is incorrect

Low Confidence Warning

Symptom: "DigitalOcean detected (Medium confidence)" or "Low confidence"

What This Means:

Nameserver pattern match is partial or ambiguous
Provider type identified, but match isn't strong
Manual verification recommended before proceeding
Not necessarily an error—just requires confirmation

Confidence Levels Explained:

Level	Score	Meaning	Action
High	≥80%	Strong, unambiguous match	Safe to auto-select
Medium	50-79%	Probable match, some uncertainty	Verify before using
Low	1-49%	Weak match, high uncertainty	Manual selection recommended
None	0%	No match found	Must select manually

Recommended Actions:

Review Detected Provider Name
- Does it match your DNS provider?
- Check against your account/records
Check Nameservers List
- Examine the nameservers shown
- Do they look familiar?
- Do they match your provider's pattern?
Verify Against DNS Account
- Log into your DNS provider
- Compare nameservers
- Confirm they match
Decide:
- If match is correct: Click Use [Provider]
- If uncertain: Click Select Manually

Example:

⚠ DigitalOcean detected (Medium confidence)

Nameservers:
• ns1.digitalocean.com
• ns2.some-other-service.com  ← Mixed nameservers

We detected DigitalOcean, but one nameserver doesn't match
the typical pattern. Please verify this is correct.

Reason for Medium Confidence: Only 1 of 2 nameservers matches DigitalOcean's pattern.

Detection Takes Too Long

Symptom: Detection hangs or takes more than 5 seconds

Possible Causes:

DNS server not responding
Network latency or packet loss
Domain's authoritative DNS servers offline

Built-in Protections:

Detection timeout: 10 seconds maximum
After timeout, detection fails gracefully
Error message: "DNS lookup timeout"

Solutions:

Wait for timeout (max 10 seconds)
Check network connectivity
Verify domain's DNS is operational
Use manual provider selection

Cache Showing Outdated Information

Symptom: Detection shows old provider after DNS migration

Explanation:

Successful detections cached for 1 hour
Improves performance for repeated requests
May show outdated results during cache window

Solutions:

Wait for Cache Expiration:

Cache automatically expires after 1 hour
Try detection again after 60 minutes

Restart Charon:

Cache is in-memory (not persistent)
Restarting clears all cached detections
Only necessary if you need immediate refresh

Use Manual Selection:

Override cached detection
Select correct provider manually
Detection cache doesn't affect manual selection

API Reference

POST /api/v1/dns-providers/detect

Detects DNS provider for a domain based on nameserver lookup

Authentication: Required (Bearer token)

Permissions: Same as DNS provider management

Request:

POST /api/v1/dns-providers/detect
Host: your-charon-instance
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "domain": "example.com"
}

Request Body:

Field	Type	Required	Description
`domain`	string	Yes	Domain to detect (with or without `*.` wildcard)

Valid Domain Formats:

example.com → base domain
*.example.com → wildcard (auto-stripped to base domain)
subdomain.example.com → uses example.com for detection

Response: (200 OK)

{
  "domain": "example.com",
  "detected": true,
  "provider_type": "cloudflare",
  "nameservers": [
    "ns1.cloudflare.com",
    "ns2.cloudflare.com"
  ],
  "confidence": "high",
  "suggested_provider": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Cloudflare Account",
    "provider_type": "cloudflare",
    "is_default": true,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  }
}

Response Fields:

Field	Type	Description
`domain`	string	Base domain that was checked
`detected`	boolean	`true` if provider was identified, `false` otherwise
`provider_type`	string	Provider type identifier (e.g., `"cloudflare"`, `"route53"`)
`nameservers`	array	List of nameserver hostnames (always returned, even if empty)
`confidence`	string	Confidence level: `"high"`, `"medium"`, `"low"`, or `"none"`
`suggested_provider`	object\|null	Matching configured DNS provider, or `null` if none found
`error`	string	Error message (only present if detection failed)

Confidence Scoring:

High (≥80%): Most nameservers match pattern, strong confidence
Medium (50-79%): Some nameservers match, partial confidence
Low (1-49%): Few nameservers match, weak confidence
None (0%): No nameservers match any pattern

Error Responses:

400 Bad Request - Invalid domain

{
  "error": "domain is required"
}

401 Unauthorized - Missing or invalid token

{
  "error": "Unauthorized"
}

500 Internal Server Error - Detection failure

{
  "domain": "example.com",
  "detected": false,
  "nameservers": [],
  "confidence": "none",
  "error": "DNS lookup timeout: no nameservers found"
}

Status Codes:

200 OK - Detection completed (success or failure)
400 Bad Request - Invalid request parameters
401 Unauthorized - Authentication required or failed
500 Internal Server Error - Unexpected server error

Rate Limiting:

Detection results cached for 1 hour
Repeated requests for same domain return cached result
No explicit rate limit (DNS timeout provides natural throttling)

Example Usage:

// JavaScript/Node.js
const detectDNSProvider = async (domain) => {
  const response = await fetch('https://charon.example.com/api/v1/dns-providers/detect', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain })
  });

  if (!response.ok) {
    throw new Error(`Detection failed: ${response.status}`);
  }

  const result = await response.json();

  if (result.confidence === 'high') {
    console.log(`✓ ${result.provider_type} detected with high confidence`);
    return result.suggested_provider;
  } else {
    console.log(`⚠ Low confidence detection, manual selection recommended`);
    return null;
  }
};

# Python
import requests

def detect_dns_provider(domain, token):
    url = 'https://charon.example.com/api/v1/dns-providers/detect'
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
    payload = {'domain': domain}

    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()

    result = response.json()

    if result['confidence'] == 'high':
        print(f"✓ {result['provider_type']} detected with high confidence")
        return result['suggested_provider']
    else:
        print(f"⚠ Low confidence detection")
        return None

# Bash with jq
detect_dns_provider() {
  local domain=$1
  local token=$2

  curl -s -X POST \
    "https://charon.example.com/api/v1/dns-providers/detect" \
    -H "Authorization: Bearer $token" \
    -H "Content-Type: application/json" \
    -d "{\"domain\": \"$domain\"}" | jq '
      if .confidence == "high" then
        "✓ \(.provider_type) detected (high confidence)"
      else
        "⚠ Low confidence: \(.confidence)"
      end
    '
}

GET /api/v1/dns-providers/detection-patterns

Returns built-in nameserver pattern database

Authentication: Required (Bearer token)

Permissions: Same as DNS provider management

Request:

GET /api/v1/dns-providers/detection-patterns
Host: your-charon-instance
Authorization: Bearer YOUR_TOKEN

Response: (200 OK)

{
  "patterns": {
    "cloudflare.com": "cloudflare",
    "awsdns": "route53",
    "digitalocean.com": "digitalocean",
    "googledomains.com": "googleclouddns",
    "ns-cloud": "googleclouddns",
    "azure-dns": "azure",
    "registrar-servers.com": "namecheap",
    "domaincontrol.com": "godaddy",
    "hetzner.com": "hetzner",
    "hetzner.de": "hetzner",
    "vultr.com": "vultr",
    "dnsimple.com": "dnsimple"
  }
}

Response Format:

patterns (object): Map of nameserver patterns to provider types
Keys: Substring pattern to match in nameserver hostname (case-insensitive)
Values: Provider type identifier used in Charon

Pattern Matching:

Case-insensitive substring matching
If any nameserver contains pattern, it's a match
Multiple patterns can match the same provider (e.g., Google Cloud DNS)
Score calculated based on percentage of nameservers matching

Error Responses:

401 Unauthorized - Missing or invalid token

{
  "error": "Unauthorized"
}

Status Codes:

200 OK - Patterns returned successfully
401 Unauthorized - Authentication required or failed

Example Usage:

# Retrieve all patterns
curl https://charon.example.com/api/v1/dns-providers/detection-patterns \
  -H "Authorization: Bearer YOUR_TOKEN" | jq .

Use Cases:

Building custom detection tools
Debugging detection issues
Understanding which providers are supported
Verifying pattern database version

Performance

Detection Speed

Typical Performance:

First Detection: 100-200ms (includes DNS lookup)
Cached Detection: <1ms (from in-memory cache)
DNS Timeout: 10 seconds maximum (prevents hanging)

Performance Factors:

Factor	Impact	Notes
DNS server latency	50-150ms	External dependency
Pattern matching	<1ms	In-memory operation
Database lookup	1-5ms	Optional, for provider suggestion
Cache hit	<1ms	In-memory hash map
Network latency	Varies	Between Charon and DNS servers

Performance Optimization:

Results cached for 1 hour
Reduces repeated DNS lookups
Cache hit rate typically 60-80%+ for active domains
Pattern matching is O(1) hash map lookup

Caching Behavior

Cache Configuration:

Setting	Value	Rationale
Success TTL	1 hour	Nameservers rarely change
Failed TTL	5 minutes	Allow quick retry after transient failures
Storage	In-memory	Fast access, automatic cleanup
Persistence	None	Cache cleared on restart

Cache Key: Base domain (e.g., example.com)

Cache Invalidation:

Automatic expiration after TTL
No manual invalidation API
Restart Charon to clear all cached entries

Cache Hit Scenarios:

Same domain detected multiple times
Multiple wildcard proxies for same domain
Repeated API calls within 1-hour window

Cache Miss Scenarios:

First detection for a domain
Cache entry expired (>1 hour old)
Domain's DNS recently changed
Charon restarted

Performance Impact:

Cache hit: <1ms response time
Cache miss: 100-200ms response time (DNS lookup required)
Cache reduces DNS query load by ~80%

Scalability

System Limits:

Metric	Limit	Notes
Concurrent detections	~100s	Limited by DNS resolver
Cache size	Unbounded	In-memory, grows with unique domains
Memory per entry	~1-2 KB	Includes result + metadata
DNS timeout	10 seconds	Per-request maximum

Recommendations for High-Volume Usage:

Deploy Charon with adequate memory (cache can grow)
Consider DNS server location/latency
Monitor cache hit rate for optimization
Use dedicated DNS resolver for production

Security

Authentication & Authorization

Endpoint Security:

All detection endpoints require authentication
Bearer token must be provided in Authorization header
Same permission model as DNS provider management
Unauthorized requests return 401 Unauthorized

Permission Requirements:

User must have access to DNS provider features
No special permissions required for detection
Detection doesn't expose sensitive credentials
Only domain metadata returned (nameservers)

Data Privacy

What Charon Collects:

✅ Domain name (from user input)
✅ Nameserver hostnames (from DNS lookup)
✅ Detection result (cached for 1 hour)

What Charon Does NOT Collect:

❌ DNS credentials or API keys
❌ Certificate private keys
❌ User browsing history
❌ DNS query contents
❌ Personal identifiable information (beyond domain ownership)

Data Storage:

Detection results cached in-memory only
No persistent storage of detection data
Cache cleared on restart
No logging of detected domains (unless debug logging enabled)

Third-Party Access:

No data sent to third-party services
DNS lookups go directly to configured DNS resolvers
No analytics or telemetry for detection feature

DNS Query Security

Query Characteristics:

Standard DNS NS (nameserver) record lookups
Uses system DNS resolver by default
Respects DNS timeout (10 seconds)
No recursive queries or zone transfers
Read-only DNS operations

Security Measures:

DNS timeout prevents hanging on unresponsive servers
No user-controlled DNS servers (uses system config)
Input validation on domain names
Error handling for malformed responses

Network Security:

DNS queries over UDP/TCP port 53
No TLS/HTTPS for DNS (standard DNS protocol)
Consider using DNS-over-HTTPS (DoH) in system resolver for privacy
Firewall must allow outbound DNS (port 53)

Attack Surface

Potential Threats:

Threat	Mitigation	Risk Level
DNS spoofing	Use trusted DNS resolvers	Low
Cache poisoning	1-hour TTL limits impact	Low
DoS via slow DNS	10-second timeout	Low
Information disclosure	Only public DNS data returned	Very Low
Credential exposure	Detection doesn't access credentials	None

Security Best Practices:

Use trusted, secure DNS resolvers (e.g., 1.1.1.1, 8.8.8.8)
Enable DNSSEC validation if possible
Monitor detection error rates for anomalies
Review detection logs for suspicious patterns

Limitations

1. Built-in Providers Only

Limitation: Currently supports 10 major DNS providers

Impact:

Custom DNS providers won't be auto-detected
Niche/regional providers not in pattern database
Self-hosted DNS servers not recognized

Workaround:

Use manual provider selection
Request provider pattern addition via GitHub issue
Contribute pattern via pull request

Future Enhancement: User-configurable custom patterns

2. Shared Nameserver Patterns

Limitation: Some hosting providers use shared nameserver pools

Impact:

Nameserver patterns may be ambiguous
Detection may suggest incorrect provider
Confidence scoring may be lower

Example:

Some resellers use white-labeled nameservers
Shared hosting platforms with generic nameserver names

Workaround:

Verify detection result against your account
Use manual selection if detection is incorrect
Report ambiguous patterns for improvement

3. DNS Propagation Delays

Limitation: DNS changes take up to 48 hours to propagate globally

Impact:

Detection may show old/outdated provider
Recent migrations not immediately reflected
Newly registered domains may fail detection

Workaround:

Wait for DNS propagation to complete
Check nameservers with dig or nslookup
Use manual selection during migration period
Re-run detection after propagation

4. Network Dependency

Limitation: Requires DNS connectivity to function

Impact:

Offline/airgapped environments cannot use auto-detection
Network issues cause detection failures
DNS server outages prevent detection

Workaround:

Use manual provider selection in offline environments
Ensure DNS connectivity for auto-detection
Detection failure doesn't block manual configuration

5. Cache Duration

Limitation: Results cached for 1 hour

Impact:

Recent DNS changes not immediately reflected
Cache may show outdated information
No manual cache invalidation

Workaround:

Wait 60 minutes for cache expiration
Restart Charon to clear cache immediately
Use manual selection to override cached result

Rationale: 1-hour cache significantly improves performance while nameservers rarely change

6. No Batch Detection

Limitation: Only one domain detected at a time

Impact:

Cannot detect multiple domains in one request
API requires separate call per domain
Bulk operations require iteration

Workaround:

Implement client-side batching
Leverage cache for repeated domains
Use async/parallel API calls

Future Enhancement: Batch detection endpoint planned

Best Practices

1. Verify Detection Results

Always Review Before Proceeding:

✅ Check detected provider name matches your expectation
✅ Review nameserver list for accuracy
✅ Verify confidence level is acceptable
✅ Compare with your DNS account if uncertain

Why:

Detection is not 100% accurate
DNS configuration can be complex
Wrong provider = certificate issuance failure

Example Review Checklist:

✓ Provider name: "Cloudflare" ← Correct?
✓ Nameservers: ns1.cloudflare.com ← Recognized?
✓ Confidence: "High" ← Acceptable?
✓ Matches DNS account? ← Verified!

2. High Confidence Only for Production

Recommendation: Only use auto-selection for "High" confidence detections

Confidence Guidelines:

Environment	Minimum Confidence	Action
Production	High (≥80%)	Auto-select OK
Staging	Medium (≥50%)	Verify first
Development	Low/Any	Manual verify

Why:

Production certificate failures are costly
High confidence = strong, unambiguous match
Medium/Low = requires human verification

3. Keep Manual Override Available

Always Provide Manual Selection:

Don't remove "Select Manually" button
Auto-detection is a convenience, not requirement
Users may know better than detection algorithm
Edge cases always exist

UI Pattern:

✓ Cloudflare detected (High confidence)
[✓ Use Cloudflare]  [Select Manually]  ← Keep both options!

4. Test Before Production

Test Detection on Development Domains First:

# Test detection
curl -X POST https://charon-dev.internal/api/v1/dns-providers/detect \
  -H "Authorization: Bearer $DEV_TOKEN" \
  -d '{"domain": "dev.example.com"}'

# Verify result
# → Check provider type
# → Check confidence level
# → Compare with known DNS provider

# If successful, proceed to production

Benefits:

Identify detection issues early
Verify your DNS setup is detectable
Test integration before production use

5. Monitor Detection Success Rates

Track Metrics:

Detection success rate (detected vs. not detected)
Confidence distribution (high/medium/low/none)
Manual override rate (users choosing manual selection)
Detection errors (timeouts, failures)

Use Metrics to:

Identify common providers not in database
Detect DNS configuration issues
Improve pattern database
Optimize cache hit rate

Example Monitoring:

Detection Stats (Last 7 Days):
- Total detections: 1,234
- Successful (high confidence): 987 (80%)
- Medium/Low confidence: 123 (10%)
- Failed/No match: 124 (10%)
- Manual overrides: 45 (3.6%)

6. Report Detection Issues

Help Improve Detection:

When detection fails or is incorrect:

✅ Note the domain (if not sensitive)
✅ Check actual nameservers: dig NS domain.com +short
✅ Note expected provider
✅ Note what Charon detected
✅ Report via GitHub issue

Example GitHub Issue:

**Title:** Detection fails for Linode DNS

**Description:**
- Domain: example.com
- Expected provider: Linode
- Detected provider: None
- Nameservers: ns1.linode.com, ns2.linode.com
- Confidence: None

**Suggested Fix:**
Add pattern: "linode.com" → "linode"

Benefits:

Helps other users with same provider
Improves detection accuracy
Expands supported provider list

7. Cache Awareness

Understand Caching Behavior:

✅ First detection: 100-200ms
✅ Repeat detection (within 1 hour): <1ms
✅ After 1 hour: Fresh DNS lookup

Considerations:

Don't rely on immediate updates after DNS changes
Wait 60 minutes or restart Charon after migration
Cache improves performance—embrace it!

When Cache Matters:

DNS provider migration in progress
Testing detection repeatedly
Debugging detection issues

Cache Doesn't Affect:

Manual provider selection
Certificate issuance
Existing proxy host configurations

Future Enhancements

Planned Features

1. Custom Nameserver Pattern Definitions

Allow users to add custom provider patterns
Define patterns via Web UI or configuration file
Support for internal/private DNS providers
Pattern validation and testing tools

2. Detection History and Statistics

View past detection results
Success/failure rates per provider
Confidence distribution charts
Most common providers in your environment

3. Support for Additional DNS Providers

Add more regional providers
Support for niche/specialized DNS services
Community-contributed pattern library
Automatic pattern updates

4. Detection Caching Configuration

Configurable cache TTL (currently fixed at 1 hour)
Per-provider cache settings
Manual cache invalidation API
Cache statistics dashboard

5. Batch Domain Detection

Detect multiple domains in one API call
Bulk import with auto-detection
CSV upload with detection report
Parallel detection processing

6. Enhanced Confidence Scoring

Machine learning-based scoring
Historical accuracy feedback
Provider-specific confidence thresholds
Confidence explanation details

7. Detection Webhooks

Notify external systems of detection results
Integrate with automation workflows
Detection event logging
Real-time detection monitoring

Community Contributions

We Welcome:

🌟 New provider pattern additions
🐛 Bug reports for incorrect detections
💡 Feature requests and ideas
📝 Documentation improvements
🧪 Test cases for edge scenarios

How to Contribute:

Add a Provider Pattern:

# 1. Fork repository
# 2. Edit: backend/internal/services/dns_detection_service.go
# 3. Add pattern to BuiltInNameservers map:

var BuiltInNameservers = map[string]string{
    // ...existing patterns...

    // Your new provider
    "newprovider.com": "newprovider",
}

# 4. Add test case to: backend/internal/services/dns_detection_service_test.go
# 5. Submit pull request

Report Detection Issues:

GitHub Issues: https://github.com/Wikid82/Charon/issues
Label: enhancement, dns-detection
Provide: Domain example, nameservers, expected provider

Share Use Cases:

How are you using auto-detection?
What workflows does it enable?
What features would be helpful?

Feedback Welcome

Help Us Improve:

Share your experience with auto-detection
Report detection accuracy issues
Suggest new provider patterns
Request feature enhancements

Contact:

GitHub Issues: https://github.com/Wikid82/Charon/issues
GitHub Discussions: https://github.com/Wikid82/Charon/discussions
Documentation: https://docs.charon.example.com
Community: https://community.charon.example.com

DNS Challenge Support - Core wildcard certificate feature using DNS-01 challenges
DNS Provider Configuration - Setting up and managing DNS provider credentials
Multi-Credential Management - Advanced multi-provider and multi-account setups
API Reference - Complete Charon API documentation
Security Overview - Security guidelines for Charon deployment

Changelog

Version 1.0.0 (January 2026)

Initial Release

✨ DNS provider auto-detection for 10+ major providers
🚀 Web UI integration with ProxyHost form
🔌 RESTful API endpoints (/detect, /detection-patterns)
⚡ Performance: 100-200ms typical detection time
🗄️ 1-hour in-memory caching
🎯 Confidence scoring (high/medium/low/none)
🧪 Comprehensive test coverage (86.3% backend, 85.67% frontend)
📚 Full API and user documentation
🔒 Security: Authentication required, no credential exposure
♿ Accessibility: ARIA labels, keyboard navigation

Supported Providers:

Cloudflare
Amazon Route 53
DigitalOcean
Google Cloud DNS
Microsoft Azure DNS
Namecheap
GoDaddy
Hetzner
Vultr
DNSimple

Technical Details:

Pattern-based nameserver matching
Automatic wildcard domain normalization
Thread-safe cache implementation
10-second DNS lookup timeout
Graceful fallback to manual selection
Zero breaking changes to existing functionality

FAQ

Q: Is auto-detection required to use wildcard certificates? A: No, it's optional. Manual provider selection always works.

Q: How accurate is auto-detection? A: Very accurate for the 10+ built-in providers. Confidence scoring helps identify uncertain matches.

Q: What happens if my provider isn't detected? A: Simply select your provider manually—detection is a convenience feature, not a requirement.

Q: Can I add support for my custom DNS provider? A: Currently, only built-in patterns are supported. Custom patterns are planned for future releases. You can contribute patterns via GitHub.

Q: Does detection work offline? A: No, detection requires DNS connectivity. Use manual selection in offline/airgapped environments.

Q: How long are results cached? A: 1 hour for successful detections, 5 minutes for failures.

Q: Can I clear the detection cache? A: Cache expires automatically. Restart Charon to clear immediately.

Q: Does detection expose my DNS credentials? A: No, detection only looks up public nameserver records. No credentials are accessed.

Q: What if detection suggests the wrong provider? A: Use "Select Manually" to override. Report the issue on GitHub to help improve accuracy.

Q: How fast is detection? A: Typically 100-200ms for first detection, <1ms for cached results.

Support

Questions or Issues?

📖 Documentation: https://docs.charon.example.com
🐛 GitHub Issues: https://github.com/Wikid82/Charon/issues
💬 GitHub Discussions: https://github.com/Wikid82/Charon/discussions
👥 Community Forum: https://community.charon.example.com

Feature Requests:

Submit via GitHub Issues with label enhancement
Describe your use case and desired functionality
Include examples and expected behavior

Bug Reports:

Submit via GitHub Issues with label bug
Include: Domain (if not sensitive), nameservers, expected vs. actual result
Attach detection API response if available

Thank you for using Charon! 🚀

Overview​

How It Works​

Supported DNS Providers​

Using Auto-Detection​

In the Web UI​

Via API​

Use Cases​

1. Quick Wildcard Certificate Setup​

2. Multi-Customer Management​

3. Mixed Environment​

4. Automation and CI/CD Integration​

Troubleshooting​

Detection Failed​

Wrong Provider Detected​

Low Confidence Warning​

Detection Takes Too Long​

Cache Showing Outdated Information​

API Reference​

POST /api/v1/dns-providers/detect​

GET /api/v1/dns-providers/detection-patterns​

Performance​

Detection Speed​

Caching Behavior​

Scalability​

Security​

Authentication & Authorization​

Data Privacy​

DNS Query Security​

Attack Surface​

Limitations​

1. Built-in Providers Only​

2. Shared Nameserver Patterns​

3. DNS Propagation Delays​

4. Network Dependency​

5. Cache Duration​

6. No Batch Detection​

Best Practices​

1. Verify Detection Results​

2. High Confidence Only for Production​

3. Keep Manual Override Available​

4. Test Before Production​

5. Monitor Detection Success Rates​

6. Report Detection Issues​

7. Cache Awareness​

Future Enhancements​

Planned Features​

Community Contributions​

Feedback Welcome​

Related Documentation​

Changelog​

Version 1.0.0 (January 2026)​

FAQ​

Support​

Overview

How It Works

Supported DNS Providers

Using Auto-Detection

In the Web UI

Via API

Use Cases

1. Quick Wildcard Certificate Setup

2. Multi-Customer Management

3. Mixed Environment

4. Automation and CI/CD Integration

Troubleshooting

Detection Failed

Wrong Provider Detected

Low Confidence Warning

Detection Takes Too Long

Cache Showing Outdated Information

API Reference

POST /api/v1/dns-providers/detect

GET /api/v1/dns-providers/detection-patterns

Performance

Detection Speed

Caching Behavior

Scalability

Security

Authentication & Authorization

Data Privacy

DNS Query Security

Attack Surface

Limitations

1. Built-in Providers Only

2. Shared Nameserver Patterns

3. DNS Propagation Delays

4. Network Dependency

5. Cache Duration

6. No Batch Detection

Best Practices

1. Verify Detection Results

2. High Confidence Only for Production

3. Keep Manual Override Available

4. Test Before Production

5. Monitor Detection Success Rates

6. Report Detection Issues

7. Cache Awareness

Future Enhancements

Planned Features

Community Contributions

Feedback Welcome

Related Documentation

Changelog

Version 1.0.0 (January 2026)

FAQ

Support