Skip to main content

Securedns Hostcheck

The SecureDNS Host Check API provides real-time hostname filtering capabilities for parental control and content filtering systems. This endpoint allows you to verify whether access to specific hostnames should be allowed, refused, or ignored based on configured security rules and policies.

Base URL: https://control.zequenze.com/api/v1

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The SecureDNS Host Check API is designed for organizations and service providers who need to implement DNS-level content filtering and parental controls. This service acts as a real-time decision engine that evaluates hostname requests against configured security policies and returns appropriate actions.

Key Features:

  • Real-time hostname evaluation against security policies
  • Categorized content filtering with customizable ACL rules
  • Response caching for improved performance
  • Detailed logging and audit trail for compliance
  • Subnet-based rule matching for network-level controls

Common Integration Scenarios:

  • DNS resolvers implementing parental controls
  • Network security appliances requiring content filtering
  • ISP services offering family-safe internet packages
  • Corporate networks enforcing acceptable use policies
  • Educational institutions blocking inappropriate content

The API uses a simple request-response pattern where you submit a hostname for evaluation and receive an action directive along with supporting metadata such as matched rules, categories, and redirect information.

Endpoints

GET /securedns_hostcheck/

Description: Evaluates a hostname against configured SecureDNS policies to determine if access should be allowed, refused, or ignored. This endpoint performs real-time policy matching and returns detailed information about the decision including matched categories, ACL rules, and any redirect instructions.

Use Cases:

  • DNS resolver checking if a domain should be blocked before resolution
  • Network gateway validating web requests against parental control policies
  • Security appliance implementing corporate content filtering
  • Educational network enforcing acceptable use policies
  • ISP providing family-safe internet filtering services

Full URL Example:

https://control.zequenze.com/api/v1/securedns_hostcheck/?hostname=example.com&client_ip=192.168.1.100

Parameters:

Parameter Type In Required Description
hostname string query Yes The hostname or domain to check against SecureDNS policies
client_ip string query No Client IP address for subnet-based rule matching
policy_id string query No Specific policy UUID to evaluate against

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/securedns_hostcheck/?hostname=social-media.com&client_ip=192.168.1.100" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response (Allowed):

[
  {
    "action": "A",
    "redirect_ip": "0.0.0.0",
    "match_subnet": "192.168.1.0/24",
    "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "category": "news",
    "acl": "allow_news_sites",
    "cached": true,
    "response_time": 0.045
  }
]

Example Response (Blocked):

[
  {
    "action": "R",
    "redirect_ip": "10.0.0.1",
    "match_subnet": "192.168.1.0/24",
    "uuid": "a1b2c3d4-58cc-4372-a567-0e02b2c3d480",
    "category": "adult_content",
    "acl": "block_adult_family_policy",
    "cached": false,
    "response_time": 0.032
  }
]

Response Fields:

Field Type Description
action string Action to take: "A" (Allow), "R" (Refuse), or "I" (Ignore)
redirect_ip string IP address to redirect blocked requests to (0.0.0.0 if no redirect)
match_subnet string Subnet that matched the client IP for rule application
uuid string Unique identifier of the matched rule
category string Content category that was matched (e.g., "social_media", "adult_content")
acl string Name of the Access Control List rule that was applied
cached boolean Whether this response was served from cache
response_time number Processing time in seconds

Response Codes:

Status Description
200 Rule matched and request allowed - Returns policy decision
401 Request not authorized - Invalid or missing API token
403 Request forbidden/not allowed - Access denied by policy
404 No rule matched OR Rules matched and request not allowed

Common Use Cases

Use Case 1: DNS Resolver Integration

Integrate SecureDNS checking into a DNS resolver to provide parental controls. Before resolving any hostname, query the API to determine if the request should proceed, be blocked, or redirected to a safe page.

Use Case 2: Corporate Network Filtering

Implement enterprise content filtering by checking web requests against corporate acceptable use policies. Block access to social media, streaming, or other non-work-related categories during business hours.

Use Case 3: Educational Institution Safety

Schools and universities can use this API to ensure students access only educational and age-appropriate content, blocking adult content, gaming sites, and other distracting categories.

Use Case 4: ISP Family Plans

Internet service providers can offer family-safe internet packages by routing DNS requests through this filtering service, automatically blocking inappropriate content for subscribers.

Use Case 5: Home Network Protection

Home router firmware can integrate this API to provide parents with easy-to-configure content filtering without requiring technical expertise in DNS configuration.

Best Practices

Performance Optimization:

  • Cache responses locally when the cached field is true to reduce API calls
  • Implement connection pooling and keep-alive for high-volume integrations
  • Monitor the response_time field to track API performance
  • Consider implementing client-side caching with appropriate TTL values

Error Handling:

  • Always handle 404 responses appropriately - they can indicate either no rule match or blocked content
  • Implement fallback behavior when the API is unavailable (fail-open vs fail-closed policy)
  • Log API responses for troubleshooting and compliance auditing
  • Retry failed requests with exponential backoff

Security Considerations:

  • Protect API tokens and rotate them regularly
  • Use HTTPS for all API communications
  • Log all filtering decisions for security auditing
  • Validate client IP addresses when using subnet-based rules

Integration Tips:

  • Test with various hostname formats (www vs non-www, subdomains, internationalized domains)
  • Monitor API rate limits and implement appropriate throttling
  • Use the policy_id parameter when you need to test against specific policies
  • Implement proper timeout handling for real-time DNS integration scenarios
Back to top