holm/shorewall_code
1
0
Fork 0
forked from extern/shorewall_code
Code Pull Requests Activity
765b748283
shorewall_code/docs/Events1.xml
Tom Eastep 3625d9eae7 Mention /proc/net/xt_recent/* in the Events document 
Signed-off-by: Tom Eastep <teastep@shorewall.net>
2013-07-12 17:08:58 -07:00

593 lines
20 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article>
<!--$Id$-->
<articleinfo>
<title>Shorewall Events</title>
<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Eastep</surname>
</author>
</authorgroup>
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright>
<year>2013</year>
<holder>Thomas M. Eastep</holder>
</copyright>
<legalnotice>
<para>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
<quote><ulink url="GnuCopyright.htm">GNU Free Documentation
License</ulink></quote>.</para>
</legalnotice>
</articleinfo>
<caution>
<para>This article applies to Shorewall 4.5.19 and later and supercedes
<ulink url="PortKnocking.html">this article.</ulink></para>
</caution>
<section>
<title>Overview</title>
<para>Shorewall events were introduced in Shorewall 4.5.19 and provide a
high-level interface to the Netfilter<firstterm> recent match</firstterm>
capability. An event is actually a list of (IP address, timestamp) pairs,
and can be tested in a number of different ways:</para>
<itemizedlist>
<listitem>
<para>Has event E ever occurred for IP address A (is the IP address in
the list)?</para>
</listitem>
<listitem>
<para>Has event E occurred M or more times for IP address A?</para>
</listitem>
<listitem>
<para>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)?</para>
</listitem>
<listitem>
<para>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)?</para>
</listitem>
</itemizedlist>
<para>The event interface is implemented as three parameterized Shorewall
<ulink url="Actions.html">Actions</ulink>:</para>
<variablelist>
<varlistentry>
<term>SetEvent</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ResetEvent</term>
<listitem>
<para>This action removes all entries for either the source or
destination IP address from an event list.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>IfEvent</term>
<listitem>
<para>This action tests an event in one of the ways listed above,
and performs an action based on the result.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Events are based on the Netfilter 'recent match' capability which is
required for their use.</para>
<para>The recent-match kernel component is xt_recent which has two options
that are of interest to Shorewall users:</para>
<variablelist>
<varlistentry>
<term>ip_list_tot</term>
<listitem>
<para>The number of addresses remembered per event. Default is
100.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ip_pkt_list_tot</term>
<listitem>
<para>The number of packets (event occurrences) remembered per
address. Default is 20.</para>
</listitem>
</varlistentry>
</variablelist>
<para>These may be changed with the xt_recent module is loaded or on the
kernel bootloader runline.</para>
</section>
<section>
<title>Details</title>
<para>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 ("-").</para>
<para>Each event is given a name. Event names:</para>
<itemizedlist>
<listitem>
<para>Must begin with a letter.</para>
</listitem>
<listitem>
<para>May be composed of letters, digits, hyphens ('-') or underscores
('_').</para>
</listitem>
<listitem>
<para>May be at most 29 characters in length.</para>
</listitem>
</itemizedlist>
<section>
<title>SetEvent</title>
<para><emphasis role="bold">SetEvent</emphasis>(
<replaceable>event</replaceable>, [ <replaceable>action</replaceable> ],
[ <replaceable>src-dst</replaceable> ], [
<replaceable>disposition</replaceable> ] )</para>
<variablelist>
<varlistentry>
<term>event</term>
<listitem>
<para>Name of the event.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>action</term>
<listitem>
<para>An action to perform after the event is initialized. May be
any action that may appear in the ACTION column of <ulink
url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5).
If no action is to be performed, use COUNT.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>src-dst</term>
<listitem>
<para>Specifies whether the source IP address (<emphasis
role="bold">src</emphasis>) or destination IP address (<emphasis
role="bold">dst</emphasis>) is to be added to the event. The
default is <emphasis role="bold">src</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>disposition</term>
<listitem>
<para>If the <replaceable>action</replaceable> involves logging,
then this parameter specifies the disposition that will appear in
the log entry prefix. If no <replaceable>disposition</replaceable>
is given, the log prefix is determines normally. The default is
ACCEPT.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>ResetEvent</title>
<para><emphasis role="bold">ResetEvent</emphasis>(
<replaceable>event</replaceable>, [ <replaceable>action</replaceable> ],
[ <replaceable>src-dst</replaceable> ], [
<replaceable>disposition</replaceable> ] )</para>
<variablelist>
<varlistentry>
<term>event</term>
<listitem>
<para>Name of the event.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>action</term>
<listitem>
<para>An action to perform after the event is reset. May be any
action that may appear in the ACTION column of <ulink
url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5).
If no action is to be performed, use COUNT. The default is
ACCEPT.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>src-dst</term>
<listitem>
<para>Specifies whether the source IP address (<emphasis
role="bold">src</emphasis>) or destination IP address (<emphasis
role="bold">dst</emphasis>) is to be removed from the event. The
default is <emphasis role="bold">src</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>disposition</term>
<listitem>
<para>If the <replaceable>action</replaceable> involves logging,
then this parameter specifies the disposition that will appear in
the log entry prefix. If no <replaceable>disposition</replaceable>
is given, the log prefix is determines normally.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>IfEvent</title>
<para><emphasis role="bold">IfEvent</emphasis>(
<replaceable>event</replaceable>, [ <replaceable>action</replaceable> ],
[ <replaceable>duration</replaceable> ], [
<replaceable>hitcount</replaceable> ], [
<replaceable>src-dst</replaceable>], [
<replaceable>command</replaceable> ], [
<replaceable>disposition</replaceable> ] )</para>
<variablelist>
<varlistentry>
<term>event</term>
<listitem>
<para>Name of the event.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>action</term>
<listitem>
<para>An action to perform if the test succeeds. May be any action
that may appear in the ACTION column of <ulink
url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5).
The default is ACCEPT.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>duration</term>
<listitem>
<para>Number of seconds over which the event is to be tested. If
not specified, the test is not constrained by time.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>hitcount</term>
<listitem>
<para>Specifies the minimum number of packets required for the
test to succeed. If not specified, 1 packet is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>src-dst</term>
<listitem>
<para>Specifies whether the source IP address (<emphasis
role="bold">src</emphasis>) or destination IP address (<emphasis
role="bold">dst</emphasis>) is to be tested. The default is
<emphasis role="bold">src</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>command</term>
<listitem>
<para>May be one of the following:</para>
<variablelist>
<varlistentry>
<term>check</term>
<listitem>
<para>Simply test if the
<replaceable>duration</replaceable>/<replaceable>hitcount</replaceable>
test is satisfied. If so, the
<replaceable>action</replaceable> is performed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>reset</term>
<listitem>
<para>Like <emphasis role="bold">check</emphasis>. If the
test succeeds, the <replaceable>event</replaceable> will be
reset before the <replaceable>action</replaceable> is
taken.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>update</term>
<listitem>
<para>Like <emphasis role="bold">check</emphasis>.
Regardless of whether the test succeeds, an entry with the
current time and for the <replaceable>src-dst</replaceable>
iP address will be added to the
<replaceable>event</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>checkreap</term>
<listitem>
<para>Requires a <replaceable>duration</replaceable>. Like
<emphasis role="bold">check</emphasis> but regardless of
whether the test succeeds, entries for the
<replaceable>src-dst</replaceable> IP address that are older
than <replaceable>duration</replaceable> seconds will be
deleted from the <replaceable>event</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>updatereap</term>
<listitem>
<para>Requires a <replaceable>duration</replaceable>. Like
<emphasis role="bold">update</emphasis> but regardless of
whether the test succeeds, entries for the
<replaceable>src-dst</replaceable> IP address that are older
than <replaceable>duration</replaceable> seconds will be
deleted from the <replaceable>event</replaceable>.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The default is <emphasis
role="bold">check</emphasis>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>disposition</term>
<listitem>
<para>If the <replaceable>action</replaceable> involves logging,
then this parameter specifies the disposition that will appear in
the log entry prefix. If no <replaceable>disposition</replaceable>
is given, the log prefix is determines normally.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>'show event' and 'show events' Commands</title>
<para>The CLI programs (<filename>/sbin/shorewall</filename>,
<filename>/sbin/shorewall-lite</filename>, etc.) support <command>show
event</command> and <command>show events</command> commands.</para>
<para>The <command>show event</command> command shows the contents of
the events listed in the command while <emphasis role="bold">show
events</emphasis> lists the contents of all events.</para>
<programlisting>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# </programlisting>
<para>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.</para>
<para>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:</para>
<programlisting>sticky002
src=172.20.1.213 : <emphasis role="bold">53</emphasis> 49 49 49 49 49 49 49 49 49 49 49 49 49 49 49 49 49 46 <emphasis
role="bold">46</emphasis></programlisting>
<para>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 <emphasis role="bold">ip_pkt_list_tot</emphasis> xt_recent option
(20).</para>
<para>The output of these commands is produced by processing the
contents of <filename>/proc/net/xt_recent/*</filename>. You can access
those files directly to see the raw data. Additional about these files
may be found in iptables (8).</para>
</section>
</section>
<section>
<title>Examples</title>
<section>
<title>Automatic Blacklisting</title>
<para>This example is taken from <ulink
url="http://www.briandowney.net/blog/2009/08/20/firewalling-brute-force-attempts-with-iptables/">this
article</ulink> which explains the nice benifits of this approach. This
example is for ssh, but it can be adapted for any application.</para>
<para>The name SSH has been changed to SSHLIMIT so as not to override
the Shorewall macro of the same name.</para>
<para><filename>/etc/shorewall/actions</filename>:</para>
<programlisting>#ACTION OPTION DESCRIPTION
SSHLIMIT #Automatically blacklist hosts who exceed SSH connection limits
</programlisting>
<para><filename>/etc/shorewall/action.SSH_BLACKLIST</filename>:</para>
<programlisting>#
# 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)</programlisting>
<para><filename>/etc/shorewall/action.SSH</filename>LIMIT:</para>
<programlisting>#
# 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)</programlisting>
<para><filename>etc/shorewall/rules</filename>:</para>
<programlisting>#ACTION SOURCE DEST PROTO DEST
# PORT(S)
SSHLIMIT net $FW tcp 22 </programlisting>
</section>
<section>
<title>Port Knocking</title>
<para>This example shows a different implementation of the one shown in
the <ulink url="PortKnocking.html">Port Knocking</ulink> article.</para>
<para>In this example:</para>
<orderedlist>
<listitem>
<para>Attempting to connect to port 1600 enables SSH access. Access
is enabled for 60 seconds.</para>
</listitem>
<listitem>
<para>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).</para>
</listitem>
</orderedlist>
<para>To implement that approach:</para>
<para><filename>/etc/shorewall/actions</filename>:</para>
<programlisting>#ACTION OPTION DESCRIPTION
Knock #Port Knocking</programlisting>
<para><filename>/etc/shorewall/action.Knock</filename>:</para>
<programlisting>#
# 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) </programlisting>
<para><filename>etc/shorewall/rules</filename>:</para>
<programlisting>#ACTION SOURCE DEST PROTO DEST
# PORT(S)
Knock net $FW tcp 22,1599-1601 </programlisting>
</section>
</section>
</article>
View Git Blame Copy Permalink