Securedns Hostcheck

The SecureDNS Host Check hostnamesAPI againstprovides SecureDNSreal-time hostname filtering for parental control serviceand content filtering systems. This endpoint allows you to determinequery accesswhether permissions.a specific hostname should be allowed, refused, or ignored based on your configured SecureDNS 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 implementing real-time content filtering and parental control systems. This API category contains a single but powerful endpoint that evaluates hostnames against your configured SecureDNS policies and returns filtering decisions.

Key Features:

Real-time hostname evaluation against parental control rules Three-state response system: Allow (A), Refuse (R), or Ignore (I) Request logging for audit and monitoring purposes Integration with existing SecureDNS parental control service

Common Integration Scenarios:

DNS filtering appliances and routers Parental control software applications Network security gateways Custom proxy and firewall solutions Educational institution content filters

The endpoint is optimized for high-frequency queries and can be integrated into DNS resolution workflows, proxy servers, or any application requiring real-time hostname filtering decisions.

---

Endpoints

GET /securedns_hostcheck/

CheckDescription: if access toEvaluates a specific hostname shouldagainst be allowed, refused, or ignored based onyour SecureDNS parental control rules.policies Alland requestsreturns area loggedfiltering decision. This endpoint logs each request for monitoringaudit purposes and compliancereturns purposes.one 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.

Use Cases:

DNS resolver integration for real-time filtering Proxy server content filtering Parental control application hostname validation Network appliance policy enforcement Educational content filtering systems

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/domainhostname to check against parentalSecureDNS controlpolicies rules(e.g., "example.com")
client_ip	string	query	No	Client IP address for logging purposesand policy application
categoryuser_id	string	query	No	ContentUser categoryidentifier filterfor topersonalized applyfiltering rules

ExamplecURL Request:Example:

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

Example Response (Allowed):

{
  "hostname": "example.educational-site.com",
  "action": "A",
  "category": "education",
  "rule_id": "safe_browsing_001",
  "category": "general"edu_allow_001",
  "timestamp": "2024-01-15T10:30:00Z",
  "client_ip": "192.168.1.100"
}

Example Response (Blocked)Refused):

{
  "hostname": "blocked-site.com",
  "action": "R",
  "rule_id": "parental_control_018",
  "category": "adult_content",
  "rule_id": "adult_block_001",
  "reason": "ContentParental blockedcontrol bypolicy parentalviolation",
  controls""timestamp": "2024-01-15T10:30:00Z",
  "client_ip": "192.168.1.100"
}

Example Response (Ignored):

{
  "hostname": "unknown-site.com",
  "action": "I",
  "category": "uncategorized",
  "timestamp": "2024-01-15T10:30:00Z",
  "client_ip": "192.168.1.100"
}

Response Fields:Codes:

Field Type Description hostname string The checked hostname action string Action code: "A" (Allowed), "R" (Refused), "I" (Ignored) rule_id string ID of the matching rule category string Content category of the hostname reason string Explanation when access is refused timestamp string ISO 8601 timestamp of the check client_ip string Client IP address (if provided)

Status	Description
200	Success - Rule matched and request allowed
401	Request not authorizedUnauthorized - invalidInvalid or missing API token
403	Request forbidden/not allowedForbidden - ruleRules matched and blockedrequest not allowed
404	Not Found - No rule matched for the hostname

---

Common Use Cases

Use Case 1: DNS Server Integration

Integrate the hostcheck endpoint into your DNS resolver to filter malicious or inappropriate content in real-time. Query the endpoint before resolving hostnames and block resolution for refused domains.

Use Case 2: Proxy Server Filtering

Implement content filtering in your proxy server by checking each requested hostname against SecureDNS policies before allowing or blocking the connection.

Use Case 3: Parental Control Applications

Build parental control software that queries the endpoint when children attempt to access websites, providing real-time protection based on age-appropriate content policies.

Use Case 4: Educational Network Filtering

Deploy in school networks to ensure students can only access educational content during school hours, with automatic logging for compliance and monitoring.

Use Case 5: Corporate Content Policy

Enforce corporate internet usage policies by checking business-related hostnames and blocking access to time-wasting or inappropriate websites during work hours.

---

Best Practices

• RateCaching LimitingStrategy: Implement client-side caching for frequently checkedqueried hostnames to reduce API calls and improve response times. Cache allow/refuse decisions for 5-15 minutes depending on your security requirements.

• Error Handling: HandleAlways handle 404 responses appropriatelygracefully -by theyimplementing maya indicatedefault eitherpolicy no(typically rules existallow or contentignore). isNetwork blockedconnectivity issues should not break your filtering system.

• 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 clear fallback behavior when the API is unavailable. Consider whether your system should fail open (allow all) or fail closed (block all) based on your security requirements.

IP Address Tracking: Include client IP addresses whenin possiblerequests forto enable more granular policy application and better audit trailslogging.

and user tracking Caching Strategy: Cache allowed responses for short periods (1-5 minutes) to improve performance Fallback Behavior: Define clear fallback actions when the API is unavailable (allow, block, or queue for later checking) Batch Processing: For high-volume environments, consider implementing request queuing to stay within rate limits

---