Securedns Hostcheck

Endpoints Summary

Method Path Swagger GET /securedns_hostcheck/ Swagger ↗

---

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

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 implementimplementing DNS-levelbased content filtering and parental controls.control systems. This service acts as a real-time decision engine that evaluates hostname requestshostnames against your configured security policies and returns appropriate actions.actions based on category classifications, access control lists (ACLs), and subnet-specific rules.

Key Features:

• Real-time hostname evaluation against security policies
• CategorizedCategory-based content filtering with(malware, customizableadult ACLcontent, social media, etc.)

Subnet-specific access control rules IP redirection capabilities for blocked content Response caching for improved performance Detailed logging and audit trail for compliance Subnet-based rule matching for network-level controlstrails

Common Integration Scenarios:

• DNS resolversresolver implementingintegration parentalfor controlsenterprise networks

Parental control software and routers Network security appliances requiring content filtering ISPContent servicesfiltering offering family-safe internet packages Corporate networks enforcing acceptable use policiesproxies Educational institutionsinstitution blockingnetwork inappropriate contentprotection

The API usesreturns astructured simpleresponses request-responseindicating patternwhether whererequests youshould submitbe aallowed hostnamethrough, forredirected evaluationto andwarning receivepages, anor actionblocked directiveentirely, along with supportingperformance metadata such as matched rules, categories,metrics and redirectcaching information.

---

Endpoints

GET /securedns_hostcheck/

Description: EvaluatesPerforms real-time evaluation of a hostname against your configured SecureDNS policiespolicies. The endpoint checks the requested hostname against category filters, access control lists, and subnet-specific rules to determine ifthe accessappropriate shouldaction. beAll allowed,requests refused,are orlogged ignored.for This endpoint performs real-time policy matchingauditing and returnsreporting detailed information about the decision including matched categories, ACL rules, and any redirect instructions.purposes.

Use Cases:

• DNS resolver checkingintegration ifto afilter domainmalicious shouldor beinappropriate blocked before resolutioncontent
• NetworkReal-time gatewaycontent validatingfiltering for corporate networks

Parental control systems checking web access requests against parental control policies Security applianceappliances implementingvalidating corporateoutbound content filteringconnections Educational network enforcingprotection acceptableagainst useinappropriate policies ISP providing family-safe internet filtering servicescontent

Full URL Example:

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

Parameters:

Parameter	Type	In	Required	Description
hostname	string	query	Yes	The hostname or domain to check against SecureDNS policies
client_ip	string	query	NoYes	ClientThe IP address forof subnet-basedthe ruleclient matchingmaking the request
policy_idsubnet	string	query	No	SpecificThe policysubnet UUIDidentifier to evaluateapply againstspecific ACL rules

category_override string query No Override automatic category detection with specific category

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/securedns_hostcheck/?hostname=social-media.com&client_ip=192.168.10.0.1.100"50&subnet=10.0.1.0/24" \
  -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.10.0.1.0/24",
    "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "category": "news"business",
    "acl": "allow_news_sites"corporate_allow",
    "cached": true,
    "response_time": 0.04512.5
  }
]

Example Response (Blocked):

[
  {
    "action": "R",
    "redirect_ip": "10.203.0.0.1"113.10",
    "match_subnet": "192.168.1.0/24",
    "uuid": "a1b2c3d4-58cc-4372-a567-0e02b2c3d480"550e8400-e29b-41d4-a716-446655440000",
    "category": "adult_content",
    "acl": "block_adult_family_policy"family_safe",
    "cached": false,
    "response_time": 0.0328.3
  }
]

Response Fields:

Field	Type	Description
action	string	Action to take: "A" (Allow), "R" (Refuse)Refuse/Block), or "I" (Ignore)
redirect_ip	string	IP address to redirect blocked requests to (0.0.0.0 iffor no redirect)allow)
match_subnet	string	SubnetThe subnet rule that matched thethis client IP for rule applicationrequest
uuid	string	Unique identifier offor thethis matchedpolicy rule match
category	string	Content category that was matchedclassification (e.g.,malware, "social_media",adult_content, "adult_content"social_media, etc.)
acl	string	Name of the Access Control List rulename that was applied
cached	boolean	Whether this response was served from cache
response_time	number	ProcessingResponse time in secondsmilliseconds

Response Codes:

Status	Description
200	Rule matched and request allowed - Returnshostname policypasses decisionall filters
401	Request not authorized - Invalidinvalid or missing API token
403	Request forbidden/not allowedforbidden - Accesshostname deniedblocked by security policy
404	No rule matched OR- hostname not found in any policy rules

404 Rules matched and request not allowed - hostname explicitly blocked

---

Common Use Cases

Use Case 1: DNS Resolver Integration

Integrate the SecureDNS checkingAPI into ayour DNS resolver to provideautomatically parentalfilter controls.malicious Beforedomains and inappropriate content. Query each hostname before resolving anyDNS hostname,requests queryand either allow resolution or redirect to a block page based on the API to determine if the request should proceed, be blocked, or redirected to a safe page.response.

Use Case 2: CorporateParental NetworkControl FilteringRouter

Implement enterprisefamily-safe contentinternet filtering by checking all outbound web requests againstthrough corporatethe acceptableAPI. useConfigure policies.different Blockpolicies for children's devices versus adult devices using subnet-based rules and redirect blocked content to age-appropriate explanations.

Use Case 3: Corporate Network Security

Protect enterprise networks by filtering access to social media, streaming,streaming services, or othermalware non-work-related categoriesdomains during business hours.

Use Case 3: Educational Institution Safety

Schools and universities can use thisthe API to ensureenforce studentsacceptable accessuse only educationalpolicies and age-appropriatemaintain content,productivity blockingwhile adultensuring content,security gaming sites, and other distracting categories.compliance.

Use Case 4: ISPEducational FamilyInstitution PlansFiltering

InternetDeploy service providers can offer family-safe internet packages by routing DNS requests through thiscontent filtering service,for automaticallyschool blockingnetworks to block inappropriate content forwhile subscribers.allowing educational resources. Implement time-based restrictions and category-specific filtering based on different areas of the campus network.

Use Case 5: HomeSecurity NetworkAppliance ProtectionIntegration

HomeEmbed routerthe firmwareSecureDNS cancheck integrateinto thisnetwork APIsecurity devices to provide parentsan additional layer of threat protection. Combine with easy-to-configureother contentsecurity filteringfeeds withoutto requiringcreate technicalcomprehensive expertiseprotection inagainst DNSemerging configuration.threats and malicious domains.

---

Best Practices

Performance Optimization:

• Cache responsesImplement locallyResponse whenCaching: Use the cached field isto trueimplement your own local caching layer for frequently requested hostnames to reduce API calls and improve response times
• Handle All Response Codes: Implement connectionproper poolingerror handling for different HTTP status codes, especially distinguishing between 403 (blocked) and keep-alive404 (no rule matched) responses

Subnet-Specific Policies: Leverage subnet parameters to implement different filtering policies for high-volumevarious integrationsnetwork segments (guest networks, employee networks, etc.) Monitor Response Times: Use the response_time field to trackmonitor API performance and implement timeout handling for slow responses Consider implementingLog client-sidePolicy cachingMatches: withStore appropriatethe TTLreturned uuid values for

Erroraudit Handling:

trails

and Alwayspolicy handleeffectiveness 404 responses appropriately - they can indicate either no rule match or blocked contentanalysis Graceful Degradation: Implement fallback behavior when the API is unavailable (fail-open- vseither fail-closedallow policy)all traffic or apply local blocking rules Log Rate Limiting: Implement client-side rate limiting to avoid overwhelming the API responsesduring forhigh-traffic troubleshootingperiods Batch Processing: For high-volume scenarios, consider implementing request queuing and compliancebatch auditingprocessing Retryto failedoptimize requestsAPI with exponential backoffusage

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