Shorewall Events Tom Eastep 2013 Thomas M. Eastep Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover, and with no Back-Cover Texts. A copy of the license is included in the section entitled GNU Free Documentation License. This article applies to Shorewall 4.5.19 and later and supercedes this article.
Overview Shorewall events were introduced in Shorewall 4.5.19 and provide a high-level interface to the Netfilter recent match capability. An event is actually a list of (IP address, timestamp) pairs, and can be tested in a number of different ways: Has event E ever occurred for IP address A (is the IP address in the list)? Has event E occurred M or more times for IP address A? Has Event E occurred in the last N seconds for IP Address A (is there an entry for the address with a timestamp falling within the last N seconds)? Has Event E occurred M or more times in the last N seconds for IP address A (are there M or more entries for the address with timestamps falling within the last N seconds)? The event interface is implemented as three parameterized Shorewall Actions: SetEvent This action initializes an event list for either the source or destination IP address in the current packets. The list will contain a single entry for the address that will have the current timestamp. ResetEvent This action removes all entries for either the source or destination IP address from an event list. IfEvent This action tests an event in one of the ways listed above, and performs an action based on the result.
Details Because these are parameterized actions, optional parameters may be omitted. Trailing omitted parameters may be omitted entirely while embedded omitted parameters are represented by a hyphen ("-"). Each event is given a name. Event names: Must begin with a letter. May be composed of letters, digits, hyphens ('-') or underscores ('_'). May be at most 29 characters in length.
SetEvent SetEvent( event, [ action ], [ src-dst ], [ disposition ] ) event Name of the event. action An action to perform after the event is initialized. May be any action that may appear in the ACTION column of shorewall-rules (5). If no action is to be performed, use COUNT. src-dst Specifies whether the source IP address (src) or destination IP address (dst) is to be added to the event. The default is src. disposition If the action involves logging, then this parameter specifies the disposition that will appear in the log entry prefix. If no disposition is given, the log prefix is determines normally. The default is ACCEPT.
ResetEvent ResetEvent( event, [ action ], [ src-dst ], [ disposition ] ) event Name of the event. action An action to perform after the event is reset. May be any action that may appear in the ACTION column of shorewall-rules (5). If no action is to be performed, use COUNT. The default is ACCEPT. src-dst Specifies whether the source IP address (src) or destination IP address (dst) is to be removed from the event. The default is src. disposition If the action involves logging, then this parameter specifies the disposition that will appear in the log entry prefix. If no disposition is given, the log prefix is determines normally.
IfEvent IfEvent( event, [ action ], [ duration ], [ hitcount ], [ src-dst], [ command ], [ disposition ] ) event Name of the event. action An action to perform if the test succeeds. May be any action that may appear in the ACTION column of shorewall-rules (5). The default is ACCEPT. duration Number of seconds over which the event is to be tested. If not specified, the test is not constrained by time. hitcount Specifies the minimum number of packets required for the test to succeed. If not specified, 1 packet is assumed. src-dst Specifies whether the source IP address (src) or destination IP address (dst) is to be tested. The default is src. command May be one of the following: check Simply test if the duration/hitcount test is satisfied. If so, the action is performed. reset Like check. If the test succeeds, the event will be reset before the action is taken. update Like check. Regardless of whether the test succeeds, an entry with the current time and for the src-dst iP address will be added to the event. checkreap Requires a duration. Like check but regardless of whether the test succeeds, entries for the src-dst IP address that are older than duration seconds will be deleted from the event. updatereap Requires a duration. Like update but regardless of whether the test succeeds, entries for the src-dst IP address that are older than duration seconds will be deleted from the event. The default is check. disposition If the action involves logging, then this parameter specifies the disposition that will appear in the log entry prefix. If no disposition is given, the log prefix is determines normally.
Examples
Automatic Blacklisting This example is taken from this article which explains the nice benifits of this approach. This example is for ssh, but it can be adapted for any application. The name SSH has been changed to SSHLIMIT so as not to override the Shorewall macro of the same name. /etc/shorewall/actions: #ACTION OPTION DESCRIPTION SSHLIMIT #Automatically blacklist hosts who exceed SSH connection limits /etc/shorewall/action.SSH_BLACKLIST: # # Shorewall version 4 - SSH_BLACKLIST Action # ?format 2 ############################################################################### #TARGET SOURCE DEST PROTO DPORT SPORT # # Log the Reject # LOG:warn:REJECT # # And set the SSH_COUNTER event for the SOURCE IP address # SetEvent(SSH_COUNTER,REJECT,src) /etc/shorewall/action.SSHLIMIT: # # Shorewall version 4 - SSHLIMIT Action # ?format 2 ############################################################################### #TARGET SOURCE DEST PROTO DPORT SPORT # # Silently reject the client if blacklisted # IfEvent(SSH_COUNTER,REJECT,300,1) # # Blacklist if 5 attempts in the last minute # IfEvent(SSH,SSH_BLACKLIST,60,5,src,checkreap) # # Log and reject if the client has tried to connect # in the last two seconds # IfEvent(SSH,REJECT:warn:,2,1,-,update,Added) # # Un-blacklist the client # ResetEvent(SSH_COUNTER,LOG:warn,-,Removed) # # Set the 'SSH' EVENT and accept the connection # SetEvent(SSH,ACCEPT,src) etc/shorewall/rules: #ACTION SOURCE DEST PROTO DEST # PORT(S) SSHLIMIT net $FW tcp 22
Port Knocking This example shows a different implementation of the one shown in the Port Knocking article. In this example: Attempting to connect to port 1600 enables SSH access. Access is enabled for 60 seconds. Attempting to connect to port 1601 disables SSH access (note that in the article linked above, attempting to connect to port 1599 also disables access. This is an port scan defence as explained in the article). To implement that approach: /etc/shorewall/actions: #ACTION OPTION DESCRIPTION Knock #Port Knocking /etc/shorewall/action.Knock: # # Shorewall version 4 - SSH_BLACKLIST Action # ?format 2 ############################################################################### #ACTION SOURCE DEST PROTO DEST # PORT(S) IfEvent(SSH,ACCEPT:info,60,1,src,reset)\ - - tcp 22 SetEvent(SSH,ACCEPT) - - tcp 1600 ResetEvent(SSH,DROP:info) etc/shorewall/rules: #ACTION SOURCE DEST PROTO DEST # PORT(S) Knock net $FW tcp 22,1599-1601