forked from extern/shorewall_code
510 lines
17 KiB
XML
510 lines
17 KiB
XML
<?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>
|
|
</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>
|
|
|
|
<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>
|