- SnortSam Conf Readme
- SnortSam specific options:
- defaultkey {key}
- port {port}
- accept {host}/{mask},{key}
- keyinterval {time}
- dontblock {host}/{mask}
- override {host}/{mask},{time}
- upperlimit {host}/{mask},{time}
- limit {host}/{mask},{time}
- lowerlimit {host}/{mask},{time}
- atleast {host}/{mask},{time}
- denysidfrom {host}/{mask}: {sid},{sid},...
- allowsidfrom {host}/{mask}: {sid},{sid},...
- rollbackhosts {amount}
- rollbackthreshold {amount} / {time}
- rollbacksleeptime {time}
- skipinterval {time}
- skiphosts {amount}
- logfile {filename}
- loglevel {level}
- screenlevel {level}
- include {file}
- statefile {filename}
- avoidstatefile
- disablereverselookups
- disablepersistentconnections
- enablepersistentconnections
- enablepersistenttcp
- disableseqnocheck
- holdsnort
- fwsamipflip
- nothreads
- forcethreads
- daemon
- bindip
- Firewall specific options:
This is a summary of configuration options in the
SnortSam configuration file.
On Windows systems it is called snortsam.cfg by default and is located in the
same directory where
SnortSam.exe resides. On Unix systems, the default is
/etc/snortsam.conf.
The config file is a text file containing one or more of the following lines.
SnortSam specific options:
# a remark
Lines starting with # or ; are remarks. All text after # (or

is
truncated which means that you can list an # after a valid option as well.
If you intend to use a # (or

as part of an option, you have to escape it
with a back-slash, for example:
{option} This is a \# valid char # But this is a comment
This would translate after parsing to:
{option} This is a # valid char
defaultkey {key}
Set's the default key for ALL allowed hosts to {key}.
The default key is used when no other key is specified in an ACCEPT option.
You have to use the same key in the snort.conf file in the
"output alert_fwsam line". If the keys, or passwords if you will, don't
match,
SnortSam can not decrypt the request from Snort and ignore it.
Example: defaultkey mydefaultpassword
If omitted,
SnortSam will use a default key (in which case it would have to
omitted in snort.conf as well).
port {port}
This sets the listening port to {port}.
Example: port 666
It defaults to 898 if this line is omitted.
accept {host}/{mask},{key}
This option lists Snort sensors that
SnortSam is accepting packets from.
You can specify hostname, IP address, IP address and network mask, and
optionally an encryption key used configured for that host or network.
Examples: accept 10.10.0.0/16, officepassword
accept snort1, hostpassword
accept 192.168.1.1
If the password is omitted, the default key specified with DEFAULTKEY will
be used. You can only specify one host per line, but you can supply
unlimited lines.
keyinterval {time}
This causes the agent to request/create a new encryption key every {time}.
If this line is omitted, the key lifetime defaults to 4 hours. You can use
'hours', 'days', 'months', 'weeks', 'years' in the duration.
Example: keyinterval 30 minutes
dontblock {host}/{mask}
This adds the host or network to the white-list of hosts/networks that will
never be blocked. Blocking request for hosts on this list are ignored.
Examples: dontblock a.root-servers.net
dontblock 192.168.10.0/24
Only one host/network per line can be specified, but you can list unlimited
lines
override {host}/{mask},{time}
Each Snort rule requests its own time interval for the blocking request.
Here on the agent, you can override the duration with a specified value.
This is good for proxy servers, or other situations, where an attacker
'shares' an IP address with other hosts/users that you don't want to
block for long. (You don't want to block ALL of AOL for a week...
Examples: override proxy.aol.com, 5 min
override 192.168.1.0/24, 10 sec
upperlimit {host}/{mask},{time}
limit {host}/{mask},{time}
This statement allows you to set a maximum time duration for all SID/blocks
dependent on the reporting sensor. It acts like 'override', but instead of
setting a new duration, this statement limits the duration to the defined
maximum blocktime. Note that the host/network refers to a Snort sensor
(or a forwarding Snortsam station) and does not refer to the IP address to
be blocked like 'override' does.
Example: limit 192.168.1.0/24, 2 weeks
lowerlimit {host}/{mask},{time}
atleast {host}/{mask},{time}
This statement allows you to set a minimum time duration for all SID/blocks
dependent on the reporting sensor. It is the complement to 'limit', but
instead of reducing the duration to a maximum limit, it bumps up any
duration that is lower to this minimum duration.
Example: limit 192.168.1.0/24, 1 day
denysidfrom {host}/{mask}: {sid},{sid},...
This statement causes Snortsam to ignore blocking requests for particular
SID based on a given sensor. Either a single SID or multiple SIDs can be
listed. When listing multiple SIDs, make sure you separate them with commas
and not just spaces.
Examples: denysidfrom 192.168.1.0/24: 1345
denysidfrom othersnortsam.someone.net: 1411, 1422, 0, 2002123
(Note the use of SID 0 which is typically used for manual blocks/unblocks
when no SID is specified, for example, on the command line when using the
samtool.)
allowsidfrom {host}/{mask}: {sid},{sid},...
This statement is the invert of 'denysidfrom'. It will cause Snortsam to
only accept the SIDs listed and by default ignore all other SIDs.
If a conflict exist by the same SID appearing in an 'allowsidfrom' line and
a 'denysidfrom' line, the deny takes priority.
Example: allowsidfrom 10.0.0.0/8: 3200, 3201, 3203, 4332, 4333, 4334
rollbackhosts {amount}
This tells
SnortSam to keep a record of {amount} last blocks for each
Snort sensor. These blocks will be rolled back, meaning the hosts
unblocked, in the event that the blocking threshold is exceeded.
Example: rollbackhosts 50
If omitted,
SnortSam will not keep a record of the IP addresses that have
been blocked for rollback purposes.
rollbackthreshold {amount} / {time}
This specifies the blocking threshold. If the threshold is exceeded (more
than {amount} blocking requests in {time}),
SnortSam will unblock the last
{x} hosts specified by the ROLLBACKHOSTS statement.
Example: rollbackthreshold 20 / 30 secs
rollbacksleeptime {time}
When the rollback threshold has been exceeded,
SnortSam will ignore
blocking requests until the level drops back below the threshold. Using
this option you can specify an additional time period that
SnortSam will
wait until it starts acting on blocking requests again.
Example: rollbacksleeptime 1 minute
If omitted, and the rollback mechanism is used, it defaults to 15 minutes.
skipinterval {time}
SnortSam skips repetitive, identical blocking requests (for performance
reasons). Here you specify the time interval for which blocks are
considered repetitive.
Example: skipinterval 30 secs
If omitted,
SnortSam will use a default time period of 10 seconds in which
it considers requests to be repetitive.
skiphosts {amount}
Tells
SnortSam how many hosts it should remember for repetitive block
checks.
Example: skiphosts 10
If omitted,
SnortSam will remember a default of 10 hosts.
logfile {filename}
SnortSam will use this file to log certain events such as program start,
block/unblock actions performed and error events. If only a file name is
specified (without a path), the file will be created a) on Windows systems
in the same directory where
SnortSam.exe resides, and b) on Unix systems
in /var/log.
Example: logfile snortsam.log
No logging occurs if this line is omitted.
loglevel {level}
The file logging level can be set to 0, 1, 2, or 3:
0: Quiet - No logging occurs.
1: Sparse - Only errors are logged.
2: Normal - Errors and blocks are logged.
3: Verbose - Additional information (such as connections/disconnections)
are logged as well.
Example: loglevel 2
If omitted, a level of 2 (normal logging) is assumed.
screenlevel {level}
The logging level, just like loglevel, but for screen output.
(See above for values)
Example: screenlevel 3
If omitted, a level of 2 (normal logging) is assumed.
include {file}
This statement includes another configuration file. Only one level of
inclusion is supported.
Example: include dontblocklist.cfg
statefile {filename}
SnortSam will use this file name for the state file instead of the default.
This avoids conflicts on hosts with mutliple Snortsam instances.
The default of /var/db/snortsam.state (or snortsam.sta on Windows) is used
if this line is omitted.
Example: statefile /var/db/2nd-snortsam.state
avoidstatefile
Starting with version 2.8,
SnortSam will always keep a state file so the
additions to dontblock-list can be checked against current blocks (and
unblocked automatically if a host is on the DONTBLOCK list, but had been
blocked before). If you are using
SnortSam only to block on Checkpoint
firewalls, you could avoid the state file since FW-1 will time-out blocks
by itself. To do that, just use this statement in the config file.
Example: avoidstatefile
Note that if you load a plugin that requires
SnortSam to unblock the
blocks, and thus requires the state file, it will be created regardless if
this option is present.
disablereverselookups
This option turns off reverse name resolution in logging plugins, currently
only used by the email plugin.
Example: disablereverselookups
disablepersistentconnections
disablepersistenttcp
This option turns off persistent TCP connections for the FORWARD plugin as
introduced with version 2.51. It also does not use persistent connections
for connecting hosts like the Snort plugin, a remote forwarder, or the
samtool. In essence, Snortsam will behave like pre-2.51 versions.
The default is now to leave persistent-TCP disabled. See also below.
Example: disablepersistentconnections
enablepersistentconnections
enablepersistenttcp
This option turns on persistent TCP connections for the FORWARD plugin as
introduced with version 2.51. It also accepts persistent connections from
connecting hosts like the Snort plugin, a remote forwarder, or the samtool.
In essence, Snortsam will behave like pre-2.51 versions.
By default, persistens TCP connections are disabled now, and you need this
option to forcefully enable it. Beware, persistent TCP connections are
still experimental and may cause problems.
Example: enablepersistentconnections
disableseqnocheck
This option turns off sequence number checking in
SnortSam.
SeqNo?
violations are currently not punished (by banning the offending Snort
sensor), but it was planned to do so in the future to increase security.
Use this option to turn packet sequence number checking off.
Example: disableseqnocheck
holdsnort
This option requires version 1.13 or higher of the Snort plugin. It places
Snort 'on hold' during processing of the blocking request, and resumes
Snort once the block is completed.
Example: holdsnort
THIS WILL SLOW SNORT DOWN! USE ONLY FOR TESTING OR IN CONJUNCTION WITH
BARNYARD!
fwsamipflip
The fwsam method should block the correct IP address if
SnortSam is run on
the firewall host itself. However, if
SnortSam runs on a small-endian box,
and FW-1 runs on a big-endian box, it may block the reversed IP address.
Use this option to flip it back to normal.
Example: fwsamipflip
nothreads
This option disables the multi-threading capability and causes
SnortSam
not to use thread functions at all. Instead, all plugins are executed
sequentially within the main process. This makes
SnortSam behave like the
old, single-threaded version 1. It is useful for testing, or if you
encounter problems with plugins that have problems with POSIX threads.
Example: nothreads
forcethreads
This option forces use of multi-threading capability on systems that have
it disabled by default, which currently is all Linux versions.
Example: forcethreads
daemon
This option causes Snortsam to turn into a daemon upon startup. It is
similar to the -D option of many other tools and services.
Example: daemon
bindip
This option causes Snortsam to bind only to one IP address (or interface)
instead of listening on all interfaces/addresses.
Example: bindip 192.168.0.1
Firewall specific options:
fwexec {path/fw.exe}
If specified,
SnortSam will call the fw.exe executable to create the blocks
on Firewall-1. Normally you would use either 'fwsam' or 'opsec' (see
below). This line is useful if there are problems with OPSEC or you don't
want to send packets to the firewall.
SnortSam will have to run on the
FW-1 host of course.
Example: fwexec c:\winnt\fw\bin\fw.exe
fwsam {host}
This statement tells
SnortSam to use the self-assembled OPSEC packet to
initiate blocks. You have to specify the name or IP address of the
firewall to which to send the block. You can only list one IP address per
line, but supply unlimited lines (one for each firewall you have).
Examples: fwsam 127.0.0.1
fwsam wanfw.corp.com
opsec {file}
This statement tells
SnortSam to use the OPSEC API functions of the OPSEC
plug-in, configured through the {file} config file (opsec.conf is available
as an example. Also see README.opsec). Use this instead of fwsam for use of
the official OPSEC API. You can add more than one config to allow more than
one firewall to execute the block (each firewall would need its own conf
file). Currently, only clear-text is supported, but you may have luck with
auth_port or SSL. If so, please let me know.
- Examples
- opsec opsec.conf opsec wan_firewall.conf
In opsec.conf, or whatever your file is named, change the IP of the server
to reflect your firewalls IP (or leave at 127.0.0.1 if you run
SnortSam on
the firewall itself).
NOTE TO ABOVE METHODS:
If you are blocking on Checkpoint Firewall-1, use ONE OF THE THREE METHODS
listed above. You don't have to specify them all. It is your choice which
method to use (although I personally recommend fwsam).
pix {ip} {telnetpw} {enablepw}
pix {ip} {username}/{password} {enablepw}
This statement tells
SnortSam to use the PIX plugin.
SnortSam will telnet
into the PIX at address {ip}, log in with the given telnet and enable
password, and use the SHUN command to block IP addresses. If the second
parameter contains a /,
SnortSam will use the word before the / as the
username and the remainder as the user password. This is useful when a PIX
has been configured to use RADIUS or TACACS for login authentication.
Examples: pix 1.2.3.4 letmein enableme
If the enable password is omitted, the telnet password will be used at the
telnet and enable prompt.
ciscoacl {ip} {telnetpw} {enablepw} {acl_filename}
ciscoacl {ip} {username}/{password} {enablepw} {acl_filename}
This statement tells
SnortSam to use the Cisco ACL plugin to block IP's on
a Cisco router.
SnortSam will telnet into router at address {ip}, log in
with the {telnetpw} as the password at the telnet prompt, or use
{username} and {password} if TACACS is used for authentication, and modify
the Access Control List. You need to supply your baseline configuration
file {acl_filename} in the configuration line.
SnortSam will insert ACL
statements so that access from and to the intruding IP address is denied,
and upload the config to the router.
Example: ciscoacl 1.2.3.4 telnetpw enablepw myconfig
If the router is configured to authenticate access with TACACS, you would
use:
ciscoacl 1.2.3.4 user/password enablepw myconfig
cisconullroute {ip} {telnetpw} {enablepw}
cisconullroute {ip} {username}/{password} {enablepw}
This statement tells
SnortSam to use the Cisco Null-Route plugin to block
IP's on a Cisco router.
SnortSam will telnet into router at address {ip},
log in with the {telnetpw} as the password at the telnet prompt, or use
{username} and {password} if TACACS is used for authentication, and issue
a route command that will "null-route" the IP to be blocked. It will then
save the configuration to memory. Once the block has expired, Snortsam
again log in and remove the added route, saving the config to memory.
Example: cisconullroute 1.2.3.4 telnetpw enablepw
If the router is configured to authenticate access with TACACS, you would
use:
cisconullroute 1.2.3.4 user/password enablepw
email {smtpserver}:{port} {recipient} {sender}
This statement sends an email for every block and unblock event. You
specify your SMTP server by name or IP address, and the email address you
want to send the notification to. Only one recipient per line is supported,
more than one line be be specified. By default,
SnortSam will send the
email from
SnortSam@{hostname}, but you can override the sender by adding
a specific sender after the recipient. Also, you can optionally specify
a custom port in case you run SMTP on a different port. (Default is 25)
Example: email mailserver.mydom.com
root@mydom.com
email 127.0.0.1
admin@mydom.com SnortSam@mydom.com
email localhost:10025
ops@mydom.com
email-blocks-only {smtpserver}:{port} {recipient} {sender}
This statement is the same as "email" except that it only sends emails for
block events, not unblock events. This was easier to implement as a plugin
since "email" requires the creation of a state file while
"email-blocks-only" does not (see also "avoidstatefile").
Example: email mailserver.mydom.com
root@mydom.com
netscreen {ip} {login id} {login password} {optional groupname} {opt zone name}
This statement will activate the Netscreen plugin. It is similar to the PIX
plugin in that is telnets into the firewall, but instead of issuing a shun
command (which the Netscreen doesn't have), it adds the IP to be blocked to
a group which you can use for a global 'deny' rule. For more info, please
see README.netscreen.
Example: netscreen 10.0.0.1 admin mypassword
MyBlockGroup? MyZone?
If the group name is omitted,
SnortSam will add/remove IP's to/from the
default group called 'SnortSam'.
Also, one can override the default zone name with a custom zone name. The
MyZone? parameter is optional. If used, a block group name must also be
specified.
ipf {adapter} {loglevel}
This plugin will execute the command ipf locally and block the host by
adding a rule to the ipf policy. You have to specify the adapter to block
on (for example, fxp0) and you can optionally add a logging facility
(default is local7.info).
Example: ipf ep0 local7.info
pf {adapter} {logoption}
This plugin will use an ioctl syscall to control the pf device in order to
block the host by adding a rule to the active rule set of pf. You have to
specify the adapter to block on (for example, fxp0) and you can optionally
add a log option (log, logall).
Example: pf dc0 log
ipchains {adapter} {logoption}
This plugin will use an setsockopt call to control the ipchains options
in order to block the host by adding a rule to the active rule set.
You have to specify the adapter to block on (for example, eth0) and you can
optionally add a log option (log, logall).
Example: ipchains eth0 log
iptables {adapter} {logoption}
This plugin will call the iptables executable in order to block the host by
adding a rule to the active rule set. You have to specify the adapter to
block on (for example, eth0) and you can optionally add a log option.
Example: iptables eth0 syslog.info
ebtables {adapter} {logoption}
This plugin will call the ebtables executable in order to block the host by
adding a rule to the active rule set. You have to specify the adapter to
block on (for example, eth0) and you can optionally add a log option.
Example: ebtables eth0 syslog.info
watchguard {path/to/fbidsmate} {ip-of-firebox} {configpassword}
watchguard {path/to/fbidsmate} {ip-of-firebox} file {configpassfile}
This plugin will call the fbidsmate program to block the host on Watchguard
firewalls. You have to specify the path to the fbidsmate program, the
IP address of the firewall, and either a clear-text password, or the name
of a file containing the encrypted password. For more information, please
see the README.wgrd file.
Examples: watchguard /bin/fbidsmate 10.1.0.1 mySecretPass
watchguard /bin/fbidsmate 10.1.0.1 file /etc/fbidsmate.passphrase
8signs {path/dfw.exe} {tarpit}
SnortSam will call the specified dfw.exe executable to create the block
on the 8signs firewall. Snortsam will always block IPs without expiration
(-expiry n) because the 8signs firewall can only block for a day, a week,
or permanently. Snortsam blocks permanently and then times-out the blocks
itself, issuing an unban of the IP to 8signs, so that normal time
intervals are possible (for example, 10 minute blocks).
Optionally, the word "tarpit" can be appended to cause 8signs to ban and
tarpit the IP address.
Examples:
8signs c:\progra~1\8signs~1\dfw.exe
8signs c:\progra~1\8signs~1\dfw.exe tarpit
isa {log}
SnortSam will use the API in msfpccom.dll to control the Microsoft ISA
Server interface in order to add blocking rules to the ISA firewall
rules.
Optionally, the word "log" can be appended to cause ISA Server to log
connection attempts from the blocked IP address.
Examples: isa
isa log
chx-i {path/fltcon.exe} {log}
SnortSam will call the specified fltcon.exe executable (or just fltcon if
none is specified, in which case fltcon would need to be in the PATH) to
create the block on the CHX-I packet filter. Snortsam can only block, and
can not forcefully unblock IP addresses. In order to frocefully remove
a blocked host, just restart the CHX-I service and all blocked IP addresses
are released.
Optionally, the word "log" can be appended to cause CHX-I to log blocked
packets.
Examples: chx-i c:\somewhere\fltcon.exe
chx-i fltcon.exe log
ipfw2 {adapter} {inbound-table} {outbound-table}
This plugin will add/remove IP addresses to be blocked/unblocked into the
corresponding table(s). Tables are a new feature of ipfw2. You have to set
up these tables manually before starting Snortsam exactly like this:
deny ip from any to table({inbound-table}) via {adapter}
and: deny ip from table({outbound-table}) to any via {adapter}
If these tables are not present in your ipfw2 rule set, Snortsam will not
start and report an error. With the tables present, configure Snortsam
accordingly.
Example: ipfw2 ep0 1 2
With tables rules like:
00010 deny ip from any to table(1) via ep0
00011 deny ip from table(2) to any via ep0
forward {snortsam-ip}:{port}/{password}
This plugin will forward a block/unblock request to another Snortsam agent
running on this or another host. This allows you link Snortsams in a chain,
providing for a completely distributed blocking infrastructure. You can
configure two Snortsam agents to forward to each other. The loop is avoided
by the repetitive block prevention. IF YOU DISABLE REPETITIVE BLOCK
SETTINGS, YOU WILL CREATE AN ENDLESS LOOP CAUSING RESOURCE EXHAUSTION OR
STARVATION OR A DENIAL-OF-SERVICE CONDITION!
Take note that any white-list or override lists are processed before the
request is forwarded. The planned "passthrough" problem will avoid this
limitation in the future. It is recommended to create separate Snortsam
instances for "distribution hubs" which don't have white-list or override
restrictions.
Example: forward secondsnortsam.domain.net
forward other-snortsam.mynet.com/otherpass
forward 127.0.0.1:890
--
MattJonkman - 09 Mar 2007