1 What is Rscan?

Rscan is a ``Heterogeneous Network Interrogator,'' which is to say that it is a tool that lets a system administrator run complex or simple scanner scripts on any number of machines in a heterogeneous environment. Rscan allows any ``module'' to be composed of scripts that run on either any operating system that is encountered, only certain operating systems (e.g. ``IRIX,'' ``SunOS,'' etc.), or only certain versions of a particular operating system (e.g. ``IRIX 4.0.5,'' ``IRIX 5.3,'' ``SunOS 4.1.1,'' etc.).

When Rscan runs, it collects data off of these scans and writes them to a report. The reports can be written in either plain ASCII or in automatically formatted HTML. If the reports are written in HTML, any text that looks like a URL (e.g. http://www.vis.colostate.edu/rscan ) is turned into a ``live'' HyperText link in the report (spacing is kept as it was). A report can be written for either each machine that is scanned (one report per machine) or for the entire scan run (one report per network).

Rscan can either be run on each machine manually, or, through the use of command line options or configuration files, can be run on one machine and collect data off of any number of machines automatically.

2 Running Rscan

Once you unpack the Rscan distribution, the program to run is rscan in the rscan directory. Many people try to run the file scanner/scan, which is the program that Rscan runs on remote hosts, and should not be run as a stand alone application.

3 Configuring Rscan

Rscan has many, many configuration options. It is hoped that there are enough options to make it customizable enough not make it necessary for each site to heavily modify (indeed, to modify at all) the code, although I don't mind if you do modify it to meet your needs.

3.1 The magic of the modlist

The word modlist appears all over this guide, and it is an extremely important feature of Rscan. A modlist allows you to specify which modules are run on a machine, and which scans inside that module are run on that machine.

A modlist at it's most basic is a list of modules to run or the word ``any'' which is a keyword that tells Rscan to run all the modules it can find. Here is an example of a simple modlist:

Module names are separated by a single comma, with no space in between anything. This tells Rscan to run the IRIX-security module, the NetSecurity module, the crack module and the demo module.

Modlists can be more complicated and more powerful than this. Using the -list option to Rscan you can get a list of modules that are installed and a list of the individual scans that compose that module. Using these lists, you can construct a custom subset of scans to run out of each module.

Let's sat that the IRIX-security module had scans named suid, sendmail, rhosts, and xsession. Then if you only wanted to run the sendmail and rhosts scans out of that module, you could replace the IRIX-security part of the above modlist with the following:

and only those scans would be run. The scanner names are the names of the *.pl files without the .pl extension. You can also get the same result if you use the negation operator (``-'') in the modlists. The above is equivalent to:

This form of a modlists tells Rscan to run everything in the IRIX-security module except the suid and xsession scans.

A if you specify scans in a modlist, be sure not to mix the two kinds. You cannot have a modlist that contains both regular and negated scans. For instance, the modlist IRIX-security[-suid:xsession] is invalid, and would be caught by the modlist parser.

A modlist has no limit on length, though your shell may impose one. You can specify as many modules and as many scans as you want, provided that the space ` ' character doesn't show up in there, and you separate modules with the ',' character and scans with the ':' character. You may need to protect a modlist with double quotes when using them on command lines, since the `[', `]' and `:' characters are special to some shells. They should not be protected in the configuration files.

3.2 Command Line Options

Command line options are as follows:

``-ascii''

Forces the writing of ASCII reports (which is the default). This would primarily be used to override an option in the configuration file to be used.

``-cf filename''

Uses a different configuration file than the default, which is ``config/default.cf.'' If a relative pathname is supplied, then it is taken to be relative to inside the config directory, if it's an absolute path, then it's (obviously) relative to the root directory.

``-config''

This enters the interactive configuration file editor, from which you can move, rename, delete, edit, and (most importantly) test configuration files.

``-debug''

Turns on debugging output. This is handy if you are having a problem or a scan is not working properly.

``-h''

This prints a list of command line options, short descriptions of each, and information on their usage.

``-html''

Force writing of HTML reports. If reports are written in html, report filenames have a `.html' added to them (although if you specify a reportname that ends in .html then another .html will not be added).

``-list''

Lists all installed modules by short and long name, beginning the module's version number also. Every scan in that module is also listed with a brief synopsis of what it does.

``-local''

Run the scans on the local machine only. If you want to specify a modlist for the local machine and there is not a default one set in the configuration file to be used (or you are not using a configuration file), you should specify the modlist using the -modlist option.

``-machine''

Specify a set of machines and associate a location for perl and a modlist with each one. You can have as many -machine calls as you like, and overlapping machine definitions will be resolved in the order they appear... the last definition for a machine sticks. The format is as follows:

-machine host1,host2,...,hostN /path/to/perl modlist

where host1,host2,...,hostN is the set of hosts, /path/to/perl is the path to the perl executable on the machines or the word ``same'' if the perl is located in the same place as the perl that is running the Rscan process, and modlist is the modlist to associate with the hosts. Unlike the configuration file option, you must specify a modlist on the command line (you can give a modlist of ``any'' you get the defaults.

``-modlist modlist''

Sets a global modlist for all scans. This will override options set in the configuration file, and all modlists given on the command line (in -machine options).

``-nocf''

Do not even look at any of the configuration files. If this is not given, then the default.cf configuration file is used (which is overridden by the -cf option).

``-quiet''

Turns off all printing to STDOUT. This is good if you are running Rscan from a crontab file and don't want to get mail all the time about it running. Reports are still written.

``-reportdir directory''

Specifies an alternate report directory. If it is a relative path (i.e. starts with the ``.'' character), then it is taken to be relative to the directory that Rscan is in, otherwise it is taken to be relative to the root directory.

``-reportname format''

Specifies the report naming format to be used. Report name formats are a string of text (whitespace and the % character are not allowed) that can use the following substitutions:

%I	Integer time (seconds since Jan. 1, 1970)
%H	hostname or ``network''
%M	month number
%D	day of the month number
%Y	two-digit year number (ex ``95'')
%h	hour when Rscan was started
%m	minute when Rscan was started
%s	second when Rscan was started

The default reportname format is:

rscan.%H-%M.%D.%Y-%h:%m:%s

``-separate''

Write a separate report for each host that is scanned. The %H in the report name is replaced with the name of the host (which is the word ``network'' if separate reports are not being written).

``-single''

Force the writing of a single report. This is used to override the separate reports option in a configuration file.

``-tmp directory''

Use the given directory as the temporary directory when running scans on a remote machine. The default is /tmp.

3.3 Configuration Files

Basically, a configuration file is a way to collect command line options in a file. Every command line option has an equivalent configuration file option (which can be overridden by the command line options). The options are as follows:

``html reports''

Force writing of HTML reports. If reports are written in html, report filenames have a `.html' added to them (although if you specify a reportname that ends in .html then another .html will not be added).

``machine''

Specify a set of machines and associate a location for perl and a modlist with each one. You can have as many -machine calls as you like, and overlapping machine definitions will be resolved in the order they appear... the last definition for a machine sticks. The format is as follows:

machine host1,host2,...,hostN /path/to/perl modlist

where host1,host2,...,hostN is the set of hosts, /path/to/perl is the path to the perl executable on the machines or the word ``same'' if the perl is located in the same place as the perl that is running the Rscan process, and modlist is the modlist to associate with the hosts. The modlist may be left out. If it is, a modlist of ``any'' is assumed.

``modlist modlist''

Sets a global modlist for all scans. This will override options set in the modlist field for each machine definition in the configuration file.

``reportdir directory''

Specifies an alternate report directory. If it is a relative path (i.e. starts with the ``.'' character), then it is taken to be relative to the directory that Rscan is in, otherwise it is taken to be relative to the root directory.

``reportname format''

Specifies the report naming format to be used. See the description of the -reportname command line option for how to write a reportname format.

``separate reports''

Write a separate report for each host that is scanned. The %H in the report name is replaced with the name of the host (which is the word ``network'' if separate reports are not being written).

``tempdir directory''

Use the given directory as the temporary directory when running scans on a remote machine. The default is /tmp.

Configuration files can be managed and tested by invoking Rscan with the -config option. This starts an interactive file editor. Once inside, you can type ``?'' to get a list of commands, and type ``help command'' to get help on a specific command.

4 Managing Modules

I should probably put more here at some point. Run modman and type help if you need it. It's pretty self-explanatory.

5 Available Modules

There are currently three modules publicly available for Rscan.

demo

This module tests Rscan to make sure it can recover from certain errors that a scan can have, and it also makes sure that the different results a scan can return are working, and that the HTML reports are generated as they should be. This is from the author of Rscan.

IRIX-security

This module knows all the security holes that are present in IRIX 4.0.5, 5.2, 5.3 and 6.0.1 as a result of bugs in the OS, etc. It also knows how to correct them all, and will tell you how (but NOT fix things itself) to fix them. This is from the author of Rscan.

NetSecurity

This module is written by Paul Danckaert pauld@umbc.edu . The scans in this module are intended to find those things that the SATAN toolkit finds and report on how to patch them up. It also looks for several other network-related security holes and recommendations. The NetSecurity module can be obtained from http://www.umbc.edu/rscan.

6 Writing Modules

Rscan is designed so that a module can be as simple as a directory and one .pl file, or as complex as you can imagine. Writing modules is a fairly simple process. The degree of customization you put into a module will make it more or less complicated, but the basic format for a module is always the same. The best way to see how a module is written is to look at one of the publicly available modules and examine it.

6.1 Module Structure

All files related to a particular module are gathered into a single directory, which sits in the ``rscan/scanner/modules'' directory. Filenames should not contain the ` ' (space) character, the ',' (comma), or the ':' (colon) character, since these are delimiters in the parser, and the parser is not really all that smart (but it is fast ;-) Files are arranged as follows:

module/                                  Main directory for the module
       init                              Generic initialization file
       fullname                          Module's "Full Name"
       version                           Module's version number
       desc                              descriptions of all *.pl files in this directory
       *.pl files                        individual scan files (with a .pl extension)
       OSNAME1/
               init                      Initialization data for OSNAME1
               VERSION1/
                        desc             descriptions of all *.pl files
                        *.pl files       scans for OSNAME1 VERSION1
               VERSION2/
                        desc             descriptions of all *.pl files
                        *.pl files       scans for OSNAME1 VERSION2
               VERSIONn/
                        desc             descriptions of all *.pl files
                        *.pl files       scans for OSNAME1 VERSIONn
               common/
                     desc                descriptions of all *.pl files
                     *.pl files          scans for all versions of OSNAME1
       OSNAME2/
               init                      Initialization data for OSNAME2
               VERSION1/
                        desc             descriptions of all *.pl files
                        *.pl files       scans for OSNAME2 VERSION1
               VERSION2/
                        desc             descriptions of all *.pl files
                        *.pl files       scans for OSNAME2 VERSION2
               VERSIONn/
                        desc             descriptions of all *.pl files
                        *.pl files       scans for OSNAME2 VERSIONn
               common/
                     desc                descriptions of all *.pl files
                     *.pl files          scans for all versions of OSNAME2
       OSNAMEn/
               init                      Initialization data for OSNAMEn
               VERSION1/
                        desc             descriptions of all *.pl files
                        *.pl files       scans for OSNAMEn VERSION1
               VERSION2/
                        desc             descriptions of all *.pl files
                        *.pl files       scans for OSNAMEn VERSION2
               VERSIONn/
                        desc             descriptions of all *.pl files
                        *.pl files       scans for OSNAMEn VERSIONn
               common/
                     desc                descriptions of all *.pl files
                     *.pl files          scans for all versions of OSNAMEn

All or none of each directory and file needs to be present. The desc files should be present, since they are used by the -list command line option. The files fullname and version should also be present, since they are used in reports and other things.

6.2 The Rscan API

Rscan has a set of functions for writing to the screen, reports, and performing other tasks. These functions should be used if applicable, and writers of modules are invited not to rewrite them, since it makes life hard when a new version of Rscan comes out with some changes.

6.3 API functions

&pcheck( LIST)

The string formed by the joining of LIST is written to the check list. This function should be used to signal the current test that is being run. There can be more than one &pcheck call in a scan, but each one should have a corresponding call to one of the result functions (&passed, &failed, &warning, and &info). If there are two calls to &pcheck without a result function call in between or if a scan exits with an unresolved call to &pcheck, Rscan catches this and inserts an error condition (with &error).

&passed

This signals that the last test should be marked as passing.

&failed

This signals that the last test should be marked as failing.

&warn

This signals that the last test should be marked as a warning.

&info

This signals that the last test should be marked as informational.

&report( LIST)

The string formed by the joining of LIST is written to the report file. This function should be used to write messages to the report file. There is no need to write different things for an ASCII and an HTML report, since Rscan takes care of formatting for you. If reports are being written in HTML, then text printed using this function will be ``linkified'' -- i.e. any text that looks like a URL will be turned into a ``real'' URL automatically when it's written to the report.

&screen( LIST)

The string formed by the joining of LIST is written to the screen. This function should be used to write messages to the screen about what is happening. It is not recommended for use in scans, but primarily in the init files for a module.

&center( LIST)

Returns the joining of LIST centered on a 65 character page.

&nprint( space, text)

Returns the text text left justified in a field space wide, padded with spaces. This function is good for making formatted tables in reports, etc.

&header( headername, Value1,..., ValueN)

Places a header field named headername in the report's header section for the current machine. The values Value1 ... ValueN are placed to it's right such that they appear as follows in the report's header:

headername:              Value1
                         Value1
                         ValueN

and so on. There is no limit to how many values can be specified, other than those imposed by perl itself. The text for the headername is printed using &nprint in a 25 space wide field, and successive text is indented 25 spaces.

&rawheader( LIST)

The text formed by the joining of LIST printed without any additional formatting into the header section of the report. This could be used to place some text centered in the header, etc.

6.4 API variables

Most API variables are all collected in the %api hash table. Variables of particular interest are:

$api{'whereami'}

This is the directory that the current script is located in. This seems pretty lame, but the script files move around depending on where the temp directory is located, etc. This variable should be used, for instance, when opening a database associated with a scan, and when doing other operations.

$api{'scanmode'}

This is either set to local or remote depending on whether the scanner is running locally or remotely.

$api{'scannerdir'}

This is set to the base directory that the scanner running in. It is usually something like /tmp/scanner or /var/tmp/scanner.

$api{'outformat'}

This is either set to ascii or html depending on whether the reports are being written in ASCII or HTML. Again, it is not recommended that you write different text for ASCII and HTML reports, but this variable is here in case you want to.

$api{'perlversion'}

This is set to the version number that perl thinks it is.

$api{'now'}

This is set to the integer time (the number of seconds since January 1, 1970) that perl was started at.

$api{'time'}

This is set to the human-readable time that looks something like ``Friday, January 1, 1970 at 05:22:44 pm''

There is also a %os hash table that contains information about the operating system of the machine running the scanner. Here are the common %os variables, and some other that pertain to the os and the machine in general.

$os{'name'}

The name of the operating system. Something like IRIX or SunOS.

$os{'version'}

The version of the operating system. Something like 4.0.5 or 6.0.1.

$os{'patchlevel'}

The operating system's patch level.

$machine

The shortname of the machine. Usually the output of ``/bin/uname -n.''

$cpu

The machine's CPU type.

$rsh

The location of the rsh utility.

$tar

The location of the tar utility.

$tar_create

The command line options necessary to have tar create an archive.

$tar_extract

The command line options necessary to have tar extract an archive (non-verbosely).

$gzip

The location of the gzip utility.

$gzip_extract

Command line options to give gzip to extract an archive to STDOUT (so you can pipe it to tar).

$remove

How to delete files and directories. Usually something like ``/bin/rm -rf.''

6.5 Porting Rscan to a new OS

In general, Rscan should run on any UNIX OS that has either perl 4 or 5 installed on it. There is one operating system dependent file that has to be created for each ``new'' operating system that Rscan will be run on. This file is called the ``pathconfig'' file for the OS, and is located in the scanner/pathconfig directory and must be called whatever ``/bin/uname'' outputs for that OS.

It should contain definitions for how to obtain the variables in the %os hash table (name, version, etc). You should model it after the others in the pathconfig directory. The really important options are the definition of where rsh and tar and how to extract a tar archive. Read through a few of the other pathconfig files to get a feel for how to write one, and give it a shot... the worst thing that can happen is that Rscan will not run the scans properly!

7 Availability

Rscan is completely free. It can be anonymously ftp'd from ftp://ftp.vis.colostate.edu/pub/rscan . The file rscan.tar.gz will always be a link to the current version of Rscan. The WWW homepage is located at http://www.vis.colostate.edu/rscan and has lots of information about Rscan including sample reports, etc.

The IRIX-security module and the demo module can be obtained from the same source as Rscan.

The Rscan mailing list can be joined by sendmail mail to majordomo@vis.colostate.edu with the following text in the body:

The list is moderated by the author, and is extremely low traffic. It only carries announcements of new versions of Rscan and of Rscan modules. It is also archived at http://www.vis.colostate.edu/cgi-bin/mail2html/list/rscan-announce .

There is an automated RFE (Request For Enhancement) and Bug Reporting facility also. It is available from http://www.vis.colostate.edu/cgi-bin/rfebug .

8 About the Author

I am a 19 year old sophomore at Colorado State Univerity and am also the System Administrator for the Computer Visualization Laboratory, where I take care of nine SGI's, three Suns, a mac, a PC, and an Amiga, along with some assorted video equipment, etc. I am majoring in Computer Science, and will be graduating in the spring of 1997 with a major in CS and minors in Mathematics and General Philosophy.

About this document ...

Rscan User's Guide Version 1.4.0

This document was generated using the LaTeX2HTML translator Version 95.1 (Fri Jan 20 1995) Copyright © 1993, 1994, Nikos Drakos, Computer Based Learning Unit, University of Leeds.

The command line arguments were:
latex2html tempfile.tex.

The translation was initiated by Nate Sammons on Sun Apr 2 17:18:55 MDT 1995