Skip to content

Development Guide

This guide covers building, testing, and debugging the EMBSEC Lab Development Kit.

Overview

The EMBSEC Kit uses a modern development workflow:

  • CMake for cross-platform builds
  • Docker for consistent environments
  • QEMU for hardware emulation
  • Python for test automation
  • GDB for debugging

Quick Reference

Essential Commands

# Configure and build
make setup
make build

# Run tests
make test

# Debug a lab
make debug-01-buffer-overflow

Development Sections

Building

  • CMake configuration
  • Build targets
  • Cross-compilation
  • Optimization levels

Testing

  • Unit test framework
  • Integration tests
  • QEMU automation
  • Coverage reports

Debugging

  • GDB with QEMU
  • Hardware debugging
  • Memory analysis
  • Exploit development

Environment Setup

  • Docker development
  • IDE configuration
  • Tool installation
  • Troubleshooting

Development Workflow

1. Make Changes

# Edit source files
vim labs/my-lab/src/main.c

# Format code
make format

2. Build and Test

# Build specific lab
cmake --build build --target my-lab

# Run tests
make unittest-lab LAB=my-lab

3. Debug Issues

# Start GDB session
make debug-my-lab

# Or manual QEMU + GDB
qemu-system-arm -M lm3s6965evb -kernel build/labs/my-lab/my-lab -S -gdb tcp::1234
arm-none-eabi-gdb build/labs/my-lab/my-lab

4. Submit Changes

# Run all tests
make test

# Create merge request
git push origin feature/my-lab

Project Structure

kit/
├── sdk/              # Core SDK library
├── labs/             # Security challenge labs
├── tools/            # Build and test tools
├── docs/             # Documentation (you are here)
└── CMakeLists.txt    # Root build configuration

Common Tasks

Adding a New Lab

  1. Copy template: cp -r labs/template labs/my-lab
  2. Update labs/my-lab/metadata.yml
  3. Implement vulnerability in src/main.c
  4. Write tests in tests/test_lab.py
  5. Add to labs/CMakeLists.txt

Updating SDK

  1. Modify headers in sdk/include/
  2. Update implementation in sdk/src/
  3. Add tests to sdk/tests/
  4. Update documentation

Creating Exploits

  1. Use tools/scripts/exploit_template.py
  2. Test with QEMU
  3. Verify with hardware
  4. Document approach

Best Practices

  • Test Early: Run tests after every change
  • Use Docker: Ensures consistent builds
  • Document Code: Update docs with API changes
  • Security First: Consider security implications
  • Cross-Platform: Test on multiple systems

Getting Help