Supybot Irccat Plugin

This is a plugin for the IRC bot Supybot that introduces the ability to listen to a TCP port and relay incoming text to one or more IRC channels, using some primitive security mechanisms.

I have used it to integrate supybot with a Jenkins build server (jenkins built-in irc plugin sucks). The build script send messages when build is completed, and we find in the irc channel:

Jenkins: build OK. http://jenkins.cloud.fedoraproject.org/job/FedoraReview_F17_py2.7

Obviously, the plugin is generic and could be used to a variety of things. It's similar to the notify plugin, but does not require the client to be on the same host as the supybot server.

Here is also a simple script which can be used to send data to a server running subybot with irccat

Dependencies

• python-twisted (tested with 12.1)
• supybot (tested with 0.83.4)
• ncat for unit tests

Getting started

• Refer to the supybot documentation to install supybot and configure your server e. g., using supybot-wizard. Verify that you can start and contact your bot.

• Unpack the plugin into the plugins directory (created by supybot-wizard):

      $ cd plugins
      $ git clone https://github.com/leamas/supybot-irccat Irccat
      $ cd Irccat
      $ git-hooks/post-commit

• Identify yourself for the bot in a private window. Creating user + password is part of the supybot-wizard process.

     <leamas> identify al my-secret-pw
     <al-bot-test> The operation succeeded.

• Load plugin and use list to verify that the plugin is loaded (still in private window):

    <leamas> load Irccat
     <al-bot-test> The operation succeeded.
    <leamas> list
    <al-bot-test> leamas: Admin, Channel, Config, Irccat, Owner, and User

• Define the port you want to use as listener port (still in private window):

     <leamas> config plugins.irccat.port 12345
     <al-bot-test> The operation succeeded.

• In order to use irccat you need to define a section. A section has a name, a password and a list of channels to feed. Define your first section named foo with password pwfoo sending data to the channel #al-bot-test:

    <leamas> sectiondata foo pwfoo #al-bot-test
    <al-bot-test> leamas: The operation succeeded.

• By default irccat will use notice messages, but some users will prefer to use privmsg messages. To do so (still in private window):

     <leamas> config plugins.irccat.privmsg True
     <al-bot-test> The operation succeeded.

• Your bot must join the channel(s) you want to feed. Do this with join, still in private window:

    <leamas> join #al-bot-test

Use the companion script to send a message...

    $ plugins/Irccat/irccat localhost -s 12345 foo footext to show
    pwfoo
    $

...and you will see a line in the selected channel:

    *al-bot-test* footext to show

Configuration

The configuration is done completely in IRC. There are general settings and section specific ones. To see the general settings:

    @config list plugins.irccat
    leamas:  port, public, and sectionspath

Each general setting has help info and could be inspected and set using the config plugin, see it's documents. Quick crash course using port as example:

• Getting help: @config help plugins.irccat.port
• See actual value: @config plugins.irccat.port
• Setting value: @config plugins.irccat.port 6060

The public, option is internal, please don't touch.

NOTE! After modifying the variables use @reload Irccat to make them effective.

The available sections can be listed using

    <leamas> sectionlist
    <al-bot-test> yngve ivar

To see actual settings (password is encrypted):

    @sectionshow ivar
    leamas: fjdk;fdsa #al-bot-test

These settings can be manipulated using sectiondata as explained in Getting Started.

Input line format

Each line read from the input port should have the following format:

<name>;<password>;<any text>

• name: The name of a configuration section i. e., a value from @sectionlist.
• password: As defined when using sectiondata, see below. Stored passwords are encrypted and cannot be displayed, so you need to remember these.
• The text after the second ';' is sent verbatim to the channel(s) listed in the section.

Unparsable lines are logged but otherwise silently dropped. Blacklisted clients are not even logged.

Command List

Plugin commands:

• sectiondata: Takes a section name, a password and a comma-separated list of channels to feed. Creates section if it doesn't exist.

• sectionkill: Delete a section given it's name.

• sectionlist: List available sections.

• sectionshow: Show encrypted password and channels for a section.

• sectionhelp: Show help URL i. e., this file.

Other useful supybot commands:

• config plugins.irccat.port: Show the TCP port irccat listens to.

• reload Irccat: Make changes in e. g., plugins.irccat.port effective

• join #channel: Make bot join a channel, required when feeding one.

Scripts:

• irccat [-s|-h] <host> <port> <section> <text...>. Sends <text..>. to a supybot <host> running irccat on <port> using the given <section>. Reads password from stdin when using [-s] Use -h/--help for details.

Security

Irc servers are normally not Fort Knox, so this is not the place for ssl or 2-factor authentication. That said, leaving a TCP port open as a relay to irc channel(s) certainly requires some precaution. The steps here are:

• The client must know the section and it's password as described above.
• Managing passwords and channels requires 'owner' capability in irc.
• Password cleartext is not saved anywhere.
• Clients which repeatedly fails to send correct data are blacklisted for a while.

Static checking and unit tests.

pep8 (in the Git directory):

  $ pep8 --config pep8.conf . > pep8.log

pylint: (in the Git directory):

  $ pylint --rcfile pylint.conf \*.py > pylint.log

Unit tests:

  $ supybot-test plugins/Irccat