diff --git a/warden3/warden_client/README b/warden3/warden_client/README
index fb7dc6186dcee675808260e9dd56372103e494d3..42d4dca69cde31acdf0352acaf1cfd71d34fa607 100644
--- a/warden3/warden_client/README
+++ b/warden3/warden_client/README
@@ -5,9 +5,10 @@
Content
A. Introduction
- B. Concepts
- C. HTTP/JSON API
- D. Python API
+ B. Quick start (TL;DR)
+ C. Concepts
+ D. HTTP/JSON API
+ E. Python API
------------------------------------------------------------------------------
A. Introduction
@@ -22,22 +23,44 @@ Server is written in Python - mature language with consistent and coherent
libraries and many skilled developers.
------------------------------------------------------------------------------
-B. Concepts
+B. Quick start (TL;DR)
+
+ * Obtain X509 key/cert, corresponding with DNS name of you machine.
+ * Obtain X509 CA chain for server validation.
+ * Choose client name ("reverse DNS", like org.example.warden.client, but
+ it does not necessary need to correspond to your machine's DNS name).
+ * Ask Warden server admins for registration. They will want to know at least
+ client name and dns name, and short description of the (planned) client
+ and its purpose. Work with them. They may request some changes or
+ clarifications, offer you useful guidelines, provide you with alternative
+ sandbox URL, etc.
+ If succesful, you will receive authentication secret.
+ * Use warden_curl_test.sh to check you are able to talk to server.
+ * See warden_client_examples.py on how to integrate sending/recieving
+ into your Python application.
+ * Alternatively, check 'contrib' directory in Warden GIT for various
+ ready to use tools or recipes. You may find senders for various
+ honeypots, or warden_filer may get handy if you do not want to delve
+ into Python at all.
+ * Welcome! Thanks for your security data, and use others' for common good.
-B.1. Event description format
+------------------------------------------------------------------------------
+C. Concepts
+
+C.1. Event description format
IDEA - Intrusion Detection Extensible Alert, flexible extensible format
for security events, see:
https://csirt.cesnet.cz/IDEA
-B.2. Event serial ID
+C.2. Event serial ID
Each received event gets assigned integer serial number. These numbers are
sequential, so each recipient can keep track of the last event "id" it
received and next time ask only for following events.
-B.3. Authentication
+C.3. Authentication
In Warden 2, clients get authenticated by server certificate, however
server certificate is usually same for the whole machine, so individual
@@ -54,7 +77,7 @@ for each particular client (which is also fully supported).
Client also has to have server CA certificate (or chain) at its disposal
to be able to verify server authenticity.
-B.4. Client name
+C.4. Client name
Unlike Warden 2, client names in Warden 3 have hierarchy. Modelled after
Java class names, client name is dot separated list of labels, with
@@ -70,7 +93,7 @@ particular client, or (for some recipients flawed) notion of "own" messages,
but based on wider units.
------------------------------------------------------------------------------
-C. HTTP/JSON API
+D. HTTP/JSON API
Client must know the base URL of the Warden server. Warden 3 accepts
queries on paths under base URL (which correspond to called method), with
@@ -94,7 +117,7 @@ particular method.
If HTTPS call succeeds (200 OK), method returns JSON object containing
requested data.
-C.1. Error handling
+D.1. Error handling
Should the call fail, server returns HTTP status code, together with JSON
object, describing the errors (there may be multiple ones, especially when
@@ -116,7 +139,7 @@ will need to inspect logs and rectify the cause.
Server errors (5xx) may be considered by client as temporary and client is
advised to try again after reasonable recess.
-C.2. Common arguments
+D.2. Common arguments
* secret - shared secret, assigned to client during registration
* client - client name, optional, can be used to mimic Warden 2
@@ -217,7 +240,7 @@ curl \
--data-binary "@-" \
"https://warden.example.org/sendEvents?client=$client&secret=SeCrEt"
-{}
+{"saved":1}
(However note that this is not the best way to generate Idea messages. :) )
@@ -273,7 +296,7 @@ $ curl \
"description": "Warden 3 server"}
-D. Python API
+E. Python API
Python API tries to abstract from raw HTTPS/URL/JSON details. User
instantiates Client class with necessary settings (certificates, secret,
diff --git a/warden3/warden_client/warden_client_test.py b/warden3/warden_client/warden_client_examples.py
similarity index 74%
rename from warden3/warden_client/warden_client_test.py
rename to warden3/warden_client/warden_client_examples.py
index 74f39f0a6c18419f5551b1d91d20a162c00d6dd2..a66262b2c8165e0419a7e9af3a85af5e69ee4334 100755
--- a/warden3/warden_client/warden_client_test.py
+++ b/warden3/warden_client/warden_client_examples.py
@@ -1,10 +1,10 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
#
-# Copyright (C) 2011-2013 Cesnet z.s.p.o
+# Copyright (C) 2011-2015 Cesnet z.s.p.o
# Use of this source is governed by a 3-clause BSD-style license, see LICENSE file.
-from warden_client import Client, Error, read_cfg
+from warden_client import Client, Error, read_cfg, format_timestamp
import json
import string
from time import time, gmtime
@@ -15,19 +15,12 @@ from os import path
from random import randint, randrange, choice, random;
from base64 import b64encode;
-def get_precise_timestamp():
- t = time()
- us = trunc((t-trunc(t))*1000000)
- g = gmtime(t)
- iso = '%04d-%02d-%02dT%02d:%02d:%02d.%0dZ' % (g[0:6]+(us,))
- return iso
-
def gen_min_idea():
return {
"Format": "IDEA0",
"ID": str(uuid4()),
- "DetectTime": get_precise_timestamp(),
+ "DetectTime": format_timestamp(),
"Category": ["Test"],
}
@@ -69,12 +62,12 @@ def gen_random_idea(client_name="cz.example.warden.test"):
event = {
"Format": "IDEA0",
"ID": str(uuid4()),
- "CreateTime": get_precise_timestamp(),
- "DetectTime": get_precise_timestamp(),
- "WinStartTime": get_precise_timestamp(),
- "WinEndTime": get_precise_timestamp(),
- "EventTime": get_precise_timestamp(),
- "CeaseTime": get_precise_timestamp(),
+ "CreateTime": format_timestamp(),
+ "DetectTime": format_timestamp(),
+ "WinStartTime": format_timestamp(),
+ "WinEndTime": format_timestamp(),
+ "EventTime": format_timestamp(),
+ "CeaseTime": format_timestamp(),
#"Category": ["Abusive.Spam","Abusive.Harassment","Malware","Fraud.Copyright","Test","Fraud.Phishing","Fraud.Scam"],
# "Category": ["Abusive.Spam","Fraud.Copyright"],
"Category": [choice(["Abusive.Spam","Abusive.Harassment","Malware","Fraud.Copyright","Test","Fraud.Phishing","Fraud.Scam"]) for dummy in range(randint(1, 3))],
@@ -119,16 +112,19 @@ def gen_random_idea(client_name="cz.example.warden.test"):
"Node": [
{
"Name": client_name,
- "Tags": [choice(["Data", "Protocol", "Honeypot", "Heuristic", "Log"]) for dummy in range(randint(1, 3))],
+ "Type": [choice(["Data", "Protocol", "Honeypot", "Heuristic", "Log"]) for dummy in range(randint(1, 3))],
"SW": ["Kippo"],
"AggrWin": "00:05:00"
+ },
+ {
+ "Name": "org.example.warden.client",
+ "Type": [choice(["Connection", "Datagram"]) for dummy in range(randint(1, 2))],
}
]
}
return event
-
def main():
wclient = Client(**read_cfg("warden_client.cfg"))
# Also inline arguments are possible:
@@ -145,13 +141,19 @@ def main():
print "=== Debug ==="
info = wclient.getDebug()
- if not isinstance(info, Error):
- pprint(info)
+ pprint(info)
+
+ # All methods return something.
+ # If you want to catch possible errors (for example implement some
+ # form of persistent retry, or save failed events for later, you may
+ # check for Error instance and act based on contained info.
+ # If you want just to be informed, this is not necessary, just
+ # configure logging correctly and check logs.
+ if isinstance(info, Error):
+ print info
print "=== Server info ==="
info = wclient.getInfo()
- if not isinstance(info, Error):
- pprint(info)
print "=== Sending 10 event(s) ==="
start = time()
@@ -164,23 +166,26 @@ def main():
# cat = ['Availability', 'Abusive.Spam','Attempt.Login']
# cat = ['Attempt', 'Information','Fraud.Scam','Malware.Virus']
- cat = ['Fraud', 'Abusive.Spam']
- nocat = ['Availability', 'Information', 'Fraud.Scam']
-
- tag = ['Log', 'Data']
- notag = ['Flow', 'Datagram']
-
- group = ['cz.tul.ward.kippo','cz.vsb.buldog.kippo']
- nogroup = ['cz.zcu.civ.afrodita','cz.vutbr.net.bee.hpscan']
-
- ret = wclient.getEvents(count=10, cat=cat, nocat=None, tag=tag, notag=None, group=None, nogroup=nogroup)
+ # cat = ['Fraud', 'Abusive.Spam']
+ # nocat = ['Availability', 'Information', 'Fraud.Scam']
+ cat = []
+ nocat = []
+
+ #tag = ['Log', 'Data']
+ #notag = ['Flow', 'Datagram']
+ tag = []
+ notag = []
+
+ #group = ['cz.tul.ward.kippo','cz.vsb.buldog.kippo']
+ #nogroup = ['cz.zcu.civ.afrodita','cz.vutbr.net.bee.hpscan']
+ group = []
+ nogroup = []
+
+ ret = wclient.getEvents(count=10, cat=cat, nocat=nocat, tag=tag, notag=notag, group=group, nogroup=nogroup)
print "Time: %f" % (time()-start)
print "Got %i events" % len(ret)
for e in ret:
- print e["Category"], e["Node"][0]["Tags"], e["Node"][0]["Name"]
- if isinstance(ret, Error):
- print ret
-
+ print e.get("Category"), e.get("Node")[0].get("Type"), e.get("Node")[0].get("Name")
if __name__ == "__main__":
main()
diff --git a/warden3/warden_client/warden_curl_test.sh b/warden3/warden_client/warden_curl_test.sh
index e77c71c7baadb8d522be6cfb072b944781f12309..71dfbc2cb8bfd5ddf1514a81e68f0df223e909d3 100755
--- a/warden3/warden_client/warden_curl_test.sh
+++ b/warden3/warden_client/warden_curl_test.sh
@@ -1,18 +1,21 @@
#!/bin/sh
#
-# Copyright (C) 2011-2013 Cesnet z.s.p.o
+# Copyright (C) 2011-2015 Cesnet z.s.p.o
# Use of this source is governed by a 3-clause BSD-style license, see LICENSE file.
-keyfile='key.pem'
-certfile='cert.pem'
-cafile='tcs-ca-bundle.pem'
+if [ "$#" -ne 6 ]; then
+ echo "Run me like:"
+ echo "${0##*/} 'https://warden-hub.example.org/warden3' org.example.warden.client 'ToPsEcReT' key.pem cert.pem tcs-ca-bundle.pem"
+ exit 1
+fi
+
+
url="$1"
client="$2"
secret="$3"
-
-# --fail \
-# --show-error \
-#
+keyfile="$4"
+certfile="$5"
+cafile="$6"
echo "Test 404"
curl \
@@ -195,9 +198,3 @@ curl \
--request POST \
"$url/getInfo?client=$client&secret=$secret"
echo
-
-#curl \
-# --fail \
-# --connect-timeout 3 \
-# --request POST \
-# $url/getEvents