Select Git revision
WApp.README
WApp.README 10.87 KiB
+-------------------------------+
| README - WardenApp (WApp) 0.1 |
+-------------------------------+
Content
A. Overall Information
B. Installation Dependencies
C. Installation
D. Uninstallation
E. Configuration
F. Modules
G. Run
H. The requirements of modules
X. Tutorial: Running of the WApp along with the database backend
XX. Tutorial: Writing your own module
--------------------------------------------------------------------------------
A. Overall Information
1. About WardenApp
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.
WardenApp included in this package is an extension of classical Warden Client.
It allows automated evaluation received data and generates base of data for
another tools or just allows generating reports for human checking.
2. Version
0.1 (2013-03-20)
3. Package structure
warden-app/
|-- bin
| |-- warden-cleaner.pl
| |-- warden-factory.pl
| `-- warden-receiver.pl
|-- doc
| |-- WApp.cron
| `-- WApp.README
|-- etc
| |-- cleaner.conf
| |-- db.conf
| |-- factory.conf
| `-- receiver.conf
|-- Modules
| |-- DNSblacklist.pm
| |-- IPblacklist.pm
| |-- IPtables.pm
| |-- IPset.pm
| `-- MailReport.pm
|-- sh
| |-- create_tables_mysql.sh
| `-- create_tables_sqlite.sh
`-- WardenApp
|-- Constants.pm
|-- DB.pm
|-- Factory.pm
|-- Receiver.pm
`-- Utils.pm
--------------------------------------------------------------------------------
A1. Essence of WardenApp
The core consists of three parts with this specific functions:
Receiver - Receives data and stores it in the selected location (stdout, file, db [sqlite, MySQL])
Factory - Generates output that is requested. In short, it processes the data from the database
and generates an output dependent on the module. More about modules in section X.
Cleaner - Erases old unnecessary events.
Each part is represented by a Perl script that runs at defined intervals by the cron daemon. See
section H.
--------------------------------------------------------------------------------
B. Installation Dependencies
Perl >= 5.10.1
Config::Simple >= 4.59-5
DBI
Supported drivers for DBI are DBD::mysql and DBD::SQLite.
--------------------------------------------------------------------------------
C. Installation
1. Check SHA1 checksum of corresponding WardenApp package archive
$ sha1sum -c warden-app-0.1.tar.gz.sig
2. Untar it
$ tar xzvf warden-app-0.1.tar.gz
3. Just copy
Copy to any directory. For simplicity, use the default location of the Warden
project (/opt).
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.
5. Configuration files
The files are located in directory 'conf'. For defails, see section E.
6. Initialize database backend
WApp has interface for use MySQL or sqlite as database engine. Preparing
for the basic database structure can use the scripts from 'bin' directory.
MySQL - create_tables_mysql.sh
sqlite - create_tables_sqlite.sh
--------------------------------------------------------------------------------
D. Uninstallation
Simply delete all files from WardenApp's installation directory.
Optionally delete database if you used this choice.
--------------------------------------------------------------------------------
E. Configuration
All configuration files are placed in 'conf' directory. File 'factory.conf'
is used for configuration each of modules, other 'db.conf', 'receiver.conf'
and 'cleaner.conf' are used for general purposes.
Each of configuration parameters is described directly in configuration file.
--------------------------------------------------------------------------------
F. Modules
Modules are placed in 'Modules' directory. Module is assigned to specific configuration
section in 'conf/facory.conf' file.
This package includes these modules with these specific functions:
DNSblacklist - generates zone file for the most widely used DNS software on the Internet.
IPblacklist - generates traditional CSV file with IP addresses.
IPtables - generates iptables rules.
IPset - generates ipset rules (use on big sets of addresses rather than iptables).
MailReport - generates reports which are sent to specific recipients.
Section XX. describes how to write own module.
Some modules require additional requirements for their proper functioning. Specific
examples are described in section H.
--------------------------------------------------------------------------------
G. Run
1. Receiver
Usage: warden-receiver.pl
2. Factory
Usage: warden-factory.pl MODULE_CONF_NAME
MODULE_CONF_NAME
Represents specific configuration section placed in 'factory.conf'. Each of modules
can have more configuration alternatives which are distinguished by name.
For simple call of individual modules is possible use prepared cron script
placed in 'etc/cron.d/' directory.
*WARNING: When generating a report using cron, the interval in configuration file and
interval in cron script must be IDENTICAL, otherwise a result may be INACCURATE.
3. Cleaner
Usage: warden-cleaner.pl
--------------------------------------------------------------------------------
H. The requirements of modules
These modules require an initial steps:
1. IPtables
Redirect of specific traffic to chain specified in the configuration.
If the 'chainname="BLOCK"' option is used and you are interested in SSH attackers (tcp/22),
it's necessary use these commands:
iptables -N BLOCK
iptables -I INPUT 1 --protocol tcp --dport 22 --jump BLOCK
2. IPset
Initialize the new set and create a blocking rule in iptables.
If the 'setname="BLOCK"' and 'outputfile="rules.txt"' options are used and and you are
interested in SSH attackers (tcp/22) it's necessary use these commands:
ipset --create BLOCK iphash
iptables -I INPUT 1 --protocol tcp --dport 22 -m set --match-set BLOCK src --jump DROP
Change of the rules using script consume a lot of CPU resources, so it is necessary
to use a pipe:
ipset - < rules.txt
--------------------------------------------------------------------------------
X. Tutorial: Running of the WApp along with the database backend
1. Database engine configuration (conf/db.conf)
[SQLITE]
db="var/warden.db"
user=
pass=
2. Receiver configuration (conf/receiver.conf)
[GENERAL]
method="db"
wardenpath="/opt/warden-client"
# Type of event which will be requested. To get all types of event, leave this option blank.
requested_type=
[DB]
dbengine="sqlite"
3. Factory configuration, IPtables module (conf/factory.conf)
[MOD_IPTABLES_1]
enabled="yes"
module="IPtables"
outputfile="tmp/iptables.txt"
threshold="10"
excludedip="1.1.1.1","2.2.2.2"
eventtype=
chainname="BLOCK"
destchain="DROP"
maxage="4M"
4. Cleaner configuration (conf/cleaner.conf)
[GENERAL]
method="db"
maxage="5D"
5. Run
I. Manually
# ./warden-receiver.pl
# ./warden-factory.pl MOD_IPTABLES_1
# ./warden-cleaner.pl
II. Regularly using cron (example in etc/cron.d/wardenapp)
SCRIPT_PATH=/opt/warden-app/
*/5 * * * * root cd $SCRIPT_PATH; ./warden-receiver.pl
21 * * * * root cd $SCRIPT_PATH; ./warden-factory.pl MOD_IPTABLES_1
1 1 * * * root cd $SCRIPT_PATH; ./warden-cleaner.pl
--------------------------------------------------------------------------------
X. Tutorial: Writing your own module
The base for modules is interface with hashes '%CONSTANTS', '%FORMAT' and sub 'run()'.
Both of them has to be implemented. Modules are placed in 'Modules' directory.
sub run() - Main subroutine, which is always called from the parent's environment.
%CONSTANTS - Variable with all supported options and their default values.
%FORMAT - Regexp for variables which must have a specific format.
IPtables module more deeply
===========================
1. Defining configuration parameters
All configuration options with their default values are stored in %CONSTANTS hash.
my %CONSTANTS = (
enabled => "no",
outputfile => "tmp/iptables.txt",
threshold => 250,
excludedip => [],
eventtype => [],
chainname => "BLOCK",
destchain => "DROP",
maxage => "1D",
);
In this case is used parameter maxage which must be in format '\d+[hdmHDM]'. Then it is
possible use '%FORMAT' hash to enforce specific format, otherwise will be used default
value from '%CONSTANTS'.
my %FORMAT = ( maxage => qr/\d+[hdmHDM]/, );
2. Implementation of the main function
I. The usual start function, reading the parameters from the parent function and retrieving
values from the config file.
sub run {
my (undef, $modprefix, $cfg, $dbh, $db_engine) = @_;
my $v = Constants::mergeConfigs($cfg, $modprefix, \%CONSTANTS, \%FORMAT);
II. Creating of string with database query. It is possible use built-in routines like joinIN,
joinNotIN, getOldDataDB or getQueryCondThreshold.
my $eventtype_query = DB::joinIN("type", \@{$v->{'eventtype'}});
my $excluded_query = DB::joinNotIN("source", \@{$v->{'excludedip'}});
my $condition = substr($excluded_query . $eventtype_query, 0, -5);
my @columns= ("source");
my @params = ($condition, DB::getOldDataDB($db_engine, "NEWER", $v->{'maxage'}));
my $query = DB::getQueryCondThreshold($db_engine, "events", \@columns, \@params, $v->{'threshold'});
III. Executing of created query and storing result to array.
my @rows = Utils::fetchall_array_hashref($dbh, $query);
IV. Implementing of subroutines 'header', 'record' and 'footer'. References to these functions
can be used like parameter in routine, which generates the final output. Mentioned routines
can get configuration values as a parameter and in addition, 'record' gets value of actual
record in loop over result of query.
sub header { my $v = shift; return "/sbin/iptables -F $v->{'chainname'}\n"; };
sub record { my ($r, $v) = @_; return "/sbin/iptables -A $v->{'chainname'} -s $r->{'source'}/32 -j $v->{'destchain'}\n"; };
my $ret = Utils::generateOutput($v->{'outputfile'}, \@rows, \&header, \&record, undef, $v);
V. Exit code is returned to parent.
return $ret;
}
--------------------------------------------------------------------------------
Copyright (C) 2013 Cesnet z.s.p.o