# Rscan User's Guide Version 1.4.0

Nathaniel Sammons
Colorado State University
nate@vis.colostate.edu

Sun Apr 2 17:19:08 MDT 1995

# 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:

`IRIX-security,NetSecurity,crack,demo`

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:

`IRIX-security[sendmail:rhosts]`

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:

`IRIX-security[-suid:-xsession]`

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:

`subscribe rscan-announce`

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 LaTeX2`HTML` 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