Qualys Connector Configuration Guide

Creating or Identifying a QualysGuard Report Template

Log into your QualysGuard account and identify a report template you want to work with. Report templates specify parameters for a vulnerability report, such as the subnets or asset groups for the data you are interested in. If you want to learn more about report templates and creating or configuring them, consult the Qualys documentation or work with your Qualys administrator.

Initially, you may want to use a template containing a small number of hosts. Work with your Qualys administrator to figure out how many hosts are in each template. The Asset Search feature in the Qualys GUI gives you information on the size of each asset group.

Obtaining a QualysGuard Report Template ID

After you identify a report template, you need its ID. To get the ID, log into your QualysGuard account and select Report Templates on the lower left, in the Tools section. Put your pointer on the Info button of the template you are interested in. Review the URL in the status bar of the browser. The URL will look something like this:

The template ID is the number after id= in the URL. In this example, the ID is 424242.

System Requirements

These are the minimum requirements for the Connector host:

• Dual core processor running at 2.4 GHz
• 2 GB RAM
• Linux or UNIX operating system
• Perl installed

If you are importing Qualys reports with a large number of hosts, it is recommended that you add more memory. A 2GB host should be able to process data for up to 10,000 hosts.

When the Connector is running, it may affect other concurrently running applications. Cisco recommends that you schedule the Connector to run when other applications are not running.

Installing the Required Components

Step 1 Verify that the Connector host has Perl installed, version 5.12.4 or later. The Qualys Connector is written in Perl, so it requires Perl on the Connector host. Consult your operating system documentation for installing Perl.

Step 2 Install or verify that the Connector host has specific Perl modules installed. These modules are:

• IO::Socket::SSL, version 1.5.3 or later
• XML::Twig, version 3.39 or later
• Net::IP, version 1.25 or later
• YAML::XS, version 0.38 or later
• LWP::UserAgent, version 6.03 or later
• Net::SSL, version 2.84 or later

Install the following optional Perl module if IPv6 support is needed:

• IO::Socket::INET6, version 2.71 or later

Tip See Table ii-4 for more information on proxy settings.

Cisco recommends that you use an OS-specific binary mechanism to download the modules such as apt, rpm, and so on. If you install the modules via CPAN or source code, you will also need to install a C compiler and the development version of OpenSSL on the Connector host.

Installing the Connector

Step 1 Copy the Connector zip file that you downloaded (qualys-connector- version.zip) to your host.

Step 2 Extract the files using a utility that extracts .zip archives.

Configuring the Connector

Most configuration parameters are located in QualysGuard.yaml in the InputPlugins subdirectory. The parameters are stored as a set of key value pairs in the YAML format.

The following parameters must be set in QualysGuard.yaml :

You can set the following optional parameters in QualysGuard.yaml. If a parameter is omitted, it is set to its default value.

Set the following optional parameters in QualysGuard.yaml for proxy support. These parameters do not have default values.

Here is a sample YAML file:

Checking the Version of the Connector

You can display the version of the connector by running the connector script without any options:

The version is in the top line of the output followed by script information, as in the following sample:

Configuring Host Input Client Authentication

The Management Center must be configured to listen for connections from the Qualys Connector. You must add the Connector host to the Management Center's peers database from the Host Input Client page. You must also copy the authentication certificate generated by the Management Center for the Connector host.

The steps required are listed in Chapter 4 of the Host Input API Guide, but are repeated here for convenience:

Access: Admin

Step 1 Select System > Integration > Host Input Client.

Step 2 Click Create Client.

Step 3 In the Hostname field, enter the host name or IP address of the host running the host input client.

Note If you use a host name, the host input server must be able to resolve the host to an IP address. If you have not configured DNS resolution, you should configure it first or use an IP address.

Step 4 If you want to encrypt the certificate file, enter a password in the Password field.

Step 5 Click Save.

The host input service allows the client computer to access port 8307 on the Management Center and creates an authentication certificate to use during client-server authentication. The Host Input Client page reappears, with the new client listed under Host Input Clients.

Step 6 Click the download icon () next to the certificate file.

Step 7 Save the certificate file to the directory used by your client computer for SSL authentication.

The client can now connect to the Management Center.

Verifying Host Connectivity

The Connector host acts as a client and initiates a TCP connection to port 8307 on the Management Center. You must therefore ensure that routing is properly configured between the hosts and that there is not a firewall or other network device blocking traffic to port 8307 on the Management Center.

To test network connectivity, you can run this command on the Connector host:

You should see results similar to this:

Configuring Vulnerability Correlation

You must ensure that the Management Center is performing impact flag correlation with QualysGuard vulnerabilities. This should already be configured by default, but you should check the setting if you encounter any issues while correlating with QualysGuard vulnerabilities.

On the Management Center, select Policies > Network Discovery, and click the Advanced tab. Under Vulnerabilities to use for Impact Assessment, the Use Third Party Vulnerability Mappings option should be set to Yes.

You must set Use Third Party Vulnerability Mappings to Yes only if you want to correlate with vulnerability mappings that you specifically created in the User 3rd Party Mappings section. You can leave it checked it if it is already checked.

To change the setting, click the edit icon (). The Edit Vulnerability Settings menu appears and shows the current selection. Change the selection and click Save. See “Managing System Policies” in the Firepower System User Guide for more information about creating and editing system policies.

Working with a Single Report Template

The main script to download and process QualysGuard data is qualys_connector.pl. Here is its syntax:

where plugin defaults to QualysGuard if it is not specified.

The following table lists the command line options. You can use the indicated option abbreviations to reduce typing. If you do not include a given option, the qualys_connector.pl script uses the default value. Examples that follow show the option syntax.

Examples

This is the simplest form of the command. It assumes that a .pkcs12 file exists in the local directory and the QualysGuard YAML file is located in InputPlugins/QualysGuard.yaml. The Management Center IP address is 10.10.10.10.

The following is the same command with the assumed options explicitly stated:

The following command dumps a CSV file of commands to transfer QualysGuard data instead of communicating with the Management Center:

The previous command can also be shortened with abbreviations as follows:

Note that the default of all these commands is to log output to standard out. If you want to log to a file or syslog instead, you can use either the -syslog or -logfile log_name options or both of those options.

The default log level of 2 generates high-level log messages. You can also set the log level to 3, which generates detailed information about every vulnerability that is imported.

Working with Multiple Templates

If you want to download and process multiple report templates one at a time, you can use the process_multiple.pl script. The syntax is as follows:

Note that the template IDs are separated by commas, but the list of IDs must not contain any spaces.

Here is an example:

Also, if you specify the -csvfile option, the process_multiple.pl script prepends the template ID to the CSV file. For example, if you run this command:

The resulting CSV files are named 424242_Output.csv and 535353_Output.csv.

Automating Connector Operation

Because connector operations are performed by scripts, they can be automated by UNIX or Linux cron or launchd. See your operating system documentation for more information about how to configure these services. You are encouraged to call out file names and command line options as explicitly as possible.

For example, your crontab file can contain a command similar to the following, assuming that the Connector files are located in /usr/local/qualys :

Problems with Initial Configuration

If you encounter problems running the connector script and downloading Qualys reports, check these items:

Step 1 You have not installed all the prerequisite Perl modules. If any library is missing, you see this error message along with the missing modules:

You must install whatever modules are missing. It is highly recommended that you use an OS-specific binary mechanism to download the modules, such as apt, rpm, and so forth.

Step 2 You have not specified the correct YAML file. The default YAML file is InputPlugins/QualysGuard.yaml. If you use a different file, you must explicitly specify it using the -plugininfo command line option.

Problems with Downloading QualysGuard Reports

The first step in processing QualysGuard reports is to download them. If the Connector host generates any error messages in this stage, check the following items:

Step 1 Check that you have entered a valid user name and password in InputPlugins/QualysGuard.yaml. If your password has any non-alphanumeric characters, put the password in single quotes.

If your username or password is incorrect, you may see this message:

Step 2 Check that you have entered a valid report template ID. Log into your QualysGuard account and confirm that you have the correct ID.

If your template ID is not correct, you could see this message:

Step 3 Check that the Connector host has network access to download QualysGuard reports. If Qualys is storing your reports and you are not storing your data locally, the host must be able to access port 443 on qualysapi.qualys.com. Verify that network access is not being prevented by firewall, proxy, or routing policies.

Problems with Sending QualysGuard Data to the Management Center

After the Connector host has downloaded the QualysGuard report data and processed it, the host will display this message: QualysGuard Report Processing Complete. At this point the Connector is ready to send data to the Management Center and continues to generate appropriate status or log messages.

If the Connector cannot send data to the Management Center, or if no hosts in the Management Center network map have any QualysGuard vulnerability data, check these items:

• Verify that you have a valid network connection between the Qualys host and the Management Center and that you can access port 8307 on the Management Center. To test this, type telnet Management_Center_IP 8307 on the host command line prompt. You should be able to establish a connection.
• Verify that you have copied a.pkcs12 certificate from the Management Center to the directory on the Connector host containing the qualys_connector.pl script. You should have created this certificate on the Host Input Client page on the Management Center. For best results, ensure that you only have a single.pkcs12 file in the directory. If you have more, the authentication process may be using the wrong one.
• Check that the Management Center has a sufficient number of host licenses installed. The Management Center must have one host license for every host that has QualysGuard vulnerability data.
• Open your YAML file (for example, InputPlugins/QualysGuard.yaml) and check the add_host parameter. If you are downloading vulnerability data for hosts that do not yet exist in the Management Center network map, this parameter must be set to y or yes. Otherwise, these hosts are not added to the network map.