Skip to main content

Securedns Categoryget

The SecureDNS Category API enables retrieval of categorization information for SecureDNS transactions using their unique identifiers. This endpoint is essential for understanding what type of DNS activity or threat category was associated with a specific transaction, providing crucial context for security analysis and compliance reporting.

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 provides access to transaction categorization data within Zequenze's SecureDNS service. When SecureDNS processes DNS requests, each transaction is assigned a unique identifier (UUID) and categorized based on the type of content, threat level, or policy match that occurred.

This API category is particularly valuable for:

  • Security Analysis: Understanding what categories of content users are accessing
  • Compliance Reporting: Generating reports on blocked or allowed content categories
  • Incident Investigation: Researching specific DNS transactions during security incidents
  • Policy Validation: Confirming that DNS filtering policies are working as expected

The categorization system helps administrators understand whether DNS requests were related to malware, phishing, social media, productivity tools, or other predefined categories. This information is crucial for maintaining security posture and ensuring compliance with organizational policies.

Endpoints

GET /securedns_categoryget/

Description: Retrieves the category name associated with a specific SecureDNS transaction using its UUID. This endpoint is essential when you need to understand what type of content or threat was associated with a particular DNS request, whether it was blocked, allowed, or flagged for review.

Use Cases:

  • Investigating security incidents by looking up transaction categories
  • Generating compliance reports showing what categories of content were accessed
  • Validating DNS filtering policy effectiveness
  • Providing detailed context for DNS transaction logs

Full URL Example:

https://control.zequenze.com/api/v1/securedns_categoryget/?uuid=550e8400-e29b-41d4-a716-446655440000

Parameters:

Parameter Type In Required Description
uuid string query Yes The unique identifier of the SecureDNS transaction for which you want to retrieve the category information

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:

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "category": "Social Media",
  "category_id": 23,
  "threat_level": "low",
  "policy_action": "allowed",
  "timestamp": "2024-01-15T14:23:45Z",
  "domain": "facebook.com",
  "subcategory": "Social Networking"
}

Response Codes:

Status Description
200 Category request Ok - Successfully retrieved category information
401 Category request not authorized - Invalid or missing Bearer token
403 Category request forbidden / not allowed - Insufficient permissions to access this transaction
404 Provided UUID don't match any transaction - The specified UUID does not exist in the system

Common Use Cases

Use Case 1: Security Incident Investigation

When investigating a potential security breach, security analysts can use transaction UUIDs from their SIEM or log analysis tools to quickly determine what categories of content were involved in suspicious DNS activity.

Use Case 2: Compliance Reporting

Organizations can batch process transaction UUIDs to generate comprehensive reports showing what categories of content users accessed during specific time periods, helping demonstrate compliance with industry regulations.

Use Case 3: Policy Effectiveness Analysis

IT administrators can sample transaction UUIDs from their DNS logs to verify that their SecureDNS policies are correctly categorizing and handling different types of content according to organizational requirements.

Use Case 4: User Activity Context

Help desk teams can look up specific transactions when users report blocked content, providing immediate context about why certain domains were categorized and blocked.

Best Practices

  • UUID Validation: Always validate UUID format before making API calls to avoid unnecessary 404 responses
  • Rate Limiting: Implement appropriate delays when processing large batches of UUIDs to respect API rate limits
  • Error Handling: Design your application to gracefully handle 404 responses for UUIDs that may have aged out of the system
  • Caching: Consider caching category results for frequently queried UUIDs to reduce API calls and improve performance
  • Security: Never log or expose Bearer tokens in your application code or configuration files
  • Monitoring: Track API response times and error rates to ensure optimal performance when processing high volumes of category lookups
Back to top