supybot-irccat

Supybot plugin relaying data from a tcp port to irc channel(s)

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

Related Repositories

supybot-irccat

supybot-irccat

Supybot plugin relaying data from a tcp port to irc channel(s) ...


Top Contributors

leamas