inicialni stav

src/warden-client/doc/CHANGELOG

+2011-11-16 v1.0.0 stable version
+--------------------------------
+- initial package of warden client
+- SSL certificate authentication/authorization supported
+- automatized installation process

src/warden-client/doc/INSTALL

+For installation of warden-client on local machine use 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.

src/warden-client/doc/LICENSE

+BSD License
+
+Copyright © 2011 Cesnet z.s.p.o
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+    * Neither the name of the Cesnet z.s.p.o nor the names of its
+      contributors may be used to endorse or promote products derived from this
+      software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COMPANY BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
+OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

src/warden-client/doc/README

++------------------------------+
+| README - Warden Client 1.0.0 |
++------------------------------+
+
+Content
+
+ A. Overall Information
+ B. Installation Dependencies
+ C. Registration
+ D. Installation
+ E. Integration with Local Applications
+ F. Client Upgrade
+ G. Functions, Arguments and Calls
+ H. 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.0.0 (2011-11-16)
+    
+ 3. Package structure
+ 
+    warden-client/
+      doc/
+        example-sender.pl.txt
+        example-receiver.pl.txt
+      etc/
+        warden-client.conf
+      var/
+      lib/
+        WardenClientSend.pm
+        WardenClientReceive.pm
+        WardenConf.pm  
+
+--------------------------------------------------------------------------------
+B. Installation Dependencies
+  
+    Perl 5.10.1  
+    SOAP::Lite
+    IO::Socket::SSL
+    SOAP::Transport::TCP
+    FindBin
+
+--------------------------------------------------------------------------------
+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.  
+    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.0.0.tar.gz.sig
+
+ 2. Untar it
+
+    $ tar xzvf warden-client-1.0.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
+  
+    You are advised to check configuration file
+    warden-client/etc/warden-client.conf. After installation.
+    
+    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' 
+
+ 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. 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 G. 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. 
+
+--------------------------------------------------------------------------------
+F. Client Upgrade
+
+   To upgrade a client, install a new version.
+
+--------------------------------------------------------------------------------
+G. 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).
+
+--------------------------------------------------------------------------------
+H. Authors
+
+Development:	Tomas PLESNIK   <plesnik@ics.muni.cz>
+		Jan SOUKAL      <soukal@ics.muni.cz>
+
+Copyright (C) 2011 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.
+
+