shorewall_code/docs/Events.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
SSH_BLACKLIST                                  #Helper for SSH</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:$LOG:REJECT
#
# And set the SSH_COUNTER trigger 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:$LOG:,2,1,-,update,Added)
#
# Un-blacklist the client
#
ResetEvent(SSH_COUNTER,LOG:$LOG,-,Removed)
#
# Set the 'SSH' trigger 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>