Part 2.c: Configuring OSSIM plugins

How a (detector) plugin works:
The plugin architecture can be described simply:

  • Detectors: Extensible portion of ossim-agent. Passively watch for regex matches within log files, socket or process output contents. ossim-agent handles sending the matched data to ossim-server. You will see an ossim-agent thread tailing specific logs (or syslog). The more detectors, the more work ossim-agent needs to do. (sort of like passive services in nagios/icinga)
  • Monitors: Actively receive a query from ossim-server, and communicate to their targets with their assigned task. (sort of like active services in nagios/icinga)

1) Let’s take a look at the arpwatch sensor will do:

vim /etc/ossim/agent/plugins/arpwatch.cfg

2) One of the functions of ossim-agent is it provides an internal “service manager” (with watchdog timer) for processes, which are the source of data that it watches. An alert is sent to ossim-server when a line matches a given regular expression.

source=log #the source is a syslog file
location=/var/log/ossim/arpwatch-eth0.log #the location of the log
process=/usr/sbin/arpwatch_eth0 #this is the process
start/stop=yes|no # allow ossim-agent to start or stop the process noted by startup and shutdown
restart=yes|no # watchdog function: do or don't restart every time the restart_interval is hit
startup=%(process)s -d -d -i %(interface)s -f /var/lib/arpwatch/arp-eth0.dat >> %(location)s 2>&1 & # the command line that is executed by ossim-agent to stop the process, as long as start=yes
shutdown=killall %(process)s # the comamnd line that is executed by ossim-agent to stop the process, as long as stop=yes

3) Additionally, there are specific events configured within this example cfg:

ip={$1} # ip is a special parameter, the value taken from the first (noted at $1) designated type (referred to as an alias, 'IPV4' in this case) that is found by the regular expression.  There are several aliases available by default (see /etc/ossim/agent/aliases.cfg).  An alias expands to a regular expression.
mac={$2} # mac is a special parameter, it is taken from the second (noted at $2) designated type (referred to as an alias, MAC in this case) that is found by the regular expression.  There are several aliases available by default (see /etc/ossim/agent/aliases.cfg).  An alias expands to a regular expression.
plugin_sid=2 # an event's ID (notice that there are three instance, but notice they are really the same actioned event, just different descriptions)
regexp=[regex] # the regular expression that matched, to trigger the event to be sent to ossim-server.

4) Now we know the arpwatch plugin will effectively:

  • allow the ossim-agent to start and stop the process using the specified commands in startup and shudown.
  • provide ossim-agent with the data source of a syslog file located at /var/log/ossim/arpwatch-eth0.log.
  • provide ossim-agent with the regular expression to search for to trigger the four configured arpwatch events.

Enable the arpwatch plugin:
1) Access the web UI.

2) On the left side menu: go to Deployment> System Configuration.

3) On the System Configuration page, click on the Sensor Configuration link above the System Status box.

4) Within the Sensor Configuration box, click on the Collection link to bring up the Plugins list.

5) In the list of “Plugins available,” find arpwatch, and click the plus symbol to the right.

6) Click Apply Changes to trigger OSSIM to reconfigure the system (by launching ossim-reconfig), restarting ossim-server and ossim-agent, which will restart openvassd.

7) Once configured, let’s make sure the files needed for arpwatch exist:

#check if 'location' plugin parameter value exist... It does because we've allowed ossim-agent to create the log file for us, regardless of if it exists.
ls -al /var/log/ossim/arpwatch-eth0.log
##-rw-r--r-- 1 root root 1413 Dec 19 15:33 /var/log/ossim/arpwatch-eth0.log
#check if files refered to in 'startup', 'shutdown' (using 'process' and 'interface' plugin) cfg parameters:
ls -al /usr/sbin/arpwatch_eth0 /var/lib/arpwatch/arp-eth0.dat
##-rwxr-xr-x 1 root root 31952 Dec 19 15:30 /usr/sbin/arpwatch_eth0
##-rw-r--r-- 1 root root     0 Dec 19 15:30 /var/lib/arpwatch/arp-eth0.dat

If files are missing, you’ll have to figure out why. Are the packages installed? I’ve created an issue, 171, which is currently private. Remember to disable auto-start.

8) If you wish ossim-agent to keep an eye on the process, and restart it, you can change the following:

restart_interval=\_CFG(watchdog,restart_interval) ; this argument is actually set in the watchdog section of /etc/ossim/agent/config.cfg, and is set to 3600 seconds (60 minutes) by default; although under testing below it restarts in 180 seconds (3 minutes).  You can set this to a decimal value if you wish, per plugin.

I’m awaiting an answer on exactly how ossim-agent checks to see if the process is running; but it looks like if you set restart=yes, ossim-agent’s watchdog will attempt to restart every five minutes.

So now what?
We just configured our first sensor!

1) For some plugins you may need to locate which config file the process is using; check out init scripts. You may need to change the destination log file (most importantly). For arpwatch, everything is configured at runtime using command line parameters with the startup parameter.

2) If you want to test the ossim-agent watchdog functionality, stop the process with the command from the given shutdown parameter, then wait for the process to respawn.

killall /usr/sbin/arpwatch_eth0
for i in {1..1600}; do echo waiting for watchdog $(($i*2-2)) seconds... && if [ $(($(ps -fC arpwatch_eth0 | wc -l) >= 2)) ]; then ps -fC arpwatch_eth0 | grep arpwatch && echo "process started at:" $(date) && break; fi; sleep 2; done #runs once every two seconds, 1600 times to check if arpwatch has started

Refer to the man page for information on using arpwatch.

You should be able to apply this same plugin bootstrapping method to work with many detector plugins. Monitor plugins are a bit different.

Selecting additional plugins:
Since you’ve performed asset discovery, you should decide on which plugins you will be using to monitor your data sources.

There are several plugins that are available by default, and several thousand additional plugins, mostly “detectors,” available.

Following the previous example with arpwatch, should give you good guidelines on how to properly implement detector plugins.

1) My immediate suggested shortlist of plugins:

  • arpwatch: Compares some info included in ARP packets heard on the interface. Checks a variety of conditions described on the man page.
  • p0f: passive OS fingerprinting tool
  • pads: rule-based, passive asset detection system
  • pam_unix: keeps track of IDM type events from pam_unix.
  • prads: pa1ssive asset detection (used to build host_attribute_table.xml to extend sguil)
  • ssh: keeps track of IDM type events from ssh, sessions, and a few more things.
  • sudo: keeps track of IDM type events from sudo, and executed commands.

2) To search for additional plugins (there are about 2171 additional plugins in v4.1), perform the following command:

cd /usr/share/ossim/scripts/
./ -s "case_insensitive_STRING" #the script uses the relative paths
#example return:
## Case_Insensitive_String
##        ID:             13933
##        Num sids:       1

3) Once you’ve located the plugin you want, use the script to extract the plugin files:

cd /usr/share/ossim/scripts/
./ -g -s "case_insensitive_STRING"
#example return:
##Start writing plugin files.
##Writing Case_Insensitive_String plugin files...
##Writing Case_Insensitive_String Manager plugin files...
##Done writing plugin files.
ls -al ./win_plugins/
##total 40
##d-wxr----t  2 root root  4096 Dec 13 16:44 .
##drwxr-xr-x 10 root root 16384 Dec 13 16:44 ..
##-rw-r--r--  1 root root   754 Dec 13 16:44 win_case_insensitive_string.cfg
##-rw-r--r--  1 root root   827 Dec 13 16:44 win_case_insensitive_string.sql
##-rw-r--r--  1 root root   790 Dec 13 16:44 win_case_insensitive_string_manager.cfg
##-rw-r--r--  1 root root  1142 Dec 13 16:44 win_case_insensitive_string_manager.sql
##-rw-r--r--  1 root root   166 Dec 13 16:44 win_config.cfg

4) Move these files to the live plugin directory:

mv ./win_plugins/win_case_insensitive_string.cfg /etc/ossim/agent/plugins

5) Process the SQL files:

ossim-db < ./win_plugins/win_backup_exec_server.sql

6) Proceed to use ossim-setup, and continue with the verification and configuration, as previously noted with arpwatch.


  1. No comments yet.
  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: