From e112193cad6f1e38c75e22bed6cf7b14eb7ace21 Mon Sep 17 00:00:00 2001 From: Tomas Plesnik <plesnik@ics.muni.cz> Date: Thu, 1 Dec 2011 22:47:53 +0100 Subject: [PATCH] inicialni stav --- src/warden-client/doc/CHANGELOG | 5 + src/warden-client/doc/INSTALL | 7 + src/warden-client/doc/LICENSE | 27 +++ src/warden-client/doc/README | 339 ++++++++++++++++++++++++++++++++ 4 files changed, 378 insertions(+) create mode 100644 src/warden-client/doc/CHANGELOG create mode 100644 src/warden-client/doc/INSTALL create mode 100644 src/warden-client/doc/LICENSE create mode 100644 src/warden-client/doc/README diff --git a/src/warden-client/doc/CHANGELOG b/src/warden-client/doc/CHANGELOG new file mode 100644 index 0000000..44c6c21 --- /dev/null +++ b/src/warden-client/doc/CHANGELOG @@ -0,0 +1,5 @@ +2011-11-16 v1.0.0 stable version +-------------------------------- +- initial package of warden client +- SSL certificate authentication/authorization supported +- automatized installation process diff --git a/src/warden-client/doc/INSTALL b/src/warden-client/doc/INSTALL new file mode 100644 index 0000000..5bc6e6f --- /dev/null +++ b/src/warden-client/doc/INSTALL @@ -0,0 +1,7 @@ +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. diff --git a/src/warden-client/doc/LICENSE b/src/warden-client/doc/LICENSE new file mode 100644 index 0000000..175c210 --- /dev/null +++ b/src/warden-client/doc/LICENSE @@ -0,0 +1,27 @@ +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. diff --git a/src/warden-client/doc/README b/src/warden-client/doc/README new file mode 100644 index 0000000..9106772 --- /dev/null +++ b/src/warden-client/doc/README @@ -0,0 +1,339 @@ ++------------------------------+ +| 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. + + -- GitLab