############################################################################ ## I N T R O D U C T I O N ## All comments relate to the privateye.config file and Privateye's ParserNormal parser. If you write some other parser for some reason, I'd suggest you write your own documentation for it. All commands are of the form The command itself is not case sensitive. Anything between [] marks is optional to the command The names of all objects are now only alphanumeric characters and '_', as defined by PCRE's \w+. ############################################################################ ## A L E R T P A R S E R ## ALERTPARSER [] Creates an AlertParser, an object that takes input from Input objects and performs various actions on it. The "ADDPATH" command is used with AlertParsers to determine what is done with the alert after it has been parsed. Types and arguments follow: ALERT ([, , ...]) Creates an alert parser that will run its regular expression on the alert string. If it does not match, the parser ignores that alert string. Otherwise, it populates the fields given with the groups from the regexp. Immediately after the alert is created, is run on it. If fails, the alert passes no further. CONFIG A special type of AlertParser, this treats each input line as a console configuration line and deals with it accordingly. This allows for on-the-fly configuration of the program. Example: ALERTPARSER alertparser1 ALERT trigger1 \ /^#(\w*)#(\w*)#(\w*)#\s*$/ (a, b, c) This parser takes in a string and creates an alert with fields 'a', 'b', and 'c', the three groups of alphanumeric chars between the first four '#' marks. It ignores other syntaxes. After creating the alert with these three fields, 'alertparser1' passes the alert through 'trigger1'. If it returns false, the alert stops there. ############################################################################ ## U S E R H A S H ## USERHASH "" Creates a user hash (the value used to reference the current user state) by taking the string and substituting all strings '${field}' with the corresponding field value in the alert. is checked before the hash string values are substituted, and if it returns false, the UserHash drops the current alert. Example: USERHASH userhash1 trigger1 "UNAME=${uname}" This UserHash checks 'trigger1', and if it returns true, substitutes the value of alert field 'uname' into the string and returns it. ############################################################################ ## T R I G G E R ## TRIGGER [] Creates a trigger of the type given. Types of triggers and args needed are as follows: ## BOOLEAN TRIGGERS ## TRUE Always returns true FALSE Always returns false AND .. Performs a boolean AND on the return values of triggers 1 through N, returning that as its value OUTOF .. Returns true if at least number of triggers 1 to N return true. OR .. Performs a boolean OR on the return values of triggers 1 through N, returning that as its value NOT Returns the opposite of 's return value. ## MISC TRIGGERS ## OUTPUT "" Tries to output to the output vector . On success, return true. On failure, return false. The message can contain any number of ${} strings, where is an alert field. The actual values of these fields will be replaced into the message before it is sent. The escape sequences \n, \t, \", and \\ work so far in ACTION Performs , and sets alert field to 's output. Always returns true. USERFLAG Returns true if the user flag is set and has not expired. See the USERFLAG action for more details. ## DATABASE TRIGGERS ## (see DICTIONARY SYNTAX below) DB_SQL \ This trigger executes the user-defined SQL statement on the database specified by the first five arguments. Each '?' in the SQL is substituted with the value of the alert field in the corresponding position in (an array like the array of fields used for AlertParser). The values of the first record returned by the SQL query are stored into the corresponding fields in , another field name array. See the examples below for one use of this trigger. It's recommended, by the way, that you postpend "LIMIT 1" to all SELECT SQL statements that you use in DB_SQL, as all information after the first record is thrown out anyway. A quick note: a returned value of NULL will result in the alert field being set to the empty string, not NULL. For the moment, this just seems to work better. ## LDAP TRIGGERS ## LDAP_SEARCH "" "" alert> [dict:ldap_opt_name->opt_val] This trigger runs a search on an LDAP directory, on server and authenticated with and . and , both of which can contain alert fields, are used to search the directory. alert> is used to specify the attributes to request (all of the 'ldap' entries) and their mappings to alert fields (the 'alert' entries). See the Dictionary Syntax below. If required, the last dictionary allows for the setting of LDAP options. See example below. ## FIELD TRIGGERS ## REGEXP Runs a regular expression on the given field of an alert, returns true on a match. SUBSTR "" [pos] Returns true if is a substring of . If is given, this will only return true if starts at position (zero indexed). COPY Copy field of the alert to field of the alert. SET "" Set alert's field to the constant string (no substitutions made). FIELD Returns true if the alert contains a field named ## MATH TRIGGERS ## (see MATH SYNTAX below) MATH_SET '' Sets alert field to the value returned by math expression , returning true on success or false on error (divide by zero, etc.) MATH_EQ '' '' Returns true if 's return value is equal to 's return value. As always, be careful with floating point integers. MATH_GT '' '' Returns true if is greater than , false if not or on error. MATH_LT '' '' Returns true if is less than , false if not or on error. Examples: TRIGGER trigger1 REGEXP a /badstuff/i Returns true if field 'a' of an alert contains the string 'badstuff', case insensitive because of the trailing 'i' TRIGGER trigger2 TRUE Always returns true TRIGGER trigger3 AND trigger2 trigger1 Tries trigger2, if true then tries trigger1, if true then returns true TRIGGER trigger4 DB_SQL mysql dbhost dbname dbuser dbpass \ "SELECT `val1`, `val2` FROM `tbl` WHERE `val3` > ? LIMIT 1" \ ( af3 ) ( af1, af2 ) When this trigger is hit, it will connect through 'mysql' to the host 'dbhost' with username 'dbname' and password 'dbpass'. It will then execute the specified SQL statement, testing if `val3` is greater than alert field value 'af3'. The alert fields 'af1' and 'af2' will be set to the first `val1` and `val2` values returned. TRIGGER trigger5 OUTPUT stdout "Field ABC has data \"${ABC}\"" Creates a trigger that outputs the string 'Field ABC has data ""', where is the data in field 'abc' of the alert. TRIGGER trigger6 LDAP_SEARCH ldap.server ldap_uname ldap_passwd \ "DC=mydomain,DC=com" "samaccountname=${username}" \ { [displayname]:[fullname] } \ { [LDAP_OPT_REFERRALS]:[0] [LDAP_OPT_PROTOCOL_VERSION]:[3] } This trigger runs an LDAP search in an Active Directory environment. Connects to LDAP server 'ldap.server', then binds with user name 'ldap_uname' and password 'ldap_passwd'. Using the given base DN, 'DC=mydomain,DC=com' and the filter 'samaccountname=${username}', it asks for the LDAP attribute 'displayname' of the first returned entry. It then takes that attribute's value and places it into the alert field 'fullname'. Since Microsoft is stupid and Active Direcory is not just LDAP, but BROKEN LDAP, the options seen above must be set when using AD. LDAP_OPT_REFERRALS must be 0, and LDAP_OPT_PROTOCOL_VERSION must be 3. *sigh* ############################################################################ ## D I C T I O N A R Y S Y N T A X ## Dictionary syntax works like this: The whole dictionary is surrounded by curly braces '{' and '}' Elements are seperated by whitespace. Each element's name/value pairs are seperated by a colon ':' Each element is surrounded by square braces '[' and ']' There can be no space between the ']' of the name, the ':' separator, and the '[' of the value. Spaces within element names are signifigant Example: { [a]:[1] [b]:[2] [c]:[froggy] } This is a dictionary that maps a->1, b->2, and c->froggy. When dictionaries are used as arguments, they will be signified as bar>, where 'foo' describes the element names and 'bar' describes the element values. ############################################################################ ## M A T H S Y N T A X ## Math Triggers use mathematical functions to create math objects, which allow for simple computations to be done between alert fields and constant values. Math equations are written in prefix notation (reverse Polish), with the operator followed by its two operands. Parentheses are never needed and are not recognized. Operators currently supported include: +: Addition -: Subtraction *: Multiplication /: Division &: Bitwise AND |: Bitwise OR ^: Bitwise XOR ~: Bitwise NOT (unary operator) Numbers are of the form /-?\d*\.?\d+/. The following are legal: 2 -6 58 .03 -2.7 -0.89 .123 -.77 The following are NOT legal: 232. Any set of alphanumeric characters that is not a number will be considered the name of an alert field. abc _qwerty_ etc An example equation: * 2 + abc 5.5 : Returns 2 * (alert['abc'] + 5.5) ############################################################################ ## A C T I O N ## ACTION [] Creates an action of the type given. Types of actions and args needed are as follows: NULL Do absolutely nothing. SH Runs the shell command given. Within the shell command may be any number of strings ${}, where is the field name of an alert. These strings will be substituted before the command is run. AND ... Perform , then , etc. and return the concatination of their outputs. BRANCH Checks to see if returns true or false. If true, execute the action . Otherwise, execute action . USERFLAG Sets a flag named on the current user. This flag will disappear after seconds. In the meantime, it can be seen by the USERFLAG trigger. Note that each new user flag with the same name will delete the previous and reset the lifetime timer to the current time plus its own lifetime. CLEARFLAGS .. Clear all specified user flags. TRIGGER Perform a trigger check, then return either " SUCCEEDED" or " FAILED" RULELIST Run the user and alert through the rule list Example: ACTION action1 SH echo "Field 'a' says ${a}" Echos the value of field 'a' to standard output ############################################################################ ## R U L E ## RULE [