Chapter 3: The `policy' file

stealth reads a policy file defining the actions that must be performed. Each policy file is uniquely associated with a host to be tested. There may be multiple policy files for a host, though. In that case, each policy file will define a certain set of checks to be performed.

Below, the term controller is used for the computer where stealth is started, while the term client is used for the computer that is scanned by stealth. The controller and the client could be the same computer, but normally they are different.

The policy file 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: letter casing is preserved.

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

3.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,

3.2: USE directives

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

Note, however, that using stealth to inspect localhost is not recommended, as it counters one of the main reasons for stealth's existence.

As yet another alternative, applicable only to localhost, ssh could be avoided altogether. In that case /bin/bash or a comparable shell may be specified with USE SSH. For example: 


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

3.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.

3.3.1: LABEL commands

The following LABEL commands are available:

Examples: 


    LABEL Inspecting files in /etc\nIncluding subdirectories
    LABEL
The second LABEL command clears the first label.

3.3.2: LOCAL commands

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

3.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 controller. 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:

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

Either by malicious intent or by accendent (as happened to me) the controller may be a victim of a Denial of Service (DOS) attack. This DOS attack may happen when the client (apparently) sends a never ending stream of bytes in response to a GET or REMOTE command. One of my controllers once fell victim to this attack when a client's power went down and the controller kept on trying to read bytes from that client filling up the controllers 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 by a hacker who manages to replace, e.g., the find(1) command by a manipulated version which would continue to write information to its standard output stream. Without further precaution stealth would receive a never ending stream of bytes as its `report' thus causing its disk to fill.

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.

Now the reasons for the size-violation should 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.