Skip to content
Snippets Groups Projects
Commit faa61a33 authored by Pavel Kácha's avatar Pavel Kácha
Browse files

* Better name for warden_client_test.py 

 * Slight help for warden_curl_test.sh
 * TL;DR README section
parent 9a2cc840
No related branches found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
warden3/warden_client/README
+ 36
− 13
View file @ faa61a33
......@@ -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,
......
warden3/warden_client/warden_client_test.py → warden3/warden_client/warden_client_examples.py
+ 41
− 36
View file @ faa61a33
#!/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()
warden3/warden_client/warden_curl_test.sh
+ 11
− 14
View file @ faa61a33
#!/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
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment