Skip to content
Snippets Groups Projects
Select Git revision
  • master default protected
  • devel
  • hruska-feature-clients-api
  • malostik-#5066-deduplicate-idea-ids
  • warden-postgresql-port
  • hruska-feature-#6799-filter-keys
  • hruska-feature-5066-duplicateIdeaID
  • warden-client-3.0-beta3
  • warden-server-3.0-beta3
  • warden-client-2.2-final
  • warden-server-2.2-final
  • warden-client-3.0-beta2
  • warden-server-3.0-beta2
  • warden-client-2.2
  • warden-server-2.2-patch3
  • warden-client-3.0-beta1
  • warden-server-3.0-beta1
  • warden-server-2.2-patch1
  • warden-client-3.0-beta0
  • warden-server-3.0-beta0
  • warden-server-2.2
  • warden-server-2.1-patch1
  • warden-client-2.1
  • warden-server-2.1
  • warden-server-2.1-beta6
  • warden-server-2.1-beta5
  • warden-server-2.1-beta4
27 results

README

Blame
  • README 13.71 KiB
    +------------------------------+
    | README - Warden Client 1.1.0 |
    +------------------------------+
    
    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
     J. Authors
    
    --------------------------------------------------------------------------------
    A. Overall Information
    
     1. About Warden Client
     
        Warden is a client-based architecture service designed to share detected
        security issues (events) among CSIRT and CERT teams in a simple and fast way.
        
        This package offers full client functionality to both report events to
        server and to retreive batch of new events from server. It is composed from
        several perl modules/libraries which should be included into local
        application of detection of reaction type. 
     
     2. Version
      
        1.1.0 (2012-02-16) - DOPLNIT
        
     3. Package structure
     
        warden-client/
          doc/
            CHANGELOG
            example-sender.pl.txt
            example-receiver.pl.txt
    	INSTALL
    	LICENSE
    	README
    	README.cesnet
          etc/
            package_version.txt
            warden-client.conf
          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::TCP	>= 0.712
        FindBin 			>= 1.50
        DateTime 			>= 0.61
    
    --------------------------------------------------------------------------------
    C. Registration
    
        Any client attempting to communicate with 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 Warden server administrator.
        Usually via e-mail.
      
        Clients need to have valid client certificate to prove their identity to
        the Warden server. 
      
        Each client is defined by its hostname, service name, type of client, type
        of requested events and CIDR the client is allowed to communicate from only.
      
        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
                                    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	Receiving of sent events from my 
        				organization = 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 do more
    				general filtering according to event source.
    				Receiver can for example decide to use only
    				events originating at honeypots, or filter out
    				events, generated by human conclusions or 
    				correlation engines. This is mandatory only
    				for 'Sender' client.
    
        CIDR			CIDR stands for IP address or IP (sub)net
        				the client is going to communicate from. Any
    				communications between the client and 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 see
        Warden project documentation.
       
    --------------------------------------------------------------------------------
    D. Installation
    
     1. Check SHA1 checksum of corresponding Warden client package archive
    
        $ sha1sum -c warden-client-1.1.0.tar.gz.sig
    
     2. Untar it
    
        $ tar xzvf warden-client-1.1.0.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
    
        Warden-client is designed to be run under standard privileges. It should be
        part of other applications run under usual user privileges. However
        warden-client uses SSL certificates for security purposes which are often 
        not accessible by standard users.
    
        To solve this issue warden-client should be install 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 any user want to preserve standard location of certificate files,
        he or she is 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
        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
        G. Configuration below.
    
     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 - DOPLNIT
    
       To upgrade a client, install a new version.
    
    --------------------------------------------------------------------------------
    F. Uninstallation - DOPLNIT
    
       To upgrade a client, install a new version.
    
    --------------------------------------------------------------------------------
    G. Configuration
        
        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 file contains following parameters:
    
        URI 	  - URI Warden server
              	    e.g. 'https://warden-dev.cesnet.cz:443/Warden'
    
        SSL_KEY_FILE  - path to a host key file,
        	    	    e.g. '/opt/warden-client/etc/warden-dev.cesnet.cz.key'
    
        SSL_CERT_FILE - path to a host certificate file,
         		    e.g. '/opt/warden-client/etc/warden-dev.cesnet.cz.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 Warden server)
      
        Client functionality 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
        warden-client sender functionality.
        
        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 uploads events from Warden server)
     
        Client functionality is included as a perl module (WardenClientReceive.pm)
        into perl code of local 'reaction' application or may be used as as core of
        standalone local application.
          
        See warden-client/doc/example-receiver.pl.txt for example how to use
        warden-client receiver functionality.   
        
        Brief information about syntax of receiving functions and functionality is
        provided in section G. Functions arguments and calls. 
    
    
    --------------------------------------------------------------------------------
    I. Functions, Arguments and Calls
    
     1. WardenClientSend::saveNewEvent
     
        Function to upload one event on 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 warden-client sender module
        require $warden_path . '/lib/WardenClientSend.pm';
        
        # Sending event to 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 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";
    
     2.  WardenClientReceive::getNewEvents
    
        Function to download batch of events from the Warden server. Downloaded
        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
        # G. 1. WardenClientSend::saveNewEvent
        $requested_type = "botnet_c_c";
    
        # Download batch of new events from Warden server
        @new_events = WardenClientReceive::getNewEvents($warden_path,
                                                        $requested_type);
                                                        
        Structure of each received event in the event array equals to this explained
        in section G. 1. WardenClientSend::saveNewEvent. It has one additional
        attribute ID - unique id of this particular event (BIGINT).
    
    --------------------------------------------------------------------------------
    J. Authors
    
    Development:	Tomas PLESNIK   <plesnik@ics.muni.cz>
    		Jan SOUKAL      <soukal@ics.muni.cz>
    
    Copyright (C) 2011-2012 Cesnet z.s.p.o
    
    Special thanks go to Martin Drasar from CSIRT-MU for his help and support
    in the development of Warden system.