PXYS - IRC Network ProxyScanner

2002-7-21 - Version 1.9

Requirements

FreeBSD 4.3 or more, NetBSD, Linux, Darwin (Mac OS X) or Solaris (not heavily tested). I would recommend FreeBSD 4.6, as lots of threads and sockets are working pretty well, and it has poll(). For systems that don't have the poll() function, pxys will emulate it using select(), so it might be a bit less efficient.
An ircd hub running ircu from 2.10.04 to 2.10.11, 2.10.10+ recommended.
Some knowledges on ircu and ircd services...

Capabilities

High rate of (mass) scans. Could handle more than 100000 scans per hour.
Run as daemon, with very low CPU time consumption, but need some RAM for big networks.
Support for Wingate, Socks v4 and v5, and HTTP proxy ("CONNECT" exploit). Pxys doesn't check for "POST" HTTP proxies, as ircu already refuses connections from this kind of proxy. The HTTP proxy ports (eg. 80, 3128 -squid-, 8080, etc.) are now configurable (and even modifiable without having the proxyscanner to restart).
Reliable scans: you will never G-line innocent users, Socks aren't only detected if the port is open, it really wait for the Socks replies. HTTP proxy, even more, are tested, ie. pxys try to connect to himself using the proxy, if it succeeds, it's a vulnerable proxy, no doubt.
Automatic G-lines: pxys automagically reissues cached G-lines for proxies, for example when a server is linking with full or proxies already found. To avoid any cached G-lines flooding, pxys queues them first, they are then progressively sent to the network. Pxys is a service for your network, its goal isn't to flood it ;-)
Pxys loads a virtual client to offer IRC operators an interface to him. The client is used to dump proxies found in a console channel, too. Commands available are mostly there for statistics purposes, as a standalone service, opers shouldn't interfere much.
Rotated daily logs for your abuse team. ;-)
Rehash feature: kill -USR1 <pid> (check example.conf file)

Guarantees

None !!! Use it at your own risk.
For your information, pxys is currently running on the Undernet IRC network (one of the biggest).

Installation

Compilation

Pxys needs some attention when it's time to compile it. The configure script contains usefull options you might or sometimes, must specify.

Your best friend is now:

  ./configure --help

Pxys doesn't have any "make install", so you use it localy. The important options are the "Optional Features" ones:

  --disable-wingate            Turn off wingate scan
  --disable-socks              Turn off socks (v4, v5) scan
  --disable-http               Turn off completely http proxy scan
                               (Ports are now specified in the conf file)
  --enable-pollemul            Turn on poll emulation (using select)
  --enable-debug               Turn on debugging mode
  --enable-profile             Generate extra code to write profile information
  --enable-dmalloc             Turn on debugging memory allocation with dmalloc
  --disable-n2k                Turn off ircu's n2k support (extended numerics and tokenization)
                               check http://coder-com.undernet.org/release.2.10.07-n2k.html
  --enable-allowp9             Force pxys to allow P9 servers on the network. This is NOT
                               recommended, as pxys doesn't support Protocol 9, but
                               sometimes it works. You have been warned.
  --disable-showcached         Show a channel message in the console channel with the IP
                               for cached proxies (glines are re-issued anyway)

  --with-maxthcon=maxthcon     Maximum number of connections per scan thread 24
  --with-nicklen=nicklen       Maximum nick length of the remote clients 9
  --with-clientq=clientq       Number of new remote clients queued in a special
                               cache (used to reduce clients search CPU time when
                               all pre-existing clients have been checked) 5000
  --with-network=network       Name of your IRC network Undernet

For example, for Undernet, I'm using something like:

  ./configure --with-maxthcon=20 --with-clientq=500000 \
              --with-network=Undernet --disable-showcached

--with-maxthcon

Maximum number of connections per scan thread. In the configuration file (pxys.conf), you will specify the number of "scanthreads" (ie. simultaneous scanning "process"). The number of IPs to be scanned is hardcoded here with the help of this option. If maxthcon is low, the scans will be faster, but the global scans rate is lower. If maxthcon is high, each scanthread is usually slower, but the global rate is faster. You need to do some test, and ajust this value and the scanthreads value for your network. Default value is 24 connections per scanthread. Perhaps it will be possible to specify this option in the configuration file in a next release...

It's not easy to explain (nor understand) in english, so this diagram might help:

--with-clientq

Since version 1.9, pxys queues all incomming users in a clientQueue, in the same time, scan threads pick up users from this clientQ to scan them. You need to be careful when setting this option, it's important. The size of the clientQ is pre-allocated when pxys starts, for more efficiency. If the clientQ is too low, some users might not be scanned! A good value is, at least:

  --with-clientq=(maximum network clients) x 2

Default value is 5000, which should be enough for small networks.

--with-network

Specify the IRC network name, eg.

  --with-network="Undernet"

--with-nicklen

By default, ircu supports 9 characters nickname length, and pxys too. If you have modified your ircd to support longer nicknames, please specify the value here. Example:

  --with-nicklen=31

--disable-n2k

This option is NEEDED if you're running an old ircu, ie. 2.10.04 to 2.10.07 (not patched). "n2k" is a major protocol change where commands are "tokens", to reduce bandwidth usage. Check this document for more infos. Pxys is made for u2.10.10 or more, so it's enabled by default. Do not disable it on 2.10.10+.

--enable-allowp9

This is NOT a recommended option. It forces pxys not to threat P9 servers as an error. Pxys doesn't have P9 support, use it as your own risk. It seems to work if your network has an old P9 channel service, for example, but that's all.

--disable-showcached

On a big network with a lot of lovely proxies, the console channel quickly start to be flooded by pxys's virtual client. If you use this option, pxys will not show cached proxies on the console channel, however, the glines are properly reissued! You will only see new found proxies.

--enable-pollemul

poll() emulation feature. Usually, this option is automagically turned on if your system doesn't have the poll() function, so you shouldn't use it.

Proxy-type configuration (--disable-wingate, --disable-socks, --disable-http)

By default, all types of proxy check are enabled (Wingate + Socks (4, 5) + HTTP proxies). It's easy to turn one or several off here. Please note that HTTP proxy ports are now defined in the configuration file (but they are ignored if you use --disable-http here...).

More...

You can customize even more your pxys by modifying the code, for example, check the file include/conf.h.

Configuration

The configuration file of pxys is pxys.conf. Use example.conf as a default configuration file, then modify it for your needs. It is documented too.

First start

pxys needs some directories around him in order to work:

data : to store cache files, statistics data files, etc.
logs : to store logs (you can change this directory name/path in the configuration file, zone "log").
logs/history : to archive logs (you can change it too)

...and the configuration file pxys.conf

By default, pxys goes to background after a few seconds. To avoid this, use "./pxys -f".

Good luck!

Stéphane Thiell (mbuna at bugged dot org)