Openkat

An experimental sandbox environment to easily experiment with (some) functionality of openkat. This version of openkat runs all services in a single process and replaces services such as Bytes, Rabbitmq and Celery with an in-memory implementation. As a consequence, the current version does not guarantee persistence beyond the lifetime of the process. It speaks for itself that this library should not be used in a production environment. To properly deploy an openkat instance, please refer to the official documentation on Github.

Overview

Features

These features of openkat are currently present in this package

The Rocky interface: UI around reporting on Findings
The Octopoes models: for modelling the Objects Of Interest (OOIs)
The Boefjes/Normalizers: the python scripts that find OOIs (excluding the containerized versions)
The Scheduler: dispatching Boefjes and Normalizers automatically

Benefits

The benefits and extra features of this package are:

Lightweight: a single process for the app, reducing overhead of the official services and installation times
A default superuser and development organization
OTP disabled to optimize for restarting the service even after an update
Adding plugins by creating plugins in a custom plugins folder

Missing Features

However, some features are excluded from this version on purpose:

Audit trailing using Bytes
Miscellaneous functionality in the interface, such as specifying a depth of an OOI tree and custom images in the KATalogus
Deletion Propagation: you have to manually delete every single OOI
ScanProfile inheritance: you have to manually add scan profiles to observed OOIs
Valid times: you cannot browse the OOI history through time

Coming Features

Some missing features are still to be added:

Bits
Object persistence beyond server lifetime

Installation

$ pip install py-openkat

Dependencies

To use the Dockerized boefjes, you must have Docker installed on your machine.

Usage

To start the instance, run

$ python -m openkat

and navigate to http://localhost:8000. Login with email super@user.com and password superuser. You can start adding your objects now (see the official documentation). Note: restarting the service clears your object database.

Adding your own plugins

To extend the functionality of openkat with custom Boefjes create a file (e.g kat.py) with the following contents:

import openkat

openkat.start(plugin_dir="plugins")

Then, create a directory in your current working directory called plugins and copy an internal Boefje (starting with kat_) into the plugins folder.

If you are like me and just want a one-liner:

$ mkdir plugins && \
  mkdir plugins/kat_dns2 && \
  for file in "__init__.py" "boefje.py" "description.md" "main.py" "normalizer.py" "requirements.txt" ; \
  do curl https://raw.githubusercontent.com/Donnype/nl-kat-boefjes/869167d1b723a1a58c044d45f668fbade33cf372/boefjes/plugins/kat_dns/$file > plugins/kat_dns2/$file; \
  done

Change the folder name, and at least the id, and name of the Boefje model definition in boefje.py, together with the name and module (this should be "{the folder name}.{module name}") of the Normalizer model definition. Be careful not to use an existing folder name or this will overwrite an existing boefje (and require re-installation).

Have I told you I like one-liners? (Note: sed behaves differently on OS X)

$ sed -i -e "s/id\=\"dns-records\"/id\=\"my-id\"/g" \
    -e "s/module\=\"kat_dns\.normalize\"/module\=\"kat_dns2.normalize\"/g" \
    -e "s/name\=\"DnsRecords\"/name\=\"MyBoefje\"/g" \
    -e "s/name\=\"kat_dns_normalize\"/name\=\"kat_dns2_normalize\"/g" \
    plugins/kat_dns2/boefje.py

Start the service by running

$ python -m kat

and you should be able to use it as usual, but with the added functionality.

Contributing

Dependencies:

poetry
yarn

To setup a development environment, run

$ make init

To build, run

$ make build

Donnype/py-openkat