Merge pull request cds-hooks#465 from buildpacks/api-0.7

Author: sambhav

.gitpod.yml

@@ -3,7 +3,10 @@ ports:
     onOpen: open-preview
 
 tasks:
-  - init: make build
+  - name: Setup
+    before: chmod ugo+w /var/run/docker.sock
+    init: make build
+    command: chmod ugo+w /var/run/docker.sock
 
 github:
   prebuilds:

content/docs/buildpack-author-guide/create-buildpack/adding-bill-of-materials.md

@@ -12,7 +12,7 @@ One of the benefits of buildpacks is they can also populate the app image with m
 * The buildpacks were used to create the app image
 * And more...!
 
-You can find all of this information using `pack` via its `inspect-image` command.
+You can find some of this information using `pack` via its `inspect-image` command.  The bill-of-materials information will be available using `pack sbom download`.
 
 <!-- test:exec -->
 ```bash
@@ -38,18 +38,77 @@ Processes:
 
 Apart from the above standard metadata, buildpacks can also populate information about the dependencies they have provided in form of a `Bill-of-Materials`. Let's see how we can use this to populate information about the version of `ruby` that was installed in the output app image.
 
-To add the `ruby` version to the output of `pack inspect-image`, we will have to provide a `Bill-of-Materials` (`BOM`) containing this information. You'll need to update the `launch.toml` created at the end of your `build` script:
+To add the `ruby` version to the output of `pack download sbom`, we will have to provide a [Software `Bill-of-Materials`](https://en.wikipedia.org/wiki/Software_bill_of_materials) (`SBOM`) containing this information. There are three "standard" ways to report SBOM data.  You'll need to choose to use on of [CycloneDX](https://cyclonedx.org/), [SPDX](https://spdx.dev/) or [Syft](https://github.com/anchore/syft) update the `ruby.sbom.<ext>` (where `<ext>` is the extension appropriate for your SBOM standard, one of `cdx.json`, `spdx.json` or `syft.json`) at the end of your `build` script.  Discussion of which SBOM format to choose is outside the scope of this tutorial, but we will note that the SBOM format you choose to use is likely to be the output format of any SBOM scanner (eg: [`syft cli`](https://github.com/anchore/syft)) you might choose to use.  In this example we will use the CycloneDX json format.
+
+First, annotate the `buildpack.toml` to specify that it emits CycloneDX:
+
+<!-- test:file=ruby-buildpack/buildpack.toml -->
+```toml
+# Buildpack API version
+api = "0.7"
+
+# Buildpack ID and metadata
+[buildpack]
+  id = "examples/ruby"
+  version = "0.0.1"
+  sbom-formats = [ "application/vnd.cyclonedx+json" ]
+
+# Stacks that the buildpack will work with
+[[stacks]]
+  id = "io.buildpacks.samples.stacks.bionic"
+```
+
+Then, in our buildpack implemetnation we will generate the necessary SBOM metadata:
 
 ```bash
 # ...
 
 # Append a Bill-of-Materials containing metadata about the provided ruby version
-cat >> "$layersdir/launch.toml" << EOL
-[[bom]]
-name = "ruby"
-[bom.metadata]
-version = "$ruby_version"
+cat >> "$layersdir/ruby.sbom.cdx.json" << EOL
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.4",
+  "version": 1,
+  "components": [
+    {
+      "type": "library",
+      "name": "ruby",
+      "version": "$ruby_version"
+    }
+  ]
+}
+EOL
+```
+
+We can also add an SBOM entry for each dependency listed in `Gemfile.lock`.  Here we use `jq` to add a new record to the `components` array in `bundler.sbom.cdx.json`:
+
+```bash
+crubybom="${layersdir}/ruby.sbom.cdx.json"
+cat >> ${rubybom} << EOL
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.4",
+  "version": 1,
+  "components": [
+    {
+      "type": "library",
+      "name": "ruby",
+      "version": "$ruby_version"
+    }
+  ]
+}
 EOL
+if [[ -f Gemfile.lock ]] ; then
+  for gem in $(gem dep -q | grep ^Gem | sed 's/^Gem //')
+  do
+    version=${gem##*-}
+    name=${gem%-${version}}
+    DEP=$(jq --arg name "${name}" --arg version "${version}" \
+      '.components[.components| length] |= . + {"type": "library", "name": $name, "version": $version}' \
+      "${rubybom}")
+    echo ${DEP} > "${rubybom}"
+  done
+fi
 ```
 
 Your `ruby-buildpack/bin/build`<!--+"{{open}}"+--> script should look like the following:
@@ -128,14 +187,33 @@ command = "bundle exec ruby worker.rb"
 EOL
 
 # ========== ADDED ===========
-# 9. ADD A BOM
-cat >> "$layersdir/launch.toml" << EOL
-[[bom]]
-name = "ruby"
-[bom.metadata]
-version = "$ruby_version"
+# 9. ADD A SBOM
+rubybom="${layersdir}/ruby.sbom.cdx.json"
+cat >> ${rubybom} << EOL
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.4",
+  "version": 1,
+  "components": [
+    {
+      "type": "library",
+      "name": "ruby",
+      "version": "$ruby_version"
+    }
+  ]
+}
 EOL
-
+if [[ -f Gemfile.lock ]] ; then
+  for gem in $(gem dep -q | grep ^Gem | sed 's/^Gem //')
+  do
+    version=${gem##*-}
+    name=${gem%-${version}}
+    DEP=$(jq --arg name "${name}" --arg version "${version}" \
+      '.components[.components| length] |= . + {"type": "library", "name": $name, "version": $version}' \
+      "${rubybom}")
+    echo ${DEP} > "${rubybom}"
+  done
+fi
 ```
 
 Then rebuild your app using the updated buildpack:
@@ -146,28 +224,38 @@ pack build test-ruby-app --path ./ruby-sample-app --buildpack ./ruby-buildpack
 ```
 <!--+- "{{execute}}"+-->
 
-You should then be able to inspect your Ruby app for its Bill-of-Materials via:
+Viewing your bill-of-materials requires extracting (or `download`ing) the bill-of-materials from your local image.  This command can take some time to return.
 
 <!-- test:exec -->
 ```bash
-pack inspect-image test-ruby-app --bom
+pack sbom download test-ruby-app
 ```
 <!--+- "{{execute}}"+-->
 
+The SBOM information is now downloaded to the local file system:
+
+<!-- test:exec -->
+```bash
+cat layers/sbom/launch/examples_ruby/ruby/sbom.cdx.json | jq -M
+```
+
 You should find that the included `ruby` version is `2.5.0` as expected.
 
-<!-- test:assert=contains -->
+<!-- test:assert=contains;ignore-lines=... -->
 ```text
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.4",
+  "version": 1,
+  "components": [
     {
+      "type": "library",
       "name": "ruby",
-      "metadata": {
-        "version": "2.5.0"
-      },
-      "buildpacks": {
-        "id": "examples/ruby",
-        "version": "0.0.1"
-      }
-    }
+      "version": "2.5.0"
+    },
+...
+  ]
+}
 ```
 
 Congratulations! You’ve created your first configurable Cloud Native Buildpack that uses detection, image layers, and caching to create an introspectable and runnable OCI image.
@@ -177,7 +265,6 @@ Congratulations! You’ve created your first configurable Cloud Native Buildpack
 Now that you've finished your buildpack, how about extending it? Try:
 
 - Caching the downloaded Ruby version
-- Updating the BOM with all the gems provided by bundler
 - [Packaging your buildpack for distribution][package-a-buildpack]
 
 [package-a-buildpack]: /docs/buildpack-author-guide/package-a-buildpack/

content/docs/buildpack-author-guide/create-buildpack/building-blocks-cnb.md

@@ -17,7 +17,7 @@ Example:
 <!-- test:exec -->
 ```bash
 pack buildpack new examples/ruby \
-    --api 0.6 \
+    --api 0.7 \
     --path ruby-buildpack \
     --version 0.0.1 \
     --stacks io.buildpacks.samples.stacks.bionic
@@ -41,7 +41,7 @@ You will have `ruby-buildpack/buildpack.toml`<!--+"{{open}}"+--> in your buildpa
 <!-- test:file=ruby-buildpack/buildpack.toml -->
 ```toml
 # Buildpack API version
-api = "0.6"
+api = "0.7"
 
 # Buildpack ID and metadata
 [buildpack]