Quick start

Installation

This quick start guides will help you to get OpenKAT started on Ubuntu using the Docker setup. The steps below were performed on a clean Ubuntu 22.04 LTS virtual machine. This quick start assumes you have a working Ubuntu installation ready. Please note that these steps help you to setup a playground/developer environment for OpenKAT, this means you should not use it as a production environment. If you do, you do so at your own risk.

Do not install Docker directly from the default Ubuntu repositories. This version is older and OpenKAT generally uses newer features. Using the Ubuntu repository version will likely break your OpenKAT install (at some point).

  1. Follow the Docker installation steps as mentioned here: Docker Ubuntu Installation steps. This tutorial followed the installation steps using the apt repository. Make sure that you can run the hello-world Docker image.

  2. Follow the Post-installations steps as described here: Docker Post-installation steps. Make sure that the Docker hello-world image can run as a normal (non-root) user.

  3. Install missing Ubuntu packages.

sudo apt install make

  1. Decide if you want to install the latest stable version of OpenKAT or if you want to run main. Clone the OpenKAT repository to a location of your choice as shown below.

$ git clone https://github.com/minvws/nl-kat-coordination.git

  1. Change into the cloned repository.

$ cd nl-kat-coordination/

  1. Create the environment file and run kat.

$ make env
$ make kat

  1. Pet your cat while you wait for all the containers to be built.

  2. Get your password from the .env file. An example of what this looks like is shown below.

$ cat .env | grep DJANGO
DJANGO_SUPERUSER_PASSWORD=83d0ddac75c3fed23d2fc3a607affe432f9916d0f9dcc12680

  1. Open your browser and go to: http://localhost:8000/en/login. Login using the username superuser@localhost and the password that you found using the previous step (everything after the equal sign =).

  2. Meowlations! You just installed OpenKAT. As this is your first time using OpenKAT, you will have to walk through the onboarding. This is explained further below.

Onboarding

If you are using OpenKAT for the first time you can go through the onboarding flow. The onboarding flow helps you to perform your very first scan. The onboarding flow introduces the basic concepts of adding an object, setting a clearance level, enabling boefjes in order to gather data and perform various scans and the creation of your first report.

The onboarding consists of two parts:

  • Registration process: creating accounts and setting up 2FA, organization creation

  • OpenKAT introduction

Login & Registration

Once you login you will see the screen for setting up 2 factor authentication (2FA). You have to scan the QR code with an authenticator application on your phone, the application on your phone will generate a token that you have to type in as a response. Every time you want to login, you have to enter your username, password and 2FA token. You can disable 2FA in the .env file if necessary.

Setting up 2 factor authentication.

Once you have successfully setup 2FA you will see the following screen.

Successful setup of 2 factor authentication.

The next step is to go through the registration process, which let’s you create your very first organization.

Start page for the registration process.

On this page you are asked to enter the name of your organization and a code that is used to identify your organization. If you are unsure what to do here, take a look at the next screenshot.

Form to ask for the name of your organization.

The dummy organization for this tutorial is called ‘Meow’, which is entered in the ‘Name’ field. The code we came up with that will identify this organization is ‘meow’. Usually this is some kind of shorthand to identify your organization.

Entering dummy organization information.

The next step is to add the indemnification statement. Before you are allowed to scan, you are legally required to sign a waiver stating that you know what you are doing when scanning websites/hosts and that the person who signed the waiver can be held accountable. Please read the indemnification carefully and click the checkboxes if you agree.

Registration of the indemnification statement.

Decide how you want to add accounts. The easiest way is to follow the onboarding flow, as this will do everything automatically. If you decide to click the ‘Create separate accounts’ button you’ll have to perform manual steps.

Create accounts.

The next page gives a quick introduction of how OpenKAT works.

How does OpenKAT work.

A brief introduction on how reports are generated is given.

Report introduction.

The onboarding shows a few report types. The only report you can choose during the onboarding is the DNS report.

Choose report type.

The next steps gives some basic information before adding your first object.

Basics of adding objects.

Here you can add your very first object! You do this by entering the URL for a website that you have permission to scan. The next screenshot will show you an example of what this could look like.

Adding your first object.

Here we add our dummy URL https://mispo.es. Feel free to add this URL, as it is part of our testing environment.

Adding a dummy URL.

The plugins in OpenKAT have various scan levels to indicate if they are more or less intrusive for the objects that are scanned. Here you can find two examples of a less intrusive plugin (DNS zone) and a more intrusive plugin (Fierce). This level of intrusiveness is indicated by the number of paws, where more paws is more intrusive.

Plugins with different intrusion levels.

Each object in OpenKAT has a clearance level, stating how intrusive the scans for the object can be. If you give an object Level 1 clearance, only non-intrusive plugins are allowed to scan it. If you give it Level 4 clearance, all plugins, including the very intrusive ones, will scan this object.

Clearance level explanation.

Since this is the onboarding, we set the clearance level to Level 1.

Set the clearance level for your URL.

Before we can scan we have to enable plugins. Here you can choose some plugins. By default all three plugins are enabled. They are all non-intrusive plugins that will gather basic DNS data for your added URL.

Select plugins.

This is the last page giving on overview of some scanning data. Click the button to start scanning!

Scan detail page

OpenKAT will now add the URL and perform the scans on this URL, gather and analyse the data and create your DNS report. This will take about 3 minutes, so get a coffee, pet your cat, or do a little dance! The button will be clickable once the report is available.

Waiting for your first scan to finish.

This is your very first DNS report! Congrats. After reviewing your report you can become familiar with the user interface by clicking on one of the items in the navigation bar at the top. If you need any help with navigating around and becoming familiar with OpenKAT, you can always go to the user manual.

In the user manual you will find information on all the user interface related items of OpenKAT.

DNS report