Skip to main content

Securedns Hostcheck

The SecureDNS Host Check API provides real-time hostname filtering for parental control and content filtering systems. This endpoint allows you to query whether 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/

Description: Evaluates a hostname against your SecureDNS parental control policies and returns a filtering decision. This endpoint logs each request for audit purposes and returns 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 to check against SecureDNS policies (e.g., "example.com")
client_ip string query No Client IP address for logging and policy application
user_id string query No User identifier for personalized filtering rules

cURL Example:

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

Example Response (Allowed):

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

Example Response (Refused):

{
  "hostname": "blocked-site.com",
  "action": "R",
  "category": "adult_content",
  "rule_id": "adult_block_001",
  "reason": "Parental control policy violation",
  "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 Codes:

Status Description
200 Success - Rule matched and request allowed
401 Unauthorized - Invalid or missing API token
403 Forbidden - Rules matched and request 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

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

  • Error Handling: Always handle 404 responses gracefully by implementing a default policy (typically allow or ignore). Network connectivity 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 in requests to enable more granular policy application and better audit logging.

Back to top