Paragon Insights Tagging Overview
You can use the Paragon Automation graphical user interface (GUI) to create tagging profiles. You can configure a tagging profile to insert fields, values, and keys into a Paragon Insights rule. You can also set conditions that are checked against values stored in the times series database (TSDB) or the Redis database.
Paragon Insights supports the following types of tagging:
Static Tagging
In static tagging, the tagging profile is applied to values stored in the time series database (TSDB). These values do not vary a lot with time. In static tagging, you can avoid using When statements, and you can add Then statements individually to a row of the TSDB. You can add tags to all rows since no conditions are present.
Dynamic Tagging
In dynamic tagging, conditions used in Paragon Insights tagging are checked against values that are stored in Redis database. This database acts like a cache memory that stores dynamic data. Dynamic data is real-time data that is stored in Redis database.
For more information on tagging, see Types of Tagging.
Tagging Profile Terminology
The following list describes the tagging profile terminologies:
- Policy
- Rules
- Terms
- When Statements
- Then Statements
- Example Configuration: Elements of a Tagging Profile
Policy
A policy is the top-level element in a tagging profile. You can add multiple policies within a single tagging profile. Multiple policies that exist within a tagging profile can have their own rules and terms.
Usage Notes:
Defining multiple policies within a single profile allows you to define terms for each rule in one profile instead of creating one profile for each rule.
Rules
A rule is any defined Paragon Insights rule. The rule element type in a tagging profile is a list element. You can apply a specific policy profile to the rule(s) ([rule1, rule2]) included within the tagging profile.
Usage Notes:
You can describe the topic-name/rule-name requirement for the rules element in the following ways:
To name specific rules within a tagging profile, use the form: topic-name/rule-name.
For example, protocol.bgp/check-bgp-advertised-routes. Navigate to Configuration>Rules to view configured rules.
Use an asterisk (*) with no other value or brackets to match all rules.
Use python-based fnmatch patterns to select all rules within a specific topic. For example,
line-cards/*
.For more information, see fnmatch — Unix filename pattern matching.
Terms
The term section of the tagging profile is where the match conditions are set and examined, and actions based on those matches are set and carried out. Set the conditions for a match in a when statement. Set the actions to be carried out upon completing a match in one or more then statements.
Usage Notes:
Each term can contain a when statement but it is not mandatory.
Each term must contain at least one then statement.
Multiple terms can be set within a single policy.
Terms are processed sequentially from top to bottom until a match is found. If a match is found, processing stops after completing the statements found in the then section. Other terms, if present, are not processed unless the next flag is enabled within the matched term. If the matched term has the next flag enabled, then subsequent terms are processed in order.
When Statements
When statements define the match conditions that you specify. When statements ultimately resolve to be true or false. You can define a term without a when statement. This equates to a default term wherein the match is assumed true and the subsequent then statement is carried out. Conversely, multiple conditions can be checked within one when statement.
If one or more of the conditions set forth in a when statement are not met, the statement is false and the term has failed to match; processing moves to the next term, if present.
Usage Notes:
When statements perform Boolean operations on the received data to determine if it matches the criteria you set. The supported operations are:
Numeric Operations:
equal-to
not-equal-to
greater-than
greater-than-or-equal-to
less-than
less-than-or-equal-to
String Operations:
matches-with
does-not-match-with
Time Operations:
matches-with-scheduler
Note:The
matches-with-scheduler
option requires that a discreet scheduler be configured in the Administration > Ingest Settings > Scheduler page. The name of the scheduler can then be used in thematches-with-scheduler
when statementGo Language Expressions:
eval <simple-go-expression>
For example:
eval a + b <= c
.
Then Statements
Then statements implement the tagging instructions that you provide. This is done only after there is a complete match of the conditions set forth in a when statement contained in the same term. Each term defined must have at least one then statement. Each then statement must have one or more than one action(s) defined; the actions available in then statements are:
add-field | Adds a normal field to the rule(s) listed in the rule section. Multiple fields can be added within a then statement. The add-field action requires that you also define the kind of field you are adding with the field-type parameter:
Note:
If you do not define a field type, the new field gets added with the default field-type of string. |
add-key | Adds a key field with string data type to the rule(s). Added key fields are indexed and can be searched for just like any other key field. |
Usage Notes:
You can set the next flag to true within a then statement. When this flag is set to true, the next term in the policy gets evaluated if all of the conditions of the current term match.
Example Configuration: Elements of a Tagging Profile
Paragon Insights configuration elements are displayed as pseudo-config. This configuration resembles the hierarchical method used by Junos OS.
This Elements of a Tagging Profile table shows how tagging profile elements are named and how they are related to each other:
healthbot { ingest-settings { data-enrichment { tagging-profile <tagging-profile-name> { policy <policy-name> { rules [ List of Rules ]; term <term-name1> { when { <condition1> <condition2> } then { add-field <field-name1> { value <field-value1>; type <field-type>; } add-field <field-name2> { value <field-value2>; type <field-type>; } add-key <key-field-name> { value <key-field-value>; } } } term <term-name2> { then { add-field <field-name> { value <field-value>; type <field-type>; } } } } } } } }
How Do Tagging Profiles Work?
You can use tagging profiles to set the conditions, define new fields and keys, and insert values into those fields. Tagging profiles are applied as part of ingest settings to allow the tags to be added to the incoming data before Paragon Insights processes the data. Since one or more rules are defined within each profile, the rules are added to a playbook and applied to a device group when the tagging profile is applied to a device.
Table 1 shows an example application identification scenario based on source-port, destination-port, and protocol of traffic seen in a NetFlow stream.
source-port |
destination-port |
protocol |
derived-application |
---|---|---|---|
2541 |
Any |
6 (TCP) |
NetChat |
Any |
2541 |
6 (TCP) |
|
1755 |
Any |
17 (UDP) |
MS-streaming |
Any |
830 |
6 (TCP) |
netconf-ssh |
7802 |
Any |
17 (UDP) |
vns-tp |
In Table 1, you use three existing fields in a NetFlow stream to guess the application traffic in the stream. You then create a new field called derived-application and populate it based on the values seen in the traffic.
You can apply tagging profiles at the device group level.
When a device in a device group has a tagging profile applied to it, and the device group has another tagging profile applied to the whole group of devices, the tagging profile of the device group is merged with the existing tagging profile of the device.
For example, D-A-Net is a device that is part of a device group called Group-D1. D-A-Net has a tagging profile applied to it. There is another tagging profile applied on the device group, Group-D1, as well. In such a scenario, the tagging profile applied to the device group is merged with the tagging profile of the device, D-A-Net.
When the tagging profile applied to the device group and the tagging profile applied to the device in the group renders the same output, the tagging profile of the device is preserved.
Example pseudo-configuration shown below
device r0 { host r0; tagging-profile [ profile1 ] } device r1 { host r1 } device-group core { devices [ r0 r1 ]; tagging-profile [ profile2 ] }
In this example, device r0 has tagging profile, profile1, assigned at the device level and tagging profile, profile2, assigned by its membership in the device- group (core).
Device r1 has tagging profile, profile2, assigned by its membership in device group, core.
In this scenario, profile1 and profile2 are merged on device r0. However, if profile1 and profile2 both define the same fields but the fields contain different values, the value from profile1 takes precedence because it is assigned directly to the device.
Device r1 only gets tagging profile profile2.
Caveats
Fields and keys added using tagging profiles cannot be used within periodic aggregation fields. This is because periodic aggregation must take place before any UDFCode function (reference, vector, UDF, ML) is applied.
Tagging profiles can consist of only fields in add-key or add-field. Vectors cannot be added to a rule by a tagging profile.
Vector comparison operations cannot be used within tagging profile terms. Only field Boolean operations are permitted.
For tagging profile conditional operations within a when statement, the used field must be of type sensor, constant, or reference.
This is applicable only in static tagging.
If the field used within tagging profile Boolean operation is of type reference, then this reference field must not depend on any user-defined-function or formula defined within the same rule.