Skip to main content

Securedns Categoryget

The SecureDNS Category API provides access to DNS transaction categorization data, allowing you to retrieve the category classification of specific SecureDNS transactions. This endpoint is essential for security monitoring, content filtering analysis, and understanding the nature of DNS requests processed through the SecureDNS service.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The SecureDNS Category API enables you to query and retrieve category information for DNS transactions that have been processed through the SecureDNS filtering system. Each DNS transaction is assigned a unique UUID when processed, and this API allows you to look up the category classification associated with that transaction.

Key Features:

  • Retrieve category names for specific SecureDNS transactions
  • Support for UUID-based transaction lookups
  • Essential for security auditing and DNS filtering analysis
  • Real-time access to transaction categorization data

Common Use Cases:

  • Security incident investigation and forensics
  • DNS filtering policy analysis and optimization
  • Compliance reporting for web access monitoring
  • Automated security workflows that need to categorize DNS activity
  • Integration with SIEM systems for enhanced threat detection

The category information returned helps classify the type of content or service associated with DNS requests, enabling better understanding of network traffic patterns and potential security threats.

Endpoints

GET /securedns_categoryget/

Description: Retrieves the category name associated with a specific SecureDNS transaction identified by its UUID. This endpoint is crucial for understanding what type of content or service was being accessed in a particular DNS request, making it invaluable for security analysis, compliance reporting, and traffic classification.

Use Cases:

  • Investigate suspicious DNS activity by looking up transaction categories
  • Generate reports on types of websites and services accessed through DNS
  • Validate DNS filtering policies by checking categorization accuracy
  • Build automated security workflows that respond based on DNS transaction categories
  • Perform forensic analysis of network traffic patterns

Full URL Example:

https://control.zequenze.com/api/v1/securedns_categoryget/

Parameters:

Parameter Type In Required Description
uuid string query Yes The unique identifier of the SecureDNS transaction to look up. Must be a valid UUID format.

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/securedns_categoryget/?uuid=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

[
  {
    "category": "Social Networking"
  }
]

Additional Example Responses:

[
  {
    "category": "Malware"
  }
]

[
  {
    "category": "Business and Economy"
  }
]

Response Codes:

Status Description
200 Category request Ok - Successfully retrieved the category information
401 Category request not authorized - Invalid or missing API token
403 Category request forbidden / not allowed - Valid token but insufficient permissions
404 Provided UUID don't match any transaction - The specified UUID was not found in the system

Common Use Cases

Use Case 1: Security Incident Investigation

When investigating a potential security incident, security analysts can use transaction UUIDs from DNS logs to quickly determine what categories of content were being accessed. This helps prioritize investigations and understand the scope of potential threats.

Use Case 2: DNS Policy Optimization

Network administrators can analyze the categories of blocked or allowed DNS requests to fine-tune their filtering policies, ensuring legitimate business traffic flows while maintaining security controls.

Use Case 3: Compliance Reporting

Organizations can generate compliance reports by categorizing DNS traffic to demonstrate adherence to acceptable use policies and regulatory requirements for internet access monitoring.

Use Case 4: Automated Threat Response

Security orchestration platforms can integrate this API to automatically categorize DNS transactions and trigger appropriate response workflows based on the category (e.g., immediate blocking for malware categories).

Use Case 5: Network Traffic Analysis

IT teams can analyze DNS transaction patterns over time by categorizing requests, helping identify unusual activity patterns or potential security risks in network usage.

Best Practices

  • UUID Validation: Always validate UUID format before making API calls to avoid unnecessary 404 errors
  • Error Handling: Implement robust error handling for all response codes, especially 404 responses when UUIDs don't exist
  • Rate Limiting: Consider implementing client-side rate limiting to avoid overwhelming the API with too many concurrent requests
  • Caching: Cache category results for frequently queried UUIDs to reduce API calls and improve performance
  • Security: Never log or expose API tokens in client-side code or logs; always use secure token storage methods
  • Monitoring: Track API response times and error rates to ensure your integration remains healthy
  • Batch Processing: When analyzing multiple transactions, implement proper queuing and throttling mechanisms to process UUIDs efficiently
Back to top