+-------------------------+ | Warden Server 3.0-beta3 | +-------------------------+ Content A. Introduction B. Dependencies C. Installation D. Configuration E. Command line ------------------------------------------------------------------------------ A. Introduction Warden is a system for efficient sharing of information about detected events (threats). Warden Server is server-side part of the software, the communication hub, allowing to publish detected events and download yet unprocessed ones. The events are exchanged in Idea, flexible and descriptive event JSON serialized format. Warden 3 protocol is based on plain HTTPS queries with help of JSON, so the clients can be thin and simple. For description of API see Warden Client, this document describes basics of Warden Server administration. Warden Server is Python/WSGI based, written primarily with Apache mod_wsgi in mind. Other WSGI servers/frameworks are not yet tested, so your mileage may vary. Authentication is X509 certificate (for machine or client identification) + shared secret (for client identification, where certificate does not suffice). ------------------------------------------------------------------------------ B. Dependencies 1. Platform Python 2.7+ Apache 2.2/2.4 mod_wsgi 3.3+ 2. Python modules python-mysqldb 5.3.3+ python-m2crypto 0.20+ jsonschema 2.4+ 3. Database MySQL | MariaDB >= 5.5 ------------------------------------------------------------------------------ C. Installation * Untar distribution archive into required destination (We're using /opt as an example.) # cd /opt # tar xjf warden_server_3.0.tar.bz2 # mv warden_server_3.0 warden_server * Create database and desired database users (We're using db "warden3" and user "warden@localhost" as an example.) # mysql -p > CREATE DATABASE warden3; > CREATE USER 'warden'@'localhost' IDENTIFIED BY 'example'; > GRANT ALL ON warden3.* TO `warden`@`localhost`; > FLUSH PRIVILEGES; * Create necessary table structure mysql -p -u warden warden3 < warden_3.0.sql * Get up to date Idea schema wget -O warden_server/idea.schema https://idea.cesnet.cz/_media/en/idea0.schema * Enable mod_wsgi, mod_ssl, include Warden configuration This depends heavily on your distribution and Apache configuration. Basically you need to create and include apache.conf: Include /opt/warden_server/apache.conf or paste the contents into whichever Directory, Location or VirtualHost you dedicate for Warden. You can use apache22.conf.dist or apache24.conf.dist (for Apache version 2.2 or 2.4, respectively) as an example. You may need to change paths to certificate/key/ca material, path to warden_server.wsgi and web path alias. Also note that warden_server itself is NOT thread safe, so included configuration expects Apache with mpm-prefork worker, or you will have to configure mod_wsgi as separate process with threads=1. Also, for warden_server.wsgi, you can use warden_server.wsgi.dist as a template. You will possibly need to change at least configuration file path. * Configure Warden server (see next chapter) * Reload Apache ------------------------------------------------------------------------------ D. Configuration Configuration is JSON object in file (warden_server.cfg by default), however, lines starting with "#" or "//" are allowed and will be ignored as comments. File must contain valid JSON object, containing configuration. See also warden_server.cfg.dist as example. Top level JSON object contains subsections, which configure particular aspect of the server. Each subsection can contain "type" key, which chooses particular implementation object of the aspect, for example type of logger (file, syslog), such as: { "Log": { "type": "SysLogger", ... }, "DB": { ... } } Sections and their "type" objects can be: Log: FileLogger, SysLogger DB: MySQL Auth: X509Authenticator, X509NameAuthenticator, X509MixMatchAuthenticator,PlainAuthenticator Validator: JSONSchemaValidator, NoValidator Handler: WardenHandler "type" keyword is not mandatory, if not specified, first implementation object from particular section list is used ("FileLogger" for example). Object function and configuration keys are as follows: FileLogger: logging into file on the filesystem filename: name of the file, defaults to "warden_server.log" at installation directory level: least log level (CRITICAL, ERROR, WARNING, INFO, DEBUG) SysLogger: logging into unix syslog socket: path to syslog socket, defaults to "/dev/log" facility: syslog facility, defaults to "daemon" level: least log level (CRITICAL, ERROR, WARNING, INFO, DEBUG) X509Authenticator: authenticate based on certificate chain validation, hostname corresponding with certificate CN or SubjectAltName and optionally shared secret (note that more clients on one machine will have to have the certificate with the same hostname, clients than can be differentiated by separate secrets). This method is OBSOLETE. X509NameAuthenticator: authenticate based on certificate chain validation, certificate CN must correspond with client _name_, NOT hostname. X509MixMatchAuthenticator: automatically choose X509Authenticator or X509NameAuthenticator based on existence of 'secret' in query. Allows for seamless transition of clients between two authentication methods. PlainAuthenticator: authenticate based on client name or shared secret, usable over plain HTTP connection or HTTPS without client certificate - note that this pretty much spoils security, and is meant only for testing and debugging purposes, NOT for production servers NoValidator: forego event JSON validation, for debug purposes JSONSchemaValidator: validate incoming events based on JSON schema file filename: path to schema file, defaults to "idea.schema" at installation directory, for information on obtaining current IDEA schema file, refer to https://idea.cesnet.cz/en/schema MySQL: database storage backend host: database server host, default "localhost" user: database user, default "warden" password: database password dbname: database name, default "warden3" port: database server port, default 3306 retry_pause: retry in case of database errors, in seconds, defaults to 5 retry_count: number of retries, defaults to 3 event_size_limit: max size of serialized event, defaults to 5 MB catmap_filename: IDEA category mapping to database ids, defaults to "catmap_mysql.json" at installation directory tagmap_filename": IDEA node type mapping to database ids, defaults to "tagmap_mysql.json" at installation directory WardenHandler: Main Warden RPC worker send_events_limit: max events sent in one bunch, defaults to 10000 get_events_limit: max events received in one bunch, defaults to 10000 description: human readable description, sent in server info ------------------------------------------------------------------------------ E. Command line When run from command line, server offers set of commands and options for runtime and database management. You can also use --help option for each command and for server itself. warden_server.py [--help] [-c CONFIG] <command> optional arguments: -c CONFIG, --config CONFIG configuration file path commands: {check,register,modify,list,loadmaps} check check configuration register register new client modify modify client registration list list registered clients loadmaps load catmap and tagmap into db warden_server.py register [--help] -n NAME -h HOSTNAME -r REQUESTOR [-s SECRET] [--note NOTE] [--valid | --novalid] [--read | --noread] [--nowrite | --write] [--nodebug | --debug] [--test | --notest] Add new client registration entry. optional arguments: -n NAME, --name NAME client name (in dotted reverse path notation) -h HOSTNAME, --hostname HOSTNAME client FQDN hostname -r REQUESTOR, --requestor REQUESTOR requestor email -s SECRET, --secret SECRET authentication token (use explicit empty string to disable) --note NOTE client freetext description --valid valid client (default) --novalid --read client is allowed to read (default) --noread --nowrite client is allowed to send (default - no) --write --nodebug client is allowed receive debug output (default - no) --debug --test client is yet in testing phase (default - yes) --notest warden_server.py modify [--help] -i ID [-n NAME] [-h HOSTNAME] [-r REQUESTOR] [-s SECRET] [--note NOTE] [--valid | --novalid] [--read | --noread] [--nowrite | --write] [--nodebug | --debug] [--test | --notest] Modify details of client registration entry. optional arguments: -i ID, --id ID client id Rest of the arguments is same as in "register" command. warden_server.py list [--help] [--id ID] List details of client registration entries. optional arguments: --id ID client id warden_server.py purge [--help] [-l] [-e] [-d DAYS] Purge old events or lastlog records. Note that lastlog purge retains at least one newest record for each client, even if it is more than number of 'days' old. optional arguments: --help show this help message and exit -l, --lastlog purge lastlog records -e, --events purge events -d DAYS, --days DAYS records older than 'days' back from today will get purged warden_server.py loadmaps [--help] Load 'categories' and 'tags' table from 'catmap_mysql.json' and 'tagmap_mysql.json'. Note that this is NOT needed for server at all, load them into db at will, should you need to run your own specific SQL queries on data directly. Note also that previous content of both tables will be lost. ------------------------------------------------------------------------------ Copyright (C) 2011-2015 Cesnet z.s.p.o
Forked from
713 / Warden / Warden
13 commits behind the upstream repository.
Jakub Maloštík
authored
In MYSQL 8.0 one cannot create users using GRANT. https://dev.mysql.com/doc/refman/8.0/en/mysql-nutshell.html#mysql-nutshell-removals (MariaDB worked fine)