Skip to main content

Buildroot

These buildroot installation instructions assume you have a working buildroot development environment with all buildroot dependencies already installed.

Install Prerequisites​

RunSafe Protect's library is written in rust and requires the rust toolchain to be installed.

  1. Install rustup with the appropriate nightly release
wget -q https://sh.rustup.rs -O - | sh -s -- -y --default-toolchain nightly-2024-11-01 --component rust-src
  1. Install the stable toolchain
rustup toolchain install stable
  1. Install cross compilation toolchains. Note: you can install all of the below or only the ones you need for your particular target.
rustup target add i686-unknown-linux-gnu aarch64-unknown-linux-gnu armv7-unknown-linux-gnueabihf --toolchain nightly-2024-11-01
rustup target add i686-unknown-linux-gnu aarch64-unknown-linux-gnu armv7-unknown-linux-gnueabihf --toolchain stable

Install RunSafe Protect on Host System​

  1. Add the RunSafe Security repo to list of repositories apt will check for packages
curl -1sLf "https://packages.runsafesecurity.com/runsafe-security/runsafe/setup.deb.sh" | sudo -E bash
  1. Update the apt cache
sudo apt-get update
  1. Install the alkemist-lfr package
sudo apt-get install -y alkemist-lfr

The buildroot integration needs symlinks for your compiler to be able to integrate properly.

For x86_64 targeting uclibc:

sudo ln -s /usr/bin/alkemist/lfr/scripts/cc /usr/bin/alkemist/lfr/scripts/x86_64-buildroot-linux-uclibc-gcc
sudo ln -s /usr/bin/alkemist/lfr/scripts/cc /usr/bin/alkemist/lfr/scripts/x86_64-buildroot-linux-uclibc-g++

For x86_64 targeting glibc:

sudo ln -s /usr/bin/alkemist/lfr/scripts/cc /usr/bin/alkemist/lfr/scripts/x86_64-buildroot-linux-gnu-gcc
sudo ln -s /usr/bin/alkemist/lfr/scripts/cc /usr/bin/alkemist/lfr/scripts/x86_64-buildroot-linux-gnu-g++

For aarch64 targeting uclibc:

sudo ln -s /usr/bin/alkemist/lfr/scripts/cc /usr/bin/alkemist/lfr/scripts/aarch64-buildroot-linux-uclibc-gcc
sudo ln -s /usr/bin/alkemist/lfr/scripts/cc /usr/bin/alkemist/lfr/scripts/aarch64-buildroot-linux-uclibc-g++

For aarch64 targeting glibc:

sudo ln -s /usr/bin/alkemist/lfr/scripts/cc /usr/bin/alkemist/lfr/scripts/aarch64-buildroot-linux-gnu-gcc
sudo ln -s /usr/bin/alkemist/lfr/scripts/cc /usr/bin/alkemist/lfr/scripts/aarch64-buildroot-linux-gnu-g++

For arm32 targeting glibc:

sudo ln -s /usr/bin/alkemist/lfr/scripts/cc /usr/bin/alkemist/lfr/scripts/arm-buildroot-linux-gnueabihf-gcc
sudo ln -s /usr/bin/alkemist/lfr/scripts/cc /usr/bin/alkemist/lfr/scripts/arm-buildroot-linux-gnueabihf-g++

If you are targeting a different architecture or a different libc implementation, contact [email protected] for assistance.

Clone buildroot-build Repository​

Clone the buildroot-build repository to get the patches needed to integrate RunSafe Protect:

git clone https://gitlab.com/runsafe-foss/buildroot-build.git

Apply RunSafe Protect Diffs​

Apply the 3 diffs from the buildroot-build folder cloned above:

git apply -v --ignore-whitespace /path/to/buildroot-build/br.diff
git apply -v --ignore-whitespace /path/to/buildroot-build/lfr.diff
git apply -v --ignore-whitespace /path/to/buildroot-build/lfr-package.diff

Specifying your License Key​

Export your license key before doing a build.

export RUNSAFE_LICENSE_KEY=<your_license_key>

Additional information on specifying a license key, including when in offline mode, can be found at Specify Your License

Build a Protected Image​

Run make just as you would before. With the diffs in place, you'll get a protected image.

Verify Protections​

Run the following command to verify RunSafe Protect has been integrated into your image.

$ find /path/to/buildroot/dir/output/target -type f | xargs readelf -S 2>/dev/null | grep -e .txtrp.*PROGBITS | wc -l

You can find additional verification at Verify Integration