.\" $Id: oinkmaster.1,v 1.26 2005/06/16 18:26:47 andreas_o Exp $
.\" Copyright (c) 2004-2005 Andreas Ostling <andreaso@it.su.se>
.\"
.\" Command to generate the man page: groff -man -Tascii oinkmaster.1
.\"
.TH OINKMASTER 1 "January 14, 2004"
.SH NAME
.B oinkmaster
\- update Snort signatures
.SH SYNOPSIS
.B oinkmaster -o
.I outdir
[options]
.SH DESCRIPTION
Oinkmaster is simple tool that helps you keep your Snort rules current 
with little or no user interaction. It downloads a tarball containing the
new rules and can then enable, disable or even make arbitrary 
modifications to specified rules before updating your local rules files.
It will also tell you the exact changes from your previous rules.
.SH OPTIONS
The only required argument to Oinkmaster is
.B -o
.I outdir
where
.I outdir
is the directory to put the new rules files in. This should be where you
keep your rules locally. The downloaded files will be compared to the ones
in here before possibly overwriting them.
.PP
Optional arguments:
.IP "\fB-b \fIdir\fP
If the rules have been modified, a tarball of your old rules will be put 
in
.I dir
before overwriting them with the new files. No backup is done if no file 
has changed or if Oinkmaster is running in careful mode.
.IP "\fB-c
Run in careful mode. This means that Oinkmaster will only check for 
updates and print them, but not update anything.
.IP "\fB-C \fIcfg\fP
Use this configuration file instead of the default.
If not specified, oinkmaster.conf will be looked for in
/etc/ and then /usr/local/etc/.
You can specify multiple
.B -C
.I cfg
to load multiple configuration files.
They will be loaded in order of appearance on the command line. If an 
option is redefined, it overrides the previous value (except for the "url"
option, as you are allowed to specify multiple URLs).
.IP "\fB-e
Enable rules that are disabled by default in the downloaded rules archive 
by removing all the leading "#" from them. If there are any disabled rules 
in the archive, they will stay that way unless you use this option. 
Remember that they are disabled for a reason (they may not even work), so 
use this option with care.
.IP "\fB-h
Show valid command line arguments with short descriptions
.IP "\fB-i
Enable interactive mode. You will be asked to approve the changes (if 
any) before updating anything.
.IP "\fB-m
Minimize/simplify the diff when printing result for modified rules by
removing common leading and trailing parts of the old and new rule so
it's easier to see the actual change. A few characters to the left and
to the right of the change are also printed so you get some context.
The rev keyword is ignored when the comparison and removal of common
parts is performed because it would often make the whole idea fail.
(If you feel it's important to be able to verify that the rev number
has increased when a rule has been updated, do not use the minimized
diff mode.)

Normally when a rule has changed the entire old and new versions are
printed, but the actual change between them can be hard to see if the rules
are long, complex and many.
.PP
       The normal output could look like this:
.PP
.nf
       Old: alert tcp any any -> any 22 (msg: "foo"; flags: A+; rev:1;)
       New: alert tcp any any -> any 123 (msg: "foo"; flags: A+; rev:2;)
.fi
.PP
       When using
.B -m
it would instead look something like:
.PP
.nf
       Old: ...any any -> any 22 (msg: "foo";...
       New: ...any any -> any 123 (msg: "foo";...
.fi
.IP "\fB-q
Run in quiet mode. Nothing is printed unless there are changes in the 
rules or if there are errors or warnings.
.IP "\fB-Q
Run in super-quiet mode. This is the same as
.B -q
but even more quiet when printing the results (the "None." stuff is not 
printed). It will also suppress some other warning messages such as
those for duplicate SIDs and non-matching modifysid expressions.
.IP "\fB-r
Check for rules files that exist in the output directory
but not in the downloaded rules archive, i.e. files that may have been 
removed from the distribution archive.
.IP "\fB-s
Leave out details when printing results (aka bmc mode).
This means that the entire added / removed / modified rules will not
be printed, just their SID and msg string, plus the filename.
Non-rule changes are printed as usual. This output mode could be useful
for example if you send the output by email to people who don't really
care about the details of the rules, just the fact that they have been
updated. Example output when running with
.B -s
.PP
.nf
       [+++]          Added rules:          [+++]

           1607 - WEB-CGI HyperSeek hsx.cgi access (web-cgi.rules)
           1775 - MYSQL root login attempt (mysql.rules)


       [///]     Modified active rules:     [///]

            302 - EXPLOIT Redhat 7.0 lprd overflow (exploit.rules)
            304 - EXPLOIT SCO calserver overflow (exploit.rules)
            305 - EXPLOIT delegate proxy overflow (exploit.rules)
            306 - EXPLOIT VQServer admin (exploit.rules)
.fi
.PP
.IP "\fB-S \fIfile\fP
Used in conjuction with with
.B -U
to specify which file(s) in the downloaded archive(s) to search
for new variables. When not specified, snort.conf is checked.
You may specify multiple
.B -S
.I file
to search for new variables in multiple files.
.IP "\fB-T
Check the configuration file(s) for fatal errors and then exit.
Possible warning messages are printed as well.
.IP "\fB-u \fIurl\fP
Download the rules archive from
.I url
instead of the location specified in the configuration file.
It must start with file://, ftp://, http://, https:// or scp:// and end 
with ".tar.gz" or ".tgz". The file must be a gzipped tarball containing 
a directory named "rules", holding all the rules files. It must not
contain any symlinks. You can also point to a local directory with
dir://<directory>. For the official Snort rules, the URL to use depends
on the version of Snort you run and it might also require registration.
Visit the rules download section at the Snort web site to find the
right URL and more information. Remember to update the URL when
upgrading to a new major version of Snort.

You may specify multiple
.B -u
.I url
to grab multiple rules archives 
from different locations. All rules files in the archives will be put in 
the same output directory so if the same filename exists in multiple 
archives, Oinkmaster will print an error message and exit. That's why it's 
usually recommended to instead run Oinkmaster once for each URL and use 
separate output directories. If
.B -u
.I url
is specified, it overrides 
any URLs specified in the configuration file(s). Note that if multiple 
URLs are specified and one of them is broken, Oinkmaster will exit 
immediately without further processing. This can be good or bad, depending
on the situation.
.IP "\fB-U \fIfile\fP
Variables (i.e. "var foo bar" lines) that exist in downloaded snort.conf
but not in
.I file
will be added to
.I file
right after any other variables it may contain. 
Modified existing variables are not merged, only new ones. 
.I file
is normally your production copy of snort.conf (which should not be a
file that is updated by Oinkmaster the normal way).
This feature is to prevent Snort from breaking in case there are new
variables added in the downloaded rules, as Snort can not start if the
rules use variables that aren't defined anywhere. By default when using
.B -U
, the file snort.conf in the downloaded archive is search for new
variables but you can override this with the
.B -S
.I file
argument. If you download from multiple URLs, Oinkmaster will look for
a snort.conf in each downloaded rules archive.
.IP "\fB-v
Run in verbose/debug mode. Should probably only be used in case you need
to debug your settings, like verifying complex modifysid statements.
It will also tell you if you try to use "disablesid" on non-existent
SIDs. Warnings about using enablesid/localsid/modifysid on non-existent
SIDs are always printed unless running in quiet mode, as those are
usually more important (using "disablesid" on a non-existent rule is
a NOOP anyway).
.IP "\fB-V
Show version and exit.
.SH EXAMPLES
Download rules archive from default location specified in oinkmaster.conf 
and put the new rules in /etc/rules/:
.PP
.nf
\fB    oinkmaster -o /etc/rules \fP
.fi
.PP
Grab rules archive from local filesystem and do not print anything unless
it contains updated rules:
.PP
.nf
\fB    oinkmaster -u file:///tmp/rules.tar.gz -o /etc/rules -q \fP
.fi
.PP
Download rules archive from default location, make backup of old rules if
there were updates, and send output by e-mail. (Note however that if you 
plan on distributing files with Oinkmaster that could be considered 
sensitive, such as Snort configuration files containing database 
passwords, you should of course not send the output by e-mail without 
first encrypting the content.):
.PP
.nf
\fB    oinkmaster -o /etc/snort/rules -b /etc/snort/backup 2>&1 | \fP\\
\fB    mail -s "subject" user@example.com
.fi
.PP
Grab three different rules archives and merge variables that exist in
downloaded snort.conf and foo.conf but not in local
/etc/snort/snort.conf:
.PP
.nf
\fB    oinkmaster -u file:///tmp/foo.rules.tar.gz \fP\\
\fB    -u http://somewhere/rules.tar.gz -u https://blah/rules.tar.gz \fP\\
\fB    -o /etc/rules -S snort.conf -S foo.conf -U /etc/snort/snort.conf
.fi
.PP
Load settings from two different files, use scp to download rules archive 
from a remote host where you have put the rules archive, merge variables 
from downloaded snort.conf, and send results by e-mail only if anything 
changed or if there were any error messages. It assumes that the "mktemp" 
command is available on the system:
.PP
.nf
\fB    TMP=`mktemp /tmp/oinkmaster.XXXXXX` && \fP\\
\fB    (oinkmaster -C /etc/oinkmaster-global.conf \fP\\
\fB    -C /etc/oinkmaster-sensor.conf -o /etc/rules \fP\\
\fB    -U /etc/snort.conf \fP\\
\fB    -u scp://user@example.com:/home/user/rules.tar.gz \fP\\
\fB    > $TMP 2>&1; if [ -s $TMP ]; then mail -s "subject" \fP\\
\fB    you@example.com < $TMP; fi; rm $TMP) \fP
.fi
.PP
.SH FILES
.B /etc/oinkmaster.conf
.br
.B /usr/local/etc/oinkmaster.conf
.SH BUGS
If you find a bug, report it by e-mail to the author. Always include as 
much information as possible.
.SH HISTORY
The initial version was released in early 2001 under the name 
arachnids_upd. It worked only with the ArachNIDS Snort rules, but as times 
changed, it was rewritten to work with the official Snort rules and the 
new name became Oinkmaster.
.SH AUTHOR
Andreas Ostling <andreaso@it.su.se>
.SH SEE ALSO
The online documentation at http://oinkmaster.sf.net/ contains more 
information.