socks5cop.conf(5)

NAME
socks5cop.conf - configuration file for socks5cop

SYNOPSIS
socks5cop.conf

DESCRIPTION
socks5cop.conf is the input file for the Socks5cop program. The file contains all the information that Socks5cop needs in determining: when to trigger an action and what action to execute.

The input file contains two language constructs: assignment statement and alarm specification.

Lines can be split by a backslash (\) followed by a newline. Lines that begin with a pound sign (#) are considered as comment lines.

ASSIGNMENT STATEMENT
The syntax for an assignment is:
        variable = value_list The value of a variable is referenced by preceding its name by a dollar sign ($). The construct can be used to define lists, if they are needed for alarm specifications. Two examples of the assignment statement are:
    Allowed_Appl= {1-30}/tcp http ftp
    SOURCE_LIST=.dl.nec.com .sj.nec.com 143.101.64. where Allowed_Appl and SOURCE_LIST are two user-defined variables. Latter on, $Allowed_Appl and $SOURCE_LIST can be used in alarm specifications.

ALARM SPECIFICATION
The input file may contain one or more alarm specifications of the following form:
    WHEN alarm_condition
    EXEC
    action
    END When a connection or a request is processed, every alarm condition is evaluated to see whether to trigger its action commands. Whenever an alarm condition is evaluated true, the associated action is executed if the action has not been executed within a certain time (defined by the value of an internal variable named react_time ). In the alarm conditions, & means an AND operation, | means an OR operation, and !, the negation. ! has higher precedence than &, and & has higher precedence than |. One example of the alarm conditions is the following: (src==.dl.nec.com | usr==root) which means the connection source is in the .dl.nec.com domain and the user is root. Here src and usr are internal variables which will be explained soon. The real meaning of `==' in a comparison is *to match*. For example, in the case of source comparison shown above, if the constant side is a domain such as .dl.nec.com, Socks5cop will check the source to be in the domain, i.e., the source has to be something like x.dl.nec.com. If the constant side is a host name, a complete match is required. `!=' means *not to match*.

INTERNAL VARIABLES
When a connection, no matter successful or not, is inspected along with the alarm conditions, its information is accessed through predefined internal variables. These variables may be compared with their patterns. Unlike the user-defined variables, they are used without the preceding dollar sign ($). The predefined internal variables are:

source or src
    the source address of the connection.

source.ip or src.ip, source.name or src.name
    the dotted address and the domain name of the source respectively. These variables may only be used in alarm actions. If the domain name is not found, its dotted address is used.

destination or dst, destination.ip or dst.ip, destination.name or dst.name
    the destination address. The explanation is similar to that of the source.

application or app
    the application being used.

application.name or app.name, application.port or app.port
    the application's name (e.g., telnet) and port number (e.g., 23/tcp) respectively. These variables may only be used in alarm actions.

user or usr
    the user of the connection.

error or err
    the error number associated with the connection.

socks.pid or pid
    the process number of the Socks5 server that proxies the connection. This variable may only be used in alarm actions.

time or tm
    the time at which the connection is processed by Socks5cop.

Two other internal variables to define alarm behavior are:

alert_time
    the time interval (in seconds) in which the aggregates are calculated. This variable has to be defined before any alarm specification.

react_time
    This variable allows the user to define the time (in seconds) in which a repeated action becomes inactive. That is, once an alarm is raised and its action executed, the same action is not executed again even the alarm condition is met for another connection in the next react_time seconds.

In the input file, the values of alert_time and react_time are in effective until another assignment of their value is found.

AGGREGATES
The information about recent connections is processed by the program to provide the following useful aggregates for the user in defining alarms:

FAIL[.]
    the number of failed attempts during the alert time.

ACCESS[.]
    the number of successful accesses (connections) during the alert time.

IN[.]
    the number of incoming bytes during the alert time.

OUT[.]
    the number of outgoing bytes during the alert time.

TRAFFIC[.]
    the total traffic which is equal to IN[.] + OUT[.].

DURATION[.]
    the connection duration in the alert time.

An aggregate has to be indexed by some internal variables, a condition or a mix of them put in its bracket. When indexed by a condition, the aggregate is the result of all the connections satisfying the condition. When indexed by an internal variable, the aggregate is the count for the current value of the internal variable. The internal variables allowed to be in the index are src, dst, app, usr and err. For example, TRAFFIC[src,dst] means the total bytes transferred between the current source and the current destination; FAIL[src==.com] means the number of failed attempts totaled for all the sources in the .com domain. Notice the difference between the condition (FAIL[src==.com]>10) and the condition (FAIL[src]>10 & src==.com). The former is true when the number of failed attempts for the hosts in the .com domain combined exceeds ten and the current source is in .com. The latter is true when the failure number of the current source exceeds ten and the current source is in .com. The index condition and the internal variables can be mixed in an index. For example, ACCESS[dst==.com & app==http, src] is the number of accesses of the current source to the .com domain via http. The appearance order of the condition has to be before the internal variables. But the order among the internal variables does not matter. For example, IN[dst,src] is the same as IN[src,dst]. If the index condition of an aggregate is not true, the aggregate is evaluated 0. For example, FAIL[src==.com] will be evaluated 0 for a host not in .com.

ALARM ACTION
Lines between EXEC and END are shell commands to be executed. Socks5cop joins these lines by placing semicolons (;) among them. It might be a good idea to use a shell script instead of writing several long action lines. When an alarm condition is evaluated true, Socks5cop makes a variable substitution for the associated action: whenever an internal variable or user-defined variable in the action lines is found, it is replaced by the current value of the variable. For example, if the current source is x.dl.nec.com and the action is
        echo src >>blacklist then the command will be expanded to
        echo x.dl.nec.com >>blacklist and be executed. A tricky point is that the aggregates and the time variable do not count toward the difference between two expanded actions. For example, the following action will be executed for different sources, but not for a same source with different failure numbers:
        echo source denied FAIL[source] times

HOST PATTERN
A host pattern is formed by an IP address, a domain name, or an IP address with mask. The specification is the same as for the Socks5 configuration. The user may consult the man page of socks5. For instance, 129.101.112.10 means the host 129.101.112.10; 222.22.22. means the network 222.22.22; (src==.nec.com) is true for any source that comes from the .nec.com domain.

APPLICATION PATTERN
An application (protocol) specification may be a port number, optionally followed by a slash (/) and a protocol name, a range of port numbers, or an application name. In the case of an application name, the program looks up in the file "/etc/services" for the corresponding port number. Only tcp and udp may be specified as the protocol name. For example, (app=={1-10} telnet) is true when the current application is using a destination port between 1 and 10, either tcp or udp, or the application is telnet; (app=={1-10}/tcp 20/udp) is true when the current application is using a destination port between 1 and 10 tcp, or udp 20; {5000-} matches any port number greater than or equal to 5000; {-} matches any port.

ERROR PATTERN
An error specification may be an error number or a range of numbers. For example, (error==15 {1-10}) is true when the current error number is 15 or between 1 and 10; {-10} matches any error number less or equal to 10 (including 0);

USER PATTERN
A user specification is similar to the shell wildcard match. To avoid confusion with brackets used for indexing aggregates, braces are used for alternative characters and intervals. A single backslash means (\) the next character is to be matched. For example, * matches any user; \* matches the username *; (usr==root {AB}*) is true if the username is root or its first letter begins with A or B; {^AB}* matches any user whose first letter does not begin with A or B; {A-Z}? matches any user whose first character is a capital letter and followed by any single character.

TIME PATTERN
A time interval specification has the same order as the standard Unix time format, i.e., weekday month day hour:minute year. Each field may be a single value, a range of values, or "don't care" indicated by a dash. For example, Wed Dec 13 {8:00-17:00} 1995 means the time between 8am and 5pm on Dec 13, 1995; (time==Sun - - - -) is true when the access time is on any Sunday; {Mon-Fri} Nov - - {1995-} matches the workdays in Novembers of 1995, 1996,...; - - {1-15} - - matches the first fifteen days of each month.

EXAMPLE 1:
socks5cop.conf contains:
        alert_time=60
        react_time=3600
        WHEN (OUT[dst] > 10000000)
        EXEC
           echo more than 10MB transferred to dst \
           in 60 seconds | mail sysadm
        END This alarm means that when the number of bytes transferred to the current destination is greater than 10M during the last 60 seconds, a mail is sent to the system administrator (sysadm). Assume that the destination host is `strange.com', then the mail content is:
 more than 10MB transferred to strange.com in 60 seconds After the action is executed, it becomes inactive in the next 3600 seconds for the same destination, even OUT[.] continues to grow.

EXAMPLE 2:
socks5cop.conf contains:
        alert_time=60
        react_time=3600
        WHEN (FAIL[src,usr] > 5)
        EXEC
          add2black src.name - user
          echo usr denied FAIL[usr] times | mail sysadm
        END where add2black is a shell script containing
        echo d - - $1 $2 $3 - - >> blacklist This alarm appends the current user to the blacklist file in the "socks5.conf" format and notifies to sysadm when a user from a same host has been denied more than 5 times in the last minute. After the action is executed, it becomes inactive for 3600 seconds for the same user.

SEE ALSO
socks5cop(1), socks5.conf(5)

LIMITATIONS
For the free version, alert_time is always 300 seconds and some aggregates are not available.

AUTHOR
Jianyu You (jyou@syl.dl.nec.com)