CustoSec:Perl Regular Expressions

From CustosecWiki
Jump to navigation Jump to search

Some service checks on ARANSEC / CustoSec allow to use Perl Regular Expressions to build sophisticated check arguments. There is a lot that can be done with these expression, making those checks even more powerful (i.e. ).

Here is a quick introduction into using Perl Regular Expressions for masking check arguments. To explain the usage within ARANSEC, we will show some examples based on the SNMP-Status Check. This nicely check allows to work with any kind of alphanumeric values delivered by OID's.


Simple String Matching

Regex in the Argument Explanation Return of the Check Remarks
!custosec!sysDescr.0!161!OK! WARNING!CRITICAL!UNKNOWN In this example we have 4 Arguments (OK, WARN, CRITICAL and UNKNOWN). As a search string we just used the names of the arguments. UNKNOWN:GS-1524 The OID "sysDescr.0" returns the system description of the host. In our case, we are talking about a Zyxel Switch GS-1524. Since this string does not apply to the four search string in the arguments the check returns an "UNKOWN"

Please note: The search string in a Regular Expression is normally entered between two slashes as delimiters, like "/String/". This is done automatically by ARANSEC, where it is enough to enter the pure string.

!custosec!sysDescr.0!161!GS-1524!WARNING!CRITICAL!UNKNOWN No we changed the "OK"-Argument to the String "GS-1524" which is what the OID will deliver. OK:GS-1524 This time, the string returned by the OID matches the search string in the OK-Argument.
!custosec!sysDescr.0!161!OK!GS-1524!CRITICAL!UNKNOWN Same as above, but the GS-1524-string is now the warning search string. WARNING:GS-1524 This time, the string returned by the OID matches the search string in the WARNING-Argument.
!custosec!sysDescr.0!161!OK![ABCDEFG]S-1524!CRITICAL!UNKNOWN Same as above, but the Search String is now using a "class" for the first letter. This class is enclosed in brackets [...] and contains possible characters, that might be at this first position to match. So a matching string could be AS-1524, BS-1524, ..GS-1524. WARNING:GS-1524
!custosec!sysDescr.0!161!OK!\107\x53-1524!CRITICAL!UNKNOWN Same as above, but the Search String is now using a ASCII Values for the first 2 characters of the search string. "\107" represents the character "G" in octal and \x53 represents the character "S" in hexadecimal noting. WARNING:GS-1524 It is possible to mix characters, octal and hexadecimal notations of ASCII characters in one string.
!custosec!sysDescr.0!161!OK!gs/i-1524!CRITICAL!UNKNOWN Same as above, but this time, the "\i" indicates that the first 2 letters of the string are case insensitive. WARNING:GS-1524 \i to set the search string case insensitive.
!custosec!sysDescr.0!161!OK![gG][sS]-1524!CRITICAL!UNKNOWN Again, the same as above, This time we have defined the first to characters as case sensitive characters g/G and s/S. WARNING:GS-1524
!custosec!sysDescr.0!161!OK!15!CRITICAL!UNKNOWN Same as above, but we take a numeric part of the string from the middle WARNING:GS-1524 Again the search string has been found somewhere and we have a match again.
!custosec!sysDescr.0!161!OK!^15!CRITICAL!UNKNOWN Almost the same as above. But this time we have used the "^" to specify that the search string ("15") should be at the beginning of the string. UNKNOWN:GS-1524 This time, the match does not work, since the search string "15" is not at the beginning of the string. Therefore the check returns an "Unknown" and the string as it got it.

Notes:

  • Regular expressions are Case Sensitive. "gs-1525" in the above examples will not lead to a match.
  • Spaces in the strings are ordinary characters. Be careful to enter all the spaces into the search string, but not too many!
  • The search string can be anywhere within the string to get a match.
  • If the search argument is very short, like just one letter "o", the match in the string "Hello World" would be the first "o", the one from "Hello". The next "o"s will not be checked any more.
  • There are some characters, that cannot be used in a match ("metacharacters"): {}[]()^$.|*+?\. If needed, a metacharacter can be used for matching with a backslash in front of it.
  • Non printable ASCII characters are represented by escape sequences (like \t for a tab, \n for a new line, \r for a carriage return). But this will not affect ARANSEC, since OID always deliver pure strings.
  • ASCII characters can be used for the search string as well. They have to have a backslash in front and can be noted by octal or by hexadecimal sequences (they are noted with an "x" after the leading back slash).
  • "\i" after a string indicates, that the match should be case insensitive.

String Matching using Wildcards

In the first section, we have worked with matches for the whole string that is returned by the snmp request. In many cases, it is needed to find sub strings of the the returned string. In the first example below, we will make a test by just using the substring and see what happens.

Regex in the Argument Explanation Return of the Check Remarks
!custosec!sysDescr.0!161!GS!WARNING!CRITICAL! UNKNOWN Now we don't give the whole string as a search string as in the examples above, but only provide a part of the string. (This time we are using the OK-Argument for our tests) UNKNOWN:GS-1524 The sub string "GS" has not been found. Reason is, that our Regular Expression simply does not work this way.
!custosec!sysDescr.0!161!OK!GS.....!CRITICAL! UNKNOWN This time we will introduce a wildcard (the "." dot) for each character of the return string that is not in the seach string ("GS"). By doing that, we say "Check the return string from the snmp request which has to have 7 characters, the first two ones being "GS" and the rest we don't care what they are, but they have to be here. OK:GS-1524 This way it works perfectly. The string is 7 characters long and starts with GS.
The wildcard for a character is "." (dot).
If we would put in one dot less or more into the search string, it would not work any more and deliver an UNKNOWN.
!custosec!sysDescr.0!161!OK!GS..52..!CRITICAL! UNKNOWN Now we build up a nice pattern the string has to match as another example. OK:GS-1524 Again, the pattern matches and the check will return OK.
!custosec!sysDescr.0!161!OK!.*15.*!CRITICAL! UNKNOWN This time we use a "quantifier metacharacter" to avoid putting in all "." for each position. We just say "look for the sub string "15" after any number of characters before and with any number of characters after it". OK:GS-1524 Again, the pattern matches and the check will return OK.


Notes:

  • The wildcard for a characters position in the string, not matter what a character it is, is a "." (dot)
  • The quantifier metacharacters are: ? * + and {}. These quantifiers are put right after the character they are quantifying.
    • a? = match "a" 1 or 0 times
    • a* = match "a" 0 or more times, i.e., any number of times
    • a+ = match "a" 1 or more times, i.e. at least once
    • a{n,m} = match a at least n times, but not more than m times
    • a{n,} = match at least n or more times
    • a{n} = match exactly n times


More Information

More Information on Perl Regular Expressions can be found here:

   Perl Regular Expressions Quick Start
   Perl Regular Expressions Tutorial
   Perl Regular Expressions

Note: This article is based on the article Perl Regular Expressions Quick Start by Mark Kvale (GNU General Public License)