User:Pathoschild/Scripts/StewardBot

This bot is named "stewbot" on IRC, and is entirely distinct from the bot named "StewardBot" on IRC.

←Scripts

User:Pathoschild (Scripts > StewardBot)

StewardBot is a Python script which idles in several channels on the freenode IRC network as "stewbot" when Pathoschild is around, including #stewardbot^connect and #wikimedia-stewards^connect. It accepts commands and performs utility operations related to steward tasks.

Secret agenda

Popular wikis are often abused to publish attacks on users or persons. This bot aims to defeat such attempts, particularly with regards to the registration of usernames containing attacks or private information. This method was particularly nefarious, because it was virtually impossible to remove this information after the account was created.

Fortunately, recent developments in the MediaWiki software make it possible to counter this, and even erase past attacks. This bot was primarily created to facilitate this. Specifically...

1. The bot automates the process of blocking a malicious user globally and locally, and if necessary removing it from logs and edit histories. A new account processed this way effectively disappears. Since the process is almost entirely automated, it takes longer for malicious users to create such accounts than it takes to suppress them.
2. By automatically scanning locked global accounts' local edits, operators are notified about hidden vandalism and page creations, avoiding the possibility that an attack page will be created on a small wiki and be indexed by search engines.

User access & security

Commands are divided into three access groups: unrestricted commands may be issued by anyone; whitelist commands may be issued by users in the bot's whitelist; and operator commands which will be accepted only from the operator. Whitelisted users may also issue op commands, but will require operator approval using !commit.

The bot only processes sensitive commands from authorized users. Its authorization is based on explicitly whitelisted Wikimedia cloaks, and its security is paranoid and handled at a code path bottleneck at the parser level. In addition, it is only running when Pathoschild is near its terminal to intervene if needed, and all its commands are reversible.

Only Pathoschild has operator access.

Current commands

Unrestricted commands

Documentation
!help !help command	Displays concise documentation about the bot, or the specified command.
!help keyword	Displays details about the bot: !help access: information about command access, and a list of whitelisted users and operators. !help commands: a list of commands, sorted by access level. !help status: information about the bot's IRC and web connections and configuration.
Utility
!activity domain !activity dbprefix	display dates of last edit, and last local sysop & bureaucrat actions by local users on the specified wiki.
!links ip !links username	Provide relevant links for IPs or global accounts.
!lookup language_code	Looks up an ISO-639 1–3 language code in iso639db.
!scanedits name	Scan for edits by a global account; privately send links to contributions for wikis with edits, or link to a sandbox list if there too many edited wikis.
!showrights name@wiki	List the specified user's local and global right-groups.
!steward	Ping available stewards, for emergency situations where a steward is needed immediately. Disabled by default; enable with "!config > stewardping > 1".
!translate text	Uses Google translation tool to detect the language the text is written in and outputs the English translation if available. !translate source language > text : Translates text from source language to English. !translate source language > target language > text : Translates text from source language to target language.
Frivolous
!bash !bash literal search terms !bash id	Display a randomly-selected quote from bash or bugzilla quips, the first quote containing the search string, or the quote selected by queue ID.
!debug	Print a random quote from Pathoschild's three-year-old niece (except when debugging).

Whitelisted guest commands

!config option > value	Changes runtime configuration: [operators only] disablerestricted > 0|1: disable processing of all restricted commands at the parser level, for even more paranoid security during operator absence. redundantconfirm > 0|1: toggle confirmation messages for wiki actions (normally redundant with another IRC bot). stewardping > 0|1: toggle response to "!steward" command (normally redundant with another IRC bot).
!exit !exit reason	Disconnect from IRC and end process.
!reset !reset reason	Delete web cookies and log back in, disconnect from IRC and reconnect.

Operator commands

Wiki-targeted commands
!block user@wiki !block user@wiki > expiry !block user@wiki > expiry > reason	Block the user on the specified wiki (with email disabled). Wiki can be 'global' or a db_prefix, and expiry can be 'never'.
!blockhide user@wiki !blockhide user@wiki > reason	Block the user on the specified wiki (with email disabled), and oversight the account name in edit histories and log entries. Wiki can be 'global' or a db_prefix.
!unblock user@wiki !unblock user@wiki > reason	Unblock the user on the specified wiki. Wiki can be 'global' or a db_prefix.
!checkuser target@wiki	[operators only] Assign checkuser access to the requesting user, and link to the checkuser form prefilled with the specified user.
!setrights user@wiki > +right1,right2 !rights user > right1,-right2 > reason	Adds or removes the specified user's right-groups, where wiki is a db_prefix. Groups are listed with commas, with '+' or '-' before a name switching between addition and removal of subsequent groups (default is addition).
CentralAuth commands
!lock name !lock; name > reason	Lock a global account.
!hide name !hide name > reason	Hide a global account.
!lockandhide name !lockandhide name > reason	Lock and hide a global account.
!unlock name !unlock name > reason	Unlock a global account.
!unhide name !unhide name > reason	Unhide a global account.
Other global commands
!gblock address > expiry > reason	Globally block an IP address or CIDR range, anonymous-users only.
!gunblock address > reason	Globally unblock an IP address or CIDR range.
!stab user	Lock & hide the global account, scan its edits on every wiki, and block all local accounts.
!stabhide user	Lock & hide the global account, scan its edits on every wiki, block all local accounts, and oversight name in local logs and edit histories.
!wikiset wikiset_id > +wiki1,-wiki2 !wikiset id > wiki1,wiki2 > reason	Add or remove the wikis to the wiki set. Wikiset_id is the numeric wikiset ID (type "!help > wikiset" for a list). Wikis are database prefixes listed with commas, with '+' or '-' before a name switching between addition and removal of subsequent groups (default is addition).
Command commands
!commit id !commit all	[operators only] Executes the specified user restricted command (or all uncommitted user commands).
!cancel id !cancel all	[operators only] Removes the specified user restricted command without executing it (or all uncommitted user commands).
!requeue	[operators only] List IDs in uncommitted queue (awaiting !commit or !cancel).
!requeue view > commit_id !requeue edit > commit_id > arg_id > value	[operators only] View or modify the queue of commands awaiting !commit or !cancel. commit_id is the command's numeric ID in the queue; arg_id is the numeric count from one of the argument you want to modify; value is the value to set for that argument.
!withlist url > command !withlist url > command > arg1 > ...	Parse a plaintext list of values at the given URL, and queue "!command > value > arguments" for each value (!commit needed). Valid with commands: block, blockhide, lock, hide, lockandhide, unlock, unhide, gblock, gunblock, setrights, stab, stabhide, unblock, wikiset, setrights.

Code documentation

Don't mind this section, just notes. This section is somewhat out of date, and will be replaced once proper code documentation is in place.

Class hierarchy

                                              ┌─────────────────┐
 ↑ abstract                                   │   __config__    │
 ↓ modules                                    └────────┬────────┘
                                              ┌────────┴────────┐
                                              │    __init__     │
                                              └────────┬────────┘
                                              ┌────────┴────────┐
                                              │    Stewardbot   │
                                              └────────┬────────┘
          ┌─────────────────────┬──────────────────────┼─────────────────────┬─────────────────────┬────────────┐
 ┌────────┴─────────┐  ┌────────┴─────────┐  ┌─────────┴────────┐  ┌─────────┴────────┐  ┌─────────┴────────┐   │
 │ Wikimedia.Browser│  │  CommandParser   │  │        IRC       │  │   Documentation  │  │       Bash       │   │
 └────────┬─────────┘  └────────┬─────────┘  └─────────┬────────┘  └─────────┬────────┘  └─────────┬────────┘   │
 ┌────────┴─────────┐           │                      │                     │                     │            │
 │      Browser     │           │                      │                     │                     │            │
 └────────┬─────────┘           │                      │                     │                     │            │
          └─────────────────────┴──────────────────────┼─────────────────────┴─────────────────────┴────────────┘
                                             ┌─────────┴────────┐
                                             │    BaseClass     │
                                             └──────────────────┘

User:Pathoschild/Scripts/StewardBot/class-header

BaseClass is inherited by all classes in the stewbot framework, and provides a common interface and internal methods. It includes an Error object (subclassing Exception) that is raised when a framework error occurs.

User:Pathoschild/Scripts/StewardBot/class-header

Browser abstracts querying, scraping, and parsing web pages and APIs, and provides high-level functions for performing actions and fetching data.

User:Pathoschild/Scripts/StewardBot/class-header

Wikimedia.Browser extends Browser with methods specific to Wikimedia wikis.

User:Pathoschild/Scripts/StewardBot/class-header

CommandParser abstracts parsing data into commands and arguments, handling configurable security, and calling command handlers.

Access levels

Commands are assigned arbitrary integer access levels, which determine who is allowed to issue them. Users can use commands whose access is less than or equal to their own access level; everyone has access level 0 by default, unless they are assigned an access level by hostmask.

Access levels are configured through the constructor. The example below adds recognition for five commands, with two arbitrary security levels in addition to the default 0. Anyone can issue help or reset commands; users with the IRC hostmask *@wikimedia/Az1568 and *@wikipedia/Bsadowski1 can use the help, reset, exit, and block commands; and *@wikimedia/Pathoschild can use all of them.

self.parser = CommandParser(
   commands = {
      0:['help', 'reset'],
      1:['exit', 'block'],
      2:['checkuser']
   },
   users = {
      1:['wikimedia/Az1568', 'wikipedia/Bsadowski1'],
      2:['wikimedia/Pathoschild']
   }
)

Committing

The CommandParser supports committing, where a user with insufficient access can issue a command to be queued until a user with commit access confirms it. The commit access level, and a list of commands that cannot be committed, can be configured through the constructor.

The following example illustrates its usage on IRC:

 user> !block some user > forever > because he sucks
  bot> user: commit id 4.
 admin> !commit 4
  bot> "some user" blocked.

Command handling

After it is configured with the constructor, CommandParser sits idly until given data through handle. This parses the data, determines whether it is a command, and determines access levels. It always returns a command data object, and also calls command handlers directly by passing the constructor a class implementing the following methods. These methods will be passed a command data object as the first positional argument.

• handle_<command> for each recognized command (for example, handle_commit for a commit command);
• handle_None, called if CommandParser gets a valid command but can't find its handler method;
• handle_Error, called if CommandParser gets a valid command but an occurred while processing it (for example, the user has an insufficient access level);
• handle_Queued, called if CommandParser gets a valid command from a user with insufficient access to issue it, but sufficient access to request a commit.

Command data object

Command data is returned in the following format:

{
   'text':'!block some user > forever > because he sucks',
   'command':'block',
   'args':['some user', 'forever', 'because he sucks'],
   'commit_id':3,
   'user_level':1,
   'command_level:2,
   'flag':MUST_COMMIT,
   'flag_type':MUST_COMMIT,
   'flag_text':None
}

• text: the unprocessed text of the command.
• command: the name of the command, extracted from the text.
• args: A list of command arguments, extracted from the text.
• commit_id: The command's numeric index in the queue, if it was queued for commit (else None); see #Access levels.
• user_level: The user's access level; see #Committing.
• flag and flag_group: constants indicating the status of the command. A human-readable explanation suitable for error output is returned by explain. Possible values:

  flag	flag_group	explain
  USER_BANNED	IGNORED	You are banned from giving me commands
  NOT_COMMAND	IGNORED	That is not recognized as a command
  BLANK_ARGS	ERROR	Arguments cannot be blank
  NOT_ALLOWED	ERROR	You have insufficient access to issue that command
  CANNOT_COMMIT	ERROR	You have insufficient access to issue that command, and it cannot be committed
  NO_SUCH_COMMIT_ID	ERROR	No commit id
  MUST_COMMIT	MUST_COMMIT	The command has been queued for !commit id
  OKAY	OKAY	The command was parsed and validated, and awaits implementation

• flag_text: a more specific human-readable error message; usually None.

Public methods

User:Pathoschild/Scripts/StewardBot/method

See also

• source code & issue tracker