Bloggity Blog

Stalker - Nickname History For IRSSI

Posted in Code

Articles for Code

Stalker is an irssi plugin to correlate information on an IRC network and discover users' previously used nicknames. The concept is fairly straightforward: given a nickname identify previously used hostnames. From those hostnames, extract all nicknames they have used. Repeat until you have identified all nicknames a user might have used. The advantage of this method over the more traditional given a hostname identify all nicknames it has used is that you can identify nicknames across hostmask addresses.

Stalker can be found on GitHub at

Why Use Stalker?

There are numerous reasons one may want this type of information at their disposal. It was written originally to identify people who were regularly evading bans, which led to the recursive search function over hostmasks.

  • Identify people evading bans
  • Locate users who are hiding from you so you can stalk them
  • Avoid users who are changing their nicknames to stalk you
  • Run SQL queries against the gathered information for statistics games

All information that is gathered is stored in an SQLite database with four columns: nickname, username, hostname, server name. One could run any type of SQL query against this information to use stalker for other purposes.

Installing Stalker

A handful of things need to be installed for Stalker to be downloaded and run. Obviously, irssi also needs to be installed and the ablity for irssi to run Perl scripts.

apt-get install git-core libdbd-sqlite libdbi-perl

Then download stalker:

symkat@symkat:~$ git clone git://
Initialized empty Git repository in /home/symkat/Stalker/.git/
remote: Counting objects: 6, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 6 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (6/6), 4.41 KiB, done.

Once the script has been downloaded, it can be installed into irssi's plugins:

symkat@symkat:~$ mkdir -p .irssi/scripts/autorun
symkat@symkat:~$ cp Stalker/ .irssi/scripts/autorun
symkat@symkat:~/.irssi/scripts/autorun$ ln -s ../ .
symkat@symkat:~/.irssi/scripts/autorun$ ls -l
lrwxrwxrwx 1 symkat symkat 13 Oct  6 19:12 -> ../
symkat@symkat:~/.irssi/scripts/autorun$ cd

Now run irssi

Let's take a look at the configuration by typing /set stalker:

19:12 -!- Irssi: Loaded stalker
19:12 [Stalker]
19:12 stalker_verbose = OFF
19:12 stalker_who_on_join = ON
19:12 stalker_search_this_network_only = OFF
19:12 stalker_max_recursion = 20
19:12 stalker_recursive_search = ON
19:12 stalker_debug = OFF
19:12 stalker_guest_nick_regex = /^guest.*/i
19:12 stalker_ignore_guest_nicks = ON
19:12 stalker_debug_log = OFF
19:12 stalker_debug_log_file = .irssi/stalker.log
19:12 stalker_db_path = .irssi/nicks.db
19:12 stalker_hide_who = OFF

Now when you whois someone, you'll have a new line, stalker:

12:24:25 -!- Irssi: Starting query in freenode with decline
12:24:27 -!- decline [] (Germany(DE))
12:24:27 -!-  ircname  : Unknown
12:24:27 __-!-  stalker  : decline_, decline.__
12:24:27 -!-  channels : #perl-cats
12:24:27 -!-  server   : [Rennes, France]
12:24:27 -!-  idle     : 5 days 5 hours 20 mins 36 secs [signon: Tue Sep 21 17:42:41 2010]
12:24:27 -!- End of WHOIS

Additionally you can use the commands /nick_lookup and /host_lookup to manually run searches.

Configuring Stalker

Stalker offers a lot of configuration variables. Let's take a look at each one:


When enabled stalker becomes more verbose, most notably it lists from where it got the nicknames shown. For example, when enabled:

12:27:00 -!- Irssi: stalker Verbose: Got nicks: decline, decline_from host
12:27:00 -!-  stalker  : decline_, decline.
  • Default: /set stalker_verbose off


When enabled each time you join a channel a WHO is issued against the channel. Stalker picks up all WHO responses, so this allows all nicknames in the channel to be recorded.

  • Default: /set stalker_who_on_join on


When enabled searches are limited to within the network the window is currently set on. Turning this off is really only useful if multiple networks don't encode the hostmask.

  • Default: /set stalker_search_this_network_only off


For each correlation between nick <-> host that happens, one point of recursion happens. A corrupt database, general evilness, or misfortune can cause the recursion to skyrocket. This is a ceiling number that says if after this maany correlation attempts we have not found all nickname and hostname correlations, stop the process and return the list to this point.

  • Default: /set stalker_max_recursion 20


When enabled, recursive search causes stalker to function better than a simple hostname to nickname map. Disabling the recursive search in effect turns stalker into a more standard hostname -> nickname map.

  • Default: /set stalker_recursive_search on


Prints debug output to irssi so you know exactly what is going on. This is far too verbose to be enabled when not actively debugging something.

  • Default: /set stalker_debug off


Some networks set default nicknames when a user fails to identify to nickserv, some irc clients set default nicknames when someone connects and often these change from network to network depending on who is configuring the java irc clients. This allows a regular expression to be entered. When a nickname matches the regular expression and stalker_ignore_guest_nicks is enabled the nickname is dropped from the search as if it had never been seen.

  • Default: /set stalker_guest_nick_regex /^guest.*/i


See stalker_guest_nick_regex.

  • Default: /set stalker_ignore_guest_nicks on


When enabled, debug messaged are recorded to the file defined by stalker_debug_log_file.

  • Default: /set stalker_debug_log off


This defined the file which debug messaged are printed to if stalker_debug_print is enabled.

  • Default: /set stalker_debug_log_file .irssi/stalker.log


This defines the path to the SQLite database where information is recorded. This database is created on loading of if it does not exist.

  • Default: /set stalker_db_path .irssi/nicks.db


When enabled all WHO responses are suppressed. If you don't normally use the WHO command and find the information sent to your client when using stalker_who_on_join is a bit too much, enable this option.

  • Default: /set stalker_hide_who off


Bugs, patches, general criticism, coffee, or any combination thereof welcome; email me:

blog comments powered by Disqus