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, no Front-Cover Texts, and 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 supersedes
    <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 id="SetEvent">
      <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 determined normally. The default is
            ACCEPT.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section id="ResetEvent">
      <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 determined normally.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section id="IfEvent">
      <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>option</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.
                  Requires the <firstterm>Mark in filter table</firstterm>
                  capability in your kernel and iptables.</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>
            </variablelist>

            <para>The default is <emphasis
            role="bold">check</emphasis>.</para>

            <para><replaceable>option</replaceable> may be one of:</para>

            <variablelist>
              <varlistentry>
                <term>reap</term>

                <listitem>
                  <para>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>ttl</term>

                <listitem>
                  <para>Constrains the test to require that the packet TTL
                  match the ttl in the original packet that created the
                  entry.</para>
                </listitem>
              </varlistentry>
            </variablelist>
          </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 determined normally.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section id="ShowEvents">
      <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:~# shorewall show events
Shorewall 4.5.19-Beta2 events at gateway - Sat Jul 13 07:17:59 PDT 2013

SSH
   src=75.101.251.91 : 2225.808, 2225.592 
   src=218.87.16.135 : 2078.490 

SSH_COUNTER
   src=65.182.111.112 : 5755.790 
   src=113.162.155.243 : 4678.249 

sticky001
   src=172.20.1.146 : 5.733, 5.728, 5.623, 5.611, 5.606, 5.606, 5.589, 5.588, 5.565, 5.551, 5.543, 5.521, 5.377, 5.347, 5.347, 5.345, 5.258, 5.148, 5.048, 4.949 
   src=172.20.1.151 : 41.805, 41.800 

sticky002
   src=172.20.1.213 : 98.122, 98.105, 98.105, 98.105, 98.088, 98.088, 98.088, 98.088, 98.058, 98.058, 80.885, 53.528, 53.526, 53.526, 53.510, 53.383, 53.194, 53.138, 53.072, 3.119 
   src=172.20.1.146 : 4.914, 4.914, 4.898, 4.897, 4.897, 4.896, 4.896, 4.896, 4.882, 4.881, 4.875, 4.875, 4.875, 4.875, 4.875, 4.875, 4.875, 4.874, 4.874, 4.874 

root@gateway:~# </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.146 that arrived between 5.733 and
      4.949 seconds ago:</para>

      <programlisting>sticky001
   src=172.20.1.146 : <emphasis role="bold">5.733</emphasis>, 5.728, 5.623, 5.611, 5.606, 5.606, 5.589, 5.588, 5.565, 5.551, 5.543, 5.521, 5.377, 5.347, 5.347, 5.345, 5.258, 5.148, 5.048, <emphasis
          role="bold">4.949</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. The raw times are the uptime
      in milliseconds. The %CURRENTTIME entry is created by the <command>show
      event[s]</command> commands to obtain the current uptime.</para>
    </section>
  </section>

  <section>
    <title>Examples</title>

    <section>
      <title>Automatic Blacklisting</title>

      <para>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 SSHLIMIT</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,check:reap)
#
# 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      DPORT
SSHLIMIT              net            $FW       tcp        22                        </programlisting>

      <caution>
        <para>The technique demonstrated in this example is not self-cleaning.
        The SSH_COUNTER event can become full with blackisted addresses that
        never attempt to connect again. When that happens and a new entry is
        added via SetEvent, the least recently seen address in the table is
        deleted.</para>
      </caution>
    </section>

    <section id="AutoBL">
      <title>Generalized Automatic Blacklisting</title>

      <para>The above two actions are generalized in the AutoBL and AutoBLL
      actions released in Shorewall 4.5.19. Only AutoBL is invoked directly
      from your rules file; AutoBL invoked AutoBLL internally.</para>

      <section>
        <title>AutoBL</title>

        <para><emphasis role="bold">AutoBL</emphasis>(
        <replaceable>event</replaceable>, [
        <replaceable>Interval</replaceable> ], [
        <replaceable>hitcount</replaceable> ], [
        <replaceable>successive</replaceable> ], [
        <replaceable>blacklist-time</replaceable> ], [
        <replaceable>disposition </replaceable>], [
        <replaceable>log_level</replaceable> ] )</para>

        <variablelist>
          <varlistentry>
            <term>event</term>

            <listitem>
              <para>Name of the event. The blacklisting event itself will be
              <replaceable>event</replaceable>_BL (analogous to SSH_COUNTER
              above).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>interval</term>

            <listitem>
              <para>Interval, in seconds, over which hits are to be counted.
              Default is 60 seconds.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>hitcount</term>

            <listitem>
              <para>Number of matching packets that will trigger automatic
              blacklisting when they arrive in
              <replaceable>interval</replaceable> seconds. Default is
              5.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>successive</term>

            <listitem>
              <para>If a matching packet arrives within this many seconds of
              the preceding one, it should be logged according to
              <replaceable>log_level</replaceable> and handled according to
              the <replaceable>disposition</replaceable>. If successive
              packets are not to be considered, enter 0. Default is 2
              seconds.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>blacklist-time</term>

            <listitem>
              <para>Time, in seconds, that the source IP address is to be
              blacklisted. Default is 300 (5 minutes).</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>disposition</term>

            <listitem>
              <para>The disposition of blacklisted packets. Default is
              DROP.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>log_level</term>

            <listitem>
              <para>Log level at which packets are to be logged. Default is
              info.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>To duplicate the SSHLIMIT entry in
        <filename>/etc/shorewall/rules</filename> shown above:</para>

        <programlisting>#ACTION               SOURCE         DEST      PROTO      DPORT
AutoBL(SSH,-,-,-,REJECT,warn)\
                      net            $FW       tcp        22                </programlisting>
      </section>
    </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 - Port-Knocking Action
#
?format 2
###############################################################################
#ACTION               SOURCE         DEST      PROTO      DPORT
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      DPORT
Knock                 net            $FW       tcp        22,1599-1601          </programlisting>
    </section>

    <section id="Stateful">
      <title>Stateful Port Knocking (knock with a sequence of ports)</title>

      <para><ulink url="http://www.wiesinger.com/">Gerhard Wiesinger</ulink>
      has contributed a Perl module that allows you to define portknocking
      sequences. Download <ulink
      url="pub/shorewall/contrib/PortKnocking/KnockEnhanced.pm">the
      module</ulink> and copy it into your site_perl directory.</para>

      <para>Using Gerhard's module, a port-knocking rule is defined via a
      '?PERL' statement. This example opens the SSH port from net-&gt;fw using
      the knock sequence 52245, 15623, 19845:</para>

      <programlisting>?BEGIN PERL
use KnockEnhanced;
KnockEnhanced 'net', '$FW', {name =&gt; 'SSH1', log_level =&gt; 3, proto =&gt; 'tcp', target =&gt; 'ssh', knocker =&gt; [52245,15623,19845]};
?END PERL</programlisting>

      <para>A few notes on the parameters:</para>

      <itemizedlist>
        <listitem>
          <para>The first parameter is the rule SOURCE</para>
        </listitem>

        <listitem>
          <para>The second parameter is the rule DEST</para>
        </listitem>

        <listitem>
          <para>The third parameter is a Perl hash reference that defines the
          remaining parameters. Each parameter is specified via
          <replaceable>param</replaceable> =&gt;
          <replaceable>value</replaceable>.</para>

          <itemizedlist>
            <listitem>
              <para><emphasis role="bold">proto</emphasis> is the protocol --
              if not specified, the default is tcp</para>
            </listitem>

            <listitem>
              <para><emphasis role="bold">seconds</emphasis> is the timeout
              between successive events -- default is 60 seconds.</para>
            </listitem>

            <listitem>
              <para><emphasis role="bold">original_dest</emphasis> is the rule
              ORIGDEST</para>
            </listitem>

            <listitem>
              <para><emphasis role="bold">target</emphasis> is the port(s)
              that you are trying to open. May either be a single name or
              number, or it may be a list of names and/or numbers separated by
              commas and enclosed in square brackets ("[...]").</para>
            </listitem>

            <listitem>
              <para><emphasis role="bold">name</emphasis> is a name used as
              the base for event and chain names. If not supplied, the first
              <emphasis role="bold">target</emphasis> is used, in which case
              the first target must be a port name.</para>
            </listitem>

            <listitem>
              <para><emphasis role="bold">log_level </emphasis>specifies
              logging for the generated rules</para>
            </listitem>
          </itemizedlist>

          <note>
            <para>Port names and numbers may be optionally followed by a colon
            (":") and a protocol name or number to override the specified
            protocol.</para>
          </note>
        </listitem>
      </itemizedlist>

      <para>The module itself contains additional examples of its
      usage.</para>
    </section>
  </section>
</article>