Skip to content

Quick Start Tutorial

This tutorial will guide you through building and running your first EMBSEC lab in under 5 minutes.

Prerequisites

Ensure you've completed the installation process.

Step 1: Clone the Repository

git clone https://gitlab.com/embsec/kit.git
cd kit

Step 2: Initial Setup

Run the one-time setup command:

make setup

This will:

  • Check all dependencies
  • Configure for both hardware and QEMU
  • Create necessary build directories

Step 3: Build for QEMU

make qemu-build

This builds all labs for the QEMU emulator.

Step 4: Run Your First Lab

make qemu-01-buffer-overflow

You should see: 

*** Booting Zephyr OS build v3.0.0 ***

Welcome to Buffer Overflow Lab!
Enter your name:

Step 5: Interact with the Lab

  1. Try entering a normal name: 

    Enter your name: Alice
Hello Alice!

  2. Exit QEMU with Ctrl-A then X

Understanding What Happened

You just:

  1. Built the EMBSEC SDK and labs
  2. Launched a lab in QEMU ARM emulator
  3. Ran embedded code with a buffer overflow vulnerability

Common Commands

Running Labs

# Run any lab
make qemu-<lab-name>

# Examples:
make qemu-01-buffer-overflow
make qemu-02-format-string

Testing

# Test all labs
make test

# Test specific lab
make unittest-lab LAB=01-buffer-overflow

Building

# Build everything
make build

# Build only SDK
make sdk

# Clean build
make clean

Troubleshooting

QEMU Won't Start

  • Ensure QEMU is installed: qemu-system-arm --version
  • Check the build succeeded: ls build-qemu/labs/

Build Fails

  • Run make clean then make setup again
  • Check ARM toolchain: arm-none-eabi-gcc --version

Can't Exit QEMU

  • Press Ctrl-A then X (not Ctrl-C)

Next Steps