Skip to content
Snippets Groups Projects
Forked from 713 / Warden / Warden
897 commits behind the upstream repository.
user avatar
pharook authored
ff4e1c77
History
+------------------------------------+
| README - Warden Client 2.0.0-beta2 |
+------------------------------------+

Content

 A. Overall Information
 B. Installation Dependencies
 C. Registration
 D. Installation
 E. Update
 F. Uninstallation
 G. Configuration
 H. Integration with Local Applications
 I. Functions, Arguments and Calls


--------------------------------------------------------------------------------
A. Overall Information

 1. About Warden Client
 
    Warden is a client-based architecture service designed to share detected
    security events (issues) among CSIRT and CERT teams in a simple and fast way.
    
    This package offers a client capable of both reporting events to server and 
    retreiving batch of new events from server. It consists of several Perl 
    modules/libraries which should be included into detection applications.
 
 2. Version
  
    2.0.0-beta2 (2012-07-20)
    
 3. Package structure
 
    warden-client/
      doc/
        CHANGELOG
        example-sender.pl.txt
        example-receiver.pl.txt
	      INSTALL
	      LICENSE
	      README
	      README.cesnet
      etc/
        warden-client.conf
	      package_version
      lib/
        WardenClientConf.pm
        WardenClientSend.pm
        WardenClientReceive.pm  
      var/


--------------------------------------------------------------------------------
B. Installation Dependencies
  
    Perl 			>= 5.10.1  
    SOAP::Lite			>= 0.712
    IO::Socket::SSL		>= 1.33
    SOAP::Transport::HTTP	>= 0.712
    FindBin 		        >= 1.50
    DateTime 		        >= 0.61


--------------------------------------------------------------------------------
C. Registration

    Any client attempting to communicate with the Warden server must be
    registered on this server. Unknown (not registered) clients are not allowed
    to exchange any data with server.
  
    Registration of your client is provided by the Warden server administrator.
    Usually via e-mail.
  
    Clients also need to have valid client SSL certificates to prove their
    identity to the Warden server. 
  
    Each client is defined by its hostname, service name, type of client, type
    of requested events, receiving of own events, description tags and CIDR
    this client is allowed to communicate from.
  
    Hostname			hostname of client to be registered

    Service name		Text string. Unique name of the service
                                the client is integrated in.
                                E.g. 'ScanDetector_1.0'. This is mandatory for
                                'Sender' client. Default value null is used for
                                'Receiver' client.

    Type of client		Either 'Sender' or 'Receiver'.

    Type of requested events	Type of events the client only accepts from
                                the Warden server. This is mandatory only for
                                'Receiver' client. Default value null is used
                                for 'Sender' client. Brief information about
                                event types is provided in section G. Functions
                                arguments and calls.

    Receiving of own events	Enables receiving of events sent from your
   				organization domain = yes/no (organizations are
				separated based on the top-level and
				second-level domain). This is mandatory only
				for 'Receiver' client.

    Description tags		Tags are case insensitive alphanumeric strings
    				designed to allow event receivers to filter
				according to event source. For example, 
				receiver can decide to use only events 
				originating from honeypots or filter out events
				generated manually by users. This is mandatory
				for 'Sender' client.

    CIDR			CIDR stands for IP (sub)net the client is going
    		      		to communicate from (see examples below!). Any
				communications between the client and the Warden
				server must be performed from IP address from
				a range stated in CIDR.
				Examples: '123.123.0.0/16', '123.123.123.123/32'

  
    For complete information about client attributes and/or event types you will
    have to contact particular Warden server administrator/provider.


--------------------------------------------------------------------------------
D. Installation (First installation of the Warden client package)

 1. Check SHA1 checksum of corresponding Warden client package archive

    $ sha1sum -c warden-client-2.0.0-beta2.tar.gz.sig

 2. Untar it

    $ tar xzvf warden-client-2.0.0-beta2.tar.gz

 3. Run install.sh 
  
    Default destination directory is /opt/warden-client/
    
    For more information about install.sh options run install.sh -h

    You must be root for running this script.

 4. Installation Privileges

    The Warden client is designed to be run under standard privileges. It should 
    be a part of other applications that are run under usual user privileges.
    However, the Warden client uses SSL certificates for security purposes which
    are often not accessible by standard users.

    To solve this issue, the Warden client should be installed under root
    privileges. It copyies local SSL key and certificate files into 
    warden-client/etc folder where those are accessible even with standard 
    privileges.

    Should users want to preserve standard location of certificate files,
    they are advised to remove key and certificate files after installation
    from warden-client/etc/ and manually edit paths to certificate files in
    warden-client/etc/warden-client.conf. In most cases, this change will force
    the Warden client to be run under root privileges though.

 5. Configuration file

    After successful installation process you are advised to check configuration
    file warden-client/etc/warden-client.conf. For more information see section
    below G. Configuration.

 6. Usage of install.sh

    Usage: install.sh [-d <directory>] [-u <user>] [-k <ssl_key_file>]
                      [-c <ssl_cert_file>] [-a <ssl_ca_file>] [-hV]
	-d <directory>            installation directory (default: /opt)
	-u <user>                 owner of warden client package (user for
				  running detection scripts)
	-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 -u detector -k /etc/ssl/private/client.key
    			    -c /etc/ssl/certs/client.pem -a /etc/ssl/certs"


--------------------------------------------------------------------------------
E. Update (Update of previously installed the Warden client package)

 1. Check SHA1 checksum of corresponding the Warden client package archive

    $ sha1sum -c warden-client-2.0.0-beta2.tar.gz.sig

 2. Untar it

    $ tar xzvf warden-client-2.0.0-beta2.tar.gz

 3. Run update.sh 
  
    Default destination directory is /opt/warden-client/
    
    For more information about update.sh options run update.sh -h

    You must be root for running this script.

 4. Configuration file

    After successful update process you are advised to check configuration
    file warden-client/etc/warden-client.conf. For more information see section
    G. Configuration.

 5. Usage of update.sh

    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

    Note: You must be root for running this script.


--------------------------------------------------------------------------------
F. Uninstallation

 1. Run uninstall.sh 
  
    The script is located in warden-client package directory. 
    
    Default uninstallation directory is /opt/warden-client/.
    
    For more information about uninstall.sh options, run uninstall.sh -h.

    You must be root for running this script.

 2. Usage of uninstall.sh

    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

    Note: You must be root for running this script.


--------------------------------------------------------------------------------
G. Configuration
    
    SOAP protocol is used for handling communication between server and clients.
    Therefore, correct URI of the 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 file contains following parameters:

    URI 	  - URI of the Warden server
          	    e.g. 'https://mywarden.server.com:443/Warden'

    SSL_KEY_FILE  - path to a host key file,
    	    	    e.g. '/opt/warden-client/etc/mywarden.server.com.key'

    SSL_CERT_FILE - path to a host certificate file,
     		    e.g. '/opt/warden-client/etc/mywarden.server.com.pem'

    SSL_CA_FILE   - path to a CA file
                    e.g. '/etc/ssl/certs/tcs-ca-bundle.pem' 


--------------------------------------------------------------------------------       
H. Integration with Local Applications
 
 (Note: Clients need to be registered on server to be able to communicate with
        server properly. See section C. Registration for more information about
        client registration.)
 
 1. Client sender (this type of client reports events to the Warden server)
  
    Client is included as a Perl module (WardenClientSend.pm) into Perl code of 
    local detection application.   
   
    See warden-client/doc/example-sender.pl.txt for example how to use
    the Warden client sender.
    
    Brief information about syntax of sending functions and functionality is
    provided in section I. Functions, Arguments and Calls.
 
 2. Client receiver (this type of clients downloads events from the Warden 
    server)
 
    Client is included as a Perl module (WardenClientReceive.pm)
    into Perl code of local 'reaction' application or may be used as core of
    standalone local application.
      
    See warden-client/doc/example-receiver.pl.txt for example how to use
    the Warden client receiver.   
    
    Brief information about syntax of receiving functions is provided in 
    section I. Functions, Arguments and Calls. 


--------------------------------------------------------------------------------
I. Functions, Arguments and Calls

 1. WardenClientSend::saveNewEvent
 
    A function to report one event to the Warden server. See example 'Sender'
    client in warden-client/doc/example-sender.pl.txt
    
    Function call (Perl):
    
    # Path to warden-client folder
    $warden_path = '/opt/warden-client';
    
    # Inclusion of the Warden client sender module
    require $warden_path . '/lib/WardenClientSend.pm';
    
    # Sending event to the Warden server
    WardenClientSend::saveNewEvent($warden_path, \@event);
    
    Event array is defined as (Perl):
    
    @event = ($service, $detected, $type, $source_type, $source, $target_proto,
              $target_port, $attack_scale, $note, $priority, $timeout );

    Event array attributes with example value and explanation on the right
    (Perl):

    # SERVICE - VARCHAR (64)
    # Name of a service detecting this event. Service must be the same with this
    # provided in 'Sender' client registration. See more about this issue in
    # section C. Registration.    
    $service      = "ScanDetector";

    # DETECTED - TIMESTAMP in UTC, ISO 8601
    # Date and time when was event detected.
    $detected     = "2011-07-16T19:20:30.45";
    
    # TYPE - VARCHAR (64)
    # Type of reported event. Currently supported values are:
    # darkspace   - access into honeypot segment
    # portscan    - scannig of TCP/UDP ports
    # bruteforce  - bruteforce/dictionary attack against authentication
    #               service(s)
    # spam        - unsolicited e-mail that does not have phishing-like
    #               character
    # phishing    - e-mail attempting to gather sensitive data
    # botnet_c_c  - command and control center of botnet
    # dos         - (distributed) denial of service attack
    # malware     - virus sample
    # copyright   - copyright infringement issue
    # webattack   - attack against web application
    # other       - anything that does not match any of previous categories
    $type         = "portscan";
    
    # SOURCE_TYPE - VARCHAR 64
    # Type of source of reported attack/issue. Currently supported values are:
    # IP, URL, Reply-To:, null
    $source_type  = "IP";
    
    # SOURCE - VARCHAR 256
    # identification of an attack source/origin according to source_type
    $source       = "123.123.123.123";
    
    # TARGET_PROTO - VARCHAR 16
    # Protocol type of reported attack/issue target. Supported are all L3 and L4
    # protocols and null. 
    $target_proto = "TCP";
    
    # TARGET_PORT - INT 2
    # Port number of reported attack/issue target or null.
    $target_port  = "22";
    
    # ATTACK_SCALE - INT 4
    # Definition of attack scale, e.g., number of affected targets. Null is also
    # possible when attack scale is not known or clear enough.
    $attack_scale = "1234567890";
    
    # NOTE - TEXT
    # Some important(!) note or comment or null. Also, it may contain virus
    # sample, phishing e-mail with headers and other accordingly to event type.
    $note         = "this threat is dangerous";
    
    # PRIORITY - INT 1
    # Subjective definition of incident severity. Values 0-255 or null are
    # possible where 0 is the lowest priority.
    $priority     = "null";
    
    # TIMEOUT - INT 2
    # Subjective time (in minutes) or null. After this time event might be
    # considered timeouted.
    $timeout      = "20";

    The return value of function SaveNewEvent is 1 when an event was
    successfully received by the Warden server. Otherwise, the return value
    is 0.

 2.  WardenClientReceive::getNewEvents

    A function to download batch of events from the Warden server. Received
    events are stored in @events array. See example 'Receiver' client in
    warden-client/doc/example-receiver.pl.txt
    
    Function call (perl):
    
    # Path to warden-client directory
    my $warden_path = '/opt/warden-client';

    # Inclusion of warden-client receiving functionality
    require $warden_path . '/lib/WardenClientReceive.pm';

    # Definition of requested event type. Type must be the same with this
    # provided in 'Receiver' client registration. See more about this issue in
    # section C. Registration. See more about event types in section
    # I. 1. WardenClientSend::saveNewEvent
    $requested_type = "botnet_c_c";

    # Download batch of new events from the Warden server
    @new_events = WardenClientReceive::getNewEvents($warden_path,
                                                    $requested_type);
                                                    
    Structure of each received event in the event array equals to those 
    explained in section I. 1. WardenClientSend::saveNewEvent. It has one 
    additional attribute ID - unique id of this particular event (BIGINT).

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

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