Provided by: specter_1.4-3ubuntu3_i386 bug
 

NAME

        specter.conf - configuration file for specter
 

DESCRIPTION

        specter  reads  its configuration parameters from file, which is mostly
        /etc/specter.conf.  It is divided into blocks. Each block start with  a
        opening  curly bracket { and end with closing curly bracket }.  Nesting
        of blocks (opening new block inside another) is forbidden, and  there’s
        no  need  for  that  in  specter configuration. In order to distinguish
        between blocks, each has a name.  You can use any  name  for  a  block,
        except two special names: global (which is used to specify general dae‐
        mon parameters) and plugins (that list available add-ons).  Numbers  in
        range  1-SPECTER_GROUPS_MAX  has  also  special functional meaning (see
        grouping option description). You cannot define the same  block  twice,
        but  don’t have to define all of them. In most configurations you’ll be
        fine with three or four blocks.
 
        Each block have to start in a new line, then goes its name and  opening
        bracket.  All  blocks  (except for global and plugins) are divided into
        logical sections, which define a configuration space for every  plugin.
        You start a section with a colon : followed by its name. Within section
        you can finally specify your configuration.  global and plugins  blocks
        are  simpler  in  that manner that they don’t have any sections.  Block
        ends with a closing bracket. So, in  general,  block  definition  looks
        like this:
 
               name {
               include other_block
               :section_one
               some_option value
               # comment
               other_option "long value that needs spaces"
               :section_two
               # this section have no options, but it’s important to specify it
               :section_three
               option
               option value # another comment
                  ...
               }
 
        As  you can see, not every option needs a value, in that case its pres‐
        ence will override a default (see below for specific  options  descrip‐
        tion).  A  hash # is used as a comment, as it will cause a rest of line
        to be ignored. Of course you can  use  comments  everywhere,  not  only
        inside  blocks.  If  you  need  to set an option to a string containing
        spaces or tabs, you can enclose it inside double  quotation  marks,  as
        shown  above.  And if you ever manage to write a very long config line,
        you can cut it by \ and continue your statement in the line below.
 
        Since 1.2 version of specter you can use include  statement  to  attach
        contents  of  other  block to current block. Length of include chain is
        unlimited, but no recursion is allowed.  Each include command  is  per‐
        formed exacly once, what mostly does what you wanted.
 
        specter  does  nearly  nothing  on its own, it uses plugins for all the
        dirty work. They are divided into two groups.  Input plugins analyze  a
        packet and create hash table concerning received data, in the form like
        key=value. They don’t open files nor they take  any  input  from  user.
        Only  output  plugins  take  options. They actually use data from input
        plugins - save it into logs/databases or execute appropriate  commands.
        So  it’s vital for you to learn about their configuration, because it’s
        the essence of using specter.
        Remember that these should be set inside global options block.
 
        errignore
               This options causes  specter  to  continue  running  despite  of
               errors  generated by plugins. That doesn’t affect initialization
               phase, when all errors cause an exit. This option can be  useful
               on heavy-load systems, when you expect some malloc() to fail. It
               doesn’t take any arguments.
 
        logfile
               Path to a file you want specter messages to get logged  to.  Can
               be set to stdout or stderr.
 
        loglevel
               The  lower  the  value,  the  more information is logged. If you
               experience any problems, check lowest, debug loglevel=1, so that
               you can see all messages. The highest loglevel is 8, which cause
               only fatal errors to be shown. The default is 3.
 
        rmem   Size of the netlink socket receive memory. You should  set  this
               to at least the size of the kernel buffer (nlbufsiz parameter of
               the ipt_ULOG netfilter module). Please note that there is a max‐
               imum  limit  in  /proc/sys/net/core/rmem_max  which  you  cannot
               exceed by increasing the rmem parameter. You may need  to  raise
               the system-wide maximum limit before.  You can define this vari‐
               able in kilobytes (suffix it by ’K’) or in  megabytes  (use  ’M’
               suffix).
 
        bufsize
               Receive  buffer for netlink packets. This should be at least the
               size rmem option has. Like rmem can be suffixed by ’M’ or ’K’.
 
        grouping
               That option sets grouping strategy. Every block which name is  a
               number  within  range  1  to SPECTER_GROUPS_MAX (default 32, use
               --with-group-max build option to change it), will be treaten  as
               a  separate  execution  block.  Setting grouping to netlink will
               cause interpreting these blocks as netlink  groups  (as  defined
               with  --ulog-nlgroup  iptables  ULOG target option). When nfmark
               value is used, groups will be compared to mark field in  netfil‐
               ter packet (see iptables(8) for more details on MARK module). If
               you find it a bit complicated, check examples section.
 
        nlgroup
               Will set netlink group to listen to. Can’t be used with grouping
               set to netlink, as several nlgroups are used in that case.
        plugins  block structure is very simple. In each line symbolic name and
        path to plugin binary have to be provided, like in a example:
 
                    BASE /lib/specter/specter_BASE.so
 
        Name can be anything you want, but it’s probably the  most  informative
        to  set  it to plugin’s name. You should then use this name as sections
        names.
 
        Please note that setting paths doesn’t mean corresponding plugins  will
        be loaded. You have to use them in blocks in order to force their load.
        That mean you can list all plugins you have compiled and  select  which
        to use by configuring execute blocks adequately.
        This  plugin  executes  specified  command  when packet is received. By
        proper use of its functions you can dynamically  change  your  firewall
        configuration, or even set up simple port-knocking utility.
 
        command
               That  option  defines  a  command that should be executed. Don’t
               rely on your $PATH environment variable, and provide  full  path
               to an executable.  Few printf-like macros can be used, which are
               expanded during parsing of every packet:
 
                    %I   interface packet got received from
                    %O   interface packet is going to be sent to
                    %S   IP address of source host
                    %D   IP address of destination host
                    %P   IP protocol number (see /etc/protocols)
                    %s   TCP/UDP source port
                    %d   TCP/UDP destination port
                    %i   ICMP type value
 
               If you want to use literal ’%’ in command, write it double ’%%’.
 
        force  When  a  macros expansion is being done, and any field is empty,
               executing of a given command is aborted.  For  example,  if  you
               have  %i  in your command and specter gets a tcp packet, command
               won’t be executed, ’cos given macro cannot be expanded  (there’s
               no  ICMP  type  field  in  a  TCP packet). You can override this
               behavior by setting force option. Instead of bogus data,  string
               "invalid"  will  be  placed.  It’s up to executed application to
               work with that.
 
        wait   If this options is set, daemon will wait until application  ter‐
               minates.   It’s  probably not a good idea to actually use it. If
               you definitely need it, do  it  with  caution,  because  it  can
               freeze the whole daemon.
 
        environment
               If  set, child will inherit specter’s environment. In other case
               child be be run in empty environment.
        LOGEMU emulates iptables LOG target.
 
        logfile
               Path to a file, where plugin  should  log  caught  packets.  The
               default is /var/log/specter.logemu.
 
        sync   Define this option if you want to have your logfile written syn‐
               chronously. This may reduce  performance,  but  makes  your  log
               lines appear immediately.
 
        tcp_options
               Works  the  same  way as ipt_LOG --log-tcp-options parameter. It
               enables logging of tcp options.
 
        ip_options
               Log options from  IP  packet  header  (equivalent  to  --log-ip-
               options from ipt_LOG target).
 
        tcp_seq
               Enable logging of tcp sequence numbers.
 
        mac_header
               Log MAC values of incoming packets.
        This  plugin insert info into a MySQL database. Amount and type of data
        is forced by table layout (see specter docs for more info).
 
        db     Name of the mysql database.
 
        table  Name of the table to which specter should log.
 
        host   Name of the mysql database  host.  If  it’s  localhost,  specter
               first tries to connect to local host by unix socket if possible.
 
        port   Server port number for the tcp/ip connection.
 
        user   Name of the mysql user, if ommited, the current user is assumed.
 
        pass   Password for mysql.
 
        buffsize
               Size  of  a  query buffer. You should set it only in a situation
               when you see "SQL buffer too small. Insert aborted." messages in
               your  logs.  Never try to lower this value below default, unless
               you really know what you’re doing.
 
        ssl_enable
               If this boolean option is set, MYSQL plugin will use SSL  during
               connection to database.
 
        ssl_key
               Pathname to the key file.
 
        ssl_cert
               Pathname to the certificate file.
 
        ssl_ca Pathname to the certificate authority file.
 
        ssl_capath
               Pathname  to  a  directory that contains trusted SSL CA certifi‐
               cates in pem format.
 
        ssl_cipher
               List of allowable ciphers to use for SSL encryption.
        Plugin useful during debugging, simply drops all  info  gathered  about
        current packet.
 
        logfile
               The  filename  where  it  should  drop  the data. The default is
               /var/log/specter.oprint.
        Plugin used to generate libpcap-style packet logfiles. This can be use‐
        ful for later analyzing the packet log with tools like tcpdump or ethe‐
        real.
 
        logfile
               The  filename  where  it  should  log  to.    The   default   is
               /var/log/specter.pcap.
 
        sync   Set  this  option  if you want to have your pcap logfile written
               synchronously. This may reduce performance, but makes your pack‐
               ets appear immediately in the file on disk.
        This  plugin insert info into a PostgreSQL database. Amount and type of
        data is forced by table layout (see specter docs for more info).
 
        db     Name of the postgresql database.
 
        table  Name of the table to which specter should log.
 
        host   Name of the postgresql database host.  When  undefined,  specter
               try to connect to local database by unix socket.
 
        port   Server  port  number  for  the tcp/ip connection, or socket file
               name extension for Unix-domain connections.
 
        user   Name of the postgresql user, if ommited,  the  current  user  is
               assumed.
 
        pass   Password for postgresql.
 
        buffsize
               Size  of  a  query buffer. You should set it only in a situation
               when you see "SQL buffer too small. Insert aborted." messages in
               your  logs.  Never try to lower this value below default, unless
               you really know what you’re doing.
 
        ssl_enable
               If this boolean option is set, PGSQL plugin will use SSL  during
               connection to database.
        This plugin behaves much like LOGEMU, but logs its input into syslog.
 
        facility
               Facility  a  message should be logged with. See syslog(3) manual
               page.  specter accepts  following  facilities:  daemon,  kernel,
               user, and localx from 0 to 7.
 
        level  Importance of a message. All standard syslog levels are allowed:
               emerg, alert, crit, err, warning, notice, info, debug.
 
        tcp_options
               Works the same way as ipt_LOG  --log-tcp-options  parameter.  It
               enables logging of tcp options.
 
        ip_options
               Log  options  from  IP  packet  header  (equivalent to --log-ip-
               options from ipt_LOG target).
 
        tcp_seq
               Enable logging of tcp sequence numbers.
 
        mac_header
               Log MAC values of incoming packets.
 

EXAMPLES

    Example 1
        Say, you just want to log non-related tcp and udp packets  in  separate
        files. You must first set up your netfilter:
 
                    # iptables -A INPUT -p tcp -m state --state INVALID -j ULOG --ulog-nlgroup 1
                    # iptables -A INPUT -p udp -m state --state INVALID -j ULOG --ulog-nlgroup 2
 
        And now use this specter configuration:
 
                    plugins {
                         BASE      /lib/specter/specter_BASE.so
                         LOCAL     /lib/specter/specter_LOCAL.so
                         LOGEMU    /lib/specter/specter_LOGEMU.so
                    }
 
                    1 {
                         :BASE
                         :LOCAL
                         :LOGEMU
                         logfile /var/log/specter.tcp
                    }
 
                    2 {
                         :BASE
                         :LOCAL
                         :LOGEMU
                         logfile /var/log/specter.udp
                    }
 
    Example 2
        Maybe  you  want  to  analyze every packet that passes your HTTP server
        with a application that uses pcap-style files? Prepare you firewall:
 
                    # iptables -A INPUT -p tcp --dport 80 -j ULOG --ulog-nlgroup 5
                    # iptables -A OUTPUT -p tcp --sport 80 -j ULOG --ulog-nlgroup 5
 
        Then use this configuration, so all http traffic will  be  saved  in  a
        /var/log/specter.http.  But you expect some attacks and want packets to
        appear immediately in log, so you use sync option as well.
 
                    plugins {
                         BASE    /lib/specter/specter_BASE.so
                         PCAP    /lib/specter/specter_PCAP.so
                    }
 
                    5 {
                         :BASE
                         :PCAP
                         file /var/log/specter.http
                         sync
                    }
 
    Example 3
        You’re very paranoid and want to save all IPs that tried to ping you in
        a  database,  yes? Logging tcp requests are also in you concern, right?
        Moreover, you don’t want to occupy more than one netlink group, so  you
        decide to use mark module to divide packets into groups. Try these ipt‐
        ables rules:
 
                    # iptables -t mangle -A INPUT -p icmp --icmp-type echo-request -j MARK --set-mark 13
                    # iptables -t mangle -A INPUT -p tcp -m state --state NEW -j MARK --set-mark 15
                    # iptables -A INPUT -m mark --mark 13 -j ULOG --ulog-nlgroup 1
                    # iptables -A INPUT -m mark --mark 15 -j ULOG --ulog-nlgroup 1
 
        This config will do the rest:
 
                    global {
                         grouping nfmark
                         nlgroup 1
                    }
 
                    plugins {
                         BASE     /lib/specter/specter_BASE.so
                         MYSQL    /lib/specter/specter_MYSQL.so
                    }
 
                    13 {
                         :BASE
                         :MYSQL
                         db mydb
                         host localhost
                         user username
                         pass password
                         table pings
                    }
 
                    15 {
                         :BASE
                         :MYSQL
                         db mydb
                         host localhost
                         user username
                         pass password
                         table tcp_requests
                    }
 
    Example 4
        You don’t like fragmented packets? You can  automaticaly  block  anyone
        who ever send you fragmented tcp packet. Use this single iptables rule:
 
                    # iptables -A INPUT -p tcp -f -j ULOG --ulog-nlgroup 1
 
        Now use this config to dynamically change your netfilter  configuration
        with the use of EXEC plugin:
 
                    plugins {
                         EXEC /lib/specter/specter_EXEC.so
                    }
 
                    1 {
                         :EXEC
                         command "/usr/sbin/iptables -A INPUT -p tcp -s %S --sport %s -j DROP"
                    }
        specter(8), iptables(8).
 

AUTHOR

        This  manual  page  was  written by Michal Kwiatkowski <ruby@joker.lin‐
        uxstuff.pl>.