+----------------------------+
| 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

--------------------------------------------------------------------------------
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 (2013-??-??)
    
 3. Package structure
 
    warden-server/
      bin/
	getClients.pl
	getStatus.pl
	registerReceiver.pl
	registerSender.pl
	unregisterClients.pl
      doc/
	AUTHORS
        CHANGELOG
	INSTALL
	LICENSE
	README
	UNINSTALL
	UPDATE
	warden.mysql
	warden20to21.patch
      etc/
	package_version
        warden-apache.conf
	warden-server.conf
      lib/
	Warden.pm
	WardenCommon.pm
	Warden/
	  ApacheDispatch.pm
      uninstall.sh


--------------------------------------------------------------------------------
B. Installation Dependencies
 
 1. Applications:

    Perl	>= 5.10.1
    MySQL	>= 5.1.63
    Apache	>= 2.2.14

 2. Perl modules:

    SOAP::Lite			>= 0.712
    SOAP::Transport::HTTP	>= 0.712
    DBI				>= 1.612
    DBD::mysql			>= 4.016
    Format::Human::Bytes	>= 0.05
    Sys::Syslog			>= 0.27
    File::Basename		>= 2.77
    Net::CIDR::Lite		>= 0.21
    DateTime			>= 0.61
    Getopt::Std			>= 1.06
    Switch			>= 2.14
    IO::Socket::SSL 		>= 1.66
    MIME::Base64 		>= 3.08
    Crypt::X509 		>= 0.40
    Carp 			>= 1.11


--------------------------------------------------------------------------------
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. 
  
    Default installation directory is /opt/warden-server/
    
    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>] [-hV]"
	-d <directory>            installation directory (default: /opt)
	-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
	-h                        print this help
	-V                        print script version number and exit
	
    Example: # ./install.sh -d /opt -k /etc/ssl/private/server.key
                            -c /etc/ssl/certs/server.pem                            
			    -a /etc/ssl/certs/bundle.pem

    You must be root for running this script.

 4. Configuration files
  
    You are advised to check configuration file warden-apache.conf and
    warden-server.conf in warden-server/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. warden

    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. 

			  %VALID_STRINGS = (
 			    'type'          => ['portscan', 'bruteforce', 'probe', 'spam', 'phishing', 'botnet_c_c', 'dos', 'malware', 'copyright', 'webattack', 'test', 'other'],
			    'source_type'   => ['IP', 'URL', 'Reply-To:']
			  );


    c) 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:+SSLv2:+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.
  
 Default destination directory is /opt/warden-server/.
    
 For more information about update.sh options run update.sh -h

   Usage: $ ./update.sh [-d <directory>] [-hV]
        -d <directory>            destination directory (default: /opt)
        -h                        print this help
        -V                        print script version number and exit

   Example: # ./update.sh -d /opt

 You must be root for running this script.

 For more information about post-update steps see UPDATE file in 'doc'
 directory.


--------------------------------------------------------------------------------
E. Uninstallation

 For uninstallation of the Warden server package from local machine use uninstall.sh.
  
 Default uninstallation directory is /opt/warden-server/.
    
 For more information about uninstall.sh options run uninstall.sh -h

   Usage: $ ./uninstall.sh [-d <directory>] [-hV]
        -d <directory>            uninstallation directory (default: /opt)
        -h                        print this help
        -V                        print script version number and exit

   Example: # ./uninstall.sh -d /opt

 You must be root for running this script.

 For more information about post-uninstallation steps see UNINSTALL file in 'doc'
 directory.


--------------------------------------------------------------------------------
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. Privileges
 
    The Warden server runs only under root privileges.

 4. Known Issues

    No issues are known.


--------------------------------------------------------------------------------
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          - 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.

--------------------------------------------------------------------------------

Copyright (C) 2011-2013 Cesnet z.s.p.o