Security Ripcord

Cutaway Security Blog and Projects

Creating a Docker IEEE 802.15.4 Toolkit

For the tl;dr crowd: I have started a project to consolidate IEEE 802.15.4 testing tools into a Docker image: cutaway/dot15d4_toolkit and a Githut repo: cutaway/dot15d4_toolkit. The Dockerfile in this project is designed to build, install, and run River Loop Securitys version of Killerbee, my implementation of Scapy-com, atlas rfcat, and Josh Wrights Killerzee.

While trying to understand Googles GRR Rapid Response framework I worked with the GRR Docker example deployment. Since I dont have any experience with Docker I decided I needed to understand what the GRR Docker was actually doing to get a grasp of how to communicate with systems running as a Docker container. I figured the best way to do this was to implement a simple Docker container of my own, other than the Docker Hello World.

First I started with doing a little light reading on the difference between Docker and virtual machines. Since most of the things I do involve virtual machines, I have never really worked with implementations of virtualization that leverage the Hypervisor. I found the following articles informative and Ill leave it to the reader to dive in.

Next I downloaded and installed Docker Toolbox and then follow the Docker installation instructions. Docker installs VirtualBox as the vitualization software. From previous experience working with VirtualBox I knew that I would need to install the VirtualBox Extension Pack to enable USB support. This started me thinking about any USB devices I would like to test and I realized that Docker would be a great way to introduce people to the updates I did to the Scapy-Com Zigbee libraries. This gave me a nice direction for getting generating a Docker image and all of the configuration settings and deployment issues that come with it.

Docker Toolbox currently installs “Docker Quick Start Terminal” and “Kitematic (Alpha)” in Windows 10. I played with both a bit and settled on using Kitematic as it provide a nice user interface and is easy to grasp for new users. The sidebar on the left provides a list of containers that have been previously been run. When a container is selected the menu near the top of the window provides access to several methods, the most useful of which is access to the containers command terminal (in Windows this opens in PowerShell).

Overview of Kitematic GUI

Since I prefer Kubuntu to Ubuntu I located a Kubuntu Dockerfile to start my testing. After installing and running it the first time I realized I do not need a windowing system and removed all but the first line: FROM ubuntu:14.04. First I just installed the OS by building the image following the Docker Build your own images instructions. Following the steps in the “Building an image from a Dockerfile” section I established the basics behind building my image. Using the Docker Command Line terminal (see picture above) I changed directories to the location of my Dockerfile. To build my image I ran the following command. I snipped the output from this command because I ran through many iterations of changes to the Dockerfile and because the Ubuntu update and installation process outputs a lot of information.

PS C:\Users\cutaw\Tools\Docker\Dot15d4> docker build -t cutaway/dot15d4:latest .
[snip for brevity]

It was easy to determine a failed build from a successful build. First, the STDOUT of the build process identified any commands that failed to run. Second, the “REPOSITORY” and “TAG” values will be “” instead of having the build values of, in the case of my build, cutaway/dot15d4:latest. A simple way to determine a successful build is to list installed Docker images.

PS C:\Users\cutaw\Tools\Docker\dot15d4> docker images
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
cutaway/dot15d4   latest              078e46855a0c        30 minutes ago      557.9 MB
ubuntu              14.04               8f1bd21bd25c        9 days ago          188 MB
hello-world         latest              94df4f0ce8a4        5 weeks ago         967 B
grrdocker/grr       v0.3.0-7-latest     387bb5f92eb9        4 months ago        1.246 GB
phanect/kubuntu     latest              2f45f7412b46        5 months ago        2.381 GB

Of course, my first build was not a successful build. In fact, I built many times only to have a fully installed Ubuntu OS but the additional software installations or system modifications failed. As you can see from the “SIZE” field each of these instances are over 500 MB. This adds up rather quickly when you have five or six builds with “” as the value for “REPOSITORY”. It took me a while to find out how to clean these up but the answer was easy. Deleting unwanted images is performed by referencing the “IMAGE ID” as follows. This command would actually delete the “cutaway/dot15d4” image from my repository. Users can just modify the “IMAGE ID” as necessary.

PS C:\Users\cutaw\Tools\Docker\Dot15d4> docker rmi 078e46855a0c

With the OS up and running I added several of my favorite Linux tools and configurations and installed Killerbee using my updated version of Scapy-com. Running my newly generated Docker image worked and I could interact with the system by clicking on the containers “Exec” button to open a terminal to the OS. However, as one knowledgeable in Linux might expect, the OS did not locate any USB devices connected to the Host OS. This is actually when I remembered about VirtualBoxs USB issues and installed the Extension Pack. Once installed I had to reconfigure the Docker virtual machines configuration settings to enable USB 2.0 support and allow access to the KillerBee ATMEL Raven dongle.

Overview of VirtualBox USB Configuration Settings

I restarted Docker, just to be sure and restarted my Docker image. Once at the command line I quickly determined that I still did not have access to any of the USB devices. Googling this issue pointed me to a helpful StackOverflow article: Docker - any way to give access to host USB or serial device?. Thus, to allow a container access to USB, it must be initialized using the following command.

PS C:\Users\cutaw\Tools\Docker\Dot15d4> docker run -t -i --privileged -v /dev/bus/usb:/dev/bus/usb cutaway/dot15d4:latest bash

Once this is done, the container listed in the “Container” sidebar of Kitematic can be restarted over and over with these permissions. These permissions allowed access to the KillerBee ATMEL Raven dongle as shown in the following textbox. First, I use the “lsusb” command to list all connected USB devices. This is followed by identifying the KillerBee dongle and then detecting a ZigBee devices I didnt know was in the area.

# bash
root@67869d196c2f:~/Tools/killerbee# lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 002: ID 03eb:210a Atmel Corp.
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hubo
root@67869d196c2f:~/Tools/killerbee# zbid
           Dev Product String       Serial Number
       002:002 KILLERB001           B7AD17FFFF25
root@67869d196c2f:~/Tools/killerbee# zbstumbler
zbstumbler: Transmitting and receiving on interface '002:002'
New Network: PANID 0x588A  Source 0x597F
        Ext PANID: 00:0d:6f:00:01:db:9b:36      Stack Profile: ZigBee Enterprise
        Stack Version: ZigBee 2006/2007
        Channel: 25

Once this was completed I suddenly realized that I needed to install some additional tools to test other IEEE 802.15.4 implementations. Thus I added rfcat and KillerZee to the Dockerfile. But, while I have tested that the image built correctly I have yet to test the functionality of rfcat and KillerZee. But, as it stands, that testing and reconfiguration, if necessary, should be easy and straightforward to accomplish.

Moving forward you can find the Dot15d4 Toolkit in Docker for your pulling pleasure. If you want to go through the build process and update the Dockerfile with your own configuration settings you can fork my Github Dot15d4 Toolkit repository.

Go forth and do good things,
Don C. Weber (cutaway)