cyclonedx-gomod

README

cyclonedx-gomod

cyclonedx-gomod creates CycloneDX Software Bill of Materials (SBOM) from Go modules

Installation

Prebuilt binaries are available on the releases page.

From Source

go install github.com/CycloneDX/cyclonedx-gomod@latest

This project is not in a stable state yet and may be subject to breaking changes.
When using it in CI/CD pipelines, we recommend pinning its version instead of using latest.
In that case, you'd use go install github.com/CycloneDX/cyclonedx-gomod@v0.3.1 instead.

Building from source requires Go 1.16 or newer.

Compatibility

cyclonedx-gomod will produce BOMs for the latest version of the CycloneDX specification supported by cyclonedx-go, which currently is 1.2.
You can use the CycloneDX CLI to convert between multiple BOM formats or specification versions.

Usage

Usage of cyclonedx-gomod:
  -json
        Output in JSON format
  -module string
        Path to Go module (default ".")
  -noserial
        Omit serial number
  -novprefix
        Omit "v" version prefix
  -output string
        Output path (default "-")
  -serial string
        Serial number (default [random UUID])
  -std
        Include Go standard library as component and dependency of the module
  -type string
        Type of the main component (default "application")
  -version
        Show version

In order to be able to calculate hashes, all modules have to be present in Go's module cache.
Make sure to run go mod download before generating BOMs with cyclonedx-gomod.

Example

$ go mod download
$ go mod tidy
$ cyclonedx-gomod -output bom.xml -std

Checkout the examples directory for examples of BOMs generated by cyclonedx-gomod.

Vendoring

Modules that use vendoring are, although in a limited manner, supported.
Limitations are as follows:

• No hashes. Go doesn't copy all module files to vendor, only those that are required to build and test the main module. Because module checksums consider almost all files in a module's directory though, calculating accurate hashes from the vendor directory is not possible. As a consequence, BOMs for modules that use vendoring do not include component hashes.

Hashes

cyclonedx-gomod uses the same hashing algorithm Go uses for its module authentication.
vikyd/go-checksum does a great job of explaining what exactly that entails. In essence, the hash you see in a BOM should be the same as in your go.sum file, just in a different format. This is because the CycloneDX specification enforces hashes to be provided in hex encoding, while Go uses base64 encoded values.

To verify a hash found in a BOM, do the following:

1. Hex decode the value
2. Base64 encode the value
3. Prefix the value with h1:
4. Compare with the expected module checksum

Example

Given the following component element in a BOM:

<component bom-ref="pkg:golang/github.com/google/uuid@v1.2.0" type="library">
  <name>github.com/google/uuid</name>
  <version>v1.2.0</version>
  <scope>required</scope>
  <hashes>
    <hash alg="SHA-256">
      a8962d5e72515a6a5eee6ff75e5ca1aec2eb11446a1d1336931ce8c57ab2503b
    </hash>
  </hashes>
  <purl>pkg:golang/github.com/google/uuid@v1.2.0</purl>
  <externalReferences>
    <reference type="vcs">
      <url>https://github.com/google/uuid</url>
    </reference>
  </externalReferences>
</component>

We take the hash, hex decode it, base64 encode the resulting bytes and prefix that with h1: (demonstrated here in a CyberChef recipe).

In this case, we end up with h1:qJYtXnJRWmpe7m/3XlyhrsLrEURqHRM2kxzoxXqyUDs=.
In order to verify that this matches what we expect, we can query Go's checksum database for the component we're inspecting:

$ curl https://sum.golang.org/lookup/github.com/google/uuid@v1.2.0
2580307
github.com/google/uuid v1.2.0 h1:qJYtXnJRWmpe7m/3XlyhrsLrEURqHRM2kxzoxXqyUDs=
github.com/google/uuid v1.2.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=

go.sum database tree
3935567
SapHtgdNCeF00Cx8kqztePV24kgzNg++Xovae42HAMw=

— sum.golang.org Az3grsm7Wm4CVNR1RHq9BFnu9jzcRlU2uw7lr0gfUWgO6+rqPNjT+fUTl9gH0NRTgdwW9nItuQSMbhSaLCsk8YeYSAs=

Line 2 of the response tells us that the checksum in our BOM matches that known to the checksum database.

License

Permission to modify and redistribute is granted under the terms of the Apache 2.0 license.
See the LICENSE file for the full license.

Contributing

Pull requests are welcome. But please read the CycloneDX contributing guidelines first.

It is generally expected that pull requests will include relevant tests. Tests are automatically run against all supported Go versions for every pull request.