Forked from
713 / Warden / Warden - archive
444 commits behind the upstream repository.
-
Tomáš Plesník authoredTomáš Plesník authored
README 14.80 KiB
+----------------------------+
| README - Warden Server 2.2 |
+----------------------------+
Content
A. Overall Information
B. Installation Dependencies
C. Installation
D. Update
E. Uninstallation
F. Miscellaneous
G. Registration of Clients
H. Status Info
I. Warden Watchdog
--------------------------------------------------------------------------------
A. Overall Information
1. About Warden System
Warden is a client-server architecture service designed to share detected
security events (issues) among CSIRT and CERT teams in a simple and fast way.
This package contains the Warden server.
2. Version
2.2 (2015-01-04)
3. Installed package structure
bin/
getClients.pl
getStatus.pl
registerReceiver.pl
registerSender.pl
unregisterClients.pl
wardenWatchdog.pl
doc/
AUTHORS
CHANGELOG
INSTALL
LICENSE
MANIFEST
README
UNINSTALL
UPDATE
warden21to22.patch
warden.mysql
etc/
package_version
warden-apache.conf
warden-server.conf
warden-watchdog.conf
lib/
Warden/
ApacheDispatch.pm
WardenCommon.pm
Warden.pm
WardenWatchdog.pm
sh/
uninstall.sh
--------------------------------------------------------------------------------
B. Installation Dependencies
1. Applications:
Perl >= 5.10.1
MySQL >= 5.1.72-2
Apache >= 2.2.16
2. Perl modules:
Carp >= 1.11
Crypt::X509 >= 0.40
DateTime >= 0.61
DBD::mysql >= 4.016
DBI >= 1.612
Email::Simple >= 2.100
File::Basename >= 2.77
FindBin >= 1.50
Format::Human::Bytes >= 0.05
Getopt::Long >= 2.38
Getopt::Std >= 1.06
MIME::Base64 >= 3.08
Net::CIDR::Lite >= 0.21
SOAP::Lite >= 0.715
SOAP::Transport::HTTP >= 0.715
Switch >= 2.14
Sys::Hostname >= 1.11
Sys::Syslog >= 0.27
--------------------------------------------------------------------------------
C. Installation
1. Check SHA1 checksum of the Warden server package archive.
$ sha1sum -c warden-server-2.2.tar.gz.sig
2. Untar it.
$ tar xzvf warden-server-2.2.tar.gz
3. Run install.sh.
For more information about install.sh options run install.sh -h
Usage: $ ./install.sh -d <directory> -k <ssl_key_file> -c <ssl_cert_file> -a <ssl_ca_file> -e <email_address> [-s <directory>] [-hV]"
-d <directory> installation directory
-k <ssl_key_file> SSL certificate key file path
-c <ssl_cert_file> SSL certificate file path
-a <ssl_ca_file> CA certificate file path
-e <e-mail address> e-mail address to Warden server administrator
-s <directory> directory for symlinks to Warden server control scripts (optional)
-h print this help
-V print script version number and exit
Example: $ ./install.sh -d /opt/warden-server
-k /etc/ssl/private/server.key
-c /etc/ssl/certs/server.pem
-a /etc/ssl/certs/bundle.pem
-e admin@domain.com
-s /usr/local/bin
For more information about installation process, see README file (section Installation).
4. Configuration files
You are advised to check configuration file warden-apache.conf and
warden-server.conf in 'etc' directory after installation.
For more information about post-installation steps see INSTALL file in
'doc' directory.
SOAP protocol is used for handling communication between server and clients.
Therefore, correct URI of Warden server must be set.
Authentication of clients and server is performed using client and server
SSL certificates. Both clients and server must have valid certificate.
Configuration files contain following parameters:
a) warden-server.conf:
The Warden server configuration file contains:
BASEDIR - base directory of the Warden server
e.g. /opt/warden-server/
SYSLOG - enable/disable syslog logging
e.g. 1
SYSLOG_VERBOSE - enable/disable logging in verbose mode (stack info added)
e.g. 1
SYSLOG_FACILITY - syslog facility
e.g. local7
DB_NAME - MySQL database name of Warden server
e.g. warden
DB_USER - MySQL database user of Warden server
e.g. root
DB_PASS - MySQL database password of Warden server
DB_HOST - MySQL database host
e.g. localhost
MAX_EVENTS_LIMIT - server limit of maximum number of events that can be
delivered to one client in one batch
e.g. 1000000
VALID_STRINGS - validation hash containing allowed event attributes
e.g.
'type'=> ['portscan',\
'bruteforce',\
'probe',\
'spam',\
'phishing',\
'botnet_c_c',\
'dos',\
'malware',\
'copyright',\
'webattack',\
'vulnerability',\
'test',\
'other'\
],
'source_type' => ['IP',\
'URL',\
'Reply-To:'\
]
b) warden-apache.conf
The Apache2 configuration file for Warden server:
SSLEngine on
SSLVerifyDepth 3
SSLVerifyClient require
SSLOptions +StdEnvVars +ExportCertData
SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+EXP:+eNULL
SSLCertificateFile <path_to_server_certificate>
SSLCertificateKeyFile <path_to_server_certificate_key>
SSLCACertificateFile <path_to_CA_certificate>
PerlOptions +Parent
PerlSwitches -I <path_to_warden_server_libs>
<Location /Warden>
SetHandler perl-script
PerlHandler Warden::ApacheDispatch
SSLOptions +StdEnvVars
</Location>
--------------------------------------------------------------------------------
D. Update
For update of the Warden server package from local machine use update.sh.
For more information about update.sh options run update.sh -h
Usage: $ ./update.sh -d <directory> [-shV]
-d <directory> destination directory
-s <directory> directory for symlinks to Warden server control scripts (optional)
-h print this help
-V print script version number and exit
Example: $ ./update.sh -d /opt/warden-server
For more information about post-update steps see UPDATE file.
--------------------------------------------------------------------------------
E. Uninstallation
For uninstallation of the Warden server package from local machine use uninstall.sh.
For more information about uninstall.sh options run uninstall.sh -h
Usage: uninstall.sh -d <directory> [-s <directory>] [-hV]
-d <directory> uninstallation directory of Warden server
-s <directory> directory for symlinks to Warden server control scripts (optional)
-h print this help
-V print script version number and exit
Example: $ ./uninstall.sh -d /opt/warden-server -s /usr/local/bin
For more information about uninstallation process, see README file (section Uninstallation).
--------------------------------------------------------------------------------
F. Miscellaneous
1. Error Messages
Error messages of the server functions are sent via Syslog.
Default is local7 facility.
2. Firewall Settings
Make sure that the TCP port listed in /etc/apache2/sites-enables/default(-ssl)
is allowed on your firewall.
3. Known Issues
No issues are known.
4. Database checks
If you want apply an offline checks to your received data health, you can use
the wardenWatchdog.pl script. You can found the documentation in chapter
I. Warden Watchdog in this document.
--------------------------------------------------------------------------------
G. Registration of Clients
The Warden server administrator is responsible for registering new clients or
removing those already registered. Both registration or unregistration scripts
are provided in the Warden server package. Those scripts should be run from
the same machine the Warden server is installed and running on.
Members of Warden community who would like to have their client registered must
contact the Warden server administrator with the requirement. This is usually
done via secured e-mail. Requestor should provide all important data to the
Warden server administrator so that the client can be successfully registered.
1. Register Sender
New sender clients are registered in Warden system via registerSender.pl.
Following attributes must be provided in order to register new client
successfully:
hostname - hostname of the client,
requestor - organization or authorized person who demands new
client registration,
service - name of the service of a new registered client,
description_tags - tags describing the nature of the service,
ip_net_client - CIDR the client is only allowed to communicate from,
client_id - user defined client ID (optionaly).
One can run registerSender.pl with -h argument to see a help.
2. Register Receiver
New receiver clients are registered in Warden system via
registerReceiver.pl.
Following attributes must be provided in order to register new client
successfully:
hostname - hostname of the client,
requestor - e-mail address of organization or authorized person
who demands new client registration,
type - the type of events the client wish to receive or '_any_'
for receiving of all types of events,
receive_own_events - boolean value describing if events originating from
the same CIDR will be sent to the client,
ip_net_client - CIDR the client is only allowed to communicate from,
client_id - user defined client ID (optionaly)
One can run registerReceiver.pl with -h argument to see a help.
3. Unregister Client
In the Warden system, already registered clients can be unregistered
via unregisterClient.pl.
Following attribute must be provided in order to unregister existing client
successfully:
client_id - ID of the client that should be removed (unregistered).
One can run unregisterClient.pl with -h argument to see a help.
The process of unregistration set client (specified by client_id) like 'invalid'
in DB table clients and all messages stored by this client (considering "sender"
client) are not deleted, they are merely set 'invalid' in DB table events too.
--------------------------------------------------------------------------------
H. Status Info
Functions in this section show status of the Warden server and active
(registered) clients to the Warden system administrator.
Similarly to (un)registration, these functions should be run from
localhost (e. g. from the same machine the Warden server is installed and
running on).
1. Get Status
Function getStatus is accessible via getStatus.pl. Function has no input
parameters and returns info about the Warden server, its DB status and
event's statistics of active registered senders.
2. Get Clients
Function getClients is accessible via getClients.pl. Function has no input
parameters and returns detailed information about all registered clients.
--------------------------------------------------------------------------------
I. Warden Watchdog
Warden Watchdog is a simple script for check of an Warden server DB. You can
create various SQL queries (checks) for an example for events from wrong IPs,
for events with incomplete description or for long quiet reporting clients.
Then you can run watchdog by hand or a repeatedly via Cron.
If one or more events are found by a check, than predefined information
email is sent to a person, who is responsible for a client. You can also set
a different recipient of a notification email for each check with a setting
'contact' field in a configuration file.
1. Configuration file
Each configuration file for a Warden Watchdog has four important groups
of settings. First group is clear and contains parameters such as path
to Warden server configuration file, notification email subject and
a email server configuration. Second group called SQL preconditions is
an array containing SQL queries which can be executed before Warden DB
check. Last, fourth, group called SQL postconditions is also an array
which can contains SQL queries useful for a Warden DB clean up after
a DB check.
The second group in a configuration file is a different. It is an array
of hashes with a following structure and each one performs one check.
In a query is possible to use a '\$date' variable, which will be expanded
by a Watchdog on a today's date.
@sql_queries = (
{
query => '<SQL query (check) on Warden DB>';
text => 'Text of notification email for this DB check';
contact => '<email address>' # override contact from 'requestor' column
}
)
2. Application run
You will need just a prepared configuration file and a count of days
back from now to the past. Warden database check from config will be
then run in this defined time interval.
USAGE:
/<path_to_warden_server>/bin/wardenWatchdog.pl -c /<path_to_warden_server>/etc/WardenWatchdog.conf -i 7
CRON USAGE:
33 00 * * * /<path_to_warden_server>/bin/wardenWatchdog.pl -c /<path_to_warden_server>/etc/WardenWatchdog.conf -i 7 >> /tmp/wardenWatchdog_err.log
--------------------------------------------------------------------------------
Copyright (C) 2011-2015 Cesnet z.s.p.o