SnortSam Conf Readme

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