***********************
* Welcome to QuIDScor *
***********************
About QuIDScor v1.2.48
**********************
QuIDScor(TM) is an open source tool for correlating Snort(TM) IDS events with
vulnerabilities detected by QualysGuard, Qualys' vulnerability management
web service.
QuIDScor verifies IDS events against QualysGuard vulnerability assessment
reports. When an IDS event is received, QuIDScor will retrieve any relevant
reports from QualysGuard on the host/service in question and correlate this
information against the incoming event.
New for v1.2
************
This release includes a number of enhancements and new capabilities designed
to improve accuracy, performance, and manageability:
- Classification of alerts into three categories: Validated, Unknown, and
Invalidated
- Correlate using information about services and applications
- User-defined mapping file for ID, service and application mappings. For more
information, see the "QuIDScor Custom Mapping Guide" section below.
- Performance enhancements, including:
- Offline processing of Snort-fastlogs
- Reprocessing of QuIDScor-logs
- Separate processes for correlation and communication to QualysGuard
Configuration Overview
***********************
The basic configuration overview for a simple class C network
of 192.168.240.0/24 could look like this:
A) QualysGuard is configured to run a scheduled scan on 192.168.240.0/24
on a regular basis.
B) Snort IDS is configured to monitor this same network block.
Note: QuIDScor must be run on the same machine as the Snort daemon.
C) QuIDScor must be able to reach the QualysGuard server to analyze reports.
Prerequisites
*************
The QuIDScor code has been tested with the following:
Operating System
----------------
Linux x86 (RedHat 7.2 - 9.0)
MacOS X
Solaris 2.8 sparc (SunOS 5.8)
Compiler/Tools (for source release)
--------------
GNU Make
gcc
Libraries
---------
libxml2 (2.4 or later (tested with 2.5.11)) (--> http://xmlsoft.org)
libcurl (7.10 or later (tested with 7.10.7)) (--> http://curl.haxx.se)
IDS
---
snort (2.0 or later (tested with 2.0.1)) (--> http://www.snort.org)
QuIDScor Installation
*********************
1) Review the QuIDScor prerequisites.
2) make && make install
(Source release compilation. You may need to adjust the paths in
the Makefile. See also the FAQ.)
3) Edit /usr/local/etc/quidscor.conf (copy from the quidscor.conf.sample)
a) Configure QGSERVER to use your QualysGuard username/password
Note: If you are an enterprise customer, it is highly recommended that
you create a new reader account for QuIDScor rather than using your
personal login credentials (NEW in QualysGuard 2.17 and QuIDScor 1.2)
b) Configure LOGDIR to point to a directory where you want to store logs.
By default, logs are stored in /var/log/quidscor.
c) Configure CACHEDIR to point to a directory where you want to store
cached QualysGuard reports. It is recommended that you store cached
reports on a cryptographic filesystem if possible. By default, these
reports are stored in /var/run/quidscor/cache.
d) Configure RULESDIR to point to your IDS signature directory
(where the .rules files referenced in your snort.conf reside).
e) Configure MODE to use QuIDScor for realtime processing (MODE snort),
where it receives the alerts via a UNIX-socket from Snort, or (MODE log)
for the processing of log-files (reprocessing of QuIDScor logfiles,
processing of Snort logfiles saved in fastlog-mode).
Also configure SOURCE to indicate the location of the log file or socket
(by default /var/log/snort/snort_alert).
f) Configure EXPIRETIME in seconds to set the expiration time of the
cache (reports from QualysGuard + mappings) after which it has to
be refreshed. The cache has to be kept at least for at least 1 hour and
is kept 1 day by default.
g) Configure CUSTOMMAP to indicate the location of the custom mapping file.
h) Configure IPGROUP to indicate which GualysGuard group to use to
determine the IPs to fetch VA data for. Reports for the hosts in the
defined group are prefetched at startup and refetched from QualysGuard
when the cache is refreshed.
4) Run "quidscor -c /usr/local/etc/quidscor.conf -D" to run the server
in daemon mode. Or run with "-d" (debug mode) to receive more diagnostics
messages.
Snort Configuration Notes
**************************
A) make && make install.
B) Run snort using "output alert_unixsock" in your snort.conf or pass
the "-A unsock" option on the command line (and a valid -c config file).
C) Run "quidscor -h" to get accustomed to the available options & features.
Most configurations will call for something like:
/usr/local/sbin/quidscor -c /usr/local/etc/quidscor.conf
or
/usr/local/sbin/quidscor -D -r /snort/rules/ -u my_qualysguard_name \
-p my_qualysguard_password
The "-D" option tells QuIDScor to run in daemon mode. The "-r" option tells
QuIDScor which directory the snort rules live in, and the "-u" and "-p" options
specify the QualysGuard username and password. If you don't want to specify the
password on the command line, you can omit the "-p" option and then you will be
prompted for the password.
Security Recommendations
************************
For optimum security it is recommended you ensure (with a firewall) that the
machine can only connect back to QualysGuard (qualysguard.qualys.com on port
443).
We also recommend you run both Snort and QuIDScor as a non-privileged user
(non root). For this to work properly, you need compatible file permissions.
Please insure that Snort has read and write access to the Unix socket file:
/var/log/snort/snort_alert
(This Unix socket is recreated each time QuIDScor is started. But Snort
does not create the socket if it does not already exist.)
QuIDScor must also have read access to the Snort rules directory (RULESDIR) in
order for it to receive and analyze the alerts properly from Snort.
Please also note that for improved performance a cached copy of relevant
QualysGuard vulnerability assessment (scan) reports is maintained on the file
system. Make sure the system is secure (Use the latest security patches for
snort and the OS components, etc...).
Output Format and Details
*************************
The format of the log files is as follows:
1 line per alert (event)
Each line is a set of fields, semicolon separated, as follows:
date; correlation-type; ids rule id; ids alert name; ids alert classification;
ids priority; protocol; source ip:port; destination ip:port; qualys id; cve id
"correlation-type" gives details on how QuIDScor interpreted the alert:
For alerts_validated.log, the possible values are :
VULN-ONPORT-VERIFIED : The CVE ID matched a previously detected
vulnerability on a specific port. The port was
also specified in the IDS alert and matched.
These alerts represent attacks against
vulnerable hosts and should be assigned the
highest priority for response.
THREAT-ONPORT-VERIFIED : The CVE ID matched a previously detected
possible threat on a specific port. The port was
also specified in the IDS alert and matched.
These alerts represent attacks against
vulnerable hosts and should be assigned the
highest priority for response.
VULN-VERIFIED : The CVE ID matched a previously detected
vulnerability, but there was no additional
port information. Either the report from
QualysGuard contained no port information at
all because of standard ports (Netbios), or
the network protocol does not use ports.
These alerts represent attacks against
vulnerable hosts and should be assigned the
highest priority for response.
THREAT-VERIFIED : The CVE ID matched a previously detected
possible threat, but there was no additional
port information. Either the report from
QualysGuard contained no port information at
all because of standard ports (Netbios), or
the network protocol does not use ports.
These alerts represent attacks against
vulnerable hosts and should be assigned the
highest priority for response.
PORT-WARNING : There is no CVE ID in the alert that can be
used for correlation, and QualysGuard
indicated that the Port is closed. As the IDS
recognizes the TCP connection as established,
QuIDScor classifies the detected attack as
successful although there is no information
from QualysGuard.
APPLICATION-VERIFIED : There is no CVE ID in the alert that can be
used for correlation, but correlation of the
application was successful. Currently
reports from QualysGuard only contain
information about the type of web
server (i.e.: IIS, Apache,..). Due to this
restriction, this classification indicates
that the attack is based on TCP and aimed at
a specific web server, which was identified as
being present by QualysGuard.
TCP-SERVICE-VERIFIED : There is no CVE ID in the alert that can be
used for correlation, but the TCP service was
mapped successfully and was detected by
QualysGuard.
Service mappings can only be processed if
the mapping information is set in the custom
mapping file.
UDP-SERVICE-VERIFIED : There is no CVE ID in the alert that can be
used for correlation, but the UDP service was
mapped successfully and was detected by
QualysGuard. Service mappings can only be
processed if the mapping information is set
in the custom mapping file.
TCP-PORT-VERIFIED : There is no CVE ID in the alert that can be
used for correlation, but the TCP port was open.
These alerts have a lower probability of
success since no corresponding vulnerability
was detected on the target host. Since the
attacked port was reported open on the target
host, the incident should be tracked.
UDP-PORT-VERIFIED : There is no CVE ID in the alert that can be
used for correlation, but the UDP port was open.
These alerts have a lower probability of
success since no corresponding vulnerability
was detected on the target host. Since the
attacked port was reported open on the target
host, the incident should be tracked.
For alerts_unknown.log, the possible values are :
NO-REPORT-FOUND : No vulnerability data was available for the
target IP address. This host should be assessed
immediately with QualysGuard in order to
provide data for correlation against future
Snort alerts.
NO-VERIFICATION : There was no previously detected vulnerability
with a CVE matching that of the IDS alert on
the target host, and the attacked service was
neither UDP nor TCP based.
For alerts_invalidated.log, the possible values are :
NO-VULN-VERIFIED : There is no previously detected vulnerability
with a CVE matching that of the IDS alert on
the target host.
NO-APPLICATION-VERIFIED : There is no CVE ID in the alert that can
be used for correlation, but the Port was
reported as open. The service and the
application could be mapped, but the application
reported by the IDS was not found by
QualysGuard.
NO-TCP-SERVICE-VERIFIED : There is no CVE ID in the alert that can
be used for correlation, but the Port was
reported as open. The TCP service was
successfully mapped. The Snort alert says the
service was running but the QualysGuard
indicates it was not there.
NO-UDP-SERVICE-VERIFIED : There is no CVE ID in the alert that can
be used for correlation, but the Port was
reported as open and the UDP service was
successfully mapped. The Snort alert indicates
that the service was running but the QualysGuard
report tells the opposite.
NO-TCP-PORT-VERIFIED : The attacked TCP port was not found open by
QualysGuard.
NO-UDP-PORT-VERIFIED : The attacked UPD port was not found open by
QualysGuard.
NOTE: The above might constitute valid attacks if for some reason the port is
open to the attacker and not to QualysGuard.
Only verified vulnerabilities are used for matching, possible threats and
information gathered are not.
QualysGuard scans by default 1800 of the most common ports. Through the user
interface, the ports to be scanned can be configured to perform up to the full
TCP port scan of 65536 ports.
QuIDScor Custom Mapping Guide
*****************************
QuIDScor basically maps the IDS alerts and the reports from QualysGuard
by using CVE IDs. Unfortunately CVEs often are not included in one input,
so the alert cannot be mapped automatically.
For this reason, QuIDScor offers the possibility of custom mapping
information. You can indicate to QuIDScor where to find the custom mapping
file in the configuration file under CUSTOMMAP. You can start from the
snortmap.xml provided in the distribution and installed by default
in /usr/local/etc/snortmap.xml which already contains useful mappings for
services and applications (web servers) correlation.
The custom mapping file has to be in XML-structure. The root element is
<MAP> and the mappings are done by <IN> and <OUT> tags.
A) SERVICE MAPPING
If the correlation through a CVE does not work, a test of service
matching is often possible. For instance using:
<IN TYPE="SERVICE" VALUE="WEB-">
<OUT TYPE="SERVICE" VALUE="http"/>
</IN>
In this example, if the snort alert message contains "WEB-", it is mapped
to the service "http" (as QualysGuard defines it in the reports). With
such a mapping, QuIDScor is able to verify if the service matches when
without this mapping it could only verify the port. When using this type
of additional correlation, the possible additional results are
TCP-SERVICE-VERIFIED, UDP-SERVICE-VERIFIED, NO-TCP-SERVICE-VERIFIED,
NO-UDP-SERVICE-VERIFIED as described in the Output Format and Details
section of this document.
B) APPLICATION MAPPING
If the service has been verified, it is also possible to do an application
mapping. For this you also add entries such as:
<IN TYPE="APPLICATION" VALUE="WEB-Apache">
<OUT TYPE="APPLICATION" VALUE="Apache"/>
</IN>
In this example, the string "WEB-Apache" in the Snort alert is then mapped
to the application "Apache" as indicated in the QualysGuard reports.
The additional possible results when using this type of mapping are:
APPLICATION-VERIFIED or NO-APPLICATION-VERIFIED.
Keep in mind that an application mapping is only used when direct IDS
id to VA id mapping is not available. Likewise in order for the application
mapping to be used, the service must have already been successfully
correlated.
C) custom SNORTID-TO-QUALYSID-MAPPING
It is also possible to directly map Snort IDs to QualysGuard IDs:
<IN TYPE="ID" VALUE="1256">
<OUT TYPE="ID" VALUE="86170">
<COR ID="CVE-2001-0500"/>
</OUT>
</IN>
In the example, the IDS alert with the SID=1256 is mapped to the
QID=86170. You can even indicate where the correlation comes from for
instance using a CVE# using the <COR> tag but this is not mandatory.
Usually you can just use the <IN> and <OUT> tags in this type of custom
mapping.
*************************************************
* Consult the FAQ for additional help/questions *
*************************************************
# Document Version $Id: README.in,v 1.32 2003/10/09 18:19:13 ldemailly Exp $
