Search

Page tree

Contents

 

The purpose of an action template is to convert an event into one or more RESTful API, DXL, and Syslog messages that are sent from the NIOS appliance to the endpoint configured in the notification rule. An action template consists of a series of statements that are interpreted into specific actions. When creating an action template, ensure that it consists of an initial section with some general template settings, followed by one or more steps that are executed in sequence. Steps are constructed for sending messages to the endpoint and for receiving responses. It can also perform specific operations on template variables.

Note

The steps in an action template are executed sequentially. Some constructs enable steps to be skipped by jumping forward in the list of steps; jumping backwards is not supported.


Consider the following guidelines while composing action templates:

  • Template error handling is active only if the severity level for logging is set to Debug, otherwise error handling is disabled and the server continues to execute a template even if the template tries to access nonexistent variables or perform invalid operations such as trying to increment a STRING variable. For information about setting the severity level for logging, see Configuring Outbound Endpoints. If you have disabled template error handling, then accessing any nonexistent variables will return an empty string and invalid operations are not executed.
  • Matching a regular expression is performed un-anchored. If anchoring is required, you must add the characters ^ and/or $ to the respective regular expression.
  • For outbound notifications, only template instances are considered. Template instances are constructed from action templates as well as template instance variables in the template. You may configure these variables through Grid Manager when a specific template is associated to an event.
  • You can use functions that contain the list of steps to be executed. The FUNCTION operation executes the steps in the function.

  • Note that the function steps use step execution limit. Step counters for functions are removed when you return to template steps from function steps.

  • You must specify the list of functions in the event template and these functions can be used only by the event template.

  • Jumping between functions and template steps is not supported.

  • Infoblox supports unused functions and allows execution of a function that is located within a function, including itself.

  • You cannot upload or update a template if the function does not exist.

An action template consists of the variables and elements listed in Table 45.3.

Note

When "yes" is indicated in the "Sub" column for a variable, it means that variable substitution (where it is possible to have ${...} variables as part of the value, and have them substituted when the template is executed) is supported for that variable, a * means that the substitution is supported for some of the fields of the struct.


Action Template Variables

 Table 45.3 Action template Variables

Variable

Type

Mandatory

Sub

Description

version

Must be 5.0

No

No

The version number of the template. Note that 5.0 is the latest version. The appliance still fully supports the previous schema version.

name

String

No

No

The template name.

type

Must be
REST_EVENT for
REST API endpoints
Must be DXL_EVENT
for DXL endpoints
Must be SYSLOG_EVENT for Syslog endpoints

No

No

The template type.

vendor_identifier

String

No

No

The vendor identifier for an endpoint.


event_type

List of ENUM (except for SESSION)


Yes


No

Available event types:

RPZ, LEASE, TUNNEL, ADP, DXL, NETWORK_IPV4, NETWORK_IPV6, RANGE_IPV4, RANGE_IPV6, FIXED_ADDRESS_IPV4, FIXED_ADDRESS_IPV6, HOST_ADDRESS_IPV4,HOST_ADDRESS_IPV6, DISCOVERY_DATA, SCHEDULE, DNS_RECORD, DNS_ZONE, SESSION, SYSLOG_SEND_EVENT, DXL_SEND_REQUEST

Note that SESSION is used for the login and logout events for the session management templates. For information about supported variables for the session management template, see Session Management Template Variables.

action_type

String

No

No

The action type.

comment

String

No

No

Additional information.

content_type

String

No

No

The content type for the whole template. If not specified, it is set as “application/json”. It can be specified either in the template, inside the transport, or both. If both are specified, then the content type specified in the template takes precedence.

quoting

ENUM

No

No

Sets the default serialization for template variables. The valid value is one of the following: JSON, XML, XMLA, ASIS, or URL. If not specified, this is set to JSON. To use XMLA for serialization, you must specify a valid quoting for variables. Infoblox strongly recommends that you use XMLA as the quoting option (as opposed to XML) when you create new action templates. New operations such as PUSH, POP, SHIFT and others are not officially supported for XML parsed data.

headers

Dictionary of key/value pairs

No

Yes

If specified, it is sent for every request of the template, in addition to any other H: namespace variables.

instance_variables

List of VARIABLE structs

No

No

It must be specified in the GUI to create a template instance.

template_variables

List of VARIABLE structs

No

No

template_variables is used when there are common settings in various steps. They are specified for maintainability and they are also available in L: namespace. Note that the template variables are evaluated immediately so that they can be used as reference values in other areas of the template.

transport

TRANSPORT struct

No

No

It is the default for steps.





Steps are executed in sequence. You cannot execute them

steps

List of STEP structs

Yes


Steps are executed in sequence. You cannot execute them in a backward manner.

step_execution_limit

Integer



The maximum number of times a step can be executed. Steps can be executed more than once if using certain template constructs. To avoid possible endless loops, you can limit an individual step to be executed up to a certain number of times. If a step is executed again after the limit is reached, the execution will be interrupted and a failure is logged. The default is 10. The maximum number is 1000.

STEP Struct

Each step can perform a different operation, such as SLEEPCONDITIONNOPGETPOST, PATCHDELETE, DXL_EVENT_SEND, SYSLOG_SEND_EVENT, DXL_EVENT_SEND, or PUTTable 45.4 lists the step variables.

Note

The name for each step must be unique.

  • SLEEP: Steps with a SLEEP operation will pause the execution for the number of seconds specified in the timeout parameter.
  • NOP: Steps with a NOP operation will only parse the text specified in body/body_list without sending it to the endpoint. This can be useful for executing operations on variables to prepare data for subsequent steps.
  • CONDITION: Steps with a CONDITION operation will cause a condition specified in statements to be matched. See Table 45.10 for information about condition variables and Table 45.11 for statement variables.

If the condition matches, the execution of the template will do the following:

    • Stop without errors If the stop field is present,
    • Stop with an errors if the error field is present,
    • Jump forward to the specified step if the next field is present,
    • and/or evaluate the text in eval if the field is present.

If the condition does not match, the text in the else_eval field will be evaluated instead, if the field is present.

  • GET, POST, PATCHDELETE, and PUT: These steps will result in an endpoint communication. The request will be sent to an URI composed by the URI configured in the endpoint, plus the path configured in the session management template if present (or replaced by it, depending on its override setting), plus the path configured in the event template if present (same override considerations), plus the path configured in the individual step if present (same override considerations).
    After variable substitution, any data present in the H: namespace will be sent as headers, any parameters listed will be sent as URI parameters, and any data in body/body_list will be sent as the body of the request. Note also that each step can override the endpoint timeout. This is useful when a certain operation is known to require a longer execution time.
    If the result variable is set in the step, the reply from the server will be evaluated and compared against the specified codes and/or REGEX, and the operation specified in the result step will be executed.
    If parse is set in the step, the result from the server will also be parsed and be made available in the P: namespace as described above.

Note

Set the "wapi" field to send WAPI requests to the Grid Master using available event data. For example, you can add or modify extensible attributes of a NIOS object at the time when the object is being synchronized. If you include the "wapi" field in a step, you must enable WAPI integration by entering the WAPI login username and password while configuring the endpoint. Otherwise, the WAPI step will fail due to an authorization error. For information about how to configure endpoints, see Configuring Outbound Endpoints.


 Table 45.4 STEP Structs

Variable

Type

Mandatory

Sub

Description

name

String

Yes

No

Used to refer to the steps used in the execution of the template.

operation

ENUM

Yes

No

The valid value can be one of the following: GET, POST, DELETE, PATCH, PUT, SLEEP, CONDITION, NOP, VARIABLEOP, DXL_EVENT_SEND, SYSLOG_SEND_EVENT, DXL_SEND_REQUEST, SERIALIZE, or FUNCTION. If you specify SLEEP, only timeout is supported, where timeout is the sleep length in seconds. If you specify NOP, only variable operations are performed, and only body/body_list is supported. If you specify VARIABLEOP, you must use the VARIABLE struct within your steps that are executed in sequence. See VARIABLE Struct for the supported fields. If you specify SERIALIZE, see SERIALIZE Struct for the supported variables.

function_nameStringYes

Function name. Applicable only if the operation is set to FUNCTION.

condition

CONDITION Struct

No


Applicable only if the operation is set to CONDITION.

timeout

String

No

Yes

If specified, overrides the endpoint configuration value (it is useful if the template is slow during execution). Note that the timeout value is invalid for NOP. Since the timeout variable is a string, you can substitute the variable in individual steps.

transport

TRANSPORT Struct

No

Path only


result

List of RESULT Structs

No

No

If not present, you can assume 200, everything else is a failure. If not specified, the steps are executed sequentially. This is not valid for SLEEP, NOP, or CONDITION variables.

parse

ENUM

No

No

If specified, the output of the server will be parsed. The valid value is one of the following: JSON, REGEXLINE, REGEXMULTILINE, REGEX, REGEXSPLIT, XMLA, or XML. Infoblox recommends that you use XMLA instead of XML for parsing. Ensure that you see Result Parsing for details.

parse_regex

String

No

No

You can set one of the following: REGEX, REGEXSPLIT, REGEXLINE, or REGEXMULTILINE

parameters

List of PARAMETERS

No

Value only

These are URI parameters.

headers

Dictionary of name/value pairs

No

Yes

This is sent as HTTP headers. The name space substitution is supported only for value. Note that assigning to the H: name space also sends headers.

override_headers

Boolean

No

No

If specified, only these headers and H: name space headers are sent instead of template headers.

body

String

No

Yes

This is applicable only for POST, PATCH, DXL_EVENT_SEND, SYSLOG_SEND_EVENT, DXL_SEND_REQUEST, and PUT requests as well as NOP and FUNCTION operations. It will be sent as the body of the request. Note that name space substitution is supported.

body_list

List of strings

No

Yes

This is an alternative to the body. If specified, the strings in the list will be joined before sending it. Any leading or trailing whitespace is removed. This is applicable to FUNCTION operation.

no_connection_debug

Boolean

No

No

The valid value is True or False. If this is set to True even if the endpoint is set to a Debug level logging, only the body, headers, and cookies for the corresponding step will NOT be output to the debug log. Only explicit DEBUG calls will be displayed. This is generally used in login templates to avoid usernames and passwords from being logged to the log files in plain text.

variable_ops

List of VARIABLEOP structs

No

No

For more information, see VARIABLEOP Struct.

serializations

List of SERIALIZE structs

No

No

For more information, see SERIALIZE Struct.

comment

String

No

No

Adds information about the steps.

wapiStringNoNo

The WAPI version. When this is set, the username and password (auth username and auth password) specified for the endpoint are ignored for WAPI related steps only. Other steps still use the configured auth username and auth password. All WAPI requests are sent to the Grid Master IP. The path of the requests is /wapi/[version]/ with the appended path as specified in the step. The override path option as well as any path configured in the session management template will have no effect.

wapi_quotingENUMNoNo

The valid value is one of the following: JSON or XML. If this is not specified, it is set to JSON. The default is JSON. JSON and XML parsing performs as usual for WAPI.

dxl_topicStringNoPath only

The DXL topic that is used to send data by DXL.
Note: This variable is applicable only for the DXL templates.

VARIABLEOP Struct

Note that all fields are optional, except operation and typeNo schema validation is made for variable combinations. Validation of the schema is performed when you add or modify the action template., no specific JSON schema validation is made for variable combinations as it would be too complex, the validation will be done at template conversion time (which is still done when users upload / edit templates).

Note

All variables listed in the following table are applicable only for the VARIALBEOP operation in the STEP struct. The VARIABLEOP struct converts specified keys/values in a complex variable (such as LIST, DICTIONARY, or XML values with attributes) or performs operations on an existing complex variable. No schema validation is made for variable combinations. Validation of the schema is performed when you add or modify the action template.


 Table 45.5 VARIABLEOP Struct

Variable

Type

Mandatory

Sub

Description

source

String

No

Yes

You must specify the variable name, including the namespace. You can include nested variables. Example: L:DICT{key}{list})

destination

String

No

Yes

You must specify the variable name, including the namespace. You can include nested variables. Example: L:DICT{key}{list})

operation

ENUM

Yes

Yes

Specifies the operation being performed for the value defined or created in type. The valid value is one of the following: PUSH, POP, SHIFT, UNSHIFT, or ASSIGN. Note that both operation and type are mandatory for the struct. For examples, see Using OPERATION in the VARIABLE Struct.


type


ENUM


Yes


Yes

Specifies the type of variables for the operation. Valid value is one of the following: LIST, DICTIONARY, COMPOSITE, or SINGLE. This field defines how the values in keys, values, and composite_value are combined to create a variable while operation defines how the variable is being used. The appliance handles keys, values and composite_value differently based on the type you select, as follows:

  • LIST: keys will be ignored; values will contain the required values and be serialized in a simple list of strings.
  • DICTIONARY: The list of key/value pairs in keys and values will be put in a simple dictionary.
  • COMPOSITE: The list of key/value pairs in keys and values will be put in an XMLA dictionary with a name set to name and a value set to either the value in composite_value OR the value in the variable set in source. See Using the COMPOSITE Type for details about how to use COMPOSITE.
  • SINGLE: keys will be ignored; the value will be the first element in the values list.

name

String

No

Yes

This is applicable only if you select COMPOSITE as the variabletype. Enter the name value for this type.

keys

List of strings

No

Yes

This can contain arbitrary serializable constructs.

values

List of strings

No

Yes

This can contain arbitrary serializable constructs. When you specify this field inside any variable operation for the VARIABLEOP step type, it is possible to use the constant of a specific type, instead of using string. For details about how to  specific type, instead of using string. For details about how to use constant, see Constant Specification for values.

composite_value

String

No

Yes

This can contain arbitrary serializable constructs.

destination_key

String

No

Yes

This can contain arbitrary serializable constructs.

if_exists

ENUM

No

Yes

The action taken if the variable exists. The valid value is one of the following: SKIP, ERROR, or NEXT.

if_exists_next

String

No

Yes

Enter the name for the next step.

conditionCONDITION StructNo
This can be specified for POP and UNSHIFT operations.

Using the COMPOSITE Type

When you use COMPOSITE as the type in the VARIABLE struct, the list of key/value pairs in keys and values is put in an XMLA dictionary with a name set to name and a value set to either the value in composite_value OR to the value in the variable set in source.

Here is an example of using COMPOSITE as the type when you use the following variables and values:

FieldValue
typeCOMPOSITE
namevarname
keys["a1", "a2"]
values["value is ${L::SOMEVAR}", "2"]
composite_value"123"

It results in the following:

{

   "<xmla>": true,

   "attrs": {

      "a1": "value is 123",

      "a2": "2",

   },

   "index": {},

   "value": ["123"],

   "name": "varname"

}

Note

If source is set, the value in source is used as is (this can be seen especially for PUSH operations).


Using OPERATION in the VARIABLE Struct

operation ASSIGN

If operation is set to ASSIGN, the value in type will be simply put in the variable identified by destination, overwriting any value it might already have.

The following are several examples of the ASSIGN operation having namespace E as follows:

{

  'some_field': 'some_value',

  'some_list': ['item1', 'item2']

}

(1) When assigning a single value:

{

  'operation': 'ASSIGN',

  'type': 'SINGLE',

  'destination': 'L:var',

  'values': ['value']

}

It returns name space L as follows:

{'var': 'value'}

(2) When assigning a list:

{

  'operation': 'ASSIGN',

  'type': 'LIST',

  'destination': 'L:list',

  'values': ['value', '${E:A:some_field}']

}

It returns the following:

{'list': ['value', 'some_value']}

(3) When assigning a dictionary:

{

  'operation': 'ASSIGN',

  'type': 'DICTIONARY',

  'destination': 'L:dict',

  'keys': ['${E:A:some_field}_1', '${E:A:some_field}_2'],

  'values': ['${E:A:some_list[0]}', '${E:A:some_list[1]}']

}

It returns the following:

{'dict': {'some_value_2': 'item2', 'some_value_1': 'item1'}}

(4) When assigning a composite value, as follows:

{

  'operation': 'ASSIGN',

  'type': 'COMPOSITE',

  'destination': 'L:composite',

  'name': 'tag_name',

  'keys': ['attr_1', 'attr_2'],

  'values': ['${E:A:some_field}', 'another_value'],

  'composite_value': 'tag_content'

}

It gives the following:

{'composite': {

  'index': {}, '<xmla>': True,

  'attrs': {

    'attr_2': 'another_value',

    'attr_1': 'some_value'

  },

  'value': ['tag_content'],

  'name': 'tag_name'

}}

This composite value can be serialized to the following XML:

<tag_name attr_1="some_value" attr_2="another_value">tag_content</tagname>

operation PUSH and SHIFT without setting if_exists

If destination_key is set, the assumption is to push or shift to a dictionary; otherwise, it is to push or shift to a list.

For pushing to a list, if the destination variable exists and is a list, the list of values in values will be added to the existing list. With PUSH, it means that the values will be added to the right side of the list (at the end) of the list. With SHIFT however, the values will be added to the left side (at the beginning) of th list.

If the destination variable is a dictionary, it will be converted to a list that contains only one element with the value appended to it. This means that for XML deserializing and JSON values, it is possible to create a list by pushing it on to an existing scalar value.

For pushing to a dictionary, it means that with destination_key set, if the destination variable exists and is anything but a dictionary, it is considered as an error. If it is a dictionary however, the value above will be added with its key set to destination_key overwriting any existing value.

If the variable denoted by destination has a composite value, the COMPOSITE type can be pushed or shifted to it only. If the destination composite value contains text, the text will be replaced with the composite value. In other cases, the PUSH operation using the new value will be added to the right side of the children list. For the SHIFT operation, the new value will be added to the left side of the children list.

The following are several examples of the ASSIGN operation having namespace E:

{'some_field': 'some_value'}

and namespace L as follows:

{

   'some_list': ['item1', 'item2'],

   'some_dict': {'key': 'val'},

   'comp1': {

     'index': {}, '<xmla>': True,

     'attrs': {

        'attr1_b': 'another_value',

        'attr1_a': 'some_value'

     },

     'value': ['tag_1_content'],

     'name': 'tag_1'

   },

   'comp2': {

     'index': {}, '<xmla>': True,

     'attrs': {},

     'value': ['tag_2_content'],

     'name': 'tag_2'

   }

}

(1) When PUSH or SHIFT to a list:

{

   'operation': 'PUSH',

   'type': 'SINGLE',

   'destination': 'L:some_list',

   'values': ['${E:A:some_field}_right'],

},

{

   'operation': 'SHIFT',

   'type': 'LIST',

   'destination': 'L:some_list',

   'values': ['left_${E:A:some_field}']

},

It returns namespace L as the following:

{'some_list': [['left_some_value'], 'item1', 'item2', 'some_value_right']}

(2) When PUSH or SHIFT to a dictionary, it returns the following:

{'some_dict': {

  'push1': 'item',

  'push2': ['item_1', 'item_2'],

  'key': 'val'

}}


Note: There is no difference between PUSH and SHIFT when destination is DICTIONARY.


(3) When PUSH or SHIFT to a composite value:

{

   'operation': 'PUSH',

   'type': 'COMPOSITE',

   'destination': 'L:comp1',

   'name': 'pushed',

   'composite_value': ''

},

{

   'operation': 'SHIFT',

   'type': 'COMPOSITE',

   'destination': 'L:comp1',

   'source': 'L:comp2'

},

It returns the following:

{

   'comp1': {

   'index': {u'pushed': 1, 'tag_2': 0},

   '<xmla>': True,

   'attrs': {'attr1_a': 'some_value', 'attr1_b': 'another_value'},

   'value': [

     {'index': {}, '<xmla>': True, 'attrs': {}, 'value': ['tag_2_content'], 'name': 'tag_2'},

     {'index': {}, '<xmla>': True, 'attrs': {'attr': 'val'}, 'value': [], 'name': 'pushed'}

   ],

   'name': 'tag_1'

  }

}

Note that the first operation (PUSH) overwrites existing value and the second operation (SHIFT) shifts the value to the existing list. This composite value can be serialized to the following XML:

<tag_1 attr1_a="some_value" attr1_b="another_value">

  <tag_2>tag_2_content</tag_2>

  <pushed attr="val"/>

</tag_1>

operation PUSH and SHIFT with if_exist set

If destination_key is set, the assumption is to push or shift to a dictionary. Otherwise it is to push or shift to a list.

If you are pushing to a list, and the variable already exists, the operation specified there will be executed as follows: SKIP will not modify the original value, NEXT will not modify and jump to the step specified in if_exists_next, and ERROR will instead return an error.

If you are pushing to a dictionary, and the variable matches, there is no need to modify the values because they would already be the same. Therefore, SKIP will be a no-operation, NEXT will not modify and jump to the step specified in if_exists_next, and ERROR will instead return an error.

The decision for whether a new value exists or not is a simple comparison with the value/attributes of the existing variables in the list or dictionary in destination_key. They all have to match for if_exists for the operation to be triggered.

If variable denoted by destination has a composite value, the semantics is as above, with additional checks. The check is complete before the value is added to the list of children. During the check, the new composite value is compared one by one with the existing values. If the values are the same, the “if_exists” logic is triggered as above.

The following are a few examples using namespace L as follows:

{

   'some_list': ['item1', 'item2'],

   'some_dict': {'key1': 'val1', 'key2': 'val2'},

   'list_of_lists': [['a', 'b'], ['a', '2'], ['1', '2']],

   'composite': {

     '<xmla>': True,

     'index': {'inner_1': 0, 'inner_2': 1},

     'name': 'outer',

     'attrs': {'outer_attr': 'outer_val'},

     'value': [

       {

          '<xmla>': True,

          'index': {},

          'name': 'inner_1',

          'attrs': {},

          'value': ['inner_1_content']

       },

       {

          '<xmla>': True,

          'index': {},

          'name': 'inner_2',

          'attrs': {'inner_attr': 'inner_val'},

          'value': []

       }

     ]

  }

}

(1) When PUSH to a list with the item exists:

{

   'operation': 'PUSH',

   'type': 'SINGLE',

   'destination': 'L:some_list',

   'values': ['item2'],

   'if_exists': 'ERROR'

}

It triggers the ‘if_exits’ login. ‘ERROR’ means stopping the template execution with error, ‘SKIP’ means ‘do nothing for this operation’ and ‘NEXT’ will jump to the step with name specified in ‘if_exists_next’.

(2) When PUSH to a dictionary with the item exists:

{

   'operation': 'PUSH',

   'type': 'SINGLE',

   'destination': 'L:some_dict',

   'destination_key': 'key2',

   'values': ['val2'],

   'if_exists': 'ERROR'

}

It triggers an error. Note that both key and value should be the same in order to trigger the ‘if_exists’ logic. If key is the same but value differs, value will be overwritten. If key is different, the new key with value will be added.

(3) When PUSH to a list of list with the item exists:

{

   'operation': 'PUSH',

   'type': 'LIST',

   'destination': 'L:list_of_lists',

   'values': ['a', '2'],

   'if_exists': 'ERROR'

}

It triggers an error.

(4a) When PUSH to a composite value with the item exists, as follows:

{

   'operation': 'PUSH',

   'type': 'COMPOSITE',

   'destination': 'L:composite',

   'name': 'inner_1',

   'composite_value': 'inner_1_content',

   'if_exists': 'ERROR'

}

It triggers an error.

(4b) When PUSH to a composite value with the item exists, as follows:

{

   'operation': 'PUSH',

   'type': 'COMPOSITE',

   'destination': 'L:composite',

   'name': 'inner_2',

   'keys': ['inner_attr'],

   'values': ['inner_val'],

   'composite_value': '',

   'if_exists': 'ERROR'

}

It triggers an error.

operation POP and UNSHIFT

If the source variable is anything but a dictionary, a list, or a composite value, an error is returned. If keys is set, the source value is assumed to be a dictionary. Otherwise, an error is returned.

If the source variable is a list, a single value is removed from the list. If the operation is POP, it is removed from the right side (from the end). If the operation is UNSHIFT, it is removed from the left (at the beginning). The removed value is put in the destination variable.

If the source variable is a composite value, the operation is on the children list of the composite value. Note that it is not possible to POP or UNSHIFT from a composite value, if it has text only.

If the source variable is a dictionary, the specified keys and/or key/value pairs will be removed from the variable in source. If only keys are passed, those keys will be unconditionally removed. If keys and values are passed, the key will be removed from the source variable only if its value matches what is passed in values here. If only one key or key/value pair is passed, the removed value will be put in destination. Otherwise, it will simply be dropped.

For the values match, the value in the list or dictionary will be serialized with quoting specified in the template before being compared to the string value passed in values. This also means that using comparison on large lists would potentially be a slow operation.

In the POP or UNSHIFT case, type is validated to be the same as the type of the popped or unshifted variable (you can validate if they were planning to pop a simple scalar if there is one). If it is not, an error will be raised if debug is turned on.

The following are a few examples using namespace L as follows:

{

   'some_list': ['item1', 'item2'],

   'some_dict': {'key1': 'val1', 'key2': 'val2'},

   'list_of_lists': [['a', 'b'], ['1', '2']],

   'list_of_dicts': [{'a': '1'}, {'b': '2'}],

   'composite': {

     '<xmla>': True,

     'index': {'inner_1': 0, 'inner_2': 1},

     'name': 'outer',

     'attrs': {'outer_attr': 'outer_val'},

     'value': [

          {

              '<xmla>': True,

             'index': {},

             'name': 'inner_1',

             'attrs': {},

             'value': ['inner_1_content']

         },

         {

            '<xmla>': True,

            'index': {},

            'name': 'inner_2',

            'attrs': {'inner_attr': 'inner_val'},

            'value': []

        }

      ]

   }

}

(1) When POP from a list:

{

   "operation": "POP",

   "type": "SINGLE",

   "source": "L:some_list",

},

It gives the variable as follows:

{"some_list": ["item1"]}

(2) When UNSHIFT from a list:

{

   "operation": "UNSHIFT",

   "type": "SINGLE",

   "source": "L:some_list",

}

It returns the following:

{"some_list": ["item2"]}

(3) When UNSHIFT from a dict by key:

{

   "operation": "UNSHIFT",

   "type": "SINGLE",

   "source": "L:some_dict",

   "keys": ["key1"]

}

It returns the following:

{"some_dict": {"key2": "val2"}} There is no difference between POP/UNSHIFT fro dictionarries

(4) When POP from a dict by multiple keys:

{

   "operation": "POP",

   "type": "SINGLE",

   "source": "L:some_dict",

   "keys": ["key1", "key2"]

}

It returns the following:

{"some_dict": {}}

(5) When POP from a dict when a key is absent:

{

   "operation": "POP",

   "type": "SINGLE",

   "source": "L:some_dict",

   "keys": ["key1", "absent_key"]

}

It returns an error in the DEBUG mode. For non-DEBUG mode, all existing keys are POPed. Note that items are popped one by one, so key1 item is popped before the error is returned.

{"some_dict": {"key2": "val2"}}

(6) When POP from composite value:

{

   "operation": "POP",

   "type": "SINGLE",

   "source": "L:composite",

}

It returns the following:

{

   "composite": {

     "index": {"inner_1": 0},

     "<xmla>": True,

     "name": "outer",

     "value": [{

        "index": {},

        "<xmla>": True,

        "name": "inner_1",

        "value": ["inner_1_content"],

        "attrs": {}

    }],

    "attrs": {"outer_attr": "outer_val"}

  }

}

This can be serialized to the following:

<outer outer_attr="outer_val">

   <inner_1>inner_1_content<inner_1>

</outer>

(7) When conditional POP/UNSHIFT from a list:

{

   "operation": "POP",

   "type": "SINGLE",

   "source": "L:some_list",

   "values": ["item1"]

}

It returns the following:

{"some_list": ["item2"]}

There is no difference between POP and UNSHIFT when ‘values’ is specified. When source is either LIST or COMPOSITE, all occurrences of a value are deleted.

(8) When conditional POP/UNSHIFT from a dictionary:

{

   "operation": "UNSHIFT",

   "type": "SINGLE",

   "source": "L:some_dict",

   "keys": ["key2"],

   "values": ["val2"]

}

It returns the following:

{"some_dict": {"key1": "val1"}}

(9) When conditional POP/UNSHIFT of multiple values:

{

   "operation": "UNSHIFT",

   "type": "SINGLE",

   "source": "L:some_dict",

   "keys": ["key2", "key2"],

   "values": ["abc", "val2"]

}

It returns the following:

{"some_dict": {"key1": "val1"}}

(10) When conditional POP/UNSHIFT with list values:

{

   "operation": "POP",

   "type": "SINGLE",

   "source": "L:list_of_lists",

   "values": ["\"['1', '2']\""]

}

It returns the following:

{"list_of_lists": [["a", "b"]]}

For conditional POP/UNSHIFT, non-string values are serialized with the template's quoting. For JSON, quoting is added to value.

(11) When conditional POP/UNSHIFT with dictionary value:

{

   "operation": "POP",

   "type": "DICTIONARY",

   "source": "L:list_of_dicts",

   "values": ["\"{'b': '2'}\""]

}

It returns the following:

{"list_of_dicts": [{"a": "1"}]}

(12a) When conditional POP/UNSHIFT with the following composite values:

{

   "operation": "POP",

   "type": "COMPOSITE",

   "source": "L:composite",

   "values": ["\"{'index': {}, '<xmla>': True, 'name': 'inner_2', 'value': [],

   'attrs': {'inner_attr': 'inner_val'}}\""]

}

It returns the following:

{

   "composite": {

     "index": {"inner_1": 0},

     "<xmla>": True,

     "name": "outer",

     "value": [{

       "index": {},

       "<xmla>": True,

       "name": "inner_1",

       "value": ["inner_1_content"],

       "attrs": {}

     }],

    "attrs": {"outer_attr": "outer_val"}

  }

}

(12b) When conditional POP/UNSHIFT with the following composite values, and with the template quoting set to XMLA:

The example in (12a) can be specified as follows:

{

   "operation": "POP",

   "type": "COMPOSITE",

   "source": "L:composite",

   "values": ["<inner_2 inner_attr=\"inner_val\"/>"]

}

Type check after POP/UNSHIFT:

{

   "operation": "POP",

   "type": "LIST",

   "source": "L:some_dict",

   "keys": ["key2"]

}

It returns an error in the DEBUG mode. Since the type of POPed value is not LIST, the possible values for type are 'SINGLE', 'LIST', 'DICTIONARY', and 'COMPOSITE', where 'SINGLE' means ‘no check’. Note that type check is done after the item is retrieved from source. In the DICTIONARY case, when several keys are specified, there is no type check. Type check is done after value comparison.

(13) When putting the item to ‘destination’:

{

   "operation": "POP",

   "type": "COMPOSITE",

   "source": "L:composite",

   "destination": "L:sub_item"

}

It returns the following:

{

   "composite": {

      "index": {"inner_1": 0},

      "<xmla>": True,

      "name": "outer",

      "value": [

        {"index": {}, "<xmla>": True, "name": "inner_1", "value": ["inner_1_content"],

   "attrs": {}}

      ],

      "attrs": {"outer_attr": "outer_val"}

      },

    "sub_item": {

      "index": {},

      "<xmla>": True,

      "name": "inner_2",

      "value": [],

      "attrs": {"inner_attr": "inner_val"}

   }

}

If the value popped/unshifted from source and destination is specified, the value is written to the destination. The value is written after the type check.

The L:sub_item can be serialized as the following:

<inner_2 inner_attr="inner_val"/>

Constant Specification for values

When you specify the values field inside any variable operation for the VARIABLEOP step type, it is possible to use the constant of a specific type, instead of string.

For example, the following describes three string values:

‘values’: [‘True’, ‘42’, ‘${L::some_var}’]

If you specify values as ‘{X:something}’, ‘something is represented as a constant of type X. Note that this is the only allowed syntax. For example, ‘text{X:something}’ is treated as a string, instead of a constant specification.

The following types are supported in constant specification:

  • Bool type (B): Both '{B:1}' and '{B:true}' are evaluated as bool true, while '{B:0}' and '{B:false} are evaluated as bool false. Note that both 'true' and 'false' are not case-sensitive. Therefore, True, FALSE or even tRuE are all allowed. Other invalid values such as 'B:' and '{B:anythingelse}' are evaluated as bool=false (the 'default value') without further debugging; and an error is logged in the debug mode.
  • Integer type (I): '{I:}' is evaluated to its corresponding integer value. For example, {I:-42} is evaluated as integer -42. The default value is 0.
  • Empty type (E): ‘{E:}’ is evaluated as None. ‘{E:[]}’ is evaluated as an empty list. ‘{E:{}}’ is evaluated as an empty dictionary. The default value is None.

  • Float type (F): The float type is similar to the integer type. Float numbers can be specified as '{F:0.0}', '{F:-4.2}', '{F:-4E+2}' or '{F:+1.23e-45}. The default value is 0.0.

  • String type (S): '{S:}' is evaluated as string ''. For example, '{S:{I:42}}' is string '{I:42}'. There is no default value for string. For the unknown type (e.g. '{U:%^&}'), the default value is an empty string.

The following example illustrates how to use constant specification to define ipv4addr with a DHCP option:

{

   “ipv4addr”: “1.2.3.4”,

   “options”: [

     {

       “name”: 'dhcp-lease-time”,

       “num”: 51,

       “use_option”: true,

       “value': '43200”,

       'vendor_class': “DHCP”

     }

   ]

}

Note that num is an integer (in this string: “num”: “51”) and use_option is bool (in this string: “use_option”:

“true”).

In the action template, you can do the following:

{

   “steps”: [

   {

     “operation': 'VARIABLEOP”,

     “variable_ops”: [

       {

         “operation”: “ASSIGN”,

         “type”: “DICTIONARY”,

         “destination”: “L:addr”,

         “keys”: [“ipv4addr”, “options”],

         “values': [“1.2.3.4”, “{E:[]}”]

      },

      {

         “operation”: “PUSH”,

         “type”: “DICTIONARY”,

         “destination”: “L:addr{options}”,

        “keys”: [ “name”, ”num”, “use_option”, “value”, “vendor_class”],

         “values': [“dhcp-lease-time”, ”{I:51}”, ”{B:true}”, “43200”, “DHCP”]

       }

     ]

   },

   {

   “operation”: “PUT”,

   “transport”: {“path”: “record:host_ipv4addr”},

   “body”: “${L:J:addr}”

   }

  ]

}

SERIALIZE Struct

Table 45.6 SERIALIZE Struct


Note: All variables listed in the following table are applicable only for the SERIALIZE operation in the STEP struct. The SERIALIZE structs inside the step are executed in sequence.


Field

Type

Mandatory

Sub

Description

content

String

Yes

Yes

Defines what to serialize. This can contain arbitrary variables and text.

destination

String

Yes

Yes

Defines the destination for the serialization.

TRANSPORT Struct


Table 45.7 TRANSPORT Structs

Variable

Type

Mandatory

Sub

Description

path

String

No

Yes, if specified in step.

If present, it is appended to the endpoint URI.

override_path

Boolean

No

No

If this is true, the specified path completely overrides the endpoint URI after the first /.

content_type

String

No

No

If specified, this overrides the endpoint content type.

RESULT Struct

Note the following:

  • codes and regex are ignored if the operation is SLEEP or NOP.
  • At least one of the following is required: nextstop, or error.


Table 45.8 RESULT Structs

Variable

Type

Mandatory

Sub

Description

codes

string separated by commas

No

No

The http return code.

regex

REGEX

No

No

If specified, REGEX is matched against the returned body.

next

id

No

No

The step to execute the next template if the code (and REGEX, if

specified) match. But if the next template is already executed once, the

appliance displays an error.

stop

Boolean

No

No

If set, the execution of the script is stopped. Note that next, error, and stop are mutually exclusive.


error


Boolean


No


No

If set, the execution of the script is stopped and then rerun with an error status if the retry_template is not set to 0. Note that next, error, and stop are mutually exclusive.

PARAMETER Struct


Table 45.9  PARAMETER Structs

Variable

Type

Mandatory

Sub

Description

name

String

Yes

No

Name of the parameter.

value

String

Yes

Yes

Value of the parameter. Note that this value is used as-is, so any strings that are not part of the variables must be URL encoded (%20 for spaces, and etc.)

CONDITION Struct

Table 45.10 CONDITION Structs

Variable

Type

Mandatory

Sub

Description

condition_type

String

Yes

No

This can be one of the following: AND, OR, NAND, or NOR. NAND means not (st1, st2, etc.)

next

String

No

No

The name of the step to jump to if the condition is successful.

eval

String

No

Yes

This is executed if the condition is successful. Generally, it will be an XC: set of operations.

else_eval

String

No

Yes

This is executed if the condition is NOT successful. Generally, it will be an XC: set of operations.

else_next

String

No

Yes

The execution will jump to specified step if the condition is NOT successful.

else_stop

String

No

Yes

The template execution will be stopped if the condition is NOT successful.

else_error

String

No

Yes

Generates an error if the condition is NOT successful.

stop

Boolean

No

No

If the condition is successful the execution will be stopped without any error.

error

Boolean

No

No

If the condition is successful the execution will be stopped with an error.

statements

List of STATEMENT
structs

Yes

Yes

The statements to evaluate.

STATEMENT Struct

Table 45.11 STATEMENT Structs

Variable

Type

Mandatory

Sub

Description

leftStringYesYes

The left operand. Note that it is acceptable to include variables that do
not exist on the left side (to test if a variable is set in an event). Any error
during evaluation of the `left` is ignored even if it is run under debug
mode.

opENUMYesNoThe operation to execute. This can be one of the following: =, >, <, >=, <=,
=~, and !~. Note that the >, <, >=, and <= operations try to convert the
operands to numbers before executing the comparison, then = ~, and !~
are REGEX matches and the right side is considered the REGEX.
rightStringYesYesThe right operand.


Action Template Variables and Name Spaces

Action templates can access variables in several different name spaces. The following are the available name spaces:

  • C: http cookies. It supports only the DEL operation (primarily for logout purposes), but it can be used as a substitution origin.
  • Read-Only E: Event data.
  • H: http headers. Note that the assigned variables are sent in the next HTTP request and it survives the template execution.
  • Read-Only I: Template instance variables. It is set in the GUI during the creation of the filter and it also includes the endpoint variables that are set in the GUI when creating an endpoint. Note that the instance variables can override endpoint variables, if needed.
  • L: Local template variables. This name space is empty at name space startup and will not survive the template invocation.
  • Read-Only P: Previous endpoint response values (if parsing is enabled for the response.)
  • Read-Only R: Previous endpoint request http-specific return values. This includes RC, the http status code of the previous request (Example: 200), BODY, and the body of the response.
  • Read-Only RH: Previous endpoint request that returned http headers.
  • S: Endpoint session state variables. These variables survive the template invocation (it is used similar to L: name space which is not cleared at the end of the template execution.)
  • Read-Only UT: Read-only utility variables. The UT: name space contains the following read-only variables:
    • EPOCH: EPOCH seconds since Jan 1st, 1970 (integer, 1 second resolution.)
    • TIME: UTC time in ISO-8601 format. Example: 2016-04-08T23:09:35Z (1 second resolution).
    • UUID: Random UUID of the form 00000000-0000-0000-0000-000000000000.
    • PROTOCOL: The protocol used for the request.
    • URI: Complete URI used for the request.
    • HOST: The endpoint address.
    • PORT: The port used for the request.
  • Read-Only XC: Execute a command on the variable. This results no output.

Action Template Variable Format

The following sequences are substituted with dynamic data:

${<data namespace>:<output format>:<name of the data or operation dependent values>}

The sequences cannot contain the following characters as variable names: {, }, [, and ]. Therefore, if names contain keys of dictionary/EA variables, they must be quoted with the \ character. Example: *${E::SOME_EA{name with \{ embedded \] braces or brackets}*. But if the \ character is desired, it must be quoted as \. Note that variable substitution happens only once, it is not nested (i.e. if the value contains ${...}, it will not be recursively substituted). Also, the dynamic data is not supported for instance and template variables which are assumed to be immediate values.
The following types of variables allow further qualifiers after the variable name. The qualifiers are always mandatory. Therefore, if a variable is a list or a dictionary, then you must specify [ ] or { }.

  • EA (Extensible Attribute) variables or dictionaries. In general, you must specify {EAname} for EA variables or dictionaries. For example, if you specify ${E::NETWORK_EA{City}}, it means the city EA from the network EAs. Note that data specific portion is mandatory for EA variables.
  • List variables. You can specify the list index using square brackets. For example, for a list of DNS names if you specify ${E::DNS_NAMES[0]}, this indicates the first DNS name in the list.

You can also use { } or [ ] to signify the full dictionary or list that is supported only in some encodings. Optionally, you can specify the output format. The following output formats are supported:

  • J: The output is in the form of JSON formatted variable. It supports deserializing lists as well as dictionaries. Note that strings will have double quotes prepended/appended when serialized with J.
  • j: The output is in the form of JSON formatted variable. It supports deserializing lists as well as dictionaries without the leading or trailing double quotes, if the variable is a string.
  • X: The output is in the form of XML formatted variable. It supports only deserializing lists, such as < item >..</item > sequence.
  • U: The output is in the form of url encoded variable. It supports deserializing lists and the output will be a string (comma separated value.)
  • A: The output will be a variable, which is as-is.
  • S: The output is in the form of a string. This is the default for JSON if you do not specify any output format. By default, even numbers will be serialized as JSON strings, meaning the output in a JSON quoted template for a numerical value of 1234 will be "1234".
  • N: The output is in the form of numbers. For example, if the variable is a boolean, the output will be 0, 1, etc.
  • B: The output will be a boolean, that is true/false.
  • L: The length of the variable. This is supported only for lists (the length of the list) and dictionaries (the number of keys).
  • T: The type of the variable. This can be one of the following characters: 'S' for strings, 'L' for lists, 'D' for dictionaries, 'B' for booleans, 'N' for numbers, and 'O' for otherwise.

The default is set by the template quoting option and by using a variable. If you have not set the template quoting, then JSON will be set, by default. If you have set the template quoting, the output format will be as specified, unless the variable is in the following fields:

  • Headers: Any variable inside a headers block is serialized by default, as ASIS.
  • Parameters: Any variable inside a parameters block is serialized by default, as URL.
  • Path: Any variable inside a path block is serialized by default, as ASIS.

Command Execution

If you use XC: name space, then the value can be one of the following:


Note: The argument will be one or two nested variable specifications separated by ':' but without the '$' symbol.
The variables inside 'XC' do not have an output format, so you must use only one ':'.


  • ASSIGN: Assigns the value to the specified variable. Note that the value assigned is in the format I/S/B:value for integer, string, and boolean values. Example: ASSIGN:variable:value.
  • DEBUG: Outputs the specified variable to the debug file (if the log level is not set to DEBUG, this will be ignored), if only the name space is used, the whole name space will be printed.
  • INC: Increments the variable value. If the value is not a number, NIOS displays an error.
  • DEC: Decreases the variable value. If the value is not a number, NIOS displays an error.
  • COPY: Copies one variable into another. Example: COPY:destination:source.
  • DEL: Removes the variable. This supports only the C:, H:, L:, and S: name spaces.
  • FORMAT: Formats the value according to what is specified after the second ':'. Currently, NIOS supports the following formats:
  • U: Converts to uppercase value.
  • L: Converts to lowercase value.
  • DATE_EPOCH: Assuming that the value is a date expressed in UTC ISO 8601 date format. For example, 2016-03-13T04:50:31Z will be converted to EPOCH seconds.
  • DATE_ISO8601: Assuming that the value contains EPOCH seconds. The value is converted to a date string expressed in UTC ISO 8601 date format. For example, 1467152565 will be converted to 2016-06-28T22:22:45Z. If the variable contains milliseconds, they will be preserved. For example 1467152565.57 will be converted to 2016-06-28T22:22:45.570Z.
  • DATE_STRFTIME: Assuming that the variable contains EPOCH seconds. The value is converted to a date string with the specified format which is passed as the second parameter to the function.
  • PUNYCODE_TO_UTF-8: Assuming that the variable contains a punycode encoded domain name. The domain name representation will be converted to UTF-8 characters. Note that there might be a failure if the domain name has non-UTF-8 characters in its wire format.
  • TRUNCATE: Assuming that the variable is a string and it will be truncated as specified. The format is a number (positive or negative) followed by the letter 'l' or 'r'. The number is the starting character of the string (positive will be counted from the beginning, negative will be counted from the end) and f/t defines if the characters are from, after, or to that point. For example, if a string is 12345, then 1f will produce 2345, 1t will produce 1, -1f will produce 5 and -1t will produce 1234.

Format operations will function like other operations if an error occurs, but the variable is not modified. However, the error can be ignored if the log setting is not set to Debug. For information about how to set the logging level, see Configuring Outbound Endpoints.

The following are some examples of using XC operations to increment and decrement IP address strings, create a network range, or remove a specific IP address.

Incrementing or Decrementing IP addresses

Use the XC:INC and XC:DEC operations respectively to increment and decrement IP address strings.

Examples:

  • For namespace {'L':{'ip_str': '1.2.3.4'}}, an evaluating variable "${XC:DEC:{L:ip_str}}" results in {'L':{'ip_str': '1.2.3.3'}}.
  • The same goes for IPv6 addresses. For namespace {'L':{'ip_str': '2001:db8::2'}}, an evaluating variable "${XC:INC:{L:ip_str}}" results in {'L':{'ip_str': 2001:db8::3'}}, and an evaluating "${XC:DEC:{L:ip_str}}" results in {'L':{'ip_str': '2001:db8::1'}}.

The increment of the last address results in the first address. The decrement of the first address results in the last address.
Examples:

INC of ‘255.255.255.255’ results in ‘0.0.0.0’
INC of ‘ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff’ results in ‘::’
DEC of ‘0.0.0.0’ results in ‘255.255.255.255’
DEC of ‘::’ results in ‘fff:ffff:ffff:ffff:ffff:ffff:ffff:ffff’

Creating Network Ranges from Strings

Use the XC:NETWORKTORANGE operation to create a range from a network string. This operation should be specified as the following: ${XC:NETWORKTORANGE:{“var_with_network”}:{“var_for_range”}} where network is a string such as ‘1.2.3.4/16’ or ‘2001:db8:ce4::/48’

The resulting range is an XMLA value such as the following:

{
   '<xmla>': True,
   'name': 'range',
   'attrs': {'from': '1.2.0.0', 'to': '1.2.255.255'},
   'value': [],
   'index': {}
}

or

{
   '<xmla>': True,
   'name': 'range',
   'attrs': {'from': '2001:db8:ce4::', 'to':
 '2001:db8:ce4:ffff:ffff:ffff:ffff:ffff'},
   'value': [],
   'index': {}

}


Note: “var_with_network” must be a top-level variable in a namespace such as E:var, but not L:var{key}[42].


When namespace E is {‘E’: {‘net’: ‘1.2.3.4/16’}} and the response is as follows:

<SiteConfigResponse success="1">
  <Site id="42" name="this_site" description="testing site" riskfactor="1.0" isDynamic="0">
   <Description>testing site</Description>
   <Hosts>
     <host>a.com</host>
   </Hosts>
   <Credentials></Credentials>
   <Alerting></Alerting>
   <ScanConfig configID="21" name="CIS" templateID="cis" engineID="3" configVersion="3">
   <Schedules></Schedules>
   </ScanConfig>
  </Site>
</SiteConfigResponse>

Then using the following steps:

{
     "name": "copy",
     "operation": "NOP",
     "body_list": [
       "${XC:COPY:{L:Site}:{P:PARSE{SiteConfigResponse}}}",
       "${XC:NETWORKTORANGE:{E:net}:{L:range}}"
     ]
},
{

     "name": "add",
     "operation": "VARIABLEOP",
     "variable_ops": [
        {
          "operation": "PUSH",
          "type": "COMPOSITE",
          "destination": "L:Site{Site}{Hosts}",
          "source": "L:range"
         }
     ]
},
{
     "name": "post",
     "operation": "POST",
     "body_list": [
        '<?xml version="1.0" encoding="UTF-8"?>',
        '<SiteSaveRequest session-id="some_sess_id">',
        '${L:x:Site}',
       '</SiteSaveRequest>'
    ]
}

returns the following XML results:

<?xml version="1.0" encoding="UTF-8"?>
<SiteSaveRequest session-id="some_sess_id">
  <Site name="this_site" isDynamic="0" description="testing site" riskfactor="1.0"id="42">
     <Description>testing site</Description>
     <Hosts>
       <host>a.com</host>

       <range from="1.2.0.0" to="1.2.255.255"/>
     </Hosts>
     <Credentials/>
     <Alerting/>
     <ScanConfig configID="21" configVersion="3" name="CIS" templateID="cis" engineID="3">
     <Schedules/>
     </ScanConfig>
  </Site>
</SiteSaveRequest>

Removing Specific IP Addresses from Hosts or Ranges

Use the XC:REMOVEIP operation to remove a specific IP address from a list of hosts or ranges. This operation should be specified as the following: ${XC:REMOVEIP:{“var_with_ip”}:{“var_with_list”}} where IP address is a string such as ‘1.2.3.4’ or ‘2001:db8:ce4::42’.

The list of hosts/ranges is as follows:

[
  {
     '<xmla>': True,
     'name': 'range',
     'attrs': {'from': '1.2.3.1', 'to': '1.2.3.7'},
     'value': [],
     'index': {}
  },
  {
     '<xmla>': True,
     'name': 'host',
     'attrs': {},
     'value': ['a.com'],
     'index': {}
  }
]


Note: “var_with_IP” must be a top-level variable in a namespace such as E:var, but not L:var{key}[42].


Having namespace E as {‘E’: {‘ip’: ‘1.2.3.4’}} and Rapid7 response as follows:

<SiteConfigResponse success="1">
  <Site id="42" name="this_site" description="testing site" riskfactor="1.0"isDynamic="0">
  <Description>testing site</Description>
  <Hosts>
    <host>a.com</host>
    <range from="1.2.3.1" to="1.2.3.7"/>
    <host>b.com</host>
  </Hosts>
  <Credentials></Credentials>
  <Alerting></Alerting>
  <ScanConfig configID="21" name="CIS" templateID="cis" engineID="3" configVersion="3">
  <Schedules></Schedules>
  </ScanConfig>
 </Site>
</SiteConfigResponse>

Use the following steps:

{
     "name": "copy",
     "operation": "NOP",
     "body_list": [

        "${XC:COPY:{L:Site}:{P:PARSE{SiteConfigResponse}}}",
        "${XC:REMOVEIP:{E:ip}:{L:Site{Hosts}}}"
      ]
},
{
     "name": "post",
     "operation": "POST",
     "body_list": [
        '<?xml version="1.0" encoding="UTF-8"?>',
        '<SiteSaveRequest session-id="some_sess_id">',
        '${L:x:Site}',
        '</SiteSaveRequest>'
      ]
}

It returns the following XML results:

<?xml version="1.0" encoding="UTF-8"?>
<SiteSaveRequest session-id="some_sess_id">
     <Site name="this_site" isDynamic="0" description="testing site" riskfactor="1.0"id="42">
     <Description>testing site</Description>
     <Hosts>
        <host>a.com</host>
        <range from="1.2.3.1" to="1.2.3.3"/>
        <range from="1.2.3.5" to="1.2.3.7"/>
        <host>b.com</host>
     </Hosts>
     <Credentials/>
     <Alerting/>
     <ScanConfig configID="21" configVersion="3" name="CIS" templateID="cis" engineID="3">
     <Schedules/>
     </ScanConfig>
  </Site>
</SiteSaveRequest>

XC:Remove* Operations

There are several XC:REMOVE* operations that can be used to remove one or more IP specified addresses from a list of hosts and ranges. Such list is the deserialized representation of the 'Hosts' element of the Rapid7 response or request.

For example,

[
{
'<xmla>': True,
'name': 'host',
'attrs': {},
'value': ['a.com'],
'index': {}
},
{
'<xmla>': True,
'name': 'range',
'attrs': {'from': '1.2.3.1', 'to': '1.2.3.7'},
'value': [],
'index': {}
},
{
'<xmla>': True,
'name': 'host',
'attrs': {},
'value': ['b.com'],
'index': {}
}
]


Represents the following `Hosts` element:


<Hosts>
<host>a.com</host>
<range from="1.2.3.1" to="1.2.3.7"/>
<host>b.com</host>
</Hosts>


Items in the list are iterated one by one upon execution of any REMOVE command. The first argument of the REMOVE* command is the variable specification that contains an IP address. The second argument is the variable with the list of ranges or hosts. If the item is ‘range’, then the specified IP address is deleted from the range. Execution of any REMOVE command may result in no range, one range or two ranges that do not contain any specified IP addresses. The IP addresses specified in non-range items and ranges with different IP addresses are ignored.

  • The XC:REMOVEIP command specifies the single IP address as string (for example, ‘1.2.3.4’ or ‘2001:db8:ce4::42’).
  • The XC:RMEOVERANGE command specifies the set of IP addresses as Rapid7 range.
  • The XC:REMOVENET command specifies the set of IP addresses as network string.

If the first argument denotes an incorrect IP address (range or network respectively), the template execution is stopped and an error is generated for DEBUG mode, and nothing happens for non-DEBUG mode.

XC:Parse* Operations

The XC:PARSE command parses variable data based on the configuration. Some endpoints may return mixed outputs that cannot be parsed using a single parse statement. Hence, Infoblox provides you the flexibility to parse a response or a variable multiple times.

Using the XC:PARSE command to evaluate a string

You can use the ${XC:PARSE:{L:config}:{L:data}} command to parse a variable data based on the configuration. Infoblox supports parsing methods such as REGEX, REGEXSPLIT, XML, and so on. The REGEXSPLIT parsing method can be used to split a string to array of items.

The second argument (L:data) is updated to the result of parsing operation.

Having the L namespace as:

{
"config": {
"parse": "REGEXSPLIT",
"regex": "/"
},
"data": "infoblox.com/contacts"
}
The ${XC:PARSE:{L:config}:{L:data}} variable will update L:data to list ["infoblox.com", "contacts"].

Using the XC:IS_IP_IN command to evaluate a string

You can use the XC:IS_IP_IN command to evaluate if a string is within a range or a network. The ${XC:IS_IP_IN:{L:address}:{L:range}} variable evaluates the string to true. You can specify the second argument as a plain string that contains a mixed list of ranges, or networks or addresses that are separated by a comma. Example: "10.0.0.1-10.1.0.0,10.1.1.0/24,10.2.2.2".

Having the L namespace as:

{

"address": "1.2.3.4",

"range": "1.2.0.0-1.2.255.255"

}

Using the XC:REMOVEIP command to remove a string

You can remove an IP address from a range as a plain string using the XC:REMOVEIP command. Example: "10.0.0.1-10.0.0.4". In this case, the result format is a plain string with ranges that are separated by a comma. You can specify the second argument as a plain string that contains a mixed list of ranges, or networks, or addresses separated by a comma. Example: "10.0.0.1-10.1.0.0,10.1.1.0/24,10.2.2.2".

Having the L namespace as:

{

"address": "1.2.3.4",

"range": "1.2.3.1-1.2.3.3,1.2.3.5-1.2.3.20"

}

The ${XC:REMOVEIP:{L:address}:{L:range}} variable updates L:range to string "1.2.3.1-1.2.3.3,1.2.3.5-1.2.3.20".

Using the XC:REMOVENET command to remove a string

You can use the XC:REMOVENET command to remove all the IP addresses of a specified network from the list of ranges. Example: "10.0.0.1-10.0.0.4". In this case, the result format is a plain string with ranges that are separated by a comma. You can specify the second argument as a plain string that contains a mixed list of ranges, or networks, or addresses separated by a comma. Example: "10.0.0.1-10.1.0.0,10.1.1.0/24,10.2.2.2".

Having the L namespace as:

{

"network": "1.2.3.0/28",

"range": "1.2.3.1-1.2.3.20"

}

The ${XC:REMOVENET:{L:network}:{L:range}} variable updates L:range to string "1.2.3.15-1.2.3.20".

Using the XC:REMOVERANGE command to remove a string

You can use the XC:REMOVERANGE command to remove all the IP addresses of a specified range from the list of ranges. Example: "10.0.0.1-10.0.0.4". In this case, the result format is a plain string with ranges that are separated by a comma. You can specify the second argument as a plain string that contains a mixed list of ranges, or networks, or addresses separated by a comma. Example: "10.0.0.1-10.1.0.0,10.1.1.0/24,10.2.2.2".

Having the L namespace as:

{

"range1": "1.2.3.2-1.2.3.10",

"range2": "1.2.3.1-1.2.3.20"

}

The ${XC:REMOVERANGE:{L:range1}:{L:range2}} variable updates L:range2 to string "1.2.3.1,1.2.3.11-1.2.3.20".

Evaluating IP Address in a Range or Network

Use the XC:IS_IP_IN operation to validate if an IP address is in the range and network. This operation should be specified as follows: ${XC:IS_IP_IN:{“var_with_IP”}:{“var_with_net_or_range”}} where IP address is a string such as ‘1.2.3.4’ or ‘2001:db8:ce4::42’.
Having the L namespace as:


{
'ip1': '1.2.3.4',
'ip2': '2001:db8:ce5::42'
'range': {
'<xmla>': True,
'name': 'range',
'attrs': {'from': '1.2.0.0', 'to': '1.2.255.255'},
'value': [],
'index': {}
},
'net': '2001:db8:ce4::/48'
}
The ${XC:IS_IP_IN:{L:ip1}:{L:range}} variable will be evaluated to string as "true".
The ${XC:IS_IP_IN:{L:ip2}:{L:net}} variable will be evaluated to string as "false".

Creating Keys

Use the XC:KEYS operation to create keys. This operation should be specified as follows: ${XC:KEYS:{“var_with_dict”}:{“var_for_key_list”}}. It creates a list from the keys of the `var_with_dict` variable and includes it in the `var_for_key_list` variable.
Having L namespace as


{
'some_dict': {
'key1': 'value',
'key2': 42,
'key3': ['item1', 'item2']
}
}
After evaluating the ${XC:KEYS:{L:some_dict}:{L:key_list}} variable, the L namespace will contain new variable key_list with the following values:
[
'key1,
'key2,
'key3'
]

 Variable Examples

The following are variable examples.


Note: The XC: examples refer to the operations discussed in the Command Execution section.



Variables and Results

Variable: ${E::FQDN}

Result: Substitute the FQDN value from the event.

Variable: ${I::QUARANTINE}

Result: Substitute the quarantine value from the template instance.

Variable: ${XC:COPY:{E:TIMESTAMP}:{L:epoch_timestamp}}${XC:FORMAT:DATE_EPOCH:{L:epoch_timestamp}}

Result: Copy the event TIMESTAMP value into a local epoch_timestamp variable.

Variable: ${XC:COPY:{E:TIMESTAMP}:{L:custom_timestamp}}${XC:FORMAT:DATE_STRFTIME:{L:custom_timestamp}:{%a, %d %b %Y %H:%M:%S}}

Result: Copy the event TIMESTAMP value to a local custom_timestamp variable and format it. In this example, the result might be Wed, 18 Jun 2015 16:13:11.

Variable: ${XC:INC:{S:SERIAL}}${S::SERIAL}

Result: Increment the state 'SERIAL' value and substitute its value

Variable: ${XC:COPY:{S:SERIAL}:{H:X-customheader}}

Result: Copy the state SERIAL value to a custom HTTP header for future requests

Variable: ${XC:DEL:{H:X-loginvalue}}

Result: Removes the specified HTTP header.

Variable: ${XC:DEL:{C:logincookie}}

Result: Removes the specified cookie.

Variable: ${XC:ASSIGN:{L:INT}:{I:123}}

Result: Assign the integer 123 to the value INT in the L name space.

Variable: ${XC:ASSIGN:{L:BOOL}:{B:true}}

Result: Assign true to the value BOOL in the L name space.

Variable: ${XC:ASSIGN:{L:STR}:{S:some } random string}}

Result: Assign the string some } random string to the value STR in the L name space.

Variable: ${XC:DEBUG:{L:INT}}

Result: Output the value of the L name space INT variable to the debug file.

Variable: ${XC:DEBUG:{L:}}

Result: Output the values in the whole L name space to the debug file.

Variable: ${XC:FORMAT:TRUNCATE:{L:VAR}:{-1f}}

Result: Truncate L:VAR to the last character.

 Event Variables

The E: event name space is populated with variables from the event. For performance reasons, only the variables referred in the template will be available in the name space. This means that if the template is changed and if a new variable is added, it might take some time for the changes to be propagated to all the Grid members and the new variable to be available in future template executions.
You can use event_type in an action template to specify the following supported event types: RPZ, LEASE, TUNNEL, NETWORK_IPV4, NETWORK_IPV6, RANGE_IPV4, RANGE_IPV6, FIXED_ADDRESS_IPV4, FIXED_ADDRESS_IPV6, HOST_ADDRESS_IPV4, HOST_ADDRESS_IPV6, and SESSION. Note that SESSION is used only for the login and logout events for the session management templates. For information about action templates, see Creating Action Templates; and for information about session management templates, see Creating Session Management Templates.
The following tables list the supported variables by event type:

Variables for RPZ Events

Table 45.12 Variables for RPZ Events

NIOS Field Name

Template Variable Name

Supported Filter(s)

Enriched Data

Comment

Timestamptimestamp (ISO 8601 format)

The timestamp when the event occurred.

Infoblox Member IPmember_ip

Infoblox Member IP (VIP or LAN1) that generated this event.

Infoblox Member Name

member_name


Action Policy

rpz_policy

equals


(PASSTHRU DROP TCP-ONLY NXDOMAIN
NODATA Local-Data CNAME MISS)

RPZ Type

rpz_type

equals


Possible values: BAD, CLIENT-IP, QNAME, IP, NSDNAME, NSIP

Query Name or Query FQDN

query_name

contains, equals, begins with, ends with



Rule Name

rule_name

contains, equals, begins with, ends with



Source IP


source_ip

equals, matches range, matches CIDR

Parent range, Associated objects' DNS Names and EAs, Parent Network, Parent Network EA, Discovered data


Source Port

source_port




Destination IP

destination_ip



The name server that responded to the RPZ rule.

Query Type

query_type



DNS query type: A, AAAA, CNAME, DNAME,
TXT, and other.

Query View Name

query_view_name



Query DNS view name.

Event Type

event_type

equals

RPZ

LEASE

TUNNEL
NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4 FIXED_ADDRESS_IPV6 HOST_ADDRESS_IPV4 HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.

Enriched from IPv4 or IPv6 Addresses
Source IP User Nameip.username

From IPv4Address and IPv6Address

This field can be empty.

Source IP Associated EA

ip.extattrs

From IPv4Address and IPv6Address pyabs class

Can be empty, EA needs to be stored as "name-value" pair.

Source IP Associated DNS Names

ip.names

From IPv4Address or IPv6Address

List of FQDN
Enriched from Discovered Data

Source IP Attached Device Model

ip.discovered_data.device_model
From discovered data

Source IP Attached Device Name

ip.discovered_data.device_port_name
From discovered data

Source IP Attached Device Port

ip.discovered_data.device_port_type
From discovered data

Source IP Attached Device Type

ip.discovered_data.device_type
From discovered data

Source IP Attached Device Vendor

ip.discovered_data.device_vendor
From discovered data

Source IP Discovered Name

ip.discovered_data.discovered_name
From discovered data

Source IP First Discovered

ip.discovered_data.first_discovered (ISO

8601 format)


From discovered data

Source IP Discovered MAC

ip.discovered_data.mac_address
From discovered data

Source IP NetBIOS Name

ip.discovered_data.netbios_name
From discovered data
Source IP Port Linkip.discovered_data.port_link_status
From discovered data
Source IP Port Speedip.discovered_data.port_speed
From discovered data
Source IP Port Statusip.discovered_data.port_status
From discovered data

Source IP VLAN Description

ip.discovered_data.port_vlan_description
From discovered data
Source IP VLAN Nameip.discovered_data.port_vlan_name
From discovered data
Enriched from Parent Range

Source IP Range Start Address

range.start_addr
From parent range

Source IP Range End Address

range.end_addr
From parent range
Enriched from Parent Network

Source IP Network View Name

network.network_view
From parent network

The network view name in string format.

Source IP Networknetwork.network
From parent network

ip_addr/cidr

Example: 1.2.3.4/24

Source IP Network

Address

network.ipv4addr
From parent networkip_addr
Source IP Network Cidrnetwork.netmask
From parent networkcidr
Source IP Network EAnetwork.extattrs
From parent network

EA name can be any UTF8 characters.

Enriched from Lease Data

Source IP Lease Start Time

lease.starts (ISO 8601 format)
From lease data

Source IP Lease End Time

lease.ends (ISO 8601 format)
From lease data
Source IP Lease Statelease.binding_state
From lease data

Possible values: UNKNOWN, ABANDONED, ACTIVE, BACKUP, DECLINED, EXPIRED, FREE, OFFERED, RELEASED, RESET, STATIC

Source IP Lease Client Host Name

lease.client_hostname
From lease data

Source IP Lease MAC Address

lease.hardware
From lease data
Source IP Lease DUIDlease.ipv6_duid
From lease data
Source IP Fingerprintlease.fingerprint
From lease data

Variables for DHCP Lease Events

When searching for DHCP lease events with associated discovered data, both the "address" and "hardware" or "duid" must match the discovered data. If there is no hardware or DUID, the lease event cannot be associated with any discovered data.
For leases, same IP addresses may be used by multiple systems, so the IP address must match the MAC address or DUID to ensure that the discovered data has the most likely correct value.

Table 45.13 Variables for DHCP Lease Events

NIOS Field Name

Template Variable Name

Supported
Filter

Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



The timestamp when the event occurs.

Infoblox Member IP

member_ip


.

Infoblox member IP (VIP or LAN1) that has generated the event

Infoblox Member Name

member_name




Lease Binding State

binding_state

equals


This can be either UNKNOWN, ABANDONED, ACTIVE, BACKUP, DECLINED, EXPIRED, FREE, OFFERED, RELEASED, RESET, or STATIC.

Lease IP address

address

equals, matches range, matches CIDR

Parent Network EA, Parent Range, DNS Names and EA of associated objects

Some information from parent network is already in the DHCP lease data.

Lease Protocol

protocol



Possible values are IPv4 or IPv6.

Lease Start Time

starts




Lease End Time

ends




Client MAC address

hardware




Client IPv6 DUID

ipv6_duid




Client Host Name

client_hostname




Fingerprint


contains, equals, begins with, ends with



Lease Network View Name

network_view

contains, equals, begins with, ends with



Lease Network

network



ip_addr/cidr

Example: 1.2.3.4/24

Lease Network Address


network_ipaddr



ip_addr

Lease Network CIDR

network_netmask



CIDR

Lease IP Range Start Address

range_start_addr




Lease IP Range

End Address

range_end_addr


Event Typeevent_typeequals

RPZ

LEASE

TUNNEL

NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4

FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4

HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.

Enriched from Network EA
Lease Network EAnetwork.extattrs

From parent network EA

EA name can be any UTF-8 characters.

Enriched from IPv4 Address and IPv6 Address
Lease IP Usernameip.username

From IPv4 Address and IPv6 Address


Lease IP Associated EAp.extattrs

From IPv4 Address and IPv6 Address pyabs class

EA must be stored as “<EA name>-<EA value>” pair.

Lease IP Associated DNS Names

ip.names

From IPv4 Address and IPv6 Address

List of FQDN
Enriched from Discovery Data

Lease IP Attached Device Model

ip.discovered_data.device_model
From discovered data

Lease IP Attached Device Name

ip.discovered_data.device_port_name
From discovered data

Lease IP Attached Device Port

ip.discovered_data.device_port_type
From discovered data

Lease IP Attached Device Type

ip.discovered_data.device_type
From discovered data

Lease IP Attached Device Vendor

ip.discovered_data.device_vendor
From discovered data

Lease IP Discovered Name

ip.discovered_data.discovered_name
From discovered data

Lease IP First Discovered

ip.discovered_data.first_discovered (ISO 8601 format)


From discovered data

Lease IP Discovered MAC

ip.discovered_data.mac_address
From discovered data

Lease IP NetBIOS Name

ip.discovered_data.netbios_name
From discovered data
Lease IP Port Linkip.discovered_data.port_link_status
From discovered data
Lease IP Port Speedip.discovered_data.port_speed
From discovered data
Lease IP Port Statusip.discovered_data.port_status
From discovered data

Lease IP VLAN Description

ip.discovered_data.port_vlan_description
From discovered data
Lease IP VLAN Nameip.discovered_data.port_vlan_name
From discovered data

Variables for Object Change Discovery Data


Note: Infoblox supports insert and update operations from Network Insight and Cloud Discovery for object change discovery data in the NIOS 8.3.0 release version.



Table 45.14 Variables for Object Change Discovery Data

NIOS Field Name

Template Variable Name

Supported Filter

Enriched Data

Comment

timestamp

timestamp



Timestamp when event occurs, will be used record_timestamp from incoming data

member_ip

member_ip



Infoblox Member IP

member_name

member_name



Infoblox Member Name

object_type

object_type



Object Type, ENUM {DiscoveryData}

operation_type

operation_type

equals {INSERT, MODIFY, DELETE}


Operation Type, ENUM {INSERT, MODIFY, DELETE}

Values

network

network


Yes

Network (from network ref)

is_ipv4

is_ipv4

equals {true, false}


This boolean flag will indicate whether structure is of type IPv4 or IPv6

ip_address

ip_address

equals,
matches range,
matches CIDR

Yes (default)

Discovered IP address

mac_address

mac_address


Yes

Discovered MAC address

duid

duid


Yes

DUID associated with IPv6 address

ap_ip_address

ap_ip_address



Discovered IP address of Wireless Access Point

ap_name

ap_name



Discovered name of Wireless Access Point

ap_ssid

ap_ssid



Service set identifier (SSID) associated with Wireless Access Point

bridge_domain

bridge_domain



Discovered bridge domain

cisco_ise_endpoint_profile

cisco_ise_endpoint_profile



Endpoint profile in Cisco ISE

cisco_ise_security_group

cisco_ise_security_group



Name of security group created in Cisco ISE

cisco_ise_session_state

cisco_ise_session_state



session state

cisco_ise_ssid

cisco_ise_ssid



service set identifier

cmp_type

cmp_type



if the IP is coming from a Cloud environment, the Cloud Management Platform type

device_contact

device_contact



Contact information from device on which the IP address was discovered

device_location

device_location



Location of device on which the IP address was discovered

device_model

device_model



Model name of the device in the vendor terminology

device_port_name

device_port_name



System name of the interface the IP associates with

device_port_type

device_port_type



Hardware type of the interface the IP associates with

device_type

device_type



Type of the device in the vendor terminology

device_vendor

device_vendor



Vendor name of the device

discovered_name

discovered_name



Name of the ip as seen by the discovery station.

discoverer

discoverer

contains,
equals,
begins with,
ends with

Yes (default)

Name of the discoverer

endpoint_groups

endpoint_groups



List of discovered endpoint groups represented as a single string containing comma-separated values

first_discovered_timestamp

first_discovered_timestamp



When was this ip first seen by the discovery station

iprg_id

iprg_id



iprg(port redundant group) ID of this device interface

iprg_no

iprg_no



Port redundant group no of this device interface

iprg_state

iprg_state



State of this IP address in the group

iprg_type

iprg_type



Type of this prg

is_end_host

is_end_host



Is this object an end host or an infrastructure device for the purpose of discovery

last_discovered_timestamp

last_discovered_timestamp



When was this data discovered

last_updated_timestamp

last_updated_timestamp



Used by NetMRI sync to store timestamp when was this data updated

method

method



What method was being used for network discovery

mgmt_ip_address

mgmt_ip_address



Management IP address of the device if the device has more than one IP

netbios_name

netbios_name



Discovered NetBIOS name

network_component_contact

network_component_contact



Contact information from network component on which the IP address was discovered

network_component_description

network_component_description



A descriptive string for the network component

network_component_ip

network_component_ip



IP Address the network component

network_component_location

network_component_location



Location of network component on which the IP address was discovered

network_component_model

network_component_model



Model name of the network component the device is connected to in the vendor terminology

network_component_name

network_component_name



The name of network component

network_component_port_description

network_component_port_description



Description of the port on the network component

network_component_port_id

network_component_port_id



Interface ID of the connected switch/switch-router

network_component_port_name

network_component_port_name



Port name on the network component on which the ip was discovered

network_component_port_number

network_component_port_number



Port number on the network component on which the ip was discovered

network_component_type

network_component_type



The type of network component. Eg. Switch, Router etc.

network_component_vendor

network_component_vendor



Vendor name of the network component the device is connected to

open_ports

open_ports



List of opened ports on the IP address, represented as: "TCP: 21,22,23 UDP: 137,139". Limited to max total 1000 ports

os

os



Guess for OS by network discovery

port_duplex

port_duplex



Duplex settings on the port on the network component

port_link_status

port_link_status



Link Status of the port on the network component

port_speed

port_speed



Speed settings on the port on the network component

port_status

port_status



Status of the port on the network component

port_type

port_type



Type of the interface on the network component the device is connected to

port_vlan_description

port_vlan_description



Description of the vlan on the port on the network component

port_vlan_name

port_vlan_name



Name of the vlan on the port on the network component

port_vlan_number

port_vlan_number



Number of the vlan on the port on the network component

task_name

task_name



Name of the task discovers this data

tenant

tenant



Discovered tenant

unmanaged

unmanaged

equals {true, false}


Flag to indicate if the discovered data is associated with a managed object or not

v_adapter

v_adapter



Vmware physical adapter in which entity was found

v_cluster

v_cluster



Vmware cluster in which entity was found

v_datacenter

v_datacenter



Vmware datacenter in which entity was found

v_entity_name

v_entity_name



Vmware entity name in which entity was found

v_entity_type

v_entity_type



Type of encryption to use

v_host

v_host



Vmware host system in which entity was found

v_os

v_os



Vmware OS system in which entity was found

v_switch

v_switch



Vmware virtual switch in which entity was found

vlan_port_group

vlan_port_group



Port group which the virtual machine belongs to

vmhost_ip_address

vmhost_ip_address



IP address of the physical node on which the virtual machine is hosted

vmhost_mac_address

vmhost_mac_address



MAC address of the physical node on which the virtual machine is hosted

vmhost_name

vmhost_name



Name of the physical node on which the virtual machine is hosted

vmhost_nic_names

vmhost_nic_names



List of all physical port names used by the virtual switch on the physical node on which the virtual machine is hosted. Represented as: "eth1,eth2,eth3"

vmhost_subnet_cidr

vmhost_subnet_cidr



CIDR subnet of the physical node on which the virtual machine is hosted

vmi_id

vmi_id



ID of the virtual machine

vmi_ip_type

vmi_ip_type



Discovered IP address type

vmi_is_public_address

vmi_is_public_address



Indicates whether the IP address is a public address

vmi_name

vmi_name



Name of the virtual machine

vmi_private_address

vmi_private_address



Private IP address of the virtual machine

vmi_tenant_id

vmi_tenant_id



ID of the tenant which virtual machine belongs to

vport_conf_mode

vport_conf_mode



Configured mode of the network adapter on the virtual switch where the virtual machine connected to

vport_conf_speed

vport_conf_speed



Configured speed of the network adapter on the virtual switch where the virtual machine connected to. Unit is kb

vport_link_status

vport_link_status



Link status of the network adapter on the virtual switch where the virtual machine connected to

vport_mac_address

vport_mac_address



MAC address of the network adapter on the virtual switch where the virtual machine connected to

vport_mode

vport_mode



Actual mode of the network adapter on the virtual switch where the virtual machine connected to

vport_name

vport_name



Name of the network adapter on the virtual switch connected with the virtual machine

vport_speed

vport_speed



Actual speed of the network adapter on the virtual switch where the virtual machine connected to. Unit is kb

vswitch_available_ports_count

vswitch_available_ports_count



Numer of available ports reported by the virtual switch on which the virtual machine/vport connected to

vswitch_id

vswitch_id



ID of the virtual switch

vswitch_ipv6_enabled

vswitch_ipv6_enabled



Indicates the virtual switch has IPV6 enabled

vswitch_name

vswitch_name



Name of the virtual switch

vswitch_segment_id

vswitch_segment_id



ID of the network segment on which the current virtual machine/vport connected to

vswitch_segment_name

vswitch_segment_name



Name of the network segment on which the current virtual machine/vport connected to

vswitch_segment_port_group

vswitch_segment_port_group



Port group of the network segment on which the current virtual machine/vport connected to

vswitch_segment_type

vswitch_segment_type



Type of the network segment on which the current virtual machine/vport connected to

vswitch_tep_dhcp_server

vswitch_tep_dhcp_server



DHCP server of the virtual tunnel endpoint (VTEP) in the virtual switch

vswitch_tep_ip

vswitch_tep_ip



IP address of the virtual tunnel endpoint (VTEP) in the virtual switch

vswitch_tep_multicast

vswitch_tep_multicast



Muticast address of the virtual tunnel endpoint (VTEP) in the virtual swtich

vswitch_tep_port_group

vswitch_tep_port_group



Port group of the virtual tunnel endpoint (VTEP) in the virtual switch

vswitch_tep_type

vswitch_tep_type



Type of virtual tunnel endpoint (VTEP) in the virtual switch

vswitch_tep_vlan

vswitch_tep_vlan



VLAN of the virtual tunnel endpoint (VTEP) in the virtual switch

vswitch_type

vswitch_type



Type of the virtual switch: standard or distributed

Variables for Security ADP Events

Table 45.15 Variables for Security ADP Events

NIOS Field Name

Template Variable Name

Supported Filter

Enriched Data

Comment



Timestamp

timestamp

timestamp (iso 8601 format)



Timestamp when event occurs

Infoblox Member IP

member_ip

member_ip

equals,
matches range,
matches CIDR


Infoblox Member IP (VIP or LAN1) that has this event generated.

Infoblox Member Name

member_name

member_name

equals


Infoblox Member Name

Rule ID

rule_sid

rule_sid

contains,
equals,
begins with,
ends with


ATP rule ID. String

Rule Name

rule_name

rule_name



ATP rule name

Rule Category

rule_category

rule_category

contains,
equals,
begins with,
ends with


Rule category. String

Rule Log Severity

rule_severity

rule_severity

equals,
more severe,
less severe


Rule log severity (CRITICAL, MAJOR, WARNING, INFORMATIONAL)

Rule Action

rule_action

rule_action

equal


Rule action (ALERT, DROP, PASS)

Source IP

source_ip

source_ip

equals,
matches range,
matches CIDR

Parent Range,
Associated objects: DNS Names and EA
Parent Network,
Parent Network EA,
Discovery

Source IP

Source Port

source_port

source_port



Source port

Is NAT Client

is_nat_client

is_nat_client



Flag indicating if client is 'nated' (True, False)

NAT First Port

nat_first_port

nat_first_port



Port block start

NAT Last Port

nat_last_port

nat_last_port



Port block end

Query FQDN

query_fqdn

query_fqdn

contains,
equals,
begins with,
ends with


DNS Query FQDN limited by second-level domain name

Count of hits

hits_count

hits_count

greater than


Count of ADP hits per interval (15 sec)

Enriched from IPv4 Address or IPv6 Address

WAPI: IPv4 Address / IPv6 Address

Source IP User Name

ip_username

ip.username


From IPv4Address and IPv6Address

maybe empty

Source IP Associated EA

ip_extattrs

ip.extattrs


From IPv4Address and IPv6Address pyabs class

maybe empty, EA need to be stored as "name-value" pair

Source IP Associated DNS Names

ip_names

ip.names


From IPv4Address or IPv6Address

list of FQDN

Enriched from Discovery data

WAPI: discovery_data struct, inside IPv4 Address / IPv6 Address

Source IP Attached Device Model

ip_discovered_data_device_model

ip.discovered_data.device_model


From Discovery Data


Source IP Attached Device Name

ip_discovered_data_device_port_name

ip.discovered_data.device_port_name


From Discovery Data


Source IP Attached Device Port

ip_discovered_data_device_port_type

ip.discovered_data.device_port_type


From Discovery Data


Source IP Attached Device Type

ip_discovered_data_device_type

ip.discovered_data.device_type


From Discovery Data


Source IP Attached Device Vendor

ip_discovered_data_device_vendor

ip.discovered_data.device_vendor


From Discovery Data


Source IP Discovered Name

ip_discovered_data_discovered_name

ip.discovered_data.discovered_name


From Discovery Data


Source IP First Discovered

ip_discovered_data_first_discovered

ip.discovered_data.first_discovered (iso 8601 format)


From Discovery Data


Source IP Discovered MAC

ip_discovered_data_mac_address

ip.discovered_data.mac_address


From Discovery Data


Source IP NetBIOS Name

ip_discovered_data_netbios_name

ip.discovered_data.netbios_name


From Discovery Data


Source IP Port Link

ip_discovered_data_port_link_status

ip.discovered_data.port_link_status


From Discovery Data


Source IP Port Speed

ip_discovered_data_port_speed

ip.discovered_data.port_speed


From Discovery Data


Source IP Port Status

ip_discovered_data_port_status

ip.discovered_data.port_status


From Discovery Data


Source IP VLAN Description

ip_discovered_data_port_vlan_description

ip.discovered_data.port_vlan_description


From Discovery Data


Source IP VLAN Name

ip_discovered_data_port_vlan_name

ip.discovered_data.port_vlan_name


From Discovery Data


Enriched from Parent Range

WAPI: range

Source IP Range Start Address

range_start_addr

range.start_addr


From Parent Range


Source IP Range End Address

range_end_addr

range.end_addr


From Parent Range


Enriched from Parent Network

WAPI: network

Source IP Network View Name

network_network_view

network.network_view


From Parent Network

network view name in string

Source IP Network

network_network

network.network


From Parent Network

ip_addr/cidr, 1.2.3.4/24

Source IP Network Address

network_ipv4addr

network.ipv4addr


From Parent Network

ip_addr

Source IP Network Cidr

network_netmask

network.netmask


From Parent Network

cidr

Source IP Network EA

network_extattrs

network.extattrs


From Parent Network EA

EA name can be any utf8 characters.

Enriched from lease data

WAPI: lease

Source IP Lease Start Time

lease_starts

lease.starts(iso 8601 format)


From Lease Data


Source IP Lease End Time

lease_ends

lease.ends(iso 8601 format)


From Lease Data


Source IP Lease State

lease_binding_state

lease.binding_state


From Lease Data

UNKNOWN, ABANDONED, ACTIVE, BACKUP, DECLINED, EXPIRED, FREE, OFFERED, RELEASED, RESET, STATIC

Source IP Lease Client Host Name

lease_client_hostname

lease.client_hostname


From Lease Data


Source IP Lease MAC Address

lease_hardware

lease.hardware


From Lease Data


Source IP Lease DUID

lease_ipv6_duid

lease.ipv6_duid


From Lease Data


Source IP Fingerprint

lease_fingerprint

lease.fingerprint


From Lease Data


Variables for Analytics DNS Tunneling Events

Table 45.16 Variables for Analytics DNS Tunneling Events

NIOS Field Name

Template Variable Name

Supported Filter

Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



When the event occurs

Infoblox Member IP

member_ip



Infoblox member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




Source IP

source_ip

equals, matches range, matches CIDR

Parent Network, Parent Network EA, Discovery


Domain Name

domain_name



Domain name that was determined as DNS tunneling domain.

RPZ Rule Policy

rpz_policy



RPZ rule policy that was created.

Event Type

event_type

equals

RPZ

LEASE

TUNNEL

NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4

FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4

HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.

Comment

comment



Comment generated from the event by the Analytics system.

Enriched from IPv4 Address or IPv6 Address

Source IP Username

ip.username


From IPv4 Address and IPv6 Address


Source IP Associated EA

ip.extattrs


From IPv4 Address and IPv6 Address pyabs class

EA must be stored as “<EA name>-<EA value>” pair.

Source IP Associated DNS Names

ip.names


From IPv4 Address and IPv6 Address

List of FQDN.

Enriched from Discovery Data

Source IP Attached Device Model

ip.discovered_data.device_model


From discovered data


Source IP Attached Device Name

ip.discovered_data.device_port_name
From discovered data

Source IP Attached Device Port

ip.discovered_data.device_port_type
From discovered data

Source IP Attached Device Type

ip.discovered_data.device_type
From discovered data

Source IP Attached Device Vendor

ip.discovered_data.device_vendor
From discovered data

Source IP Discovered Name

ip.discovered_data.discovered_name
From discovered data

Source IP First Discovered

ip.discovered_data.first_discovered (ISO

8601 format)


From discovered data

Source IP Discovered MAC

ip.discovered_data.mac_address
From discovered data

Source IP NetBIOS Name

ip.discovered_data.netbios_name
From discovered data
Source IP Port Linkip.discovered_data.port_link_status
From discovered data
Source IP Port Speedip.discovered_data.port_speed
From discovered data
Source IP Port Statusip.discovered_data.port_status
From discovered data

Source IP VLAN Description

ip.discovered_data.port_vlan_description
From discovered data
Source IP VLAN Nameip.discovered_data.port_vlan_name
From discovered data
Enriched from Parent Range

Source IP Range Start Address

range.start_addr
From Parent Range

Source IP Range End Address

range.end_addr
From Parent Range
Enriched from Parent Network

Source IP Network View Name

network.network_view
From Parent Network

Network view name in string format.

Source IP Networknetwork.network
From Parent Network

ip_addr/cidr

Example: 1.2.3.4/24

Source IP Network Address

network.ipv4addr
From Parent Networkip_addr
Source IP Network Cidrnetwork.netmask
From Parent NetworkCIDR
Source IP Network EAnetwork.extattrs

From Parent Network EA

EA name can be any UTF-8 characters.

Enriched from Lease Data

Source IP Lease Start Time

lease.starts (ISO 8601 format)
From Lease Data

Source IP Lease End Time

lease.ends (ISO 8601 format)
From Lease Data
Source IP Lease Statelease.binding_state
From Lease Data

Source IP Lease Client Host Name

lease.client_hostname
From Lease Data

Source IP Lease MAC Address

lease.hardware
From Lease Data
Source IP Lease DUIDlease.ipv6_duid
From Lease Data
Source IP Fingerprintlease.fingerprint
From Lease Data

Variables for DB Object Change Event - DHCP Network IPv4

Table 45.17 Variables for DB Object Change Event - DHCP Network/Network Container IPv4

NIOS Field Name

Template Variable Name

Filter

Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



When the event occurs

Infoblox Member IP

member_ip



Infoblox member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




WAPI object reference

_ref




Comment

comment




Disable

disable

equals


Boolean

Extensible Attributes

extattrs



dictionary of extensible attributes

Network

network

equals, contained in


ip_addr/cidr

network_view

network_view

contains, equals, begins with, ends with


String format

Members

members




MS AD User Data

ms_ad_user_data




Comment

comment




network_container

network_container




options

options




unmanaged

unmanaged




Event Type

event_type

equals

RPZ

LEASE

TUNNEL
NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6 FIXED_ADDRESS_IPV4 FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4 HOST_ADDRESS_IPV6
SESSION

SESSION is used for the login and logout events for the session management templates.

Variables for DB Object Change Event - DHCP Network IPv6

Table 45.18 Variables for DB Object Change Event - DHCP Network/Network Container IPv6 

NIOS Field Name

Template Variable Name

Filter

Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



When the event occurs

Infoblox Member IP

member_ip



Infoblox member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




WAPI object reference

_ref




Comment

comment




Disable

disable

equals


Boolean

Extensible Attributes

extattrs



Dictionary of extensible attributes


Network


network

equals, contained in



ip_addr/cidr

network_view

network_view

contains, equals, begins with, ends with


String

Members

members




MS AD User Data

ms_ad_user_data




Comment

comment




network_container

network_container




options

options




unmanaged

unmanaged




Event Type

event_type

equals

RPZ

LEASE

TUNNEL
NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6 FIXED_ADDRESS_IPV4 FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4 HOST_ADDRESS_IPV6
SESSION

SESSION is used for the login and logout events

for the session management templates.

Variables for DB Object Change Event - DHCP Range IPv4

Table 45.19 Variables for DB Object Change Event - DHCP Range IPv4

NIOS Field Name

Template Variable Name

Supported
Filter

Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



When the event occurs

Infoblox Member IP

member_ip



Infoblox Member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




WAPI object reference

_ref




Comment

comment




Disable

disable

equals


Boolean

Extensible Attributes

extattrs



Dictionary of extensible attributes

Network

 network

equals, contained in


ip_addr/cidr

network_view

network_view

contains, equals, begins with, ends with


String

Member

member




Boot File

bootfile




Start Address

start_addr




End Address

end_addr




MAC Filter Rules

mac_filter_rules




MS AD User Data

ms_ad_user_data




Next Server

nextserver




Server Association Type

server_association_type

contains, equals, begins with, ends with



Event Type

event_typeequals

RPZ

LEASE

TUNNEL

NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4

FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4

HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.

Variables for DB Object Change Event - DHCP Range IPv6

Table 45.20 Variables for DB Object Change Event - DHCP Range IPv6

NIOS Field Name

Template Variable Name

Supported
Filter
Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



Timestamp when the event occurs.

Infoblox Member IP

member_ip



Infoblox Member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




WAPI object reference

_ref




Comment

comment




Disable

disable

equals

Boolean

Extensible Attributes

extattrs



Dictionary of extensible attributes

Network

network

equals, contained in


ip_addr/cidr

network_view

network_view

contains, equals, begins with, ends with


String

Member

member




Boot File

bootfile




Start Address

start_addr




End Address

end_addr




MAC Filter Rules

mac_filter_rules




MS AD User Data

ms_ad_user_data




Next Server

nextserver




Server Association Type

server_association_type

contains, equals, begins with, ends with



Event Typeevent_typeequals

RPZ

LEASE

TUNNEL

NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4

FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV6

HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.

Variables for DB Object Change Event - DHCP Fixed Address IPv4

Table 45.21 Variables for DB Object Change Event - DHCP Fixed Address IPv4

NIOS Field Name

Template Variable Name

Supported
Filter

Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



The timestamp when the event occurs.

Infoblox Member IP

member_ip



Infoblox member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




WAPI object reference

_ref




Comment

comment




Disable

disable

equals


Boolean

Extensible Attributes

extattrs



Dictionary of extensible attributes

Network

network

equals, contained in


ip_addr/cidr

network_view

network_view

contains, equals, begins with, ends with


String format

MS AD User Data

ms_ad_user_data




Name

name

contains, equals, begins with, ends with



MAC Address

mac

contains, equals, begins with, ends with



IPv4 Address

ipv4addr

equals, matches range, matches CIDR



Event Typeevent_typeequals

RPZ

LEASE

TUNNEL

NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4

FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4

HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.

Variables for DB Object Change Event - DHCP Fixed Address IPv6

Table 45.22 Variables for DB Object Change Event - DHCP Fixed Address IPv6

NIOS Field Name

Template Variable Name

Supported
Filter
Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



The timestamp when the event occurs.

Infoblox Member IP

member_ip



Infoblox member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




WAPI object reference

_ref




Comment

comment




Disable

disable

equals

Boolean

Extensible Attributes

extattrs



Dictionary of extensible attributes

Network

network

equals, contained in


ip_addr/cidr

network_view

network_view

contains, equals, begins with, ends with


String format

MS AD User Data

ms_ad_user_data




Name

name

contains, equals, begins with, ends with



IPv6 DUID

duid

contains, equals, begins with, ends with



Address Type

address_type

equals

Address, Prefix, or Both

IPv6 Address

ipv6addr

equals, matches range, matches CIDR



IPv6 Address Prefixipv6prefix

equals, matches range, matches CIDR



IPv6 Address Prefix bitsipv6prefix_bitsequals

Event Typeevent_typeequals

RPZ

LEASE

TUNNEL

NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4

FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4

HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.

Variables for DB Object Change Event - DHCP Host Address IPv4

Table 45.23 Variables for DB Object Change Event - DHCP Host Address IPv4

NIOS Field Name

Template Variable Name

Supported
Filter
Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



The timestamp when the event occurs.

Infoblox Member IP

member_ip



Infoblox member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




WAPI object reference

_ref




Extensible Attributes

extattrs



Dictionary of extensible attributes from parent host record

Network

network

equals, contained in


ip_addr/cidr

network_view

network_view

contains, equals, begins with, ends with


String format

MS AD User Data

ms_ad_user_data




Host

host

contains, equals, begins with, ends with



MAC Address

mac

contains, equals, begins with, ends with



IPv4 Address

ipv4addr

equals, matches range, matches CIDR



Event Typeevent_typeequals

RPZ

LEASE

TUNNEL

NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4

FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4

HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.

Variables for DB Object Change Event - DHCP Host Address IPv6

Table 45.24 Variables for DB Object Change Event - DHCP Host Address IPv6

NIOS Field Name

Template Variable Name

Supported
Filter
Enriched Data

Comment

Timestamp

timestamp (ISO 8601 format)



The timestamp when the event occurs.

Infoblox Member IP

member_ip



Infoblox member IP (VIP or LAN1) that has generated the event.

Infoblox Member Name

member_name




WAPI object reference

_ref




Extensible Attributes

extattrs



Dictionary of extensible attributes from parent host record

Network

network

equals, contained in


ip_addr/cidr

network_view

network_view

contains, equals, begins with, ends with


String format

MS AD User Data

ms_ad_user_data

contains, equals, begins with, ends with


Host

host

contains, equals, begins with, ends with



IPv6 DUID

duid

contains, equals, begins with, ends with



Address Type

address_type

equals

Address, Prefix, or Both

IPv6 Address

ipv6addr

equals, matches range, matches CIDR



IPv6 Address Prefixipv6prefix

equals, matches range, matches CIDR



IPv6 Address Prefix bitsipv6prefix_bitsequals

Event Typeevent_typeequals

RPZ

LEASE

TUNNEL

NETWORK_IPV4

NETWORK_IPV6

RANGE_IPV4

RANGE_IPV6

FIXED_ADDRESS_IPV4

FIXED_ADDRESS_IPV6

HOST_ADDRESS_IPV4

HOST_ADDRESS_IPV6

SESSION

SESSION is used for the login and logout events for the session management templates.

Variables for DNS Record

NIOS Field NameTemplate Variable NameSupported FilterEnriched DataComment
Record Name record_namecontains, equals, begins with, ends with

Record Typerecord_typeequals
A Record, AAAA Record, CAA Record, NS Record,
MX Record, Alias Record, PTR Record, NAPTR Record,
CNAME Record, DNAME Record, TLSA Record, TXT Record,
SOA Record, SRV record, Unknown Record
Auto created Recordsauto_rec


Network Viewnetwork_viewcontains, equals, begins with, ends with

Zone Namezone_namecontains, equals, begins with, ends with

DNS Viewdns_viewcontains, equals, begins with, ends with

USER NAMEUSER_NAME

Filtered by user name

Variables for DNS Zone

NIOS Field NameTemplate Variable NameSupported FilterEnriched DataComment
Zone Namezone_namecontains, equals, begins with, ends with

Zone Typezone_typeequals
Authoritative Zone, Delegated Zone, Forward Zone,
Response Policy Zone, Stub Zone
Network Viewnetwork_viewcontains, equals, begins with, ends with

DNS Viewdns_viewcontains, equals, begins with, ends with

USER NAMEUSER_NAME

Filtered by user name

Result Parsing

Besides the R: name space, which is always initialized, if a template step includes the parse setting, then the result returned by the server is interpreted and will be available in the P: name space. Result parsing is extremely naive and supports only the following:

  • JSON: In this case, the returned JSON will be available in the P name space if it is a dictionary, otherwise it will be as-is in the P:PARSE variable. If JSON is malformed, an error will be logged and P:PARSE will be set to an empty dictionary.
  • REGEX: The supplied REGEX is applied to the whole body and it will be available in P:PARSE[0] to P:PARSE[N], if you have specified more than one groupings. In this case, P:PARSE[0] contains the full match, and P:PARSE[1..N] contains each individual grouping match. If no groupings are parsed, then P:PARSE will be a string with the matched expression. If one grouping is parsed, then P:PARSE will be a string with the matched grouping result. Note that ^ and $ anchors are the anchors for the whole output to be parsed.
  • REGEXLINE: The supplied REGEX is applied to every line returned by the server, and each match is assigned to P:PARSE[0] to P:PARSE[N] depending on how many lines match. The REGEX must contain only one grouping. If there are many groupings then the last matched grouping is put in the PARSE value, but if there are no groupings provided then the full match is put in each line. Note that ^ and $ anchors in this case are the anchors for each line.
  • REGEXMULTILINE: REGEXMULTILINE can be used when multiple groupings are required to be matched in multiple lines. Each match will be in P:PARSE[0..n] and each individual match is a list where the first value is the full REGEX match, and each subsequent value is a grouping match. The first grouping match of the first match can be accessed via ${P:PARSE[0][1]}. Note that ^ and $ anchors in this case are the anchors for each line.

For all REGEX cases, if there are no matches, P:PARSE is set to an empty string.

  • CONDITION: In some cases, when a condition on a REGEX match is required, it is recommended to use a CONDITION step with the :L (length) format specifier applied to PARSE. So when ${P:L:PARSE} is matched with = 0, it would create a condition evaluating to true if there was a regular expression match.
  • XML: For XML, the XML data is converted into a dictionary of dictionaries/lists depending on the XML present. Similar to JSON, this will be available in the P name space if it is a dictionary, otherwise it will be as-is in the P:PARSE variable. If the XML is malformed or not parsable, then an error is logged and P:PARSE is set to an empty dictionary.

Parsing does not support DTDs, schemas, or XML attributes. It simply converts the XML document as-is. This also means that if the schema defines a particular element to be a list, it might not be deserialized as a list depending on how many members are present (if there is only one, then the parent is not considered a list.) When serializing XML, any variable composed of a dictionary with an '<xmla>' member set to True will be serialized as an XML element with attributes.

If an XMLA element is serialized under JSON/XML, the attributes will be ignored and the appliance returns a meaningful result (a list of XMLA variables will be serialized in JSON as a list of the values of these elements, assuming the values are simple strings/numbers).

For example, consider the following XML:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE APPLIANCE_LIST_OUTPUT SYSTEM
"https://qualysapi.qualys.com/api/2.0/fo/appliance/appliance_list_
output.dtd">
<APPLIANCE_LIST_OUTPUT>
   <RESPONSE>
     <DATETIME>2014-01-02T09:26:01Z</DATETIME>
     <APPLIANCE_LIST>
       <APPLIANCE>
          <ID>777</ID>
          <NAME>scanner1</NAME>
          <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>
          <RUNNING_SCAN_COUNT>0</RUNNING_SCAN_COUNT>
          <STATUS>Online</STATUS><S2>Online</S2>
      </APPLIANCE>
      <APPLIANCE>
          <ID>1127</ID>
          <NAME>scanner2</NAME>
          <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>
          <RUNNING_SCAN_COUNT>0</RUNNING_SCAN_COUNT>
          <STATUS>Online</STATUS><S2>Online</S2>
      </APPLIANCE>
      <APPLIANCE>
          <ID>1131</ID>
          <NAME>scanner3</NAME>
          <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>
          <RUNNING_SCAN_COUNT>0</RUNNING_SCAN_COUNT>
          <STATUS>Offline</STATUS><S2>Online</S2>
      </APPLIANCE>
    </APPLIANCE_LIST>
    <LICENSE_INFO>
      <QVSA_LICENSES_COUNT>10</QVSA_LICENSES_COUNT>
      <QVSA_LICENSES_USED>3</QVSA_LICENSES_USED>
    </LICENSE_INFO>
  </RESPONSE>
</APPLIANCE_LIST_OUTPUT>

The XML will be deserialized as follows:

{

    "APPLIANCE_LIST_OUTPUT":

    {

         "RESPONSE": {

            "APPLIANCE_LIST": [

               {

                  "ID": "777",

                  "NAME": "scanner1",

                  "RUNNING_SCAN_COUNT": "0",

                  "S2": "Online",

                  "SOFTWARE_VERSION": "2.6",

                  "STATUS": "Online"

               },

               {

                  "ID": "1127",

                  "NAME": "scanner2",

                  "RUNNING_SCAN_COUNT": "0",

                  "S2": "Online",

                  "SOFTWARE_VERSION": "2.6",

                  "STATUS": "Online"

               },

               {

                  "ID": "1131",

                  "NAME": "scanner3",

                  "RUNNING_SCAN_COUNT": "0",

                  "S2": "Online",

                  "SOFTWARE_VERSION": "2.6",

                  "STATUS": "Offline"

               },
        ],
        "DATETIME": "2014-01-02T09:26:01Z",
        "LICENSE_INFO": {
            "QVSA_LICENSES_COUNT": "10",
            "QVSA_LICENSES_USED": "3"
        }
      },
   }
}

But the following will be deserialized differently:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE APPLIANCE_LIST_OUTPUT SYSTEM
"https://qualysapi.qualys.com/api/2.0/fo/appliance/appliance_list_ output.dtd">

<APPLIANCE_LIST_OUTPUT>

      <RESPONSE>

         <DATETIME>2014-01-02T09:26:01Z</DATETIME>

         <APPLIANCE_LIST>

            <APPLIANCE>

               <ID>777</ID>

               <NAME>scanner1</NAME>

               <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>

               <RUNNING_SCAN_COUNT>0</RUNNING_SCAN_COUNT>

               <STATUS>Online</STATUS><S2>Online</S2>

           </APPLIANCE>

        </APPLIANCE_LIST>

        <LICENSE_INFO>

            <QVSA_LICENSES_COUNT>10</QVSA_LICENSES_COUNT>

            <QVSA_LICENSES_USED>3</QVSA_LICENSES_USED>

        </LICENSE_INFO>

    </RESPONSE>

</APPLIANCE_LIST_OUTPUT>

The XML will be deserialized as follows (note the difference in the appliance_list):

{

       "APPLIANCE_LIST_OUTPUT":

       {

           "RESPONSE": {

              "APPLIANCE_LIST": {

                  "APPLIANCE": {

                  {

                      "ID": "777",

                      "NAME": "scanner1",

                      "RUNNING_SCAN_COUNT": "0",

                      "S2": "Online",

                      "SOFTWARE_VERSION": "2.6",

                      "STATUS": "Online"

                 }

        },

        "DATETIME": "2014-01-02T09:26:01Z",

        "LICENSE_INFO": {

             "QVSA_LICENSES_COUNT": "10",

             "QVSA_LICENSES_USED": "3"

        }

     },

  }

}

  • XMLA: Infoblox strongly recommends that you use XMLA as the quoting option (as opposed to XML) when you create new action templates. New operations such as PUSH, POP, SHIFT and others are not officially supported for XML parsed data.

    XMLA parsing strips all white spaces (horizontal tab, line feed, vertical tab, form feed, carriage return, and space). To keep all white spaces, XMLA_WHITESPACE enum is added. The parsing is the same as XMLA except that there is no white space stripping.

    If you set parse to XMLA, the XML parsing supports XML attributes, and the XML document is put in the P:PARSE namespace variable, as illustrated in the following example. This example contains a mixed-attribute XML message with some values that contain attributes and some do not.

<?xml version="1.0" encoding="utf-8"?>
<SiteConfigResponse success="1">
   <Site id="27" name="SOAPUI13006925d-7dac-428d-aaf1-4038a98838a1" description="" riskfactor="1.0" isDynamic="0">
     <Description/>
     <Hosts a0="123">
         <host a1="123">server1.example.com</host>
         <host>server2.example.com</host>
         <host>server3.example.com</host>
         <host>server4.example.com</host>
         <host>server5.example.com</host>
     </Hosts>
     <Credentials></Credentials>
       <Alerting>
          <Alert name="test" enabled="1" maxAlerts="2">
          <scanFilter scanStart="1" scanStop="1" scanFailed="1" scanResumed="1" scanPaused="1"/>
          <vulnFilter severityThreshold="1" confirmed="1" unconfirmed="1" potential="1"/>
          <smtpAlert sender="user1@example.com" server="server6.example.com" limitText="0">
          <recipient>user2@example.com</recipient>
         </smtpAlert>
        </Alert>
       </Alerting>
     <ScanConfig configID="28" name="Full audit" templateID="full-audit" engineID="3" configVersion="3">
       <Schedules></Schedules>
     </ScanConfig>
   </Site>
</SiteConfigResponse>

The following is the deserialized response in P:PARSE when using XMLA parsing:

[

     {

         "<xmla>": true,

         "attrs": {

              "success": "1"

         },

         "index": {

              "Site": 0

         },

         "name": "SiteConfigResponse",

         "value": [

            {

               "<xmla>": true,

               "attrs": {

                  "description": "",

                  "id": "27",
                  "isDynamic": "0",
                  "name": "SOAPUI13006925d-7dac-428d-aaf1-4038a98838a1",
                  "riskfactor": "1.0"
                },
                "index": {
                  "Alerting": 3,
                  "Credentials": 2,
                  "Description": 0,
                  "Hosts": 1,
                  "ScanConfig": 4
                },
                "name": "Site",
                "value": [
                   {
                      "<xmla>": true,
                      "attrs": {},
                      "index": {},
                      "name": "Description",
                      "value": []
                   },
                   {
                      "<xmla>": true,
                      "attrs": {
                          "a0": "123"
                      },
                      "index": {
                          "host": 4
                      },
                      "name": "Hosts",
                      "value": [
                          {
                              "<xmla>": true,
                              "attrs": {
                                  "a1": "123"
                               },
                               "index": {},
                               "name": "host",
                               "value": ["server1.example.com"]
                          },
                          {
                               "<xmla>": true,
                               "attrs": {},
                               "index": {},
                               "name": "host",
                               "value": ["server2.example.com"]
                          },
                          {
                               "<xmla>": true,
                               "attrs": {},
                               "index": {},
                               "name": "host",
                               "value": ["server3.example.com"]

                          },
                          {
                               "<xmla>": true,
                               "attrs": {},
                               "index": {},
                               "name": "host",
                               "value": ["server4.example.com"]
                          },

                          {
                               "<xmla>": true,
                               "attrs": {},
                               "index": {},
                               "name": "host",
                               "value": ["server5.example.com"]
                           }
                       ]
                    },
                    {
                       "<xmla>": true,
                       "attrs": {},
                       "index": {},
                       "name": "Credentials",
                       "value": []
                    },
                    {
                       "<xmla>": true,
                       "attrs": {},
                       "index": {
                           "Alert": 0
                       },
                       "name": "Alerting",
                       "value": [
                          {
                               "<xmla>": true,
                               "attrs": {
                                   "enabled": "1",
                                   "maxAlerts": "2",
                                   "name": "test"
                               },
                               "index": {
                                  "scanFilter": 0,
                                  "smtpAlert": 2,
                                  "vulnFilter": 1
                               },
                               "name": "Alert",
                               "value": [
                                  {
                                      "<xmla>": true,
                                      "attrs": {
                                           "scanFailed": "1",
                                           "scanPaused": "1",
                                           "scanResumed": "1",
                                           "scanStart": "1",
                                           "scanStop": "1"
                                       },
                                       "index": {},
                                       "name": "scanFilter",
                                       "value": []

                                  },

                                  {

                                       "<xmla>": true,

                                       "attrs": {

                                          "confirmed": "1",

                                          "potential": "1",

                                          "severityThreshold": "1",

                                          "unconfirmed": "1"

                                        },

                                        "index": {},

                                        "name": "vulnFilter",

                                        "value": []
                                  },
                                  {
                                        "<xmla>": true,
                                        "attrs": {
                                             "limitText": "0",
                                             "sender": "user1@example.com",
                                             "server": "server6.example.com"
                                        },
                                        "index": {
                                             "recipient": 0
                                        },
                                        "name": "smtpAlert",
                                        "value": [
                                             {
                                                 "<xmla>": true,
                                                 "attrs": {},
                                                 "index": {},
                                                 "name": "recipient",
                                                 "value": ["user2@example.com"]
                                              }
                                         ]
                                      }
                                   ]
                                 }
                               ]
                            },
                            {
                               "<xmla>": true,
                               "attrs": {
                                  "configID": "28",
                                  "configVersion": "3",
                                  "engineID": "3",
                                  "name": "Full audit",
                                  "templateID": "full-audit"
                               },
                               "index": {
                                  "Schedules": 0
                               },
                               "name": "ScanConfig",
                               "value": [
                                  {
                                        "<xmla>": true,
                                        "attrs": {},
                                        "index": {},
                                        "name": "Schedules",
                                        "value": []

                                  }

                               ]

                           }

                       ]

                  }

             ]

      }

]

As shown in the example above, any XML value will become an internal dictionary that contains separate 'attrs' and 'value' members representing the XML attributes (if exist) and the XML values (if exist) of the element respectively, as well as the single "" boolean (set to True) to qualify this particular field as an XML attribute field (this is used when serializing, as well as for user-created XMLA values, see below).

You typically address the XMLA variable by using VAR{tag}{subtag}, which uses the VALUES of the tag (its value or its subtag(s)). To access the attributes of a tag, you use VAR{tag}{{attributename}}. Example: P::PARSE{SiteConfigResponse}{{success}}

If you need to access the name of a tag instead (for example if the remote server can return different tags depending on the status), use the [[name]] syntax. For example, you can use P::PARSE[[name]].

Repeating a Parse Operation

You can use the XC:PARSE operation to parse the body once again using another method. R:BODY contains the body of the response.

Example:

Having the L namespace as:

{

"config": {

"parse": "JSON"

},

}

L:data contains the result of the parsing operation after the following step:

{

"version": "4.0",

...

"steps": [

...

{

"name": "repeat_parse",

"operation": "NOP",

"body_list": [

"${XC:COPY:{L:data}:{R:BODY}}",

"${XC:PARSE:{L:config}:{L:data}}"

]

},

...

],

...

}


This page has no comments.