nstsguil

Name

nstsguil — NST Script To Manage The Analyst Console for Network Security Monitoring (SGUIL).

Synopsis

nstsguil [ -m TEXT | --mode TEXT ] [ --passwd TEXT ] [ --server HOST|IP ] [ --hostid TEXT ] [ --start [true]|false ] [ --cron [true]|false ] [ -i DEVICE | --interface DEVICE ] [ --snort-rules DIRECTORY ] [ --url TEXT ] [ -rd DEVICE | --ram-device DEVICE ] [ -rds SIZE | --ram-disk-size SIZE ] [ -rmp PATH | --ram-mount-point PATH ] [ -rdir DIRECTORY | --runtime-directory DIRECTORY ] [ -h [true]|false | --help [true]|false ] [ -H [true]|false | --help-long [true]|false ] [ -v [true]|false | --verbose [true]|false ] [ --version [true]|false ]

Description

The nstsguil script is used in a NST distribution to manage the sguil package included in the distribution. It is important to understand that the sguil package includes three different components:

Server Component

There must be a sguild daemon process running and accepting connections from the client and sensor components. The sguild daemon does not need to be running on the same machine as the other components.

Sensor Component

There will usually be one or more sensor components configured and running. Each sensor component is responsible for monitoring a particular interface and reporting information back to a sguild server. It should be noted that a single sensor component requires multiple processes to be running and logging data (two instances of snort, a instance of barnyard, etc). The sensor component does not need to be running on the same machine as the server component (many sensors can report to the same server).

Client Component

The sguil package includes a handy GUI client which connects to the sguild server to examine the information being acquired and logged by the sensors. There can be more than one GUI client running and connected to the same server at the same time. The GUI client does not need to be running on the same system as the server.

Note

The sguil package is resource intensive. It is not recommended that one try to run all of the components in RAM (the sensor components in particular can archive quite a bit of data over time). It is recommended that the user have the /var/nst directory pointing at a hard disk partition with plenty of space and include the "-rdir /var/nst" option on the command line when using "--mode setup". This is particularily true if there will be one or more sensor components running on the system.

The nstsguil script has several "modes" of operation, and is typically used in the following fashion:

  • The MySQL server must be setup and running on the system (the setup_mysql script makes this an easy task).

  • The nstsguil script is then run using the "--mode setup" option to prepare the NST to run both the server and client components of the sguil package (it also does the initial setup for the sensor components).

  • One can then start, stop and get status about the server component using the /etc/rc.d/init.d/sguild service script.

  • One can configure one or more sensor components by running the nstsguil script with the "--mode logsetup -i eth0" options.

  • One can start and stop a configured sensor component via the nstsguil script using the "--mode logstart -i eth0" or "--mode logstop -i eth0" options.

  • One can run the client component via the /usr/bin/sguil command installed by the nstsguil script.

  • Finally, one can shutdown all of the sensor components and the server component and remove all of the resources used via the nstsguil script using the "--mode remove" option. NOTE: This will remove the client component as well - but does not attempt to kill the any running client process(es).

The following assumes that the /var/nst directory already exists and that the MySQL server is already running. Given these assumptions, the following command can be used to setup sguil and start the server component:

[root@probe ~]# service mysqld status
mysqld (pid 29758) is running...
[root@probe ~]# nstsguil --mode setup
New password for "sguil" login to sguild: 
Retype new password:
[root@probe ~]# service sguild start
Starting sguild daemon:                                    [  OK  ]
[root@probe ~]# service sguild status
sguild (pid 862) is running...
[root@probe ~]#

Now that the server component of sguil is up and running, we can configure and start sensor components. The following demonstrates how to set up two sensor components to monitor the traffic on interfaces "eth0" and "eth2":

[root@probe ~]# nstsguil --mode logsetup -i eth0 --cron --start
[root@probe ~]# nstsguil --mode logsetup -i eth2 --cron --start
[root@probe ~]#

At this point in the example, we have the sguil server component running and two sensor components running. Traffic on two interfaces ("eth0" and "eth2") is now being monitored and suspicous activity is being logged. The following example runs the ping_attack.sh command on network 192.168.10.0 which should trigger the sensor component monitoring "eth0". The sguil client program is then started to examine the attacks which have been detected so far. Running the ping_attack.sh isn't necessary, but gives us a mechanism to verify that events are being monitored and logged properly. It should be noted that the /usr/bin/sguil GUI interface will require us to login to the server, we will need to login using the "sguil" user account and password we specified at the time of setup (this account was created above when we ran the: "nstsguil --mode setup" command).

[root@probe ~]# ifconfig eth0 | grep "inet addr:"
          inet addr:192.168.10.66  Bcast:192.168.10.255  Mask:255.255.255.0
[root@probe ~]# ping_attack 192.168.10.0
PATTERN: 0x7569643d3028726f6f74290a
WARNING: pinging broadcast address
PING 192.168.10.0 (192.168.10.0) 56(84) bytes of data.
64 bytes from 192.168.10.1: icmp_seq=0 ttl=64 time=3.81 ms
64 bytes from 192.168.10.1: icmp_seq=1 ttl=64 time=1.13 ms
64 bytes from 192.168.10.1: icmp_seq=2 ttl=64 time=1.14 ms

--- 192.168.10.0 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2008ms
rtt min/avg/max/mdev = 1.135/2.032/3.815/1.261 ms, pipe 2
[root@probe ~]# /usr/bin/sguil
[root@probe ~]#

Finally, after quiting the client application, we can completely remove the sguil setup using the "--mode remove" option as shown below.

[root@probe ~]# nstsguil --mode remove
[root@probe ~]#

Note

The nstsguil script produces a minimal amount of output by default (you should see very little output unless something goes wrong). If you want more diagnostics about about what the script is doing, include the "--verbose" (or "-v") option.

For scripting purposes, the nstsguil script exits with a return code of 0 if the command completed successfully (or 1 if not).

By default a single "sguil" user account is created in the sensor component setup. You can add user accounts to the sguil server component by running: "(cd ~sguild/server; ./sguild -adduser NAME)". You can remove user accounts by running: "(cd ~sguild/server; ./sguild -deluser NAME)".

Serverless Setup

If you are setting up multiple systems to feed one centeral sguil server, you only need to have one of the systems to act as the sguil server component. The systems which will only be running the sguil sensor and/or client components should be setup using the "--server ADDRESS" option.

For example, lets assume that you've followed the steps in the previous section and have a sguil server running on "192.168.10.66". To setup another system ("192.168.10.77" in this example), one would use the following command:

[root@probe ~]# nstsguil --mode setup --server 192.168.10.66
[root@probe ~]#

One could then run the following command to configure and start up a sguil sensor component which would monitor the ethernet traffic on "eth0" at "192.168.10.77" and forward the information to the sguil server at "192.168.10.66".

[root@probe ~]# nstsguil --mode logsetup -i eth0 --cron --start
[root@probe ~]#

One could start up multiple sensors in this manner. In addition one could run the sguil client (/usr/bin/sguil) and monitor the information recorded on the central server.

Notes:

  • The sensor would have the ID of "192-168-10-77-eth0" in the database. We could use the "--hostid HOSTID" if we'd like to use something other than the IP address to form this unique identifier.

  • By default, the server running at "192.168.10.66" would reject the sensor data reported by "192.168.10.77" until we add the following line to the server's ~sguild/server/sguild.access file and restart the server:

    # Enable the server to accept data from our remote sensor
sensor 192.168.10.77

Modes of Operation

The following sections provide additional information on the different modes of operation. In particular, the other parameters which can be combined with each mode of operation are shown:

--mode status

This mode of operation is used to tell whether the sguil package has already been setup on the system or not. It returns 0 if the sguil package has been setup and 1 if not. It does not echo any output information unless you include the "--verbose" (or "-v") option.

--mode setup

This mode of operation is used to initialize the sguil setup. It is important to remember that invoking this mode will DESTROY any previous sguil setup. The following command line options may be used in "setup" mode (all are optional):

--verbose (-v)

Provides verbose diagnostic output about what the script is doing.

--server HOST

If you specify this option, we will only setup the system for the sguil client and sensor components. The client and sensor components will connect to server running on the "HOST" specified (instead of "127.0.0.1"). You will not be able to run the sguil server component on the local system when this option is specified.

--start

If you specify this option, the sguild daemon process will be started after setup. If you don't include this option, you will need to start the sguil server using the /etc/rc.d/init.d/sguild script.

-rdir DIR

By default, the sguil installation will go into its own subdirectory (sguild) under the /var/nst directory, but only if the /var/nst directory exists. By default, if the /var/nst does not exists, a RAM disk at /mnt/ram4 will be used (and created if it doesn't yet exist). You may use this option to specify a root directory other than /var/nst to create the "sguild" package directory under. It is not recommended that one start up ANY sensor components when using a RAM disk. If you do want to make use of a RAM disk, you may want make use the "--ram-device", "--ram-mount-point", "--ram-mount-point" and "--ram-disk-size" options described later in this document.

--passwd TEXT

By default, you will be prompted to specify the password for the "sguildb" database and the initial "sguil" user account created. You may use this command line option to avoid being prompted.

--snort-rules RULESDIR

This option allows you to specify the location of the snort rules directory to be used.

--url PKGURL

This option is intended for NST developers. It allows one to try out newer versions of sguil by specifying the URL of the sguil distribution to install.

--mode remove

This mode of operation first shuts down any running server and sensor components of the sguil package. It then completely removes the entire sguil package from the system (you will need to use "--mode setup" before you will be able to run any of the sguil components again). It returns 0 if successful and 1 if not. It does not echo any output information unless you include the "--verbose" (or "-v") option.

--mode logsetup -i INTERFACE

This mode of operation is used to initialize a configuration for a single sensor component associated with a particular interface. For example, you could use this mode to prepare the system to monitor and log traffic on ethernet "eth0". The following command line options may be used in combination with the "logsetup" mode (all but the interface settings are optional):

--interface INTERFACE (-i)

This option is required when using "--mode logsetup" to indicate what interface is to be used.

--verbose (-v)

Provides verbose diagnostic output about what the script is doing.

--server HOST

You almost NEVER need to specify this option. It is only required if you want a particular sensor configuration to connect to a different sguil server. If you specify this option, we will configure the sguil sensor to use the "HOST" specified. If you omit this option, we will use the "HOST" specified when you originally setup the system via "--mode setup", or "127.0.0.1" (if never specified).

--hostid HOSTID

This simple text string is used to form the unique "HOSTID-INTERFACE" identifier associated with the sensor. By default, the IP address of the machine is used as the "HOSTID". For example, by default, you might see something like "192-168-10-66" used resulting in a unique identifer of "192-168-10-66-eth0" when monitoring the traffic on Ethernet "eth0". If one were to specify: "--hostid probe1 -i eth2", the unique identifier would be: "probe1-eth2". When networking multiple systems, it is critical to keep the "HOSTID" values unique on each system.

--cron

If you specify this option, a script will be created in the /etc/cron.hourly directory to automatically restart the sensor logging process once an hour (this is recommended in the Sguil installation notes).

--start

If you specify this option, the processes associated with the sensor component will be immediately started after being setup. If you don't include this option, you will be able to review the configuration files associated with the sensor component and then use the nstsguil script with the "--mode logstart -i INTERFACE" options to start the sensor component.

--snort-rules RULESDIR

If you want the sensor component associated with this component to use a different set of snort rules, you can use this option to specify the location of the snort rules directory.

--mode logstart -i INTERFACE

This mode of operation is used to start the processes for the sensor component associated with a particular interface. For example, you could specify "--mode logstart -i eth0" to start up the sensor component associated with the "eth0" interface. You MUST use the "--mode logsetup" prior to using this feature. The following command line options may be used in combination with the "logstart" mode (all but the interface settings are optional):

--interface INTERFACE (-i)

This option is required when using "--mode logstart" to indicate what interface is to be started.

--verbose (-v)

Provides verbose diagnostic output about what the script is doing.

--mode logstop -i INTERFACE

This mode of operation is used to stop the processes for the sensor component associated with a particular interface. For example, you could specify "--mode logstop -i eth0" to stop the sensor component associated with the "eth0" interface. You MUST use the "--mode logsetup" prior to using this feature. The following command line options may be used in combination with the "logstop" mode (all but the interface settings are optional):

--interface INTERFACE (-i)

This option is required when using "--mode logstop" to indicate what interface is to be stopped.

--verbose (-v)

Provides verbose diagnostic output about what the script is doing.

--mode logremove -i INTERFACE

This mode of operation is used to stop and completely remove a sensor component. For example, you could specify "--mode logremove -i eth0" to stop and remove the sensor component associated with the "eth0" interface. You MUST use the "--mode logsetup" prior to using this feature. The following command line options may be used in combination with the "logremove" mode (all but the interface settings are optional):

--interface INTERFACE (-i)

This option is required when using "--mode logremove" to indicate what interface is to be stopped and removed.

--verbose (-v)

Provides verbose diagnostic output about what the script is doing.

Options

The following command line options are available:

[-m TEXT] | [--mode TEXT]

This option controls what nstsguil will do. If you specify status (the default), it will indicate whether nstsguil has been setup yet or not. If you specify setup it remove any previous instance of nstsguil and set up your NST system to run the Sguil server component, sensor component and/or client component. If you specify remove it will shut down any running sensor and/or server components and then remove the sguil installation from the system. If you specify logsetup, a sguil sensor component for the specified interface will be setup (include "-i INTERFACE"). If you specify logstart, a sguil sensor component which was previously setup will be started and begin monitoring and logging data (include "-i INTERFACE"). If you specify logstop, a sguil sensor component, which was previously setup and started, will stop monitoring and logging data (include "-i INTERFACE"). If you specify logremove, a sguil sensor component, which was previously setup, will stop monitoring and logging data and its setup will be removed (include "-i INTERFACE").

[--passwd TEXT]

This option allows one to set the password used for access to the "sguildb" database that will be created during setup. This password is also used for the initial "sguil" user account created for the sguild server.

[--server HOST|IP]

The default value (when omitted on the command line) for this option will either come from the "SERVER_HOST" setting in "~squild/sensor/sensor_agent.conf", or the literal "127.0.0.1". The value of "127.0.0.1" was chosen because we assume that all of the sguil components (server, sensor, and client) will be running on the same system. Specify this option if the sguild daemon process (the sguil server component) is running on a different system. When this option is combined with "--mode setup", it will disable the configuration and setup of a local squil server component. In this case, the system will only be capable of running the client and sensor components. When this option is combined with the "--mode logsetup", it indicates which sguil server the sensor component should report its data to. NOTE: One will need to update the server's "~sguild/server/squild.access" file in order for the server to accept remote connections.

[--hostid TEXT]

Each sensor component should have a unique name which identifies it to the database. This is present in each sensor configuration file as the "HOSTNAME" setting. We attempt to generate a unique identifier for this configuration value using "HOSTID-INTERFACE" where the "HOSTID" is replaced by your system's default IP address and "INTERFACE" is replaced by what you specify in the "-i INTERFACE". You can use this option to overide the "HOSTID" portion of this unique identifier. NOTE: As this unique key can not contain periods (dots), all periods are converted to dashes (for example "192.168.0.100" becomes "192-168-0-100").

[--start [true]|false]

If this option is included with "-mode setup", the sguild daemon process will be started immediately after setup. If this option is included with "--mode logsetup" the sensor logging daemon process will be started immediately after setup.

[--cron [true]|false]

If this option is included with "--mode logsetup", a script will be created in the /etc/cron.hourly directory to automatically restart the sensor logging process once an hour (this is recommended in the Sguil installation notes).

[-i DEVICE] | [--interface DEVICE]

When using the "logsetup" mode, this option is used to indicate which interface is to be monitored. If you omit the interface option, we will default to "eth0". If the interface is not yet active, we will attempt to activate it in stealth mode (no IP). A "/usr/sbin/sguild-logwatch-HOSTID-INTERFACE" script will be created that will keep a instance of snort up and running. When using the "logremove" mode, this option is used to indicate the interface which you want to disable monitoring on (you may specify "all" if you want to remove all network logging instances).

[--snort-rules DIRECTORY]

Use this option if you need to specify the directory containing the location of your snort rules. By default, we will check "../snort/rules" (which is where one might expect to find them if you've been managing your rules with the setup_snort script) and if there aren't any newer ones, we will fall back to what comes on the NST distribution under "/usr/local/snort/rules".

[--url TEXT]

This option allows one to override what SGUIL package is installed. By default, we will install the version included with the NST distribution ("file:///usr/local/share/nstsguil/sguil.tar.bz2"). It is recommended to leave this at the default setting (as it is known to work). Developers wishing to test newer releases of the SGUIL package may use values like: "file:///tmp/sguil/sguil-0.6.1.tar.gz".

[-rd DEVICE] | [--ram-device DEVICE]

Use this optional parameter to change the default RAM device that will be used for setting up the runtime environment by the nstsguil script. The following RAM device names are available on NST: /dev/ram0 - /dev/ram9. A corresponding mount point path: /mnt/ram0 - /mnt/ram9 will be automatically selected for the RAM device. One can use the following optional parameter: [-rmp PATH] to change the mount point path location for the selected RAM device. If not specified, a reasonable default value for the nstsguil script shall be chosen.

[-rds SIZE] | [--ram-disk-size SIZE]

Use this optional parameter to change the default RAM disk size in MegaBytes (MB) that will be used if a RAM disk is created by the nstsguil script. **Note: Use a reasonable value and make sure you to not exceed your available system RAM. The system memory utility: "free" can be used to help make your determination. If omitted, a reasonable value will be chosen by the nstsguil script. The minimum value permitted is 10. The maximum value permitted is 1024.

[-rmp PATH] | [--ram-mount-point PATH]

Use this optional parameter to change the selected RAM device: [-rd DEVICE] mount point path location for the runtime environment created by the nstsguil script.

[-rdir DIRECTORY] | [--runtime-directory DIRECTORY]

One can use this optional parameter to force the nstsguil script to use an existing runtime directory on a locally attached disk drive or a mounted network file system and bypass the creation of a RAM disk. To do this, make sure the directory initially exists prior to using this option. If omitted and the -rd DEV option is omitted, then the nstsguil will make a "smart choice" as to whether to allocate a RAM disk or use a existing directory.

[-h [true]|false] | [--help [true]|false]

When this option is specified, nstsguil will display a short one line description of nstsguil, followed by a short description of each of the supported command line options. After displaying this information nstsguil will terminate.

[-H [true]|false] | [--help-long [true]|false]

This option will attempt to pull up additional nstsguil documentation within a text based web browser. You can force which browser we use setting the environment variable TEXTBROWSER, otherwise, we will search for some common ones.

[-v [true]|false] | [--verbose [true]|false]

When you set this option to true, nstsguil will produce additional output. This is typically used for diagnostic purposes to help track down when things go wrong.

[--version [true]|false]

If this option is specified, the version number of the script is displayed.

Files

/usr/share/nstsguil

Directory containing resource files used by nstsguil. This includes the tar ball (sguil.tar.bz2) of the sguil distribution bundled with the NST.

Environment

TEXTBROWSER

This controls what text based browser is used to display help information about the script. If not set, we will search your system for available text-based browsers (Ex: elinks, lynx ...).

See Also

setup_mysql, setup_snort, Network Security Toolkit