Add documentation on scripting mailman actions

Change-Id: I1d5343f9baba9eb5d07cc42d516a393db87c807d

doc/source/lists.rst

@@ -43,3 +43,48 @@ example:
     mailserver  => $listdomain,
   }
 
+Scripted Changes to Lists
+=========================
+
+This may only be performed with root access to the list server.
+
+Mailman supports running a python code snippet in the context of
+individual lists or every list on the system.  The following example
+adds an address to the list of banned addresses for every list.  This
+has proved useful in the case of attackers abusing the HTTP
+subscription interface to subscribe a target's address to multiple
+mailing lists.
+
+Banning an Address from All Lists
+---------------------------------
+
+Create the file `/usr/lib/mailman/bin/ban.py` with the following
+content:
+
+.. code-block:: python
+
+  def ban(m, address):
+      try:
+          m.Lock()
+          if address not in m.ban_list:
+              m.ban_list.append(address)
+          m.Save()
+      finally:
+          m.Unlock()
+
+And then run the withlist script as:
+
+.. code-block:: bash
+
+  sudo -u list /usr/lib/mailman/bin/withlist -a -r ban "<address to ban>"
+
+Because the script itself handles locking, do not use the `-l`
+argument to withlist.  To run the same script on a single list, use:
+
+.. code-block:: bash
+
+  sudo -u list /usr/lib/mailman/bin/withlist -r ban listname "<address to ban>"
+
+Note that the ban list accepts regular expressions, so to ban an
+address and all suffixes, use '^address.*@example.com' as the "address
+to ban".