Table of contents

1. Getting Started
2. Your first karton
3. Malware extraction with malduck

What is Karton?

Karton is a framework for microservice orchestration, designed by security researchers for security researchers (but flexible enough to be used everywhere).

It shines in scenarios where there is a clear separation of "input" and "output" data, for example:

• Process every new .js file with box-js (javascript sandbox).
• Upload incoming .exe files to your sandbox.
• Watch the Certstream for interesting domains, and scan them with some tool (or upload to MISP).
• Quickly react to new malware campaigns and prototype a new system in no time.

This may not look impressive. But the real strength of the system is chaining multiple boxes ("Kartons") into a single pipeline:

In the real world, there may be multiple consumers and producers for resources of every type.

The system is production-ready and used in practice. One of the more pressing issues right now is poor public documentation of real-world examples. This post (and others that will follow) will tackle that issue and focus on Karton patterns and practices.

Play in the playground

The easiest way to start is with Karton-playground. First, clone the repository and set up the playground:

$ git clone https://github.com/CERT-Polska/karton-playground.git
$ cd karton-playground
$ sudo docker-compose up  # this may take a while

That's it! A simple Karton deployment is running on your local machine. It's a stripped-down environment, without any actual "logic" inside:

You're supposed to fill in the blanks. But first, let's take a look around.

Open the mwdb-core UI. It's not strictly related to Karton, but it's tightly integrated with Karton. It's used as a file database and upload interface.

Open your browser and navigate to http://127.0.0.1:8080. You should see this:

Now login with username admin and password admin. Voilà, an empty malware database:

There are no files yet. This is about to change. But first, check out the Karton dashboard too. Navigate to http://127.0.0.1:8030 and you'll see:

There's not a lot going on here. Two Karton services are running - a classifier and an mwdb reporter. You can check out the queues, but understandably they're both empty.

And that's about it. There's also a Minio interface available at http://127.0.0.1:8090 where all the samples, analysis artifacts and temporary files live (login with mwdb:mwdbmwdb).

Shoulders of the giants other researchers

It's time to do something useful. There is a small but steadily growing collection of publicly available Karton services. Most of them are listed in the README of the main Karton repository. Let's focus on karton-autoit-ripper. It's a small service used to extract AutoIT scripts from compiled binaries.

You can build it from source, but it's unnecessary (and not recommended, unless you want to submit a PR). It's packaged as a PyPi package installable with pip. Let's install it into our playground (run this in the cloned repository):

# Karton services expect a valid `karton.ini` file. It can be located
# via --config-file flag, stored in cwd, or installed system-wide.
# There is a working one in the `config/` directory.
# Copy it to the repository root for convenience.
$ cp config/karton.ini ./karton.ini

# Create a virtual environment to avoid package version conflicts.
$ python3 -m venv venv; source ./venv/bin/activate

# Instal autoit-ripper from the official package.
$ pip install karton-autoit-ripper

Almost done! This service doesn't need any configuration, so you can just run it:

$ karton-autoit-ripper

It should work out of the box:

$ karton-autoit-ripper
[2021-04-20 15:45:38,611][INFO] Service karton.autoit-ripper started
logger.py:57: UserWarning: There is no active log consumer to receive logged messages.
[2021-04-20 15:45:38,614][INFO] Service binds created.
[2021-04-20 15:45:38,615][INFO] Binding on: {'type': 'sample', 'stage': 'recognized', 'kind': 'runnable', 'platform': 'win32'}
[2021-04-20 15:45:38,615][INFO] Binding on: {'type': 'sample', 'stage': 'recognized', 'kind': 'runnable', 'platform': 'win64'}

Ignore the warning about a missing log consumer. If there are any problems, ensure that docker-compose still runs, and there is a karton.ini file in the directory you're located in.

Time to upload your first malware sample. Any autoit-packed sample will work. You can also get one from our Github:

$ wget https://github.com/CERT-Polska/training-mwdb/raw/main/autoit-malware.bin

Now, navigate to http://127.0.0.1:8080, login with admin:admin, and click on "upload sample":

If everything works correctly, you'll see a Karton analysis attribute in the lower right corner:

After a few seconds (remember to refresh using the F5 key, this does not not yet happen automatically), the status should change to "done":

And a new "child" will appear in the relationship tab:

You can navigate to the child sample, and check out the "Preview" tab:

It looks like the unpacking worked!

What's next

This is the end of the first post, but just the beginning of the planned series. Future topics include:

• Development of your own Karton microservices.
• Other publicly available and ready-to-use services (and where to find them).
• Reliable production deployment.
• Tips&tricks for Karton programmers.
• ...and more.

If anything's not clear, feel free to ask us or open an issue on karton's repo or the playground repo.