peer whitelist

[Kolcha]

implemented peer whitelist feature: user can define a list of expressions describing peers (peer id + client name) allowed to connect, everything that didn't match these rules is dropped (connection is closed). suggested peer whitelist is also attached.

why: initially I wanted to drop connections from specific clients on my server, but found that there are a lot of clients with very different peer id but the same client name, or even with peer id containing just a set of random bytes (do not following any rules), so just blacklisting (banning) them is pretty problematic. allowing something and ban anything else is much simpler solution.

why I decided to check client names: there are a lot of strange clients representing itself as uTorrent (very often with insane version) or qBittorrent (usually real version) according to its peer id, but when handshake is passed and real client name is already known (string actually reported by peer, not just resolved by libtorrent based on peer id), such clients very often report that they are "libtorrent 1.1.x" or "libtorrent 1.2.x". so, just checking peer id is not enough to distinguish such clients.

see attached screenshot, here you can find some "uTorrent 5.x.y" or "uTorrent 6.x.y" clients and clients with random peer id. these screenshots from the times I collected statistics to create suitable peer whitelist, and also I was very curious what connects to my server. now I don't have code that collects such info, and info collected by that filter is not enough.

this extension/filter was created long time ago (at the beginning of December 2020), and was thoroughly tested. suggested peer whitelist was created based on statistics collected by my server with ~2k torrents during these few months. suggested peer whitelist is good enough for average user, it covers +/- well-known and "ideologically true" desktop and mobile (Android) clients.

whitelist rules are placed in external file 'peer_whitelist.txt', located in qBittorrent data directory ($HOME/.local/share/qBittorrent in case of Linux). if there is NO such file plugin is not activated. but beware, placing an empty file will drop all connections!

peer whitelist syntax is very simple - each rule is just a line containing 2 Perl-compliant regular expressions: one for peer id (first), another - for client name. tabs or spaces can be used as separator for expressions.

there is one restrictions to expressions - spaces can't be used. this is due to very simple syntax and parser for it. use \s in expressions to describe space.

everything in file is parsed! there are no any comments support, so be careful! invalid expressions just lead to not working one rule containing them, other rules keep working fine.

suggested peer whitelist (and this works on my server):

-BC01\d{2}-                         BitComet\s\d(\.\d+){1,3}
-BT[67]\w{3}-                       BitTorrent\s\d(\.\d+){1,3}
-DE[1-2]\w{3}-                      Deluge[\/\s]\d(\.\d+){2,3}(.*)?
-KT\w{4}-                           KTorrent[\/\s]\d\.\d(\.\d+){0,2}(dev)?
-TR[1-3]\w{3}-                      Transmission[\/\s]\d\.\d+(\.\d+)?$
-qB[3-4]\w{3}-                      qBittorrent[\/\s]v?\d\.\d\.\d+(\.\d+)?(\S+)?
-qB[3-4]\w{3}-                      qBittorrent(\sEnhanced)?[\/\s]\d(\.\d+){3}
-lt0\w{3}-                          (r|lib)Torrent\s0\.\d+\.\d+
TIX02\d{2}-                         Tixati(\s\d\.\d+)?
-UT(1[0-8]\d|2[0-2]\d|3[0-5]\d)\w-  [u\N{U+00B5}\N{U+03BC}]Torrent\s\d(\.\d+){1,3}
-UM1\w{3}-                          [u\N{U+00B5}\N{U+03BC}]Torrent\sMac\s1(\.\d+){1,2}
-Lr[1-3].{3}-                       LibreTorrent\s\d(\.\d+){1,3}(.*)?
-tT1\w{3}-                          tTorrent\sv\d(\.\d+){1,3}

[Kolcha]

some more technical details how it works

peer validation is done in two steps:

• on handshake (when connection only established), only peer id is validated because real client name is not known yet and peer_info.client string is string resolved by libtorrent based on peer id, it is inaccurate in most cases and should not be used for checking. if peer id is not matched any expression, connection is closed. most peers are dropped here
• when any other handler is called (very likely on_bitfield() or on_have_all()), real client name is already known. validation happens again, but that time both values (peer id and client name) are validated across all rules. this step happens for all "trusted" peers, only few tricky clients are dropped on this step

to do not cause extra CPU usage or slow down qBittorrent/libtorrent download/upload logic, filtering is automatically turning off for peers which are passed validation (actually handlers are still called, but they do nothing, no any checking/filtering process happens). peer validation logic runs only twice for each new peer for each torrent, i.e. if the same user asks two different torrents it will be validated twice, but I think this is not big deal. moreover, such scenarios require multiple connections from user, and all of them should be dropped in case of blacklisting.

filter rules are applied in order they are written in 'peer_whitelist.txt'. filtering stops when at least one match is found.

existing blacklist (ban bittorrent media players, etc.) implementation co-exists with this whitelist implementation and takes precedence.

some tips and tricks for whitelist adjustment

to whitelist anything (blacklist still will work), just place (doesn't matter add or just replace whole content) next line into 'peer_whitelist.txt':

.*   .*

for debugging purposes (or just if you are curious), to find real client name for interested peer id place next line into 'peer_whitelist.txt':

<peer id matching expression>    <any text NOT matching client name, random string is fine>

all information about banned peers is stored in SQLite database peers.db in qBittorrent data directory ($HOME/.local/share/qBittorrent in case of Linux), use any db viewer (for example SQLite Browser) software to open it.

[c0re100]

invalid expressions just lead to not working one rule containing them, other rules keep working fine.

How about logging "invalid expressions"? 🤔
Let user know if expressions is invalid.

[Kolcha]

logging was added, fortunately QRegularExpression has method isValid(). also added messages when plugin is not activated (will be shown when any torrent is added) and when no rules where loaded (due to syntax errors or empty file).

filters file absence (inability to activate plugin) is logged as INFO, invalid expression message is logged as WARNING (because this is not critical), empty rules list (but plugin was activated) is logged as CRITICAL (because torrent client becomes unusable).

all added log lines where tested.

[c0re100]

Thank you~

[yeezylife]

modified leeching client getting more and more difficult to deal with, had to use peer whitelist now.
I just wonder is there any updates on the 'suggested peer whitelist' now?
@Kolcha

[Kolcha]

@yeezylife , sorry, I'm not running the server anymore (almost 2 years yet) and even very rarely use torrent client at all, so don't have updated whitelist.

the list I posted here still can be used, but need some adjustments for version checks at least for Transmission and probably for Tixati. you can just use it as is, and monitor what was banned and then adjust.

also you can refer to this list of torrent clients I created (and maintained for a while) some time ago (as result of some statistics from my server). it is a bit messy (just because was created solely for personal use), but is contains valuable information, such as peer id examples, corresponding torrent client name, and link to the client page (where actual client version can be found). also it has some very assorted notes (mostly personal), but they still may be useful to decide what to allow and what to do not.

many of clients listed there (mostly what were faced more often on my server) were installed and their traffic was inspected with Wireshark to confirm/verify their identification information. so, the information there is +/- relevant and reliable (only entries containing '?' after names are "unsure", due to lack of information, and very low number of occurrences).

[yeezylife]

I ask chatgpt how to use regular expression and did some updates, seems to work

^-(BC01|BC02)\d{2}-             BitComet\s\d(\.\d+){1,3}
-BT[67]\w{3}-                       BitTorrent\s\d(\.\d+){1,3}
-DE[1-2]\w{3}-                      Deluge[\/\s]\d(\.\d+){2,3}(.*)?
-KT\w{4}-                           KTorrent[\/\s]\d\.\d(\.\d+){0,2}(dev)?
-TR[1-4]\w{3}-                      Transmission[\/\s]\d\.\d+(\.\d+)?$
-qB[3-5]\w{3}-                      qBittorrent[\/\s]v?\d\.\d\.\d+(\.\d+)?(\S+)?
-qB[3-5]\w{3}-                      qBittorrent(\sEnhanced)?[\/\s]\d(\.\d+){3}
-lt0\w{3}-                          (r|lib)Torrent\s0\.\d+\.\d+
^(TIX02|TIX03)\d{2}-               Tixati(\s\d\.\d+)?
-UT(1[0-8]\d|2[0-2]\d|3[0-7]\d)\w-  [u\N{U+00B5}\N{U+03BC}]Torrent\s\d(\.\d+){1,3}
-UM1\w{3}-                          [u\N{U+00B5}\N{U+03BC}]Torrent\sMac\s1(\.\d+){1,2}
-Lr[1-3].{3}-                       LibreTorrent\s\d(\.\d+){1,3}(.*)?
-tT1\w{3}-                          tTorrent\sv\d(\.\d+){1,3}
-BI[1-3]\d{3}-                     .*
-AZ[4-5]\d{3}-                     .*