Embedded CTF Example Code
This repository contains an example reference system for MITRE's 2017 Embedded System CTF. This example meets all the requirements outlined in the challenge writeup document, but is not implemented securely.
This code is incomplete, insecure, and does not meet MITRE standards for quality. This code is being provided for educational purposes to serve as a simple example that meets the minimum functional requirements for the 2017 MITRE eCTF competition. Use this code at your own risk!
Before you can work on your bootloader, you'll first need to get up and running with our common development environment. All eCTF development and testing will happen in a vagrant provisioned virtual machine.
Note: if you already have one of these dependencies installed you should not need to install it again.
- Download and install VirtualBox here: [https://www.virtualbox.org/wiki/Downloads] using the provided instructions.
- Download and install VirtualBox Extensions (for USB support) from the same link: [https://www.virtualbox.org/wiki/Downloads] using the provided instructions.
- Download and install Vagrant here: [https://www.vagrantup.com/downloads.html] using the provided instructions.
- Download and install git here: [https://git-scm.com/download] using the provided instructions.
Downloading the Build Environment
Clone this repo using git by running the following command in your preferred shell:
git clone https://github.com/mitre-cyber-academy/2017-ectf-insecure-example.git
This will download the latest version of the build environment and example source code into the current directory.
Getting the VM Up and Running
Once you have downloaded the build environment, change into its direcotry in your shell and follow these steps to start up your VM:
Vagrantfile.localand ensure that the configurations make sense for your system configuration.
vagrant upin the shell/command line of your choice to download the VM image, provision your VM, and start it up.
vagrant sshto log in to the VM.
If any errors occur during steps 3 or 4, try to resolve them by modifying
Vagrantfile.local rather than
The AVR Dragon and USB to RS232 converters should be automatically handed over to the VM when it is running, but if they are not you should be able to attach them through the virtualbox GUI. If you run into problems with USB that you cannot resolve on your own, please ask for help in the eCTF Slack channel.
Connecting the Boards
To connect the AVR Dragon to the Protostack board, use the included ribbon cable to connect the 6-pin ISP header on the AVR Dragon to the ISP10 header on the protostack board. The notch on the connecting cable should face towards pin-1 on the Dragon. Do not use the 10-pin connector on the Dragon -- this is for JTAG and is not needed to get up and running.
VagrantfileThe base configurations for vagrant. You are not allowed to modify this file.
Vagrantfile.local.example) Local configurations for the VM on your computer only. An example is provided with basic configurations for reference. You should not submit this file, as we have our own configurations.
Vagrantfile.teamConfigurations for your team's submission. This is where you add tools, dependencies, and configurations that are required for your submission. Please add only required dependencies and configurations (editors, IDEs, etc go in Vagrantfile.local).
bootloader/In this directory is the example bootloader we have provided to you for reference. When you submit your code, your bootloader should be in this directory. See
bootloader/README.mdfor bootloader-specific instructions and help.
host_tools/In this directory are the example host tools we have provided to you for reference. When you submit your code, your host tools should be in this directory. See
host_tools/README.mdfor host-tool-specific instructions and help.
The host tools are intended to be run from your VM. They communicate with the bootloader over UART1 on the AVR.
How to Run the Tools
All of the example host tools are written in python, but do not have .py file
extensions. In Linux (e.g., on your vagrant VM) you should be able to run them
as a regular program/script (i.e.,
./bl_build). If that isn't working you may
need to run them an argument to the python interpreter (i.e.,
python bl_build). The result will be the same either way.
All tools that take arguments should have a help flag (
-h) that will provide
Checking Code Size
To check the size of your bootloader code you can run:
Also, the file
bootloader.map is now created when the firmware is created. It provides a description on where functions are located in program memory.
Programming the Board
The following command should program your board with the output from your
avrdude -P usb -p m1284p -c dragon_isp -B 200 -u -U flash:w:flash.hex:i \ -U eeprom:w:eeprom.hex:i \ -U lfuse:w:lfuse.hex:i \ -U hfuse:w:hfuse.hex:i \ -U efuse:w:efuse.hex:i
Refer to the avrdude documentation for additional help with avrdude.
The AVR dragon may occasionally end up in a state where it no longer responds to avrdude. If this happens, the problem can be resolved by disconnecting and reconnecting the dragon's USB cable.
Makefile, Flashing and Debugging
The Makefile contains targets for both flashing and debugging the AVR as well as using the JTAG functionality of the Dragon. There is a number of caveats to getting this to work. The first is that JTAG must be connected by jumpers since neither the 10-pin or 6-pin ISP connectors on the protostack board.
Refer to the JTAG connector pinout on the Dragon Board here in Figure 27.
The JTAG pins connect to the AVR as follows:
|JTAG PIN||AVR PIN|
NOTE: The VCC, Reset and Ground lines from the dragon must also be connected. If the 6-pin header of your protostack board is unpopulated, these pins are exposed on the 10-pin ISP connector. The pinout for the 10-pin ISP connector can be found here
In order to start a debug session, simply have the dragon propely connected over JTAG, then flash your
bootloader image calling avrdude from the command line or using
make flash. Once the bootloader has been
successfully loaded you can either run
make debug which should open an instance of avarice by calling
avarice -R -g :4242 which connects to the microcontroller, then starts/configures an instance of
avr-gdb with the elf file full of debug symbols.
avr-gdb tools are now included in the
Vagrant.team files. If you setup your VM previously,
you can run
sudo apt-get install avarice and
sudo apt-get install gdb-avr. Alternatively, you can run
vagrant up --provision to re-provision the VM with the new configuration.
NOTE: The specific configuration of avr-gdb is handled behind the scenes in the
IMPORTANT NOTE: Debugging will ONLY work if your dragon has the latest firmware version (reported by avrdude to be 7.39) You can run
avrdude -P usb -p m1284p -c dragon_jtag -vv to get something that looks similar to
the following report. YOU want the
firmware_version for the
S_MCU to both be 7.39 as shown
bellow. IF your dragon does not have the latest FW version you must install ATMEL Studio, connect your dragon
and protostack using the programming tools menu. From there once you read from the AVR the first time ATMEL
studio will prompt you to update your dragon to firmware 7.xx. Update then run avrdude again to make sure
you have the proper firmware version.
avrdude: Version 6.0.1, compiled on Dec 16 2013 at 17:26:24 Copyright (c) 2000-2005 Brian Dean, http://www.bdmicro.com/ Copyright (c) 2007-2009 Joerg Wunsch System wide configuration file is "/usr/local/CrossPack-AVR-20131216/etc/avrdude.conf" User configuration file is "/Users/hgiannopoulos/.avrduderc" User configuration file does not exist or is not a regular file, skipping Using Port : usb Using Programmer : dragon_jtag avrdude: jtagmkII_dragon_open() avrdude: usbdev_open(): Found AVRDRAGON, serno: 00A20006485C avrdude: jtagmkII_getsync(): Sending sign-on command: 0x86 (26 bytes msg) JTAG ICE mkII sign-on message: Communications protocol version: 1 M_MCU: boot-loader FW version: 255 firmware version: 7.39 hardware version: 1 S_MCU: boot-loader FW version: 255 firmware version: 7.39 hardware version: 7 Serial number: 00:a2:00:06:48:5c Device ID: AVRDRAGON
Detailed tool specifications should be found in the challenge rules document.
Note that while you may completely rewrite the tools, they should still live in this directory.
Your tools must be written to the exact specifications in the rules with no additional required arguments or other user inputs. This allows us to write automated tests to check if your submission is complete. If you have questions about the specifications please contact the organizers in Slack or by email: firstname.lastname@example.org.