+----------------------------+
| README - Warden Client 2.1 |
+----------------------------+
Content
A. Overall Information
B. Installation Dependencies
C. Installation
D. Update
E. Uninstallation
F. Configuration
G. Registration
H. Integration with Local Applications
I. Functions, Arguments and Calls
--------------------------------------------------------------------------------
A. Overall Information
1. About Warden Client
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.
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
2.1 (2013-02-05)
3. Package structure
warden-client/
doc/
CHANGELOG
example-sender.pl.txt
example-receiver.pl.txt
INSTALL
LICENSE
README
README.cesnet
etc/
warden-client.conf
package_version
lib/
WardenClientConf.pm
WardenClientSend.pm
WardenClientReceive.pm
WardenClientCommon.pm
var/
--------------------------------------------------------------------------------
B. Installation Dependencies
Perl >= 5.10.1
SOAP::Lite >= 0.712
IO::Socket::SSL >= 1.74
SOAP::Transport::HTTP >= 0.712
FindBin >= 1.50
DateTime >= 0.61
Carp >= 1.11
--------------------------------------------------------------------------------
C. Installation (First installation of the Warden client package)
1. Check SHA1 checksum of corresponding Warden client package archive
$ sha1sum -c warden-client-2.1.tar.gz.sig
2. Untar it
$ tar xzvf warden-client-2.1.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
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.
Install script does check the accessibility of SSL certificates to
provided user. If these files are restricted, the install script will raise
a warning. However this will not stop the install process. Either privileges
to read them must be changed or Warden client must be run under root.
Of course, after installation of Warden client, SSL certificates may also be
copied to another location accessible by the user and corresponding paths
changed in warden-client/etc/warden-client.conf.
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
below F. Configuration.
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"
--------------------------------------------------------------------------------
D. Update (Update of previously installed the Warden client package)
1. Check SHA1 checksum of corresponding the Warden client package archive
$ sha1sum -c warden-client-2.1.tar.gz.sig
2. Untar it
$ tar xzvf warden-client-2.1.tar.gz
3. Run update.sh
Default destination directory is /opt/warden-client/
For more information about update.sh options run update.sh -h
You must be root for running this script.
4. Configuration file
After successful update process you are advised to check configuration
file warden-client/etc/warden-client.conf. For more information see section
F. Configuration.
5. Usage of update.sh
Usage: update.sh [-d <directory>] [-hV]
-d <directory> destination directory (default: /opt)
-h print this help
-V print script version number and exit
Example: # ./update.sh -d /opt
Note: You must be root for running this script.
6. Note that unlike version 2.1, in 2.2 the name of the file in which id of
the last received message is stored have changed. Previously, name was
"CALLER_NAME.id" (where CALLER_NAME is the name of calling script),
whereas now name contains name of requested message type
"CALLER_NAME-TYPE.id".
Should you want to continue downloading events where previous version
left off, you will have to rename the file by hand.
For example, where name of the file was "./var/example-receiver.pl.id"
and downloaded type was "portscan", new name should be
"./var/example-receiver.pl-portscan.id". If caller passes undef as
requested type to receive all types, new name should be
"./var/example-receiver.pl-any.id"
--------------------------------------------------------------------------------
E. Uninstallation
1. Run uninstall.sh
The script is located in warden-client package directory.
Default uninstallation directory is /opt/warden-client/.
For more information about uninstall.sh options, run uninstall.sh -h.
You must be root for running this script.
2. Usage of uninstall.sh
Usage: uninstall.sh [-d <directory>] [-hV]
-d <directory> uninstallation directory (default: /opt)
-h print this help
-V print script version number and exit
Example: # ./uninstall.sh -d /opt
Note: You must be root for running this script.
--------------------------------------------------------------------------------
F. Configuration
SOAP protocol is used for handling communication between server and clients.
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 of the Warden server
e.g. 'https://mywarden.server.com:443/Warden'
SSL_KEY_FILE - path to a host key file,
e.g. '/opt/warden-client/etc/mywarden.server.com.key'
SSL_CERT_FILE - path to a host certificate file,
e.g. '/opt/warden-client/etc/mywarden.server.com.pem'
SSL_CA_FILE - path to a CA file
e.g. '/etc/ssl/certs/tcs-ca-bundle.pem'
Client receives events in batches. Maximum number of events received in one
batch can is set in MAX_RCV_EVENTS_LIMIT. Note that this option only
affects clients that receives events from the Warden server (e.g., uses
lib/WardenClientReceive.pm module).
MAX_RCV_EVENTS_LIMIT - maximum number of events in one batch
- default set to 6000, which generates app. 250 MB
of memory consumption.
- only affects "receiving" clients
Note: server is queried for the MAX_RCV_EVENTS_LIMIT number of events,
however server can have its own internal maximum size of batch. Contact
your Warden server administrator if you need to know Warden server batch
limits.
Option CONNECTION_TIMEOUT was added to prevent some troubles when receiving
large batches of new data. Default value is 60 seconds.
CONNECTION_TIMEOUT - interval in seconds to timeout connection with Warden
server. If your client timeouts, consider using higher
timeout number. Also, in case of receiving clients, you
can optimize the MAX_RCV_EVENTS_LIMIT value.
Since Warden client 2.1 there is also possibility to log status and other
information either to STDERR of Syslog.
LOG_STDERR - if set to 1 (default), all status information and
possible error will be printed to STDERR
- to disable, set LOG_STDERR to 0
LOG_SYSLOG - if set to 1, all status information and possible
errors will be reported to Syslog
- default is 0, which means that reporting to Syslog
is disabled
LOG_SYSLOG_FACILITY - facility to use when logging via Syslog
- deafult is "local7"
LOG_VERBOSE - when set to 1, also debug information (such as stack
dump) will be printed when logging.
- default is 0, which means that verbose mode is
disabled
--------------------------------------------------------------------------------
G. Registration
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 the Warden server administrator.
Usually via e-mail.
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
this client is allowed to communicate from.
Hostname Hostname of client to be registered
Requestor E-mail address of organization or authorized person
who demands new client registration.
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
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 I. Functions
arguments and calls.
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 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 (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'
For complete information about client attributes and/or event types you will
have to contact particular Warden server administrator/provider.
--------------------------------------------------------------------------------
H. Integration with Local Applications
(Note: Clients need to be registered on server to be able to communicate with
server properly. See section G. Registration for more information about
client registration.)
1. Client sender (this type of client reports events to the Warden server)
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
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 the Warden
server)
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
the Warden client receiver.
Brief information about syntax of receiving functions is provided in
section I. Functions, Arguments and Calls.
--------------------------------------------------------------------------------
I. Functions, Arguments and Calls
1. WardenClientSend::saveNewEvent
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):
# Path to warden-client folder
$warden_path = '/opt/warden-client';
# Inclusion of the Warden client sender module
require $warden_path . '/lib/WardenClientSend.pm';
# Sending event to the 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 G. 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)
# probe - other connection attempts (for example ICMP) or
# unrecognized/undecided portscan or bruteforce
# 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:'
$source_type = "IP";
# SOURCE - VARCHAR 256
# 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 or 'undef'.
$target_proto = "TCP";
# TARGET_PORT - INT 2
# Port number of reported attack/issue target or 'undef'.
$target_port = "22";
# ATTACK_SCALE - INT 4
# Definition of attack scale, e.g., number of affected targets. 'undef' is also
# possible when attack scale is not known or clear enough.
$attack_scale = "1234567890";
# NOTE - TEXT
# Some important(!) note, comment or 'undef'. 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
# Note: Currently obsolete (although still supported). Will be removed in
# warden-client 3.0!
# Subjective definition of incident severity. Values 0-255 are
# possible where 0 is the lowest priority or 'undef'.
$priority = "1";
# TIMEOUT - INT 2
# Note: Currently obsolete (although still supported). Will be removed in
# warden-client 3.0!
# Subjective time (in minutes) or 'undef'. After this time event might be
# considered timeouted.
$timeout = "20";
The return value of function SaveNewEvent is 1 when an event was
successfully received by the Warden server. Otherwise, the return value
is 0.
2. WardenClientReceive::getNewEvents
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
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 G. Registration. See more about event types in section
# I. 1. WardenClientSend::saveNewEvent
$requested_type = "botnet_c_c";
# 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 those
explained in section I. 1. WardenClientSend::saveNewEvent. It has one
additional attribute ID - unique id of this particular event (BIGINT).
Amount of events received in each batch equals to MAX_RCV_EVENTS_LIMIT
value set in warden-client/etc/warden-client.conf. For more information see
section F. Configuration.
--------------------------------------------------------------------------------
Copyright (C) 2011-2013 Cesnet z.s.p.o
Forked from
713 / Warden / Warden - archive
413 commits behind the upstream repository.
Tomáš Plesník
authored