Labtainers Student Guide

Fully provisioned cybersecurity labs

December 1, 2020

1 Introduction

This manual is intended for use by students performing lab exercises with Labtainers. Labtain-

ers provide a fully provisioned execution environment for performing cybersecurity laboratory

exercises, including network topologies that include several diﬀerent interconnected computers.

Labtainers assume you have a Linux system, e.g., a virtual machine appliance described

below. If you are accessing a Labtainers VM via a web browser, you can skip to section 2.

1.1 Obtaining and installing Labtainers

The easiest way to obtain Labtainers is to download one of the pre-conﬁgured virtual machines

from https://nps.edu/web/c3o/virtual-machine-images, and import it into either Virtu-

alBox or VMWare. Follow the brief instructions on that download page. When you ﬁrst boot

the resulting VM, Labtainers will take a moment to update itself. You are then provided a

terminal that includes some hints, and can be used to run Labtainers.

Note that the VM’s Ubuntu Linux distribution is conﬁgured to NOT automatically perform

system updates. It may prompt you to download and install updates. That is typically not

necessary and may tie up your network bandwidth. Yes, we are suggesting you not update your

Linux VM unless and until you have the time and the bandwidth.

You may now skip to section 2.

1.2 Alternatives to the Labtainers VM Appliance

Skip this section and go to section 2 if you are using a Labtainers VM appliance or accessing

Labtainers remotvely via a browser.

Please note that Docker runs as a privileged service on your computer, and Labtainers

containers run as privileged containers. If you have sensitive data on your computer, you should

understand the isolation provided by Dockers on your system. An alternative is to use one of

our virtual machine appliances rather than running Docker directly on your computer.

1.2.1 Installing Labtainers on an existing Linux system

The Labtainer framework is distributed as a tarball from: https://my.nps.edu/web/c3o/

labtainers Click the link named: “Download the Labtainer framework”, and untar the re-

sulting ﬁle into a permanent directory on your Linux system, e.g., into ~/home. For example,

if you downloaded the ﬁle from a browser on your Linux system:

tar -xf ~/Downloads/labtainer.tar

From the directory into which you untarred the tarball start the installer script:

cd labtainer

./install-labtainer.sh

This script will install the latest version of Docker and packages required by the Labtainer

framework. It will cause your Linux host to reboot when it completes.

After the Linux host reboots, open a terminal to your Linux host and change directory to

wherever you untarred the tarball, e.g., your HOME directory.

1.2.2 Docker Desktop on Mac and Windows

This option assumes you have installed Docker Desktop and are familiar with its operation and

its security considerations. Instead of using the window manager of your computer, this option

lets you use a web browser to interact with windows managed by the NOVNC program. The

window manager appears in your browser.

Download the script from https://raw.githubusercontent.com/mfthomps/Labtainers/

master/headless-lite/headless-labtainers.sh, make it executable and run it. On a Mac,

this would be done from a terminal. On Windows, use Powershell. Open a browser and goto

http://localhost:6901/vnc.html?password= No password is needed, if prompted, simply

click the submit button.

In addition to starting the Labtainers, the script will create a /headless-labtainers di-

rectory. You should then run headless-labtainers.sh from that directory in the future to

start Labtainers. That directory will also contain persistent data, including results stored in the

labtainer xfer subdirectory. Note: Where lab messages and lab manuals indicate results are

found in /labtainer

xfer, your results will be in /headless-labtainers/labtainer xfer

Use ctrl-C to quit Labtainers.

2 Performing a Lab

All labs are run from the same Labtainer workspace directory, which is typically at:

cd $LABTAINER_DIR/scripts/labtainer-student

The prepackaged virtual machines automatically start a terminal in this directory.

To see a list of available labs, run the labtainer command with no arguments:

labtainer

Then run a speciﬁc lab, include the name of the lab:

labtainer <labname>

where labname is the name of the lab to run.

Most labs direct you to a PDF version of a lab manual, which can usually be done by right

clicking on the displayed path, or you can open the ﬁle in a browser. Please note that some

of the initial lab instructions repeat the steps you’ve already taken, and you need not perform

those again.

A list of labtainer commands can be found in Appendix A of this document.

Once you start the lab, you will typically see one or more virtual terminals connected to

computers within the lab. While running the lab, if you require more virtual terminals, use:

moreterm.py <labname> <container>

where container is the host name of the component on which to attach a terminal. It can be

omitted for labs having a single component.

The virtual terminals for most labs present bash shells via which you can interact with the

attached computer, (which is actually a Docker container designed to appear like a separate

computer). A single computer may have multiple virtual terminals attached to it. Each com-

puter is independent, and may use networks to interact with other Labtainer computers within

the lab.

Many labs automatically gather results of your work, which you will provide to your in-

structor. Note that, unless otherwise directed, exploration and experimentation you perform

either before or after performing the expected activity will not diminish or dilute your results.

And you typically do not have to take actions to collect or record your results. This occurs

automatically as noted in the next section.

2.1 Interrupting and Completing Labs

When you want to stop working for a while or are ﬁnished and ready to turn it in to your

instructor, type:

stoplab

from the Linux system from which you issued the labtainer command. All changes to the

ﬁles, etc. will be preserved and you will be able to resume the lab just the way you started it.

You can resume your work, as needed.

The stoplab command always displays the directory containing a zip ﬁle that should be

provided to your instructor. It shows the current results of your work.

The easiest way to forward the complete zip ﬁle to the instructor is to start a browser, e.g.,

Firefox, on the VM from which you are running Labtainers. Then use the browser to either

email the zip ﬁle, or upload it into an LMS system, e.g., Sakai. Alternately, you can conﬁgure

the VM to use a shared folder, and use that to copy the zip ﬁle to the host computer.

2.2 Redoing a Lab

Sometimes you might want to redo the lab from the beginning. In this case, type:

labtainer -r <labname>

This will delete any previous containers associated with this lab and start it fresh. Warning:

this will cause all previous data from the named lab to be lost.

2.3 Checking your work

Some labs include criteria by which to automatically assess your progress. Where enabled and

supported, this feature can be utilized by issuing the checkwork command from Linux system.

That command can be run while the lab is still running.

2.4 Getting Help and Things to Avoid

To get help, type:

labtainer -h

from the Linux system from which you issued the labtainer command. A list of useful labtainer

commands will be displayed.

Do not run multiple labs simultaneously. Consistent results cannot be guaranteed when

more than one lab runs at the same time.

2.5 Networking

In addition to network properties deﬁned for the lab, each component /etc/host ﬁle includes

a “my host entry” that names the host Linux. Most containers will include a default gateway

that leads to the Linux host. This allows students to scp ﬁles to/from the container and host. It

also allows the student to reach external networks, e.g., to fetch additional packages in support

of student exploration.

In some instances, the lab requires one or more components to a have diﬀerent default

route. Typically, these components will include a togglegw.sh script that the student can use

to toggle the default gateway between one that leads to the host, and one deﬁned for the lab.

This allows students to add packages on components having lab-speciﬁc default gateways. Use

of the togglegw.sh script is not necessary to reach the Linux host, (e.g., to scp ﬁles).

2.6 Installing and Using Labtainers Behind a Web Proxy

If you are not behind a web proxy, ignore this section (most school environments are not behind

proxies). If you are behind a web proxy, Labtainer installation requires that you have conﬁgured

your Linux package management conﬁguration to reﬂect the proxy, e.g., the /etc/atp/apt.conf

or /etc/dnf.conf ﬁles.

Additionally, you will need to conﬁgure your Docker service as described at: https://

docs.docker.com/engine/admin/systemd/#httphttps-proxy And set the HTTP PROXY

environment variable to your proxy, e.g.,

HTTP_PROXY=http://myproxy:3128

If you wish to use apt-get from within a container to add new software to a container, you must

ﬁrst modify the container’s /etc/apt/apt.conf ﬁle to reﬂect your proxy.

2.7 Limitations

The Labtainer “computers” are individual Docker containers that are interconnected via virtual

networks. These containers each share the Linux kernel of your host. Thus, a change to the

kernel conﬁguration on one computer, (e.g., enabling ASLR), will be visible on other containers,

as well as your host.

It is suggested that the student’s Linux host be a virtual machine that is not used for

purposes requiring trust. Software programs contained in cybersecurity lab exercises are not,

in general, trusted. And while Docker containers provide namespace isolation between the

containers and the Linux host, the containers run as privileged. Labtainers run as Docker

containers and use the Docker group which is root-equivalent. In other words, even though

you start a Docker container as a non-privileged user, software in the resulting container can

modify the Linux host, e.g., the VM.

The computers each include a “local” directory beneath the HOME directory. This is used

by the Labtainer framework and includes results that get packaged up for forwarding to the

instructor. Do not modify any ﬁles beneath the .local directory. Otherwise, you can treat those

containers as Linux systems, and explore them.

Pasting multiple commands into a labtainer terminal may result in the not all of the com-

mands being executed.

Appendix A: Labtainer Command Summary

The following labtainer commands are available from the labtainer/labtainer-student di-

rectory. Most of these commands include a -h option for help:

• labtainer <lab> -- Start the named lab. If no name is given, a list of available labs

will be displayed.

• stoplab -- Stop the currently running lab.

• moreterm.py <lab> <container> -- create a new virtual terminal for the container.

• labtainer <lab> -r -- Delete any previous containers associated with this lab and

start it fresh. Warning: this will lose any previous data from the named lab.

• checkwork – Performs automated assessment for selected labs and provides you with

information about your progress.

• quiz – Provides a quiz for selected labs to help prepare you to perform the lab.

• check nets.py – Runs diagnostics to potentially resolve Docker related problems.

Most labs display lab instructions in one of the windows that appears after the lab starts.

If those instructions stop displaying, e.g., because “q” is pressed in that window, then type the

following in a virtual terminal (e.g., in a new terminal created using the moreterm.py script:

less instructions.txt