finalni drobne upravy

src/warden-client/doc/README

@@ -22,12 +22,11 @@ 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.
+    security events (issues) 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. 
+    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
   
@@ -67,19 +66,19 @@ B. Installation Dependencies
 --------------------------------------------------------------------------------
 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.
+    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 Warden server administrator.
+    Registration of your client is provided by the Warden server administrator.
     Usually via e-mail.
   
-    Clients need to have valid client SSL certificate to prove their identity to
-    the Warden server. 
+    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
-    the client is allowed to communicate from only.
+    this client is allowed to communicate from.
   
     Hostname			hostname of client to be registered
 
@@ -92,31 +91,30 @@ C. Registration
     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
+                                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	Receiving of sent events from my 
-    				organization = yes/no (organizations are
+    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 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
+    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 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
+    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'
 
@@ -126,7 +124,7 @@ C. Registration
 
 
 --------------------------------------------------------------------------------
-D. Installation (First installation of warden client package)
+D. Installation (First installation of the Warden client package)
 
  1. Check SHA1 checksum of corresponding Warden client package archive
 
@@ -146,20 +144,21 @@ D. Installation (First installation of warden client package)
 
  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.
+    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 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.
+    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 any user want to preserve standard location of certificate files,
-    he or she is advised to remove key and certificate files after installation
+    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
-    warden-client to be run under root privileges though.
+    the Warden client to be run under root privileges though.
 
  5. Configuration file
 
@@ -185,9 +184,9 @@ D. Installation (First installation of warden client package)
 
 
 --------------------------------------------------------------------------------
-E. Update (Update of previously installed warden client package)
+E. Update (Update of previously installed the Warden client package)
 
- 1. Check SHA1 checksum of corresponding Warden client package archive
+ 1. Check SHA1 checksum of corresponding the Warden client package archive
 
     $ sha1sum -c warden-client-1.1.0.tar.gz.sig
 
@@ -207,7 +206,7 @@ E. Update (Update of previously installed warden client package)
 
     After successful update process you are advised to check configuration
     file warden-client/etc/warden-client.conf. For more information see section
-    below G. Configuration.
+    G. Configuration.
 
  5. Usage of update.sh
 
@@ -219,8 +218,6 @@ E. Update (Update of previously installed warden client package)
     Example: # ./update.sh -d /opt
 
     Note: You must be root for running this script.
-          For more information about update process, see README file (section
-	  Update).
 
 
 --------------------------------------------------------------------------------
@@ -230,9 +227,9 @@ F. Uninstallation
   
     The script is located in warden-client package directory. 
     
-    Default uninstallation directory is /opt/warden-client/
+    Default uninstallation directory is /opt/warden-client/.
     
-    For more information about uninstall.sh options run uninstall.sh -h
+    For more information about uninstall.sh options, run uninstall.sh -h.
 
     You must be root for running this script.
 
@@ -246,21 +243,20 @@ F. Uninstallation
     Example: # ./uninstall.sh -d /opt
 
     Note: You must be root for running this script.
-          For more information about uninstallation process, see README file
-	  (section Uninstallation).
+
 
 --------------------------------------------------------------------------------
 G. Configuration
     
     SOAP protocol is used for handling communication between server and clients.
-    Therefore, correct URI of Warden server must be set.
+    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 Warden server
+    URI 	  - URI of the Warden server
           	    e.g. 'https://mywarden.server.com:443/Warden'
 
     SSL_KEY_FILE  - path to a host key file,
@@ -280,28 +276,29 @@ H. Integration with Local Applications
         server properly. See section C. Registration for more information about
         client registration.)
  
- 1. Client sender (this type of client reports events to Warden server)
+ 1. Client sender (this type of client reports events to the Warden server)
   
-    Client functionality is included as a Perl module (WardenClientSend.pm)
-    into Perl code of local detection application.   
+    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
-    warden-client sender functionality.
+    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 Warden server)
+ 2. Client receiver (this type of clients downloads events from the Warden 
+    server)
  
-    Client functionality is included as a perl module (WardenClientReceive.pm)
-    into perl code of local 'reaction' application or may be used as core of
+    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
-    warden-client receiver functionality.   
+    the Warden client receiver.   
     
-    Brief information about syntax of receiving functions and functionality is
-    provided in section I. Functions, Arguments and Calls. 
+    Brief information about syntax of receiving functions is provided in 
+    section I. Functions, Arguments and Calls. 
 
 
 --------------------------------------------------------------------------------
@@ -309,7 +306,7 @@ I. Functions, Arguments and Calls
 
  1. WardenClientSend::saveNewEvent
  
-    Function to report one event on the Warden server. See example 'Sender'
+    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):
@@ -317,13 +314,13 @@ I. Functions, Arguments and Calls
     # Path to warden-client folder
     $warden_path = '/opt/warden-client';
     
-    # Inclusion of warden-client sender module
+    # Inclusion of the Warden client sender module
     require $warden_path . '/lib/WardenClientSend.pm';
     
-    # Sending event to Warden server
+    # Sending event to the Warden server
     WardenClientSend::saveNewEvent($warden_path, \@event);
     
-    Event array is defined as (perl):
+    Event array is defined as (Perl):
     
     @event = ($service, $detected, $type, $source_type, $source, $target_proto,
               $target_port, $attack_scale, $note, $priority, $timeout );
@@ -364,12 +361,12 @@ I. Functions, Arguments and Calls
     $source_type  = "IP";
     
     # SOURCE - VARCHAR 256
-    # identification of attack source/origin according to source_type
+    # 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 
+    # protocols and null. 
     $target_proto = "TCP";
     
     # TARGET_PORT - INT 2
@@ -377,7 +374,7 @@ I. Functions, Arguments and Calls
     $target_port  = "22";
     
     # ATTACK_SCALE - INT 4
-    # Definition of attack scale, e.g. number of affected targets. Null is also
+    # 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";
     
@@ -398,7 +395,7 @@ I. Functions, Arguments and Calls
 
  2.  WardenClientReceive::getNewEvents
 
-    Function to download batch of events from the Warden server. Downloaded
+    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
     
@@ -416,13 +413,13 @@ I. Functions, Arguments and Calls
     # I. 1. WardenClientSend::saveNewEvent
     $requested_type = "botnet_c_c";
 
-    # Download batch of new events from Warden server
+    # 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 this explained
-    in section I. 1. WardenClientSend::saveNewEvent. It has one additional
-    attribute ID - unique id of this particular event (BIGINT).
+    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).
 
 --------------------------------------------------------------------------------
 J. Authors
@@ -433,4 +430,4 @@ Development:	Tomas PLESNIK   <plesnik@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.
+in the development of the Warden system.