From 3625d9eae740d3e55c8f16aa54dd4cf95f8c5990 Mon Sep 17 00:00:00 2001 From: Tom Eastep Date: Fri, 12 Jul 2013 17:08:58 -0700 Subject: [PATCH] Mention /proc/net/xt_recent/* in the Events document Signed-off-by: Tom Eastep --- docs/Events.xml | 4 + docs/Events1.xml | 592 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 596 insertions(+) create mode 100644 docs/Events1.xml diff --git a/docs/Events.xml b/docs/Events.xml index 41c4cf8d3..8cd2f21ec 100644 --- a/docs/Events.xml +++ b/docs/Events.xml @@ -457,6 +457,10 @@ root@gateway:/usr/src/linux-source-3.2/net/netfilter# but the system where this example was captured used the default value of the ip_pkt_list_tot xt_recent option (20). + + The output of these commands is produced by processing the + contents of /proc/net/xt_recent/*. You can access + those files directly to see the raw data. diff --git a/docs/Events1.xml b/docs/Events1.xml new file mode 100644 index 000000000..5e5f7da46 --- /dev/null +++ b/docs/Events1.xml @@ -0,0 +1,592 @@ + + +
+ + + + 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. + + + + + Events are based on the Netfilter 'recent match' capability which is + required for their use. + + The recent-match kernel component is xt_recent which has two options + that are of interest to Shorewall users: + + + + ip_list_tot + + + The number of addresses remembered per event. Default is + 100. + + + + + ip_pkt_list_tot + + + The number of packets (event occurrences) remembered per + address. Default is 20. + + + + + These may be changed with the xt_recent module is loaded or on the + kernel bootloader runline. +
+ +
+ 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. + + + +
+ +
+ 'show event' and 'show events' Commands + + The CLI programs (/sbin/shorewall, + /sbin/shorewall-lite, etc.) support show + event and show events commands. + + The show event command shows the contents of + the events listed in the command while show + events lists the contents of all events. + + root@gateway:/usr/src/linux-source-3.2/net/netfilter# shorewall show events +Shorewall 4.5.19-Beta2 events at gateway - Fri Jul 12 15:57:20 PDT 2013 + +SSH + src=125.46.13.163 : 3453 + src=200.59.55.50 : 3900 3900 + src=65.182.111.112 : 2946 + +SSH_COUNTER + +sticky001 + src=172.20.1.146 : 8 8 8 8 8 8 8 8 8 8 8 8 8 8 7 7 7 7 7 7 + +sticky002 + src=172.20.1.213 : 53 49 49 49 49 49 49 49 49 49 49 49 49 49 49 49 49 49 46 46 + +root@gateway:/usr/src/linux-source-3.2/net/netfilter# + + The SSH and SSH_COUNTER events are created using the following + Automatic Blacklisting example. The sticky001 and sticky002 events are + created by the SAME rule action. + + Each line represents one event. The list of numbers following the + ':' represent the number of seconds ago that a matching packet triggered + the event. The numbers are in chronological sequence, so In this event, + there were 20 packets from 172.20.1.213 that arrived between 53 and 46 + seconds ago: + + sticky002 + src=172.20.1.213 : 53 49 49 49 49 49 49 49 49 49 49 49 49 49 49 49 49 49 46 46 + + Note that there may have been earlier packets that also matched, + but the system where this example was captured used the default value of + the ip_pkt_list_tot xt_recent option + (20). + + The output of these commands is produced by processing the + contents of /proc/net/xt_recent/*. You can access + those files directly to see the raw data. Additional about these files + may be found in iptables (8). +
+
+ +
+ 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 +
+
+