src/warden-client/doc/README.cesnet

-+-----------------------------------+
-| README.cesnet - Warden Client 2.1 |
-|				    |
-| CESNET Specifics                  |
-+-----------------------------------+
-
-Content
-
- A. Overall Information
- B. Registration
- C. Description tags
- D. Types of events
- E. Configuration
- F. Testing
- G. Authors of this document
-
---------------------------------------------------------------------------------
-A. Overall Information
-
- 1. About CESNET Warden Server
-
-    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.
-
-    CESNET offers Warden server for security events exchange within its networks.
-
- 2. Version
-
-    2.1 (2012-10-18)
-
---------------------------------------------------------------------------------
-B. Registration
-
-    Client attempting to communicate with CESNET Warden server must be
-    registered. Registration is currently provided by Tomas Plesnik at
-    mail address plesnik@ics.muni.cz and following information is needed:
-
-    * For sender client:
-      - hostname of the machine, where client runs,
-      - client type = sender,
-      - name of the detection service (for example 'ScanDetector'),
-      - description tags of sent events (see below)
-      - CIDR from which client will communicate with Warden server.
-
-    * For receiver client:
-      - hostname of the machine, where client runs,
-      - client type = receiver,
-      - whether client should receive all events, or type of requested
-        events (for example 'portscan', see below) otherwise
-      - receiving of sent events from my organization = yes/no (organizations
-        are separated based on the top-level and second-level domain),
-      - CIDR from which client will communicate with Warden server.
-
-    Clients need to have valid certificate to prove their identity to the
-    Warden server. For CESNET network, 'server' type certificate from Terena
-    Certificate Service (provided by Comodo) is needed. Hostname of the
-    machine must correspond with certificate subject, Alternative Name
-    extension is not supported. Administrator of Warden client must be
-    entitled to obtain this certificate. CESNET TCS request service 
-    interface resides at
-
-      https://tcs.cesnet.cz/
-
---------------------------------------------------------------------------------
-C. 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.
-
-   Sender client specifies its descriptive tags during registration, it is
-   up to client administrator's judgment to select or omit any particular tag.
-   Currently tags fall into four general categories - based on event medium,
-   data source, detection methodology and detector or analyzer product name.
-   Product name tag is free to choose if same product name was not yet
-   accepted by registrar, otherwise existing form must be used (registrar will
-   notify about such cases).
-   Categories list is certainly not complete. Therefore if new client's
-   administrator feels that name or type of important feature of his (or
-   others) detector is not covered, providers of Warden server are glad to
-   discuss it at registration address or at Warden project mailing list 
-   (warden@cesnet.cz).
-   However, it may or may not be accepted, as aim is to keep the list of
-   categories possibly unambiguous, short and usable.
-
-   Following is grouped list of tags together with closer description and
-   examples.
-
- 1. Detection medium
-
-    * Network - network data based (Snort, Suricata, Bro, FTAS, LaBrea, Kippo,
-                Dionaea)
-    * Host - host based (Swatch, Logcheck)
-    * Correlation - corellation engines (Prelude, OSSIM)
-    * External - credible external sources (incident reporting, ticket
-                 systems, human verified events)
-
- 2. Data source
-
-    * Content - datagram content based detectors (Snort, Bro)
-    * Flow - netflow based (FTAS, FlowMon, HoneyScan)
-    * Connection - connection data (portscan, portsweep)
-    * Data - application data based (SpamAssassin, antiviruses)
-    * Log - based on system logs, where more specific source is not
-            applicable (Swatch, Logcheck, SSH scans)
-    * IR - incident reporting, ticket systems, human verified events
-
- 3. Detection methodology
-
-    * Honeypot (LaBrea, Kippo, Dionaea)
-    * Antispam (SpamAssassin, Bogofilter, CRM114, Policyd, greylisting)
-    * Antivirus (ClamAV)
-    * IDS - IDS/IPS, Snort, Suricata, Bro
-
- 4. Detector/analyzer product name examples
-
-    * Snort, FTAS, SpamAssassin, LaBrea, Swatch, Prelude, Kippo, Dionaea
-
---------------------------------------------------------------------------------
-D. Types of events
-
-   Event types purpose is to allow event receivers to filter and/or categorise
-   particular events according to attack characteristics. Types are loosely
-   chosen as list of common security incidents nowadays observed. List is by no
-   means complete, however it was created based on expected use cases at
-   receiving places. Possibility of a new type is also open to discussion.
-
-   * portscan - TCP/UDP port scanning/sweeping
-   * bruteforce - dictionary/bruteforce attack to services authentication
-   * probe - other connection attempts (for example ICMP) or
-             unrecognized/undecided portscan or bruteforce
-   * spam - unsolicited commercial email (except phishing)
-   * phishing - email, trying to scam user to revealing personal information
-     (possibly by some other channel)
-   * botnet_c_c - botnet command & control master machine
-   * dos - (possibly distributed) denial of service attack
-   * malware - virus/malware sample
-   * copyright - copyright infringement
-   * webattack - web application attack
-   * test - clients can use these at will when debugging/testing, these
-            messages will be processed and stored, but ignored later
-   * other - the rest, uncategorizable yet
-
-   In case of complex scenarios with structured info more events with
-   particular parts of information can be created.
-
---------------------------------------------------------------------------------
-E. Configuration
-
-    CESNET Warden server resides at URI 'https://warden.cesnet.cz:443/Warden'.  
-
---------------------------------------------------------------------------------       
-F. Testing
-
-    For testing purposes of sender clients, event type 'test' can be used.
-    These events will end up in server database, but will not be taken
-    further into consideration.
-
---------------------------------------------------------------------------------
-G. Authors of this document
-
-    Pavel Kacha     <ph@cesnet.cz>
-    Jan Soukal      <soukal@ics.muni.cz>
-
-Copyright (C) 2011-2012 Cesnet z.s.p.o

src/warden-client/doc/example-receiver.pl.txt

-#!/usr/bin/perl -w
-#
-# Copyright (C) 2011-2012 Cesnet z.s.p.o
-#
-# Use of this source is governed by a BSD-style license, see LICENSE file.  
-
-use strict;
-
-#------------------------------------------------------------------------------
-# Warden 2.1 Client, Receiver, Example
-#
-# Simple use of warden-client receiver functionality to download new events
-# from # Warden server. This code illustrates how to integrate warden-client
-# receive functionality into local applications.
-#------------------------------------------------------------------------------
-
-#------------------------------------------------------------------------------
-# This code should developer add into his/her application.
-
-# 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. This attributes is also set on server
-# and must not change.
-my $requested_type = "portscan";
-
-#------------------------------------------------------------------------------
-# Simple code that prints out new events obtained from Warden server.
-
-print "+------------------------------------------------------------------------------------------------------------------------------------------+\n";
-print "| id | hostname | service | detected | type | source_type | source | target_proto | target_port | attack_scale | note | priority | timeout |\n";
-print "+------------------------------------------------------------------------------------------------------------------------------------------+\n";
-
-# Download of new evetns from Warden server
-while (my @new_events = WardenClientReceive::getNewEvents($warden_path, $requested_type)) {
-  foreach my $event_ref (@new_events) {
-    my @event = @$event_ref;
-    print "| " . join(' | ', @event) . " |" . "\n";
-  }
-print "+------------------------------------------------------------------------------------------------------------------------------------------+\n";
-}
-
-print "+------------------------------------------------------------------------------------------------------------------------------------------+";
-print "\n";
-print "Last events in: " . scalar(localtime(time)) . "\n";
-
-exit 0;

src/warden-client/doc/example-sender.pl.txt

-#!/usr/bin/perl -w
-#
-# Copyright (C) 2011-2012 Cesnet z.s.p.o
-#
-# Use of this source is governed by a BSD-style license, see LICENSE file.  
-
-use strict;
-use DateTime;
-
-#-------------------------------------------------------------------------------
-# Warden 2.1. Client, Sender, Example 
-#
-# Sample script using warden-client sending functionality. This example is not
-# intended to be a standalone script. It only shows how to use warden-client
-# functionality.
-#-------------------------------------------------------------------------------
-
-#-------------------------------------------------------------------------------
-# Preparation of event attributes.
-# This should be handled by detection application.
-
-
-my $local_detected = DateTime->from_epoch(epoch => time());
-
-
-my $service 		= "ScanDetector";
-my $detected 		= "$local_detected";
-my $type 		= "portscan";
-my $source_type 	= "IP";
-my $source 		= "123.123.123.123";
-my $target_proto 	= "TCP";
-my $target_port 	= "22";
-my $attack_scale 	= "1234567890";
-my $note 		= "important note or comment";
-my $priority 		= undef;
-my $timeout 		= "20";
-
-my @event 		= ($service, $detected, $type, $source_type, $source,
-			   $target_proto, $target_port, $attack_scale, $note,
-			   $priority, $timeout );
-
-#-------------------------------------------------------------------------------
-# Use of warden-client sender.
-# This code should developer add to his/her detection application
-# (with corresponding paths appropriately changed).
-
-# Path to warden-client folder
-my $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);
-
-exit 0;

src/warden-client/etc/package_version

-warden-client-2.1

src/warden-client/etc/warden-client.conf

-#
-# warden-client.conf - configuration file for the warden sender/receiver client
-#
-
-#-------------------------------------------------------------------------------
-# URI - URI address of Warden server
-#-------------------------------------------------------------------------------
-$URI = "https://warden-dev.cesnet.cz:443/Warden";
-
-#-------------------------------------------------------------------------------
-# SSL_KEY_FILE - path to client SSL certificate key file
-#-------------------------------------------------------------------------------
-$SSL_KEY_FILE = "/opt/warden-client/etc/warden-dev.cesnet.cz.key";
-
-#-------------------------------------------------------------------------------
-# SSL_CERT_FILE - path to client SSL certificate file
-#-------------------------------------------------------------------------------
-$SSL_CERT_FILE = "/opt/warden-client/etc/warden-dev.cesnet.cz.pem";
-
-#-------------------------------------------------------------------------------
-# SSL_CA_FILE - path to CA certificate file
-#-------------------------------------------------------------------------------
-$SSL_CA_FILE = "/etc/ssl/certs/tcs-ca-bundle.pem";
-
-#-------------------------------------------------------------------------------
-# MAX_RCV_EVENTS_LIMIT - maximum number of events the client is allowd to get
-#                        from the Warden server in one batch
-#-------------------------------------------------------------------------------
-$MAX_RCV_EVENTS_LIMIT = 6000; #consumes app. 250 MB of memory
-
-#-------------------------------------------------------------------------------
-# Log options
-#
-# LOG_STDERR, LOG_SYSLOG - hide (0) or allow (1) error reporting on STDERR
-#                          and/or to Syslog
-# LOG_STDERR_VERBOSE, LOG_SYSLOG_VERBOSE - print only error message without
-#                                          a stack (0) or print debug info
-#                                          including err. message and stack (1)
-#-------------------------------------------------------------------------------
-$LOG_STDERR = 1;                        
-
-$LOG_SYSLOG = 1;   
-$LOG_SYSLOG_FACILITY = "local7"; 
-
-$LOG_VERBOSE = 0;        
-
-
-
-1;
-     
\ No newline at end of file

src/warden-client/lib/WardenClientConf.pm

-#!/usr/bin/perl -w
-#
-# WardenClientConf.pm
-#
-# Copyright (C) 2011-2012 Cesnet z.s.p.o
-#
-# Use of this source is governed by a BSD-style license, see LICENSE file.  
-
-package WardenClientConf;
-
-use strict;
-
-# preset of default variables
-our $URI = undef;
-our $SSL_KEY_FILE = undef;
-our $SSL_CERT_FILE = undef;
-our $SSL_CA_FILE = undef;
-our $MAX_RCV_EVENTS_LIMIT = undef;
-our $LOG_STDERR = 1;
-our $LOG_SYSLOG = 0;
-our $LOG_SYSLOG_FACILITY = "local7";
-our $LOG_VERBOSE = 0;
-
-
-our $VERSION = "2.1";
-
-sub loadConf
-{  
-  my $conf_file = shift;
-
-  # load configuration variables set by user
-  unless (do $conf_file) {
-    die("Errors in config file '$conf_file': $@") if $@;
-    die("Can't read config file '$conf_file': $!") unless defined $_;
-    # if $_ defined, it's retvalue of last statement of conf, for which we don't care
-  }
-}
-
-1;

src/warden-client/lib/WardenClientSend.t

-#!/usr/bin/perl
-
-use strict;
-use warnings;
-
-use Test::More tests => 2;
-
-use lib '..';
-use WardenClientSend;
-
-my $uri_ok           = 'https://warden-dev.cesnet.cz:443/Warden';
-my $ssl_key_file_ok  = '/opt/warden-client/etc/warden-dev.cesnet.cz.key';
-my $ssl_cert_file_ok = '/opt/warden-client/etc/warden-dev.cesnet.cz.pem';
-my $ssl_ca_file_ok   = '/opt/warden-client/etc/tcs-ca-meta-bundle.pem';
-my $method_ok        = 'saveNewEvent';
-my $data_ok          = '';
-
-my $warden_path_ok   = '/opt/warden-client';
-my $warden_path_fail = '/path/to/fail';
-my @event_ok = ("honeyscan", "1234567890", "portscan","IP", "123.123.123.123", "TCP", "22", "1234567890", "important note or comment", "null", "20");
-my @vent_ok = ('HoneyScan', '2012-09-01T23:02:48', 'webattackReply-To:', '170.96.48.164', 'UDP', '44392354', 'tohle je takova normalni jednoducha poznamka', '180187');
-
-my $ret;
-
-#my ($ret) = WardenClientSend::c2s($uri_ok, $ssl_key_file_ok, $ssl_cert_file_ok, $ssl_ca_file_ok, $method_ok, $data_ok);
-#ok ($ret == 1, 'Everything is fine!');
-
-$ret = WardenClientSend::saveNewEvent($warden_path_fail,\@event_ok);
-ok ($ret == 0, 'Bad Warden path!');
-
-$ret = WardenClientSend::saveNewEvent($warden_path_ok,\@event_ok);
-ok ($ret == 1, 'Everything is fine.');