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 queryverify whether aaccess to specific hostnamehostnames should be allowed, refused, or ignored based on your configured SecureDNSsecurity 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 implementingorganizations real-timeand service providers who need to implement DNS-level content filtering and parental control systems.controls. This APIservice categoryacts containsas a singlereal-time butdecision powerful endpointengine that evaluates hostnameshostname requests against your configured SecureDNSsecurity policies and returns filteringappropriate decisions.actions.

Key Features:

  • Real-time hostname evaluation against parentalsecurity controlpolicies
Categorized content filtering with customizable ACL rules Three-stateResponse responsecaching system:for Allowimproved (A), Refuse (R), or Ignore (I)performance RequestDetailed logging forand audit andtrail monitoringfor purposescompliance IntegrationSubnet-based withrule existingmatching SecureDNSfor parentalnetwork-level control servicecontrols

Common Integration Scenarios:

  • DNS filteringresolvers appliancesimplementing andparental routers
Parental control software applicationscontrols Network security gatewaysappliances requiring content filtering CustomISP proxyservices andoffering firewallfamily-safe solutionsinternet packages Corporate networks enforcing acceptable use policies Educational institutioninstitutions blocking inappropriate content filters

The endpointAPI isuses optimizeda simple request-response pattern where you submit a hostname for high-frequency queriesevaluation and canreceive bean integratedaction intodirective DNSalong resolutionwith workflows,supporting proxymetadata servers,such oras anymatched applicationrules, requiringcategories, real-timeand hostnameredirect filtering decisions.information.

Endpoints

GET /securedns_hostcheck/

Description: Evaluates a hostname against yourconfigured SecureDNS parentalpolicies controlto policiesdetermine if access should be allowed, refused, or ignored. This endpoint performs real-time policy matching and returns adetailed filteringinformation decision.about Thisthe endpointdecision logsincluding eachmatched requestcategories, forACL audit purposesrules, and returnsany oneredirect of three possible actions: Allow (A) for permitted content, Refuse (R) for blocked content, or Ignore (I) for uncategorized content that should use default policies.instructions.

Use Cases:

  • DNS resolver integrationchecking forif real-timea filteringdomain should be blocked before resolution
  • ProxyNetwork servergateway validating web requests against parental control policies
Security appliance implementing corporate content filtering ParentalEducational controlnetwork applicationenforcing hostnameacceptable validationuse policies NetworkISP applianceproviding policyfamily-safe enforcement Educational contentinternet filtering systemsservices

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 (e.g., "example.com")
client_ip string query No Client IP address for loggingsubnet-based andrule policy applicationmatching
user_idpolicy_id string query No UserSpecific identifierpolicy forUUID personalizedto filteringevaluate rulesagainst

cURL Example:

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

Example Response (Allowed):

[
  {
  "hostname": "educational-site.com",
    "action": "A",
    "category"redirect_ip": "education"0.0.0.0",
    "rule_id": "edu_allow_001",
  "timestamp": "2024-01-15T10:30:00Z",
  "client_ip"match_subnet": "192.168.1.100"0/24",
    "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "category": "news",
    "acl": "allow_news_sites",
    "cached": true,
    "response_time": 0.045
  }
]

Example Response (Refused)Blocked):

[
  {
  "hostname": "blocked-site.com",
    "action": "R",
    "redirect_ip": "10.0.0.1",
    "match_subnet": "192.168.1.0/24",
    "uuid": "a1b2c3d4-58cc-4372-a567-0e02b2c3d480",
    "category": "adult_content",
    "rule_id"acl": "adult_block_001"block_adult_family_policy",
    "reason"cached": "Parental control policy violation",false,
    "timestamp"response_time": "2024-01-15T10:30:00Z",
  "client_ip": "192.168.1.100"0.032
  }
]

Example Response (Ignored):Fields:

{
Field Type Description action string Action to take: "hostname":A" "unknown-site.com"(Allow), "action":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., "category": "uncategorized"social_media", "timestamp":adult_content") "2024-01-15T10:30:00Z", "client_ip":"192.168.1.100"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 Success - Rule matched and request allowed - Returns policy decision
401 UnauthorizedRequest not authorized - Invalid or missing API token
403 ForbiddenRequest forbidden/not allowed - Access denied by policy
404 No rule matched OR Rules matched and request not allowed 404 Not Found - No rule matched for the hostname

Common Use Cases

Use Case 1: DNS ServerResolver Integration

Integrate theSecureDNS hostcheck endpointchecking into youra DNS resolver to filterprovide maliciousparental controls. Before resolving any hostname, query the API to determine if the request should proceed, be blocked, or inappropriateredirected contentto ina real-time.safe Query the endpoint before resolving hostnames and block resolution for refused domains.page.

Use Case 2: ProxyCorporate ServerNetwork Filtering

Implement enterprise content filtering in your proxy server by checking eachweb requested hostnamerequests against SecureDNScorporate policiesacceptable beforeuse allowingpolicies. Block access to social media, streaming, or blockingother thenon-work-related connection.categories during business hours.

Use Case 3: ParentalEducational ControlInstitution ApplicationsSafety

BuildSchools parentaland controluniversities softwarecan thatuse queriesthis the endpoint when children attemptAPI to ensure students access websites,only providingeducational real-time protection based onand age-appropriate contentcontent, policies.blocking adult content, gaming sites, and other distracting categories.

Use Case 4: EducationalISP NetworkFamily FilteringPlans

DeployInternet inservice school networks to ensure studentsproviders can onlyoffer accessfamily-safe educationalinternet packages by routing DNS requests through this filtering service, automatically blocking inappropriate content during school hours, with automatic logging for compliance and monitoring.subscribers.

Use Case 5: CorporateHome ContentNetwork PolicyProtection

EnforceHome corporaterouter internetfirmware usagecan policiesintegrate bythis checking business-related hostnames and blocking accessAPI to time-wastingprovide orparents inappropriatewith websiteseasy-to-configure duringcontent workfiltering hours.without requiring technical expertise in DNS configuration.

Best Practices

Performance Optimization:

  • Cache

    Cachingresponses Strategy:locally Implementwhen client-sidethe cachingcached forfield frequentlyis queried hostnamestrue to reduce API calls

Implement connection pooling and improve response times. Cache allow/refuse decisionskeep-alive for 5-15high-volume minutes depending on your security requirements. integrations Monitor the response_time field to track API performance Consider implementing client-side caching with appropriate TTL values

Error HandlingHandling::

    Always handle 404 responses gracefullyappropriately by- implementingthey acan defaultindicate policyeither (typicallyno allowrule match or ignore).blocked Network connectivity issues should not break your filtering system. content

    Rate Limiting: Be mindful of API rate limits when integrating into high-traffic systems. Consider batching requests or implementing request queuing for busy networks.

    Logging Integration: Correlate the API's built-in request logging with your own system logs to create comprehensive audit trails for compliance and troubleshooting.

    Fallback Policies: Always define clearImplement fallback behavior when the API is unavailable.unavailable Consider whether your system should fail (fail-open (allowvs all) or fail fail-closed (blockpolicy)

    all)Log basedAPI onresponses yourfor 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 requirements. auditing

      IP Address Tracking: IncludeValidate client IP addresses inwhen requestsusing tosubnet-based enable more granular policy application and better audit logging.

      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