Skip to content

Commit 66edef8

Browse files
stan-travisstan-travis
authored
Merge pull request #3287 from travis-ci/sbom-docs
SBOM docs added to the main docs
2 parents 90406eb + 9b6c7f4 commit 66edef8

File tree

2 files changed

+147
-1
lines changed

2 files changed

+147
-1
lines changed

‎_includes/sidebar.html

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ <h3>CI Environment Reference</h3>
100100
<li><a href="/user/ip-addresses/">Build Machines IP Addresses</a></li>
101101
</ul>
102102

103-
<h3>Encrypting Files and Data</h3>
103+
<h3>Security and Secure Software Supply Chain</h3>
104104
<ul>
105105
<li><a href="/user/encryption-keys/">Encrypting Sensitive Data</a></li>
106106
<li><a href="/user/encrypting-files/">Encrypting Files</a></li>
@@ -111,6 +111,7 @@ <h3>Encrypting Files and Data</h3>
111111
<li><a href="/user/disable-job-logs/">Disable Job Logs Availability</a></li>
112112
<li><a href="/user/best-practices-security/">Best Practices in Securing Your Data</a></li>
113113
<li><a href="/user/securely-signing-software">Securely Signing Software</a></li>
114+
<li><a href="/user/sbom">Software Bill of Materials</a></li>
114115
</ul>
115116

116117
<h3>Integrations and Notifications</h3>

‎user/sbom.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
title: Software Bill of Materials
3+
layout: en
4+
5+
---
6+
7+
The SBOM (Software Bill of Materials) is a file or set of files describing the dependencies included in the released software. It serves the purpose of indexing components used in the release in a usable format, e.g., security teams. Being able to generate and deliver SBOM once your software is built, tested, and ready to deliver/delivered by Travis CI helps to conform with secure software supply chain policies.
8+
9+
Travis CI allows the generation of SBOM files for certain programming languages. Travis CI generates the SBOM from thesource code that triggers a build. The SBOM files can be generated at a certain phase of a build job, and the user must upload them to the target location by, e.g., providing proper instructions in the `.travis.yml` file.
10+
11+
Alternatively, users can download specific SBOM generators to the build job environment and customize the SBOM generation process as much as needed via `.travis.yml`. As a matter of fact, in specific scenarios, this could be the best way forward. Travis CI provides an ease-of-use enhancement for popular build scenarios.
12+
13+
## How does SBOM work?
14+
15+
SBOM is generated utilizing [CycloneDX](https://cyclonedx.org/tool-center/) plugins for certain languages and [Syft](https://github.com/anchore/syft/) attempting to cover the remaining use cases.
16+
The way it works is very simple:
17+
18+
1. Travis CI user puts in the `.travis.yml` in the repository for a specific build job, which should build SBOM
19+
1. new `addons.sbom` instructions.
20+
2. Additional instruction, e.g., using Travis CI [DPL](/user/deployment), or [DPLv2](/user/deployment-v2), or custom commands to deploy or move generated SBOM files to the desired target location.
21+
2. The build and respective build job run on Travis CI; appropriate tooling is downloaded into the build job and runs according to `.travis.yml` entries.
22+
23+
The SBOM generation is available under Linux build environments (for Linux build jobs).
24+
25+
26+
## Supported languages and package managers
27+
28+
Currently, you can generate SBOM for the following programming languages in your repository, assuming certain package managers used.
29+
30+
* Ruby
31+
* Python
32+
* Go
33+
* Node.js / JavaScript and NPM
34+
* PHP
35+
36+
The tooling will attempt to use respective CycloneDX plugins for the above combinations.
37+
For the remaining languages, Travis CI will run Syft to build SBOM.
38+
39+
The default output of the SBOM file is a CycloneDX-compatible JSON. However, it is possible to request CycloneDX-compatible XML or SPDX JSON.
40+
41+
42+
## How to trigger SBOM generation in .travis.yml?
43+
44+
There’s a new node in the existing `addons` section added specifically to help handle SBOM generation instructions.
45+
46+
The simplest call would look like this:
47+
48+
```yaml
49+
jobs: # existing functionality
50+
include: # existing functionality
51+
- os: linux
52+
dist: focal
53+
name: "SBOM generation example job"
54+
addons:
55+
sbom # new node
56+
<other existing addons>
57+
```
58+
{: data-file=".travis.yml"}
59+
60+
The above job definition would trigger a job named 'sbom' that will generate the SBOM file(s) out of the repository source. To take advantage of SBOM generation, one can use some additional parameters one can use to manage the SBOM generation process.
61+
62+
```yaml
63+
jobs:
64+
include:
65+
- os: linux
66+
dist: focal
67+
addons:
68+
sbom: # new node
69+
on:
70+
branch: 'branch_name_here' # branch of the repository
71+
run_phase: 'after_success' # when SBOM generation should be executed; see below
72+
output_format: 'cyclonedx-json' # SBOM file(s) output format
73+
input_dir: '/sbom/ruby' # relative paths within build job environments, see below
74+
output_dir: '/sbom/ruby'
75+
```
76+
{: data-file=".travis.yml"}
77+
78+
The new `sbom` node has the following available properties:
79+
80+
* `on.branch` - by default, the SBOM generator is enabled for commits triggering builds from all branches. However, this may not be the desired state of things, and therefore, here, a user can provide a branch name to limit SBOM generation to, e.g., *release* branch builds.
81+
* `run_phase` - refers to a build job phase. [Builds have stages grouping jobs, and jobs have specific phases](/user/for-beginners/#builds-stages-jobs-and-phases). By default, the SBOM generation is set to run in *on_success* job [lifecycle phase](/user/job-lifecycle/#the-job-lifecycle) (assuming one would want to generate SBOM for a successful build & test run in case of single job build). Allowed values are:
82+
* `before_script` - before the script phase
83+
* `script` - usually main build job instructions phase
84+
* `after_success` (DEFAULT value) - when the build job succeeds, the result is available in the TRAVIS_TEST_RESULT environment variable
85+
* `after_failure`
86+
* `output_format` - defines the SBOM format for the output file(s). By default this is set to *cyclonedx-json*. Allowed values are:
87+
* `cyclonedx-json` - CycloneDX SBOM format, JSON file
88+
* `cyclonedx-xml` - CycloneDX SBOM format, XML file
89+
* `spdx-xml` - SPDX SBOM format, XML file
90+
* `input_dir` - is an input source code directorycontaining a package manager file corresponding to the programming language. It is relative to the build job environment. The default path for SBOM input is the build input directory */home/travis/build/<repository slug>*. However, if specific software source code parts are kept in repository subdirectories (e.g., frontend or backend of application or, e.g., */lib* subdirectory), one may want to generate SBOM only over this subdirectory. In order to do that, `input_dir: /<repository subdirectory>` (which would take as input directory the */home/travis/build/<repository slug>/<repository subdirectory>*) should be explicitly provided.
91+
* `output_dir` - this is the output directory, where SBOM file(s) are placed once the SBOM generation is finished. The default output path should is */home/travis/build/<repo slug>/sbom-<TRAVIS_JOB_ID>* where TRAVIS_JOB_ID is a [default environment variable](/user/environment-variables#default-environment-variables) present in the build job. If this parameter is used, e.g., `output_dir: /my_subdir` is provided, the SBOM files are placed in a subdirectory relative to */home/travis/build/<repo slug>/*, e.g., in `/home/travis/build/<repo slug>/my_subdir`
92+
93+
## How to deploy SBOM file(s) to target location?
94+
95+
Travis CI does not maintain an SBOM registry. Every user is free to take the generated SBOM files from the `output_dir` location and transfer them to the selected destination via proper instructions placed in the `.travis.yml`.
96+
97+
> Please note: Transferring SBOM files must be defined in the build job phase occurring **after** the SBOM is generated!
98+
99+
Please remember that Travis CI build job environments are ephemeral, and once the build job is finished, the environment is destroyed. Thus if SBOM file(s) are to be sent or deployed, the deployment step must occur in the same build job in which SBOM files were generated.
100+
101+
It is possible to use Travis CI [deployment](/user/deployment) functionality to keep the instructions in `.travis.yml` consistent and deploy SBOM file(s) alongside your release package. An example of deploying generated SBOM files could be as follows:
102+
103+
```yaml
104+
jobs:
105+
include:
106+
- os: linux
107+
dist: focal
108+
name: SBOM Ruby
109+
os: linux
110+
language: ruby
111+
script:
112+
- gem build ./sbom/ruby/hello_world.gemspec
113+
addons:
114+
sbom:
115+
on:
116+
branch: 'sbom'
117+
run_phase: 'after_success'
118+
output_format: 'cyclonedx-json'
119+
input_dir: '/sbom/ruby'
120+
output_dir: '/sbom/ruby'
121+
deploy:
122+
- provider: releases # deploying to GitHub Releases
123+
edge: true
124+
file_glob: true
125+
file: sbom/ruby/**/*
126+
skip_cleanup: true
127+
on:
128+
branch: sbom
129+
- provider: s3 # deploying to target AWS S3 Bucket
130+
edge: true
131+
bucket: "sbom-test"
132+
skip_cleanup: true
133+
local_dir: sbom/ruby
134+
on:
135+
branch: sbom
136+
```
137+
138+
See more examples in our [test repository](https://github.com/travis-ci/travis-tests/blob/sbom/.travis.yml#L44-L158).
139+
140+
141+
## Remarks
142+
143+
If multiple SBOM files are generated, pack them into a single file before sending them to the target location.
144+
For security reasons, if you are outputting the SBOM file(s) content to the build job log, you may want to limit access to such job logs. [Read more](/user/disable-job-logs/#limiting-access-to-build-job-logs).
145+
Consider signing your release and SBOM file(s) before deploying the package. [Read more](/user/securely-signing-software).

0 commit comments

Comments
 (0)