MediaWiki Administrator's Handbook/Countervandalism IRC Bots

This page documents two bots used extensively by countervandalism channels.

Bot overview

Computer was the original recent changes filtering bot written as a mIRC script, developed by White Cat. It was replaced by pgkbot in 2005.

pgkbot is a python bot developed by pgk. It is designed for use in one channel, and includes a number of customization options such as plugin support, complex event routers, individual lists, individual user name and article title watchlists, detection of page move vandalism, and IP address categories (like open proxies). However, configuration is difficult and it is relatively resource-intensive.

SWBot is a C# bot developed by Tangotango and Az1568. It is designed for use in networked or multiwiki channels. Features include dynamic loading and unloading of wikis and channels, a central configuration file and database, global lists, auto-broadcast of global changes to all other SWBot instances, and detection of page blanking and replacement using automated MediaWiki summaries. However, per-channel event configuration is not possible.

CVNbot is a unified centralized bot written in Perl by Pathoschild. It is currently in development and not actively used. The bot is intended to facilitate channel network administration and provide edit monitoring, without extraneous features.

pgkbot

Common bots: ErosionBot-1, MiszaBot, TheDJBot, ClueBot(RC).

Operation

Using commands

Commands are issued to the bot by appending their name or "computer" to the beginning of the line. If you append the name, the command will only be recognized by the bot named. If you append "computer", all bots present will recognize the command. For example, if you want to add a user to pgkbot's blacklist, you would say pgkbot bl add username. Alternately, you could add the user to the blacklist of every bot in the channel. This is recommended, as it synchronises the backup bots. To do this, you would say computer bl add username.

Which commands a user can issue depends on which list they are in.

Level	Users	List of commands
Information	Any user	intelligence commands; help.
Operation	Voiced users	watchlist; intelligence; help, status, quiet, speak.
Restricted	Channel operators	all commands.

Lists of users

The bots maintain several lists of users, which can be reported, formatted, and treated differently from each other.

• Admins: this is a list of admins on the project. The relevant command is computer al add|del username.
• Whitelist: this is the list of trusted users. The relevant command is computer wl add|del username.
• Greylist: this is a temporary blacklist which the bot automatically populates with users that have recently been reverted, or matched one of the bnu list expression. Entries can be removed from the list, but cannot be added manually.
• Blacklist: this is a list of suspicious users. All edits by blacklisted users are reported. The relevant command is computer bl add|del username.
• Bots: this is a list of bots on the project. The relevant command is computer bot add|del user.

Reference table

This table is a quick overview of commands. For additional help, address the following command to pgkbot on IRC: pgkbot help <command>. There are two optional flags which can be used with most commands. These can be used by appending them to the end of the command (expiry must be stated before the reason, if both are used).

• "r=value" provides a reason. This is useful for other users, who may not know why something has been added to the list without.
• "x=value" provides an expiry time in hours. After the specified number of hours, the command will be automatically undone.

Note that the symbols "[|]" are used in the table; these symbols should not be used with the bot (for example, use "pgk add blah" and not "pgk [add] blah"). Multiple possible actions are denoted as [option 1|option 2]; only one can be used at a time. Values are designated as <value>; all strings accept regex.

Restricted bot commands

Command	Usage	Description
aclo	computer aclo [add|del] IRC_name	Add or remove users who can give restricted bot commands.
config (set)	computer config <option> <newvalue>	Modifies the configuration values. See in-depth documentation below.
config (list)	computer config list	List current settings
config (get)	computer config [getadmins|getbots]	Retrieve the list of admins or bots direct from the wiki being monitored
config (read)	computer config [readmsgs|readcmds]	Reread some configuration files.
dest (set)	computer dest [add|del] #<channel name> grey	Configure the events to report to the channel.
dest (swap)	computer dest swap #<channel name> #<second channel name>	Switch the events reported between two channels, useful for changing to preset settings.
reader	computer reader reset	Reset the connection to the recent changes channel (if the bot stops reporting).

Bot- and channel-related commands

Command	Usage	Description
help	computer help <command>	Provides detailed help on a command. If a command is not specified, it will provide a link to this page.
status	computer status	Provides basic status information about the bot, such as whether it is reporting and connected to the RC feed.
stats	computer stats	Miscellaneous channel statistics.
quiet	computer quiet	Stop reporting event to the channel.
speak	computer speak	Report events to the channel.
acl	computer acl [add|del|show] <IRC_name>	A list of trusted IRC users. These users can issue operation commands to the bot.

Watchlist commands

Command	Usage	Description
bl	computer bl [add|del|show] <IP or username>	A list of distrusted or vandal users.
wl	computer wl [add|del|show] <username>	A list of trusted users.
gl	computer gl [del|show] <username>	A list of possible distrusted or vandal users.
al	computer al [add|del|show] <username>	A list of administrators.
bot	computer bot [add|del|show] <username>	A list of bots.
bnu	computer bnu [add|del|show] <string>	Report all new usernames containing the string.
bna	computer bna [add|del|show] <string>	Report all new articles created containing the string.
cvp	computer cvp [add|del|show] <string>	Report all edits to a given article.
cnvp	computer cnvp [add|del|show] <article name>	A list of articles to be ignored.
cvi	computer cvi [add|del|show] <image name>.<extension>	Report all uploads to a particular image name.
wheels	computer wheels [add|del|show] <string>	Report pages renamed to a title containing the string.

Intelligence commands

Command	Usage	Description
intel	computer intel <IP or username>	Queries information about an IP or username.
aintel	computer aintel <article name>	Queries information about an article.
iintel	computer iintel <image name>.<extension>	Queries information about an image.

Configuration

Settings

These settings affect the way the bot filters the raw recent changes to the reported events. They are viewed with the command computer config list and modified with the command computer config <option> <new value>.

Content

option	Description
editbig	Possible nonsense (big addition of content)
editblank	Possible blanking (big removal of content)
newbig	Possible copyright violations (big new article size)
newsmall	Possible vandalism or substubs (small new article size)

Users

option	Description
blockconflict	The number of simultaneous blocks to a single user to report.
glonrollback	The number of minutes to add a user to the greylist if their edits are rolled back by an administrator.
flagnewuser	The number of hours to add new users to the greylist.
glonbnu	The number of minutes to add new users that match a string on the bnu list.

Other

option	Description
pseudonym	Alternate name a bot should respond to as well as its name. This should be "computer" in Countervandalism network channels.
startupquiet	Don't report events on startup (toggle, "yes" or "no")
bnubnasame	Synchronise the Bad new username and Bad new article name lists.

Event report toggles

These options toggle which events are reported to the channel. They are accessed with the command computer dest list and computer dest [add|del] #<channel name> <event>. The events are listed below. Each event will only be reported to a channel once, irrespective of fitting into several of these categories.

"Actions" in the tables below refer to all visible changes to the database, including edits, page moves, and deletions.

Users

Event	Description
-admin	Don't report actions by administrators.
-white	Don't report actions by whitelisted users.
-bot	Don't report actions by bots.
black	Report all actions by blacklisted users.
grey	Report all actions by greylisted users.
newuser	Report the creation of all new users.
ip	Report all edits by anonymous users.
iptmp	Report all edits of templates by non logged in users
ipcat	Report all edits of categories by non logged in user

Strings and regex

Event	Description
wwuser	Report new usernames matching an entry in the bnu list.
wheeler	Report page moves to titles matching an entry in the wheel list.
bna	Report creates of articles which match an entry in the bna list.
cvp	Report edits to pages on the cvp list.
cvi	Report uploads of images on the cvi list.

Actions

Event	Description
block	Report blocks.
unblock	Report unblocks.
delete	Report page deletions.
move	Report page moves.
protect	Report non userspace page protections/unprotections.
upload	Report file uploads.

Content

Event	Description
bigremove	Report possible blanking (removal of content exceeding config bigremove).
bigedit	Report possible gibberish (addition of content exceeding config bigedit).
bignew	Report possible copyright violation (creation of a page whose size exceeds config bignew).
tinynew	Report possible nonsense (creation of a page whose size is smaller than config tinynew).

Bot commands

Event	Description
cmdsq	Listen for commands in this channel, but don't respond unless addressed by nickname rather than "computer".
cmds	listen for commands in this channel, and respond.

Installation

Pre-requisites

• Python: The bot requires the python environment to run, which is freely available from the python.org download page. It is recommended that you install for all users to C:\Python with all options enabled.
• Twisted: Also required is the Twisted python library, available from the official website.
• Note - Pgkbot can only work with Python version 2.4 or 2.5 and will not work with older versions.

Download

1. Download the latest public version of pgkbot (1.7) from pathos.ca/tools/pgkbot.
2. Unzip it to C:\pgkbot.

Configure

There are a few text files that need to be edited before use.

C:\pgkbot\Config\IRCConsole.conf
Field	Value	Notes
server	irc.freenode.net	This is the IRC server the bot will connect to.
port	6667	The server port to connect to; this value should be fine.
nick	botnick	Change this to the nickname of the bot you want to use. Do not use "pgkbot" or "computer".
password	password	The password to use when identifying. Comment out this line if not using Nickserv
owner	yournick	Change to your nickname. This gives you full access to the interface.

C:\pgkbot\Config\RCReader.conf
Field	Value	Notes
server	irc.wikimedia.org	This is the IRC server the bot will connect to to get the RC feed.
port	6667	The server port to connect to; this value should be fine.
nick	yournick	Change to your nickname. This gives you full access to the interface.

C:\pgkbot\Config\en\StaticConfig
Field	Value	Notes
controlchannel	#pgktesting	The channel the bot will report to.
rcsourcechannel	#en.wikipedia	The channel with the raw RC feed (see IRC channels).

Run the bot

1. Open a DOS prompt.
2. Navigate to the directory pgkbot is installed in.
3. Type in c:\python24\python.exe CVUBot.py en.
4. pgkbot will be silent upon connecting. Be sure to make it speak and route some events (see above).

SWMTBot

Common bots: SWBot* (except SWBot2), SWMTBot*, TheDJBot(3-5).

Comparison with pgkbot

SWMTBot is a port of pgkbot to C#, specially made to suit the needs of the Small Wiki Monitoring Team and other users who monitor a large number of feeds in one channel. Most commands have been kept identical to their pgkbot equivalents except where necessary; messages have also been kept as close to pgkbot's as possible.

Features new to SWMTBot

Features in pgkbot but not in SWMTBot

Hot-pluggable wikis (load/unload on demand) Supports simultaneous monitoring of a very large number of wikis with minimal resource usage One small configuration file containing information for all wikis One SQLite database, using minimal resources, for all wikis Global blacklists/whitelists/greylists Global username/article title watchlists (supports regular expressions) Global edit summary watchlist (flags potentially vandalistic edit summaries; supports regular expressions) Auto-broadcast of all global lists to other SWMTBots Catches page blankings/replacements (using the new autosummaries)

Plugins A choice of database backends Telnet interface Complex destination/event routers Individual blacklists/whitelists Individual username/article title watchlists Wheeler detection IP categories Command renaming

Usage

Lists

All global lists are automatically synchronized across all SWMTBots; per-wiki lists are not. There is a global article watchlist for all wikis, and one for each one; you can add/delete/show items on the global list by leaving out the "p=" parameter (see the command lists below for more information).

Global lists	Per-wiki lists
Bad new usernames (BNU) Bad new article titles (BNA) Bad edit summaries (BES) User whitelist (WL) User blacklist (BL) User greylist (GL) Global article watchlist (CVP)	Lists of admins (AL) Lists of bots (BOTS) Article watchlists (CVP)

Commands

Global commands
Command	Description	Example
quit	Quits the bot	SWMTBot quit
restart	Restarts the bot	SWMTBot restart
list	Returns a list of all currently monitored wikis	SWMTBot list
load wiki.name [interwiki]	Loads a wiki for monitoring	SWMTBot load en.wikipedia en: SWMTBot load meta.wikimedia
reload wiki.name	Downloads new messages from the wiki; use if any of the log entry messages in the MediaWiki: namespace on that wiki have changed	SWMTBot reload fr.wikipedia
batchreload	Performs reload for all currently loaded wikis. Extremely resource-intensive and thoroughly not recommended	SWMTBot batchreload
drop wiki.name	Stops monitoring a wiki	SWMTBot drop als.wikipedia
purge wiki.name	Removes from the database all users and watchlisted items pertaining to a particular wiki	SWMTBot purge als.wikipedia
msgs	Re-loads messages from the Console.msgs file; necessary only when the file has changed	SWMTBot msgs
bleep wiki.name	Finds out which bot monitors a particular project. You can issue this command to any networked bot to receive the same results	SWMTBot bleep commons.wikimedia
count	Finds out how many wikis each bot monitors, and each bot's version. You can issue this command to any networked bot to receive the same results	SWMTBot count
List commands
Command	Description	Example
bl add/del/show username [x=duration] [r=reason]	Adds, deletes, or shows an item on the global blacklist. Set x=0 to make indefinite	SWMTBot bl add Tangotango x=0 r=Bad vandal (Adds Tangotango to the global blacklist indefinitely) SWMTBot bl del Tangotango (Removes Tangotango from the global blacklist)
gl del username	Deletes a user from the greylist. Use this if you want to whitelist a user, but they are on the greylist. Remove them from gl and add to wl.	SWMTBot gl del Mike.lifeguard (removes Mike.lifeguard from the greylist)
wl add/del/show username [x=duration] [r=reason]	Adds, deletes, or shows an item on the whitelist. Set x=0 to make indefinite	(See above; wl has the same syntax as bl)
cvp add/del/show article name [p=wiki.name] [x=duration] [r=reason]	Adds, deletes, or shows an article on the watchlist. Leave out p= to monitor articles with the same name on all wikis; set x=0 to make indefinite	SWMTBot cvp add United States p=en.wikipedia x=0 (Adds "United States" to the en.wikipedia watchlist) SWMTBot cvp add Main Page x=0 (Adds all pages named "Main Page" on all wikis to the watchlist)
al add/del/show username p=wiki.name [x=duration] [r=reason]	Adds, deletes, or shows an item on the admin list on a particular wiki. Set x=0 to make indefinite	SWMTBot al add Tangotango p=ga.wikipedia (Adds Tangotango to the admin list on ga.wikipedia)
bots add/del/show username p=wiki.name [x=duration] [r=reason]	Adds, deletes, or shows an item on the flagged-bot list on a particular wiki. Set x=0 to make indefinite	(See above; bots has the same syntax as al)
bnu add/del/show regex [x=duration] [r=reason]	Adds, deletes, or shows an item on the global bad new username list. Set x=0 to make indefinite	SWMTBot bnu add Tangot.*?ngo x=128 r=vandal meme (Adds Tangot.*?ngo as a bad new username)
bna add/del/show regex [x=duration] [r=reason]	Adds, deletes, or shows an item on the global bad new article title list. Set x=0 to make indefinite	SWMTBot bna add index\.php r=vandal meme (Matches "index.php" as a bad new page title)
bes add/del/show regex [x=duration] [r=reason]	Adds, deletes, or shows an item on the global bad edit summary list. Set x=0 to make indefinite	SWMTBot bes add !{3,} r=Too many exclamation marks (Makes SWMTBot flag any edit summary with 3 or more exclamation marks)
config getadmins wiki.name	Downloads a list of admins from the specified project and automatically adds it to the SWMTBot database	SWMTBot config getadmins en.wikipedia
config getbots wiki.name	Downloads a list of flagged bots from the specified project and automatically adds it to the SWMTBot database	SWMTBot config getbots da.wiktionary
batchgetusers	Performs getadmins and getbots for all currently loaded wikis	SWMTBot batchgetusers

Installation

SWMTBot is tested and actively developed to work on Mac OS X, Linux (Debian), and Windows. The software is licensed under the MIT License.

CVNbot

See m:CVN/CVNbot.

See also

Support

• #countervandalism for bots in channels operated by the countervandalism network
• pgkbot
  • pgk— For comments, suggestions, and troubleshooting the bot script.