Below is the file 'README' from this revision. You can also download the file.

Proktos
-------

Proktos is a network scanner written in Python. It makes use of threads,
and requires at least:
  * python2.3, python2.3-libxml2, nmap (to run main program)
  * xlibs-dev (for x11 plugin)
  * samba-common, smbclient (for samba plugin)
  * snmp (for snmp plugin)

Usage
-----

Edit scanner.cfg to suit your site. The defaults should be sane; follow
the pattern to add or remove plugins. You will want to change the "range"
option under "nmap" to be a space seperated list of your networks.

If your system is running out of resources during a scan, you may wish
to reduce the number of threads. The configuration option is in the
"resources" section.

Design
------

nmap has been wrapped; see nmapwrapper.py. It is run with a wrapper that
parses nmap XML output. The interface is a generator; each time a host
is found that is interesting, it is emitted via "yield". A pool of threads
is used to scan these hosts; the threads block until woken up to process
an event. If no threads are available, the host is queued.

A thread assigned a host will determine the list of plugins to be called,
and run each of them in no particular order. Results are grouped together
and then passed to any configured output plugins.

Writing plugins
---------------

If you write a plugin and would like it to be included in the proktos
distribution, please email it to me and license it under the GPL.

Plugins should be careful to stop within a reasonable period of time.
This documentation may not be complete or up to date, so if in doubt
look at the provided modules.

Specific notes;
  * attempt to use non-blocking I/O; if you want to run an external program
    and read its output use the utility function run_with_timeout
    in scan.py.
  * if you have to use blocking I/O on sockets, call socket.settimeout()
  * make sure your plugin doesn't leak filedescriptors. Call waitpid() as
    necessary; a thread calls os.wait() periodically but don't rely on it

Plugins should be installed into plugins/ and are enabled in scanner.conf.

Known issues
------------

  * doesn't seem to work properly under Debian/AMD64. You get a lot of
    pipes open (do an lsof on the process) for no good reason
    which cause it to run out of file descriptors on a large scan. A
    definite oddity is that it never says it has reaped any child
    processes - wait() doesn't seem to work properly.  (may be resolved;
    TODO check this)

Todo
----

  * some sort of database output; it would be nice if issues were uniquely
    identifyable in some way so that each run can merely update issues that
    are already in the database; this would allow integration with some
    sort of issue tracking system.

Copyright
---------

Proktos: python network scanner
Copyright (C) 2004  Grahame Bowland

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA