Chapter 4: The `policy' file

Stealth uses a policy file consisting of two sections, the second section is optional, and starts at a line merely containing %%.

Each policy file is uniquely associated with a host to be tested. Each host may have multiple policy files, though. In that case, each policy file defines its own set of checks to be performed.

The policy file's first section consists of three sets of data: define directives (starting with the keyword DEFINE), use directives (starting with the keyword USE) and commands.

Directives are written in capitals, and should appear exactly as written below.

Blank lines and information beyond hash-marks (#) are ignored, while lines following lines terminating in backslashes (\ ) will be concatenated (en passant removing these backslashes). Leading white space on lines of the policy file is ignored.

4.1: DEFINE directives

DEFINE directives can be used to define symbols for longer strings. A DEFINE directive is constructed as follows:
    DEFINE name     that what is defined by `name'
Here,

4.2: USE directives

USE directives provide stealth with arguments which may be conditional to a certain installation. The following USE directives are supported:

In some installations stealth is used to inspect the monitor itself, even though this is not recommended, as it breaks one of the main reasons for stealth's existence. But in those situations (so, where stealth is used to monitor the integrity of the localhost), /bin/bash could be specified at the USE SSH directive. For example:

    # For stealth inspecting localhost:
        USE SSH /bin/bash --noprofile

4.3: Commands

Following the USE specifications, commands can be specified. The commands are executed in their order of appearance in the policy file. Processing continues until the last command has been processed or until a tested command (see below) returns a non-zero return value.

4.3.1: LABEL commands

The following LABEL commands are available:

Examples:


    LABEL Inspecting files in /etc\nIncluding subdirectories
    LABEL
The latter LABEL command clears the text of the former LABEL command.

4.3.2: LOCAL commands

LOCAL commands can be used to specify commands that are executed on the monitor itself. The following LOCAL commands are available:

4.3.3: REMOTE commands

Plain commands can be executed on the client computer by merely specifying them. Of course, this means that programs called LABEL, LOCAL USE or DEFINE, cannot be executed, since these names are interpreted otherwise by stealth. It's unlikely that this will cause problems. Remote commands must succeed (i.e., their return codes must be 0).

Remote commands are commands executed on the client using the SSH shell. These commands are executed using the standard PATH set for the SSH shell. However, it is advised to specify the full pathname to the programs to be executed, to prevent ``trojan approaches'' where a trojan horse is installed in an `earlier' directory of the PATH-specification than the intended program.

Two special remote commands are GET and PUT, which can be used to copy files between the client and the monitor. Internally, GET and PUT use the DD use-specification. If a non-default specification is used, one should ensure that the alternate program accepts dd(1)'s if=, of=, bs= and count= options. With GET the options bs=, count= and of= are used, with PUT the options bs=, count= and if= are used. Normally there should be no need to alter the default DD specification.

The GET command may be used as follows:

The PUT command may be used as follows:

Other commands to be executed on the client can be specified as follows:

4.3.4: Preventing Controller Denial of Service (--max-size)

Either by malicious intent or by accident (as happened to me) the monitor may be a victim of a (self-inflicted) Denial of Service (DOS) attack. This DOS attack may occur when the client (apparently) sends a never ending stream of bytes in response to a GET or REMOTE command. Once one of my monitors fell victim to this attack when a client's power went down and the monitor kept on trying to read bytes from that client filling up the monitor's disk....

This problem was of course caused by a programming error: while reading information from a client stealth failed to check whether the reading had actually succeeded. This bug has now been fixed, but an intentional DOS attack could still be staged along this line when, e.g., the find(1) command is somehow replaced by a manipulated version continuously writing information to its standard output stream. Without further precaution stealth would receive a never ending stream of bytes to be written to its `report' file, thus causing its disk to fill up.

To prevent this from happening stealth now offers the --max-size command line option allowing the specification of the maximum size of a stream of bytes received by stealth (e.g., a report or downloaded file). The maximum is used for each individual download and can be specified in bytes (using no suffix or the B suffix), kilo-bytes (using K), mega-bytes (using M) or giga-bytes (using G). The default is set at 10M, equivalent to the command line specification of --max-size 10M.

If a file or report received from the client exceeds its maximum allowed size then stealth terminates after writing the following message to the report file (which is sent to the configured mail address):

    
STEALTH - CAN'T CONTINUE: `<name of offending file>' EXCEEDS MAX. 
                                                DOWNLOAD SIZE (<size shown>)
    STEALTH - THIS COULD SIGNAL A SERIOUS PROBLEM WITH THE CLIENT
    STEALTH - ONE OR MORE LOG FILES MAY BE INVALID AS A RESULT
    STEALTH - *** INVESTIGATE ***
Since a --max-size specification may cause stealth to terminate while receiving the output of a (remotely run) command, an empty or partial log file will be the result. Of course this partial result is spurious as it is a direct result of stealth terminating due to a size violation.

After investigating (and removing) the reasons for the size violation a new stealth run using the previous log file as the latest baseline should show only expected changes.

For example, assume the following situation represents a (valid) state of logfiles:

    etc                       stealth                   
    setuid                    stealth.20080316-105756
Now stealth is run with --max-size 20, prematurely terminating stealth. This results in the following set of logfiles:
    etc                       stealth
    setuid                    stealth.20080316-105756   
                              stealth.20080316-110215
The file stealth now contains incomplete data with the (latest) file stealth.20080316-110215 containing its previous contents.

The reasons for the size-violation should of course be investigated and removed. It is suggested to move the file last saved (stealth.20080316-110215) to the file stealth, as it represents the state before the size violation was encountered. Following this stealth should operate normally again.