apps/irssi/docs/botnet.txt

   1
   2  Irssi's botnet description
   3
   4  Copyright (c) 1999-2000 Timo Sirainen
   5
   6
   7  0. History
   8
   9  draft v0.1 : 21.8.1999
  10
  11         Just a first draft of my botnet design I did on a boring friday
  12         work afternoon :) I'll try to implement this to irssi some day, it
  13         feels pretty interesting now so it might be pretty soon even. Any
  14         comments are welcome :)
  15
  16  draft v0.2 : 21.11.1999
  17
  18         Exactly three months since the first draft :) Now I actually have
  19         some code done, just committed pretty simple botnet to irssi CVS.
  20         Made several changes to this document.. Still missing much details
  21         but the basic idea should be clear.
  22
  23  draft v0.3 : 21.05.2000
  24
  25         Strange, again the same day. I really didn't plan this :)
  26         Reformatted the text, added lots of text, implemented more of the
  27         stuff.
  28
  29
  30  1. General
  31
  32  1.1 Description
  33
  34         A small description of what botnet would do: A group of bots
  35         efficiently working together to perform their tasks. Like when
  36         someone's trying to take over your channel, bots will quickly
  37         decide who deops/kicks whom instead of multiple bots deopping or
  38         trying to kick the same people.
  39
  40         Irssi's botnet is pretty much based on trust. Some malicious bot
  41         can quite well mess up the whole botnet. Connecting the bots to
  42         each other via ssh would be a good idea.
  43
  44  1.2 Configuration
  45
  46         example config file:
  47
  48         mybotnet =
  49         {
  50           priority=5;
  51           nick=mybot;
  52           uplinks = (
  53             { host = "main.botnet.org"; password = "mypass"; },
  54             { host = "alter.botnet.org"; password = "pass2"; }
  55           );
  56           downlinks = (
  57             { password = "thepass"; valid_addrs = ( "192.168.0.*" ); },
  58             { password = "blah"; valid_addrs = ( "*.botnet.org" ); },
  59             { password = "localpass"; valid_addrs = ( "127.*" ); }
  60           );
  61         }
  62
  63         When connecting to botnet, the bot first tries to connect to the
  64         first bot in uplinks list, then the second, etc. Setting port to -1
  65         will prevent connecting to the bot, 0 uses the default.
  66
  67  1.3 Botnet master
  68
  69         To avoid total chaos inside botnet, the bots shouldn't do (almost)
  70         anything without a command from botnet's master. The master should
  71         know everything, and give commands to clients that can perform the
  72         task best.
  73
  74         Master is the bot with the highest priority. If there's multiple
  75         with the same priority, the one that already was the master will
  76         stay master. When joining two botnets to one, the uplink's master
  77         stays. If link to master breaks, the closest bot to it will choose
  78         a new one.
  79
  80         The priorities should be given so that the bots that have the
  81         fastest connections and are in the middle of the botnet have the
  82         highest priorities.
  83
  84  1.4 Command format
  85
  86         Commands that are sent inside botnet are in the following format:
  87
  88           <from_nick> <to_nick> COMMAND [command specific data..]
  89
  90         If to_nick is '-', the command should be sent to everyone.
  91
  92
  93  2. Handshake
  94
  95         First host checks from bots' valid_addrs who is connecting. If
  96         there's no matches it just disconnects the client.
  97
  98           CLIENT: PASS <password>
  99           HOST  : (if error, disconnect)
 100
 101           CLIENT: NICK <nick>
 102           HOST  : NICKERROR | CONNECTED
 103
 104         If nick is already in use, the host sends NICKERROR and waits for
 105         new nick.
 106
 107         Now we're connected to botnet. The commands from now on use the
 108         format specified in section 1.4.
 109
 110         Both the client and the host sends information to other side of
 111         all the clients they serve (if any):
 112
 113           BOTINFO <nick> <connected_to_nick> <priority>
 114
 115         BOTINFOs must be sent sorted so that connected_to_nick bot is
 116         always known. Like first comes the bots connected to the
 117         host/client, then the bots connected to them etc.
 118
 119         If the client had downlinks, nick collisions might happen. The
 120         uplink is responsible for noticing them from BOTINFO commands.
 121         It should automatically replace the nicks with new ones and
 122         send nick change command to client and all it's downlinks. For
 123         example if host received:
 124
 125           BOTINFO bot highbot 10
 126
 127         And the bot already exists, the BOTINFO is changed to:
 128
 129           BOTINFO bot2 highbot 10
 130
 131         And the client and it's downlinks are notified:
 132
 133           BOTNICK bot2 bot
 134
 135         After sending BOTINFOs, the host tells the current master:
 136
 137           MASTER <nick>
 138
 139         The client now checks if it's priority is higher than the current
 140         master's. If it is, it will send the MASTER command without any
 141         parameters.
 142
 143
 144  3. Bot connections
 145
 146  3.1 General
 147
 148         Everyone's connections should be kept in n-way tree. Example:
 149
 150
 151                               [highuplink]
 152                  _____________/    |  |   \
 153                 /                  | [h5] [h6]
 154               [h1]                 |     /  | \
 155              /    \                |   [h7] | [h8]
 156            [h2]   [h3]             |        |    \
 157                    |            [uplink]   [h9] [h10]
 158                   [h4]         /   |    \
 159                             [up2]  |   [up1]
 160                            /   |   |     |
 161                        [up3] [up4] |    [up5]
 162                                    |
 163                                   [we]
 164                                  /    \
 165                          [client1]     [client2]
 166                                         /     \
 167                                       [c3]    [c4]
 168
 169
 170         Botnet should try to keep together even if some hub in the middle
 171         crashes. Each bot should have at least two uplinks in case one
 172         dies. For example if [uplink] dies, [we] and [up1] could connect
 173         to [up2], and [up2] could connect to [highuplink].
 174
 175         When connection is closed to some bot, a notice is sent by the
 176         bot's uplink:
 177
 178           BOTQUIT <nick>
 179
 180         The quit notice should be sent only about the bot that was
 181         disconnected. Bots should figure out themselves the other bots and
 182         remove them too from their lists.
 183
 184  3.2 Lag
 185
 186         Each bot should send PING commands to their up/downlinks every
 187         now and then (1min?) to check that the connection is still active.
 188         If the PONG isn't received in 10 seconds, it's priority should be
 189         temporarily lowered to -1. If the PONG isn't received in 3
 190         minutes, the whole connection should be closed.
 191
 192         Master should know lag times of every bots. It could then
 193         automatically raise/lower bots' priorities depending on how big
 194         their lag is. Master could also lower it's own priority and pass
 195         the master status to someone else with lower lag.
 196
 197         If there's lot of lag (>3sec?) somewhere and something urgent
 198         happens, the botnet could split and behave independently.
 199
 200
 201  4. IRC networks
 202
 203  4.1 Server connections
 204
 205         When bot is connected to some irc server and is ready to take
 206         commands, it says:
 207
 208           IRCJOIN <tag> <ircnet> <server> <nick>
 209
 210         Tag is the bot specific unique tag of the server, so that the bot
 211         can connect multiple times to same IRC network. All IRC related
 212         commands should specify the server tag where it should be sent.
 213
 214         If bot quits an irc network, it says:
 215
 216           IRCQUIT <tag>
 217
 218  4.2 IRC commands
 219
 220         Master asks a bot to send some command to IRC server by saying:
 221
 222           CMD <id> <tag> <command>
 223
 224         <command> can't really be anything, since the bot should also be
 225         able to reply to it. The <id> is for identifying the command/reply
 226         pair. Master should keep the command in memory until it receives
 227         the reply:
 228
 229           CMDREPLY <id> <last> <reply>
 230
 231         The command could get a reply of multiple lines, so <last>
 232         specifies if the reply is the last line (1 or 0).
 233
 234         If the command failed for some reason, the bot will reply with
 235
 236           CMDFAIL <id>
 237
 238         and master should send the command to some other bot.
 239
 240  4.3 Channels
 241
 242         When joined/left channels, the bot says:
 243
 244           CHANJOIN <tag> <channel>
 245           CHANPART <tag> <channel>
 246
 247         After BOTJOIN, master tries to op the bot. When bot receives +o,
 248         it says:
 249
 250           CHANOP <tag> <channel>
 251
 252         If it is the first opped bot in channel, master orders the bot to
 253         op the rest of the bots.
 254
 255         If the bot is kicked, it says:
 256
 257           CHANKICK <tag> <channel>
 258
 259         When master notices that bot is kicked, it first checks if there's
 260         any other opped bots in channel. If not, it waits for a random
 261         pause, 5-10sec before letting the bot join the channel again so
 262         that it won't get autorejoin ban.
 263
 264         If bot can't join channel, it says:
 265
 266           CHANBANNED <tag> <channel>
 267           (or)
 268           CHANCANTJOIN <tag> <channel>
 269
 270         When received BOTBANNED, master tries to unban bot or set a ban
 271         exception. BOTCANTJOIN results as invite to channel.
 272
 273  4.4 Channel information
 274
 275         When master notices that bot is the first one joined to channel,
 276         it asks the bot for some channel information:
 277
 278           CMD <id> <tag> NAMES <channel>
 279           CMD <id> <tag> WHO <channel>
 280           CMD <id> <tag> MODE <channel>
 281           CMD <id> <tag> MODE b <channel>
 282           CMD <id> <tag> MODE e <channel> (if IRC network supports this)
 283           CMD <id> <tag> MODE I <channel> (if IRC network supports this)
 284
 285         It's also possible that if several bots join immediately after the
 286         first bot, the commands are shared between all the bots.
 287
 288         Bots should cache the information as much as possible, at least
 289         NAMES command.
 290
 291  4.5 Channel priorities
 292
 293         Every channel has a priority: LOW, NORMAL, HIGH.
 294
 295         Normally LOW operates just as NORMAL channels, except when some
 296         channel has HIGH priority and bots are really busy, LOW channels
 297         just wait until there's time for them.
 298
 299         In NORMAL channels, the most urgent operations (kicks, ops, deops)
 300         are performed quite soon even while bots are busy handling HIGH
 301         priority commands.
 302
 303         Channels shouldn't normally be HIGH priority, but if attack
 304         against channel is detected (like someone comes from split, gets
 305         ops and gets to op someone else), it's priority is set to HIGH.
 306         When channel's priority is HIGH, botnet does everything it can to
 307         get rid of unauthorized opped people as fast as possible.
 308
 309         LOW channel's priority can also be raised to HIGH, but it's
 310         priority is dropped back to LOW if some NORMAL channel's priority
 311         is raised to HIGH too.
 312
 313         Master notifies about channel's priority change by saying:
 314
 315           CHANPRIORITY <ircnet> <channel> <LOW/NORMAL/HIGH>
 316