--- title: "DNS Event" canonical: "https://docs.infoblox.com/space/BloxOneThreatDefense/35437944/DNS%20Event" format: markdown --- DNS Query and Response Infoblox security checks are applied to the complete DNS query and response. Infoblox parses all DNS query types (link to different query types we support) to find malicious IPs and servers embedded in DNS messages. An RPZ event is generated when a domain or IP address within a DNS query or response is matched to an Infoblox threat feed. For information on Infoblox policy threat intelligence options, see Security Policies . For information on custom lists, see Custom Lists . API Calls for dns_event The Infoblox Threat Defense API allows you to make REST API calls to gather DNS security data from Infoblox Threat Defense for SIEM (Security Information and Event Management) purposes. Based on your business needs, you can configure a SIEM system in your network to collect the DNS security data so you can filter the data and create custom reports. Security data can be collected for both public and private IP addresses. The Swagger documentation for DNS Event api calls can be found here . Prerequisites You must have the following in place before using the InfobloxThreat Defense API: Infoblox Threat Defense subscription The API key that you obtain through the Infoblox Portal. For information see Transport and Authentication . Supported Object for dnsdata The Infoblox Threat Defense API supports a single API object (dns_event) for the dnsdata (or threats ) endpoint, which allows you to obtain a list of DNS requests. Table 1. API Call for dns_event HTTP Method URI Description GET https://csp.infoblox.com/api/ dnsdata/v2 /dns_event or https://csp.infoblox.com/api/ threats/v2 /dns_event Get a list of the blocked DNS requests To authenticate requests, you should pass an HTTP “Authorization” header with the API key and the prefix “Token.” The following are some sample API requests using curl commands in JSON format: Example 1: For RPZ data curl -k -i -H "Authorization: Token " "https://csp.infoblox.com/api/dnsdata/v2/dns_event?source=rpz&t0=1483228653&t1=1514768554" -s Example 2: For Analytic data curl -k -i -H "Authorization: Token " "https://csp.infoblox.com/api/dnsdata/v2/dns_event?source=analytic&t0=1483227865&t1=1514769667” -s Example 3: For Category data curl -k -i -H "Authorization: Token " "https://csp.infoblox.com/api/dnsdata/v2/dns_event?source=category&t0=1529907657&t1=1530189855" -s The following are some sample API requests using curl commands in CEF format: Example 1: For RPZ data curl -k -i -H "Authorization: Token " "https://csp.infoblox.com/api/dnsdata/v2/dns_event?source=rpz&t0=1483224387&t1=1514787535_&format=cef” -s Example 2: For Analytic data curl -k -i -H "Authorization: Token " "https://csp.infoblox.com/api/dnsdata/v2/dns_event?source=analytic&t0=1483227698&t1=151473967&_format=cef” -s Example 3: For Category data curl -k -i -H "Authorization: Token " "https://csp.infoblox.com/api/dnsdata/v2/dns_event?source=category&t0=1529905639&t1=1530188767&_format=cef" -s Request Parameters It is possible for an API call to return a huge dataset. Infoblox currently limits the result dataset to 50,000 records and recommends that you narrow the search and execute it frequently to avoid polling a big dataset. The following table explains the supported parameters you can use in your API requests to filter the results: Table 2. Request Parameters for dns_event Parameter Description Example t0 Start time in seconds (Unix timestamp). Query records on or after the start time. ( required ) “1508591340” t1 End time in seconds (Unix timestamp). Obtain records before (but not on) the end time. ( required ) “1511686800” source Enter rpz for RPZ events, analytic for detection (threat insight) events, or category for content category. If omitted, data from all sources are provided. (optional) “rpz” network Source Network (NAT case) / Server name / AT Endpoint (optional) “Some Network” qip Device IP that sent the DNS query (optional) “ 192.0.2.1 ” qname Queried name/Domain (optional) “example.com” policy_name Policy name (optional) “Policy name” threat_level Threat Level (optional, case-insensitive, accepts numeric or string values). Valid levels are: 1 = LOW, 2 = MEDIUM, and 3 = HIGH. You must enter the numeric number when using this parameter. See the following example for usage: curl -k -i -H "Authorization: Token " " https://csp.infoblox.com/api/dnsdata/v2/dns_event?source=rpz&t0=1576490602&t1=1576512247&_format=cef& threat_level=MEDIUM " “HIGH” OR “High” OR “3” threat_class Threat category (optional) “MalwareDownload” _limit Number of rows to return (optional) 2 policy_action Indicates what action is performed as a result of policy evaluation (policy is a set of rules that specifies decisions for resources). Possible actions are: Log, Block, Default, Redirect Log _offset Offset of first row to return, for paging (optional) 42 _format JSON (default) or CEF (Optional) “cef” feed_name Infoblox threat feed name or custom feed name. Can be the following: raw feed name or human-readable mapping from a raw feed name, if available custom list name “Threat Insight - Data Exfiltration” feed_type Type of the feed described in feed_name above. “FQDN”, “IP ADDRESS” app_name application is a cloud-hosted software in which a remote server performs tasks on behalf of the user, either in isolation or in coordination with a local software package, or a local software package that utilizes cloud servers for updates, heartbeats / phone home, or other services "Application Name" app_category Category of the application (see the app_name description for what an application means). Communication app_subcategory Subcategory of the application (see the app_name description for what an application means). Email _field_list Comma separated list of event fields to be included in the response. All the fields will be returned if not specified. “qname,device_name,category,qip” dns_view DNS View name received from NIOS . “default” threat_indicator Threat Indicator. May indicate malicious or unauthorized activity. “example.com” rdata Response data, corresponding to dns query. “ 192.0.2.1 ”, “” threat_family Threat Family is used to group domains which have similar threat property (optional, allows multiple values - comma separated.) "Log4Shell" OR "Log4Shell","OPENRESOLVER" There is a short delay (a few seconds to a few minutes) between a query being blocked and that information being available via the Infoblox Threat Defense API. Output Format for dns_event After you have sent the API request, the system returns DNS security data based on the parameters in your command. This data can include DNS threat (or RPZ) events and detection (or analytic) events. The returned data can be in JSON format or CEF (Common Event Format). The default is JSON. Events in JSON are listed in the “result” object array. CEF is a variation of the syslog format. If you specify to receive your data output in CEF, every event is encoded as a line of CEF. The CEF data output includes the following header: CEF:Version|Device Vendor|Device Product|Device Version|Signature ID|Name|Severity|Extension Example: CEF:0|Infoblox|ATC|2.0||dns_event|10| The following table explains the header fields in the CEF output: Table 3. CEF Header Fields CEF Prefix Field Description Value Version An integer that identifies the version of the CEF. Event consumers use this information to determine what the following fields represent. “0” Device Vendor Strings that uniquely identify the type of sending device. No two products may use the same device-vendor and device-product pair. There is no central authority managing these pairs. Event producers must ensure that they assign unique name pairs. “Infoblox” Device Product “ATC” Device Version “2.0” Signature ID Unique identifier per event-type SHA2 digest of CEF log line (with an empty Signature ID field) Name String representing a human-readable and understandable description of the event. “dns_event” or “detection_event” Severity In CEF format, an integer that reflects the importance of the event. Only numbers from 0 to 10 are allowed, where 10 indicates the most important event. “5” Extension A collection of key-value pairs. The keys are part of a predefined set. An event can contain any number of key value pairs in any order, separated by spaces (“ “). If a field contains a space, such as a filename, it is valid and can be logged in exactly in that manner, as follows: fileName=c:\ProgramFiles\ArcSight is a valid token. The following example illustrates a CEF message using the syslog transport: Sep 19 08:26:10 host CEF:0|security|threatmanager|1.0|100|worm successfully stopped|t|src=10.0.0.1 dst=2.1.2.2 spt=1232 Use the same fields as output in JSON format but apply CEF field name and data value conventions (see the CEF field map table below). InfobloxAtcEventTime=149901680000InfobloxAtcRip= 172.28.4.211 InfobloxAtcRcode=NOERROR InfobloxAtcUser=administrator InfobloxAtcNetwork= AT Endpoint InfobloxAtcQname=006a2.9efded5b8e.dnsm.in.example.net. InfobloxAtcQtype=TXT InfobloxAtcConfidence=HIGH The data output rows are not displayed in any particular order. To preserve row order for paging operations, the query results are cached. The default cache expiry time is set to five minutes (300 seconds). Queries that are sent after the cache expiry time may not have the same order of rows. You can control the output paging by using the _limit and _offset parameters in your curl command. Data output is limited to 50,000 rows of data. Depending on the paging properties and data record size, more rows of data can be returned in certain cases. Response in JSON Format If you do not specify an output data format in your API call, it defaults to JSON. The following are some sample JSON outputs: curl --request GET ‘http://csp.infoblox.com/api/dnsdata/v2/dns_event?source=category&t0=1646883299&t1=16502767654&_limit=1&_format=json&_field_list=qname,device_name,user,severity,tclass,tproperty,event_time,confidence,rcode,response,country,query_type,network,feed_name,feed_type,policy_name,rip,mac_address,dhcp_fingerprint,os_version,category,qip,app_name,app_category,app_subcategory,dns_view,private_ip’ --header 'Authorization: Token ' Response: { "result": [ { "app_category": "", "app_name": "", "app_subcategory": "", "category": "Parked Domain", "confidence": "", "country": "United States", "device": "EXAMPLE-DEVICE", "dhcp_fingerprint": "", "dns_view": "", "event_time": "2022-04-14T10:36:42.000Z", "feed_name": "CAT_Parked Domain", "feed_type": "FQDN", "mac_address": "example MAC address", "network": "BloxOne Endpoint", "os_version": "macOS 11.6.5", "policy_name": "zvellow_policy", "private_ip": "192.x.x.1,192.x.x.2", "qip": "192.x.x.x", "qname": "example.org.", "qtype": "AAAA", "rcode": "", "rdata": "2606:2800:220:1:248:1893:25C8:1946", "rip": "127.0.0.1", "severity": "", "tclass": "", "tproperty": "", "user": "USERNAME" } ], "status_code": "200" } curl --location --request GET 'http://csp.infoblox.com/api/dnsdata/v2/dns_event?source=category&t0=1646876343&t1=1650256432&_limit=50000&_format=json&_field_list=qname,device_name,category,qip'--header 'Authorization: Bearer ' Response: { "result": [ { "category": "Parked Domain", "device": "EXAMPLE-DEVICE", "qip": "192.x.x.1", "qname": "example.org." }, { "category": "Mac OS", "device": "EXAMPLE-DEVICE", "qip": "192.x.x.2", "qname": "1-courier.sandbox.push.example.com." }, .. .. .. ..<3000005 lines total = 50k records> } curl --location --request GET 'http://csp.infoblox.com/api/dnsdata/v2/dns_event?source=category&t0=1646876304&t1=1650243320&_offset=10000&_limit=60000&_format=json&_field_list=qname,device_name,category,qip'--header 'Authorization: Token ' Response: { "result": [ { "category": "Software/Hardware", "device": "DEVICE_NAME", "qip": "192.x.x.1", "qname": "detectportal.example.com." }, { "category": "Software/Hardware", "device": "DEVICE-NAME", "qip": "192.x.x.2", "qname": "detectportal.example.com." }, .. .. .. ..<2400005 lines total = 40k (=50k max -10k offset) records> } Response in CEF The following is an example of the CEF data output: curl --location --request GET 'https://csp.infoblox.com/api/dnsdata/v2/dns_event?t0=1649701945&t1=1650566453&source=rpz&_limit=1&_format=cef' --header 'Authorization: Token ' CEF:0|Infoblox|ATC|2.0||dns_event|10| InfobloxAtcAppCategory= InfobloxAtcAppName= InfobloxAtcAppSubcategory= InfobloxAtcCategory= InfobloxAtcConfidence=HIGH InfobloxAtcCountry= InfobloxAtcDevice=192.0.2.1 InfobloxAtcDhcpFingerprint= InfobloxAtcDnsView= InfobloxAtcEventTime=2022-04-21T09:27:41.000Z InfobloxAtcFeedName=Threat Insight - Data Exfiltration InfobloxAtcFeedType=FQDN InfobloxAtcMacAddress= InfobloxAtcNetwork=TI_Network InfobloxAtcOsVersion= InfobloxAtcPolicyAction=Log InfobloxAtcPolicyName=RO_SEC_POL_REPORT_AUTOMATION InfobloxAtcPrivateIp= InfobloxAtcQip=192.0.2.2 InfobloxAtcQname=6c6530787377327772797a7836720a6937406f3975787264617973.24.jnrmn597.scr.y69gzsdo5w.example.com. InfobloxAtcQtype=A InfobloxAtcRcode=PASSTHRU InfobloxAtcRdata=NXDOMAIN InfobloxAtcRip= InfobloxAtcSeverity=HIGH InfobloxAtcThreatClass=Data Exfiltration InfobloxAtcThreatIndicator=jnrmn597.scr.y69gzsdo5w.example.com InfobloxAtcThreatProperty=Threat Insight - Data Exfiltration InfobloxAtcUser=unknown InfobloxAtcUserGroups= The following table describes the data output fields (if they exist) that can appear in the output: Table 4. Data Output Fields JSON format CEF format Description Examples qname InfobloxAtcQname Destination Domain, Destination IP address “example.com.” device InfobloxAtcDevice Device IP or AT Endpoint name “ 192.0.2.1 ”, “ATE” (tracks public and private IP addresses) user InfobloxAtcUser User Info “administrator” severity InfobloxAtcSeverity Threat Level (threat_level) Values: LOW/MEDIUM/HIGH “HIGH” tclass InfobloxAtcThreatClass Threat class indicates the category of the threat. For example: phishing, spambots, malware, etc. “MalwareDownload”, “CUSTOM”, "Phishing", "Spambot" tproperty InfobloxAtcThreatProperty Threat property indicates a further refinement of threat class. For example, when the threat class is malware, then the threat property is a type of malware. “Locky”, “LIST” event_time InfobloxAtcEventTime Event timestamp “2018-01-28T17:28:01.000Z” confidence InfobloxAtcConfidence Confidence (decoded, e.g., LOW, MEDIUM, HIGH) “HIGH” rcode InfobloxAtcRcode This is the DNS response type (decoded, e.g. NXDOMAIN, NOERROR, etc.) from ATC that gets returned for each query made. The following are the all possible return values PASSTHROUGH NXDOMAIN REDIRECT REFUSE Note : Rcode is derived from policy_action. So, when _ field _list contains rcode, policy_action will be returned as well. "REDIRECT" rdata InfobloxAtcRdata Response data “127.0.0.2”, “” country InfobloxAtcCountry Country code. Reflect location of the resolved IP “US”, “unknown” qtype InfobloxAtcQtype Query type (decoded, e.g., A, AAAA, MX, etc.) “TXT” network InfobloxAtcNetwork Source Network (NAT case) / Server / ATE (decoded) “Some Network”, “AT Endpoint” feed_name InfobloxAtcFeedName Infoblox threat feed name or custom feed name. Can be the following: raw feed name or human-readable mapping from a raw feed name, if available custom list name “Threat Insight - Data Exfiltration” feed_type InfobloxAtcFeedType Type of the feed (feed_name described above). “FQDN”, “IP ADDRESS” policy_name InfobloxAtcPolicyName Policy name “Default Global Policy” rip InfobloxAtcRip Returned IP address “ 192.0.2.2 ”, “” mac_address InfobloxAtcMacAddress MAC address ATEP dhcp_fingerprint InfobloxAtcDhcpFingerprint DHCP fingerprint os_version InfobloxAtcOsVersion OS version ATEP category InfobloxAtcCategory Content category “Search Engines” qip InfobloxAtcQip Device IP “ 192.0.2.3 ” dns_view InfobloxAtcDnsView DNS View name received from NIOS . view policy_action InfobloxAtcPolicyAction Indicates what action is performed as a result of policy evaluation (policy is a set of rules that specifies decisions for resources). Possible actions are: Log, Block, Default, Redirect Log app_name InfobloxAtcAppName Application name where an application is a cloud-hosted software in which a remote server performs tasks on behalf of the user, either in isolation or in coordination with a local software package, or a local software package that utilizes cloud servers for updates, heartbeats / phone home, or other services "Application Name" app_category InfobloxAtcAppCategory Category of the application (see the app_name description for what an application means). Communication app_subcategory InfobloxAtcAppSubcategory Subcategory of the application (see the app_name description for what an application means). Email user_groups InfobloxAtcUserGroups Format: String, comma separated values. User Groups from third party IDPs (Identity Providers) like Okta, OpenAM, Azure and LDAP. Once the user is authenticated, we store the user details (user name, user group information, MAC address) in Onprem Authn Service. From there, any queries happening from that user behind the Server network, the queries will be encrypted with site-id, user groups information and forwarded to Cloud. Then Cloud apply the policy rules based on the user group and DFP configuration in security policies in CSP “dl example,example,Engineering-core” threat_indicator InfobloxAtcThreatIndicator Threat Indicator. May indicate malicious or unauthorized activity. “example.com” tfamily InfobloxAtcThreatFamily Threat Family is used to group domains which have similar threat property. One threat class can contain multiple threat families, like DNSTunnel (Tclass) has DNScat2, Generic, TunnelGuru (Tfamily) MalwareC2 (Tclass) has Asprox, Azorult, BackdoorRAT, BadRabbit, Bamital "DNSTunnel,MalwareC2" Error Handling for dns_event Data returned in JSON format might contain the status detail field in case of errors and warnings, which could be ERROR or ERROR_MANDATORY_START. Note that the status_detail dictionary supports both “errors” and “warnings,” which are lists of strings containing individual messages appropriate for the errors. In addition, HTTP can return the following status code: 200 – Success 400 – Missing or invalid parameter 401 – Authentication error 500 – Server error The following are some examples: JSON output with no errors: { "status_code": "200", "status_detail": { "errors": [] } } JSON output with detected errors: { "status_code": "500", "status_detail": { "errors": [ "" ] } }