Skip to content

Instructor Guide

Welcome to the EmbSec Kit Instructor Guide. This comprehensive documentation covers the technical aspects of creating, managing, and deploying embedded security labs.

Overview

The EmbSec Kit provides a complete framework for developing hands-on embedded security labs targeting ARM Cortex-M microcontrollers. This guide focuses on the technical implementation details needed to create effective vulnerability demonstrations and exploits.

Guide Structure

Creating Labs

Step-by-step process for developing new lab exercises, including:

  • Using the lab template system
  • CMake integration and build configuration
  • Implementing vulnerabilities safely
  • Writing comprehensive tests

Lab Design Principles

Best practices for designing educational embedded security challenges:

  • Vulnerability selection and implementation
  • Difficulty progression strategies
  • Learning objective alignment
  • Hardware and software constraints

Writing Tests

Comprehensive testing strategies for lab validation:

  • Using the test framework
  • Implementing automated exploit verification
  • Testing deterministic behavior
  • CI/CD integration

Vulnerability Patterns

Common vulnerability implementations for embedded systems:

  • Memory corruption vulnerabilities
  • Logic flaws and race conditions
  • Cryptographic weaknesses
  • Hardware-specific vulnerabilities

Best Practices

Technical guidelines for lab development:

  • Security considerations
  • Code quality standards
  • Documentation requirements
  • Debugging strategies

Quick Start

  1. Set up development environment: Ensure you have the ARM toolchain, QEMU, and Python 3.8+ installed
  2. Clone the repository: Get the latest EmbSec Kit source
  3. Review existing labs: Study labs/01-buffer-overflow and labs/02-format-string for examples
  4. Create from template: Use labs/template as your starting point
  5. Test thoroughly: Run automated tests before deployment

Technical Requirements

Development Tools

  • ARM Toolchain: arm-none-eabi-gcc 10.3 or newer
  • QEMU: 6.0+ with ARM system emulation
  • CMake: 3.16 or newer
  • Python: 3.8+ with unittest framework
  • Docker: For containerized deployment (optional)

Target Platform

  • Architecture: ARM Cortex-M3/M4
  • Board: Texas Instruments LM3S6965EVB (QEMU emulated)
  • Memory: 64KB Flash, 32KB SRAM
  • Peripherals: UART, GPIO, Timers

Lab Framework Architecture

The EmbSec Kit uses a modular architecture:

embsec-kit/
├── sdk/                    # Core SDK library
│   ├── include/           # Header files
│   ├── src/              # Implementation
│   └── cmake/            # Build helpers
├── labs/                  # Lab exercises
│   ├── template/         # Lab template
│   ├── common/           # Shared resources
│   └── XX-lab-name/      # Individual labs
└── tools/                # Development tools
    ├── scripts/          # Helper scripts
    └── docker/           # Container configs

Key Concepts

Flag Generation

Labs use deterministic flag generation based on:

  • Lab-specific salt values
  • Student identifier (compile-time)
  • SHA-256 hashing algorithm

Vulnerability Safety

All vulnerabilities are:

  • Contained within QEMU emulation
  • Limited to specific memory regions
  • Designed to prevent system crashes
  • Implemented with educational constraints

Testing Philosophy

  • Automated verification: All exploits must be scriptable
  • Deterministic behavior: Same input produces same output
  • Cross-platform support: Works on Linux, macOS, Windows (WSL)
  • CI/CD integration: Automated testing on every commit

Support Resources

  • Repository: GitHub Issues
  • Documentation: This guide and inline code documentation
  • Examples: Reference implementations in existing labs

Contributing

When contributing new labs:

  1. Follow the established patterns and conventions
  2. Include comprehensive tests and documentation
  3. Ensure cross-platform compatibility
  4. Submit via pull request with detailed description

This guide focuses on technical implementation. For course management, grading policies, or pedagogical strategies, consult the EMBSEC course instructor.