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.
Every input plugin analyze incoming packet in special way and generate
appropriate keys, which then can be parsed or saved by output plugins.
You can check what keys are generated by each input plugin by looking at
plugin's source - somewhere on top there's a definition of
specter_iret_t array, which lists all of them. For example,
specter_BASE generates keys like raw.mac,
ip.protocol or icmp.type, among many others of course.
Note that not all keys will be set during packet parsing, these that
won't be set will remain empty. Different output plugins handle this
case differently, please read details in their documentation.
specter comes with the following input plugins:
Basic input plugin for nfmark, timestamp, mac address, ip header, tcp header, udp header, icmp header, ah/esp header... Most output plugins need this very important plugin.
Example input plugin to log plaintext passwords as used with FTP and POP3. Don't blame me for writing this plugin! The protocols are inherently insecure, and there are a lot of other tools for sniffing passwords... it's just an example.
This is a 'virtual interpreter'. It doesn't really return any information on the packet itself, rather the local system time and hostname. Please note that the time is the time at the time of logging, not the packets receive time.
This plugin divides http message into set of keys, like protocol version or User-Agent header value. Number of supported headers is high, check the sources for full list.
specter comes with the following output plugins:
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.
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:
interface packet got received from
interface packet is going to be sent to
IP address of source host
IP address of destination host
IP protocol number (see /etc/protocols)
TCP/UDP source port
TCP/UDP destination port
ICMP type value
If you want to use literal '%' in command, write it double '%%'. You can also
use shell-like stdin/stdout/stderr redirections. > or 1>
truncates file to zero length and redirects stdout to it. >>
or 1>> will append stdout stream to destination file. In the
same manner work 2> and 2>> redirections, except
that they apply to stderr. To redirect stdout and stderr to the same file,
use &> or &>>. Redirecting input is done
by < operator, of course.
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.
Deprecated. Specter should never hang on another process. This was a bad fix to prevent zombie processes. Now it's fixed and this option does nothing.
If set, child will inherit specter's environment. In other case child be be run in empty environment.
A very simple output module, dumping all packets in the format
===>PACKET BOUNDARY
key=value
key=value
...
===>PACKET BOUNDARY
...
The module defines the following configuration directives:
The filename where it should log to. The default is
/var/log/specter.oprint
An output module which tries to emulate the old syslog-based LOG targed as far as possible. Logging is done to a seperate textfile instead of syslog, though.
The module defines the following configuration directives:
The filename where it should log to. The default is /var/log/specter.logemu
Define this option if you want to have your logfile written synchronously. This may reduce performance, but makes your log-lines appear immediately.
Works the same way as ipt_LOG --log-tcp-options parameter. It enables logging of tcp options.
Log options from IP packet header (equivalent to --log-ip-options from ipt_LOG target).
Enable logging of tcp sequence numbers.
Log MAC values of incoming packets.
An output plugin for logging into a mysql database. This is only compiled if you have the mysql libraries installed, and the configure script was able to detect them. (that is: --with-mysql was specified for ./configure)
The plugin automagically inserts the data into the configured table. It connects to mysql during the startup phase of specter and obtains a list of the columns in the table. Then it tries to resolve the column names against keys of input plugins. This way you can easly select which information you want to log - just by the layout of the table.
If, for example, your table contains a field called 'ip_saddr', specter will resolve this against the key 'ip.saddr' and put the ip address as 32bit unsigned integer into the table.
You may want to have a look at the file 'doc/mysql.table' as an
example table including fields to log all keys from specter_BASE.so and
some from specter_HTTP.so. Just delete the fields you are not interested
in, and create the table.
The module defines the following configuration directives:
Name of the mysql database.
Name of the table to which specter should log.
Name of the mysql database host. If it's 'localhost' or undefined,
specter first tries to connect to local host by unix socket if possible.
Server port number for the tcp/ip connection.
Name of the mysql user, if ommited, the current user is assumed.
Password for mysql.
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.
If this boolean option is set, MYSQL plugin will use SSL during connection to database.
Pathname to the key file.
Pathname to the certificate file.
Pathname to the certificate authority file.
Pathname to a directory that contains trusted SSL CA certificates in pem format.
List of allowable ciphers to use for SSL encryption.
An output plugin for logging into a postgresql database. This is only compiled if you have the postresql libraries installed, and the configure script was able to detect them. (that is: --with-pgsql was specified for ./configure)
The plugin automagically inserts the data into the configured table; It connects to postgresql during the startup phase of specter and obtains a list of the columns in the table. Then it tries to resolve the column names against keys of input plugins. This way you can easly select which information you want to log - just by the layout of the table.
If, for example, your table contains a field called 'ip_saddr', specter will resolve this against the key 'ip.saddr' and put the ip address as 32bit unsigned integer into the table.
You may want to have a look at the file 'doc/pgsql.table' as an
example table including fields to log all keys from specter_BASE.so and
some from specter_HTTP.so. Just delete the fields you are not interested
in, and create the table.
The module defines the following configuration directives:
Name of the postgresql database.
Name of the table to which specter should log.
Name of the postgresql database host. When undefined, specter try to connect to local database by unix socket.
Server port number for the tcp/ip connection, or socket file name extension for Unix-domain connections.
Name of the postgresql user, if ommited, the current user is assumed.
Password for postgresql.
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.
If this boolean option is set, PGSQL plugin will use SSL during connection to database.
An output plugin that can be used to generate libpcap-style packet logfiles. This can be useful for later analysing the packet log with tools like tcpdump or ethereal.
The module defines the following configuration directives:
The filename where it should log to. The default is:
/var/log/specter.pcap
Set this option if you want to have your pcap logfile written synchronously. This may reduce performance, but makes your packets appear immediately in the file on disk.
This plugin behaves much like LOGEMU, but logs its input into syslog.
Two options are allowed:
Facility a message should be logged with. See syslog(3) manual page. specter accepts following facilities: deamon kernel, user, localx (where x is from 0 to 7).
Importance of a message. All standard syslog levels are allowed: emerg, alert, crit, err, warning, notice, info, debug.
Works the same way as ipt_LOG --log-tcp-options parameter. It enables logging of tcp options.
Log options from IP packet header (equivalent to --log-ip-options from ipt_LOG target).
Enable logging of tcp sequence numbers.
Log MAC values of incoming packets.