1. Log in to a OpenVAS server

IP Address: This is the IP address of the OpenVAS server. The field has a default value set at compile time (i.e. set to localhost were I run a OpenVAS daemon), but it can be overwritten anytime for a different OpenVAS server IP address. There is no DNS name conversion built in, so don't use names but IP addresses only.

OpenVAS Port: That's the TCP port number were the OpenVAS daemon listens. Port 9391 is standard and set as the default. Should a remote OpenVAS daemon run on a different port, it can be set here.

Encryption: The INOVASC client communication is encrypted only, no cleartext connection is possible. The encryption setting must match what is configured at the OpenVAS server (openvassd.conf: ssl_version=). If there is no entry in openvassd.conf, default is 'TLSv1'.

Username: This is the user configured in the OpenVAS server. A default user is set at compile time to correspond with a default server. It can be overwritten with any valid scanner username. For information on how to set up a openvassd user, see the manual for the 'openvas-adduser' command.

Password: This is the OpenVAS user login password. Security warning: Although the password is encrypted between INOVASC and the OpenVAS daemon, it is part of the argument hand-off between cgi's (although not visible in the URL through the POST method. This could need improvement. Maybe by means of a cookie? Would a SSL session alone be enough for protection? Your ideas are welcome).

Certificate: INOVASC also supports user authentication with a client certificate. This client certificate name is currently set at compile time. If you use password authentication, select 'None (use pass)' from the list. According to the current OpenVAS communication protocol, a password *must* be set and presented to the OpenVAS server. But it s now a random value, I usually use five stars '*****'. Client cert authentication has the same security concerns, as knowlegde of the certificate name is as good as the password. Read more in section 6.

Current issue: When the "continue" button is pressed, there is a long wait until the plugin selection screen. This is a shortcoming both in OpenVAS and Inovasc. The OpenVAS daemon sends all plugin data as a uncompressed ASCII stream, approx. 35 MBytes or more. Inovasc's current CGI technology must wait until all data has been received. This takes about two minutes time, without any feedback.

A good solution would be if the OpenVAS scanner protocol OTP could to be updated to support data compression (i.e. zlib), and Inovasc should use AJAX for asynchronous processing, eliminating the wait. (planned for next version). See also "8. Known issues".

2. Configure the OpenVAS scanner server for a new scan

After the successful login, OpenVAS sends a full set of configuration data. The data of available plugins is sorted and displayed in a table of plugin families. A checkbox in front of the family name enables a particular family. The number after the family is the number of plugins belonging to it. Be careful what and how much to enable. Besides that certain plugins have the potential to 'crash' the scan target, a scan with lot's of plugins and multiple targets can create considerable stress to networks. Enabling everything will also *substantially* increase the scan time. OpenVAS comes with an enormous number of plugins. Although some have a certain intelligence through dependencies, often they just probe nonexistent services were OpenVAS needs to wait for the network timeout before it can move on. These seconds and minutes add up and you'll risk a timeout error! The latest plugin addition to OpenVAS are so-called 'Local Security' checks that verify a systems patch level. These plugins work only if OpenVAS is able to log into the system (currently only via secure shell with passwordless public/private key authentication). Please enable these checks only if that is correctly set up with your target system. My advice is to start easy with say the 'General' section plugin group and add other groups as necessary.

Above the plugin family selection is were the scan target system IP address needs to be specified. Although a netmask field is available and suggests the possibility to scan a network, this feature is not yet implemented. Currently, INOVASC scans a single host IP only and ignores the netmask field.

By click on the 'Scan' button, INOVASC logs on to OpenVAS again and starts the scan, enabling the plugins from the selected plugin families. It then updates the scan status html page, which forwards to the results html page once the scan is complete.

3. Using Scan Templates

Scan templates are scan configuration files containing a list of plugins, their preferences and "enabled" status. They allow a fine-grained scan configuration to enable or disable single plugins rather then whole plugin families. A scan template can be generated after a normal scanner login with INOVASC at the scan configuration page. The template file generation in INOVASC is limited to a maximum of 999 files.

Once a template is selected for scanning, the OpenVAS login screen comes up to ask for the OpenVAS server login. After that, the scan configuration display highlights plugin families were at least one plugin has been selected and asks for the target IP address to scan. Then, start the scan as usual.

4. Scheduled scanning

Scans with a scan template can be scheduled using wget with a crontab entry. Here is a working example: Run a scan each saturday for host with template "Windows Systems" (is template-003.rc)

Add to the crontab of the webserver user (i.e. wwwrun) a line like this:

11 8 * * 6  wget http://localhost/inovasc/cgi-bin/"scanprocess.cgi
> /dev/null 2>&1

(make sure to remove the newlines in the crontab).

5. Most common errors:

SSL connection errors, example 1: Error SSL_connect during SSL handshake. Reason: Operation not permitted.

Check that all certificates match: client certificate and openvassd server certificate are signed by the same CA certificate and the client has the correct CA certificate available. The error also occurs when a certificate has been expired.

SSL connection errors, example 2: Error SSL_connect() during SSL handshake. 0 Input/output error || 0 No such device or address

SSL connection errors, example 3: Error connecting to OpenVAS server [ip] port on [num].

Either the remote OpenVAS server is down, firewalled, just starting up loading its plugins - or the host is just simply not reachable or doesn't even exist.

Other connection errors, example 4: Can't login to OpenVAS server.

Either your OpenVAS username or password is wrong or the OpenVAS user does not exist. You will also see a 'Bad login attempt' message in the OpenVAS server log.

Scan configuration errors, example 1: No plugin family has been selected.

You forgot to select at least one plugin family.

Scan configuration errors, example 2: These hosts could not be tested because you are not allowed to do so.

A scan server ruleset prevents you from scanning that particular host/ network. Check the scan server user rules configuration.

Scan process errors: If a scan is taking too long, the webserver can and will cut the connection through a timeout. When this happens, the web client didn't write a result page and forwards to an nonexisting document with error 404.

Increasing the timeout on the web server makes sense as scans can easily take longer than the defaults. For the Apache web server, I increased the standard timeout from 300 (seconds, equals 5 minutes) to 1800 (half an hour).

INOVASC Client Error: max number of plugins exhausted (30000).

The max number of plugins is set in inovasc.h. With the OpenVAS plugin list constantly growing, it can easily exceeding INOVASC's internal limitation. This limit can be increased, i.e. #define MAXPLUGS 40000 followed by a recompilation.

6. Restrictions and more security concerns

In the INOVASC software version I run online, the default user 'guest' is restricted to only be able to scan localhost and the official IP address of my web server. You are free to set the OpenVAS server and user name to your own system and scan with the limited or unlimited abilities of *your own* OpenVAS daemon. You'll be responsible for the scans originating from your OpenVAS daemon, since this software only provides the ability to configure and start a scan that is ultimately executed and traceable to the OpenVAS daemon IP itself.

Also, the generated scan results on this server are open to public review. Should that be a concern, feel free to download, configure and compile the source on your own system were you can control and restrict access to this scanner interface and/or the results, which is highly advisable.

7. Supported Versions

INOVASC has been reported running on all major Linux distributions and Apple's OS X. It works with all OpenVAS servers from version 4 up.

8. Known Issues

Cannot connect to server: Users of Fedora Core 4 (FC4) and up, please watch out for the SELinux functionality, now enabled by default. It will stop the Apache daemon from opening a network socket. The error you will get is: Error connecting to OpenVAS server [ip] port [num]. ... even if your opnvassd daemon is running on the localhost.

Long wait after login: When the "continue" button is pressed, there is a long wait until the plugin selection screen appears. This is a design shortcoming both in OpenVAS and Inovasc:

OpenVAS daemon "hangs": The OpenVAS transfer protocol OTP does not specify a way for the client to terminate the connection. If the connection ends premature, the OpenVAS daemon "hangs" in CLOSE-WAIT forever. This is a protocol and programming flaw, because a networked client could get disconnected anytime. It seems to depend on the openvassd version, some do a tcp time out properly.

This shortcoming could be fixed through a protocol update for OTP, adding a definition and handling for: CLIENT <|> BYE <|> BYE <|> CLIENT followed by SERVER <|> BYE <|> ACK. See also: OTP Compendium - BYE

Happy Scanning! Frank