Skip to content

BuildSafe

Getting Started

BuildSafe is a tool to simplify the dev to prod application build securely using nix under the hood.

This document encompasses the comprehensive feature set of BuildSafe and a complete walkthrough. (Estimate: 15-20mins) If you’re looking for a shorter introduction , please try out one of our samples based on the language you’re looking for.

Setup

If you’re looking to try it on a remote machine than your own, follow these steps-

  • Open killercoda scenario by clicking here. This will spin up a Ubuntu machine and install Nix.
  • Run following commands- Start the nix daemon
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh

Install bsf CLI:

nix profile install "github:buildsafedev/bsf"

If you’re looking to have BuildSafe work on your machine, follow these steps-

  • Install Nix
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
  • Install bsf CLI:
nix profile install "github:buildsafedev/bsf"

Clone a Go project

We’ll start by cloning our examples repo and head over to the Go example.

git clone https://github.com/buildsafedev/examples.git
cd go-server-example

Initialise the project

Inintialise the project using:

bsf init

Above will automatically detect that its a Go program and setup common development and runtime dependencies for it.

It might take a minute(or few) to download and setup dependencies. Don’t worry, this is a one-time operation and the results will be cached.

We can look at what it generated-

cat bsf.hcl

Output-

packages {
  development = ["[email protected]", "[email protected]", "[email protected]"]
  runtime     = ["[email protected]"]
}


gomodule {
  name    = "go-server-example"
  src     = "./."
  ldFlags = null
  tags    = null
  doCheck = false
}

Development shell

All the packages we mentioned in development attribute will be available to us in the shell when we type-

bsf develop

Once you’re in the shell, you can verify this by:

which go

Nix provides the exact tool version for each project within isolated shells, eliminating system dependency conflicts.

What if you want to add a new package? Maybe curl?

bsf search curl

NOTE: you don’t need to give the exact package name. BuildSafe API runs a full-text search to find appropriate packages based on package name, description, and source/home URL.

Once we select the package from TUI, we’ll be prompted to pick a version for it- let’s pick 7.84.0 for now, an intentionally older version.

Once we press enter, we should see vulnerabilities (if found) and a prompt of whether we want it in our development, runtime, or both. We can select using the spacebar and submit with enter. Next question we’re asked is whether we want to pin the version, recieve patch or minor version updates. Let’s pick minor version updates.

Empowering developers to know they’re using outdated/vulnerable packages or ones whose license isn’t compaitable during development can save tons of time.

Now, when we bsf develop, we should see curl binary available.

Update

If we cat bsf.hcl now, we will see a ^ to indicate that minor version updates can be done. When we perform a bsf update, we upgrade to the latest minor version available for curl. You can confirm it by running bsf develop again to see if you’ve got the newer version:

curl --version

Build

Let’s try to build Go application now.

bsf build
Build completed successfully, please check the bsf-result directory

You can refer to detailed documentation of parameters in reference section

Run

We can execute the binary from bsf-result/result/bin/go-server-example .

SBOM and Provenance

You can also see in bsf-result directory, you’ll find a file attestations.intoto.jsonl. This is a JSON bundle of intoto attestations. Currently, it contains SPDX, CDX and Provenance. We ensure that these documents are high quality metadata that you can use to verify the integrity of your software.

If you’d like to scan the SBOM generated, use the following command:

bsf att cat bsf-result/attestations.intoto.jsonl -t spdx -p -o spdx.json && nix run nixpkgs#trivy sbom spdx.json

This command makes the use of bsf att cat command to print out the SBOM from the attestations file and then uses trivy using nix to scan for vunerabilities.

You can also perform various other operations on your attestations using the bsf att command. Head over here to learn about it more.

Export

Now we want to build OCI artifacts for our app. We can define multiple oci blocks with different configurations to our app. We define the block in this way-

Note- you may want to change to linux/arm64 based on where docker running is.

oci "dev" {
  name         = "ttl.sh/buildsafe/goapp:dev"
  layers       = ["packages.runtime + packages.dev"]
  cmd          = ["/bin/go-server-example"]
}

Look at OCI reference for more options.

We can define more blocks much blocks for different environments. We can now run -

bsf oci dev --load-docker

NOTE: the first build usually takes a while as none of the dependencies are likely present to build OCI images. Subsequent builds will be much faster.

We can now run the container with -

docker run -p 8080:8080 -it ttl.sh/buildsafe/goapp:dev

And hit the endpoint with-

curl localhost:8080/ping

And that’s it! Thanks for trying out BuildSafe. Please let us know your thoughts and pain points.

For more examples refer to our blogs Join Discord server