Operator DNSTunneling

Specialized toolkits - release 4.3.1.0-prod20190605 > com.ibm.streams.cybersecurity 2.1.1 > com.ibm.streams.cybersecurity.analytics > DNSTunneling

Primitive operator image not displayed. Problem loading file: ../../image/tk$com.ibm.streams.cybersecurity/op$com.ibm.streams.cybersecurity.analytics$DNSTunneling.svg

The DNSTunneling operator analyzes DNS response traffic and reports suspicious behaviour that may indicate the presence of DNS tunneling in the network.

DNS tunneling is technique whereby data is transmitted and received through DNS query and response packets. Since DNS traffic is typically not blocked by network firewalls, users can use this technique to access blocked domains and transfer data between systems that they would otherwise not be allowed to access.

By default, the operator requires the following attribute types and names to exist in the input schema. You can specify different names for these attributes using the operator parameters (see the Parameters section).

  • rstring questionName
  • uint16 questionType
  • list<rstring> answerData
  • list<uint16> answerTypes

Behavior in a consistent region

  • The operator cannot be the start of a consistent region. An error occurs when you compile your streams processing application.

Exceptions

The DNSTunneling operator throws an exception in the following cases:

  • The length of the 'answerData' list is different from the length of the 'answerTypes' list
  • The input schema does not contain the required default attribute names, and different names were not assigned via the operator's parameters.

Summary

Ports
This operator has 1 input port and 1 output port.
Windowing
This operator does not accept any windowing configurations.
Parameters
This operator supports 6 parameters.

Optional: answerDataAttr, answerTypesAttr, filterSHA512Hash, questionNameAttr, questionTypeAttr, trimTXTLengthField

Metrics
This operator does not report any metrics.

Properties

Implementation
C++
Threading
Never - Operator never provides a single threaded execution context.

Input Ports

Ports (0)

Ingests tuples containing DNS response records. The input tuple must contain, at a minimum, the following attributes:

  • rstring questionName
  • uint16 questionType
  • list<rstring> answerData
  • list<uint16> answerTypes

NOTE: The attribute names can be changed via the operator's parameters.

For convenience, the com.ibm.streams.cybersecurity.types::DNSTunnelingInput_t type contains all of the necessary attributes needed by the DNSTunneling operator.

Properties

Output Ports

Assignments
This operator allows any SPL expression of the correct type to be assigned to output attributes.
Output Functions
TunnelingFunctions
<any T> T AsIs()

The default function for output attributes. By default, this function assigns the output attribute to the value of the input attribute with the same name.

rstring getPredictedClass()

Returns the predicted class of the DNS response packet. If one or more of the answerData values is considered suspicious, this function will return a value of suspicious. Otherwise, this function will return a value of benign.

list<rstring> getPredictedClasses()

Returns a list containing the predicted class for each answer. Possible values include: benign, suspicious.

list<rstring> getSuspiciousText()

Returns a list containing the suspicious text fields from the current DNS response packet

list<rstring> getBenignText()

Returns a list containing the benign text fields from the current DNS response packet

uint64 getSuspiciousCount()

Returns the total number of suspicious text fields received for a given questionName (domain name) since the application started.

uint64 getBenignCount()

Returns the total number of benign text fields received for a given questionName (domain name) since the application started.

Ports (0)

Submits a tuple for each DNS response packet that was received. Custom output functions are used to specify the value of the output tuple attributes. The output tuple attributes whose assignments are not specified are assigned from the input attribute.

For convenience, the com.ibm.streams.cybersecurity.types::DNSTunnelingResult_t type can be used as the output tuple type of this operator. This type contains attributes that can be assigned from the output functions.

Properties

Parameters

Optional: answerDataAttr, answerTypesAttr, filterSHA512Hash, questionNameAttr, questionTypeAttr, trimTXTLengthField

answerDataAttr

Specifies the input attribute containing the answer data. By default, the operator will look for an input attribute named answerData.

Properties

answerTypesAttr

Specifies the input attribute containing the answer types. By default, the operator will look for an input attribute named answerTypes.

Properties

filterSHA512Hash

If set to true, SHA512 hashes sent via the TXT field will be reported as benign. If set to false, these payloads will be reported as suspicious. By default, this value is false.

Properties

questionNameAttr

Specifies the input attribute containing the question name (domain name). By default, the operator will look for an input attribute named questionName

Properties

questionTypeAttr

Specifies the input attribute containing the question type. By default, the operator will look for an input attribute named questionType

Properties

trimTXTLengthField

DNS TXT records generally contain two length fields: one length describes the length of the record as a whole. The second length field describes the length of the character string inside the record. This second length field is typically prepended to the TXT data. If this parameter is set to true, the first character of the TXT field (the character representing the second length field) will be removed prior to analyzing the data. If set to false, the entire character string will be analyzed. The default value for this parameter is true.

Properties

Libraries

No description for library.
Library Name: csa, re2
Library Path: ../../impl/lib/csa/, ../../impl/lib/re2/
Include Path: ../../impl/include/re2/, ../../impl/include/csa/, ../../impl/include/csa/tunneling/, ../../impl/include/