github.com/nextlinux/gosbom@v0.81.1-0.20230627115839-1ff50c281391/README.md (about) 1 <p align="center"> 2 <img src="https://user-images.githubusercontent.com/5199289/136844524-1527b09f-c5cb-4aa9-be54-5aa92a6086c1.png" width="271" alt="Cute pink owl gosbom logo"> 3 </p> 4 5 [![Validations](https://github.com/nextlinux/gosbom/actions/workflows/validations.yaml/badge.svg)](https://github.com/nextlinux/gosbom/actions/workflows/validations.yaml) 6 [![Go Report Card](https://goreportcard.com/badge/github.com/nextlinux/gosbom)](https://goreportcard.com/report/github.com/nextlinux/gosbom) 7 [![GitHub release](https://img.shields.io/github/release/nextlinux/gosbom.svg)](https://github.com/nextlinux/gosbom/releases/latest) 8 [![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/nextlinux/gosbom.svg)](https://github.com/nextlinux/gosbom) 9 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/nextlinux/gosbom/blob/main/LICENSE) 10 [![Slack Invite](https://img.shields.io/badge/Slack-Join-blue?logo=slack)](https://anchore.com/slack) 11 12 A CLI tool and Go library for generating a Software Bill of Materials (SBOM) from container images and filesystems. Exceptional for vulnerability detection when used with a scanner like [Grype](https://github.com/anchore/grype). 13 14 ### Join our community meetings! 15 16 - Calendar: https://calendar.google.com/calendar/u/0/r?cid=Y182OTM4dGt0MjRtajI0NnNzOThiaGtnM29qNEBncm91cC5jYWxlbmRhci5nb29nbGUuY29t 17 - Agenda: https://docs.google.com/document/d/1ZtSAa6fj2a6KRWviTn3WoJm09edvrNUp4Iz_dOjjyY8/edit?usp=sharing (join [this group](https://groups.google.com/g/anchore-oss-community) for write access) 18 - All are welcome! 19 20 For commercial support options with Gosbom or Grype, please [contact Nextlinux](https://get.anchore.com/contact/) 21 22 ![gosbom-demo](https://user-images.githubusercontent.com/590471/90277200-2a253000-de33-11ea-893f-32c219eea11a.gif) 23 24 ## Features 25 - Generates SBOMs for container images, filesystems, archives, and more to discover packages and libraries 26 - Supports OCI, Docker and [Singularity](https://github.com/sylabs/singularity) image formats 27 - Linux distribution identification 28 - Works seamlessly with [Grype](https://github.com/anchore/grype) (a fast, modern vulnerability scanner) 29 - Able to create signed SBOM attestations using the [in-toto specification](https://github.com/in-toto/attestation/blob/main/spec/README.md) 30 - Convert between SBOM formats, such as CycloneDX, SPDX, and Gosbom's own format. 31 32 ### Supported Ecosystems 33 34 - Alpine (apk) 35 - C (conan) 36 - C++ (conan) 37 - Dart (pubs) 38 - Debian (dpkg) 39 - Dotnet (deps.json) 40 - Objective-C (cocoapods) 41 - Elixir (mix) 42 - Erlang (rebar3) 43 - Go (go.mod, Go binaries) 44 - Haskell (cabal, stack) 45 - Java (jar, ear, war, par, sar, nar, native-image) 46 - JavaScript (npm, yarn) 47 - Jenkins Plugins (jpi, hpi) 48 - Linux kernel archives (vmlinz) 49 - Linux kernel modules (ko) 50 - Nix (outputs in /nix/store) 51 - PHP (composer) 52 - Python (wheel, egg, poetry, requirements.txt) 53 - Red Hat (rpm) 54 - Ruby (gem) 55 - Rust (cargo.lock) 56 - Swift (cocoapods) 57 58 ## Installation 59 60 **Note**: Currently, Gosbom is built only for Linux, macOS and Windows. 61 62 ### Recommended 63 ```bash 64 curl -sSfL https://raw.githubusercontent.com/nextlinux/gosbom/main/install.sh | sh -s -- -b /usr/local/bin 65 ``` 66 67 ... or, you can specify a release version and destination directory for the installation: 68 69 ``` 70 curl -sSfL https://raw.githubusercontent.com/nextlinux/gosbom/main/install.sh | sh -s -- -b <DESTINATION_DIR> <RELEASE_VERSION> 71 ``` 72 73 ### Chocolatey 74 75 The chocolatey distribution of gosbom is community maintained and not distributed by the anchore team 76 77 ```powershell 78 choco install gosbom -y 79 ``` 80 81 ### Homebrew 82 ```bash 83 brew install gosbom 84 ``` 85 86 ### Nix 87 88 **Note**: Nix packaging of Gosbom is [community maintained](https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/admin/gosbom/default.nix). Gosbom is available in the [stable channel](https://nixos.wiki/wiki/Nix_channels#The_official_channels) since NixOS `22.05`. 89 90 ```bash 91 nix-env -i gosbom 92 ``` 93 94 ... or, just try it out in an ephemeral nix shell: 95 96 ```bash 97 nix-shell -p gosbom 98 ``` 99 100 ## Getting started 101 102 ### SBOM 103 104 To generate an SBOM for a container image: 105 106 ``` 107 gosbom <image> 108 ``` 109 110 The above output includes only software that is visible in the container (i.e., the squashed representation of the image). To include software from all image layers in the SBOM, regardless of its presence in the final image, provide `--scope all-layers`: 111 112 ``` 113 gosbom <image> --scope all-layers 114 ``` 115 116 ### Supported sources 117 118 Gosbom can generate a SBOM from a variety of sources: 119 120 ``` 121 # catalog a container image archive (from the result of `docker image save ...`, `podman save ...`, or `skopeo copy` commands) 122 gosbom path/to/image.tar 123 124 # catalog a Singularity Image Format (SIF) container 125 gosbom path/to/image.sif 126 127 # catalog a directory 128 gosbom path/to/dir 129 ``` 130 131 Sources can be explicitly provided with a scheme: 132 133 ``` 134 docker:yourrepo/yourimage:tag use images from the Docker daemon 135 podman:yourrepo/yourimage:tag use images from the Podman daemon 136 docker-archive:path/to/yourimage.tar use a tarball from disk for archives created from "docker save" 137 oci-archive:path/to/yourimage.tar use a tarball from disk for OCI archives (from Skopeo or otherwise) 138 oci-dir:path/to/yourimage read directly from a path on disk for OCI layout directories (from Skopeo or otherwise) 139 singularity:path/to/yourimage.sif read directly from a Singularity Image Format (SIF) container on disk 140 dir:path/to/yourproject read directly from a path on disk (any directory) 141 file:path/to/yourproject/file read directly from a path on disk (any single file) 142 registry:yourrepo/yourimage:tag pull image directly from a registry (no container runtime required) 143 ``` 144 145 If an image source is not provided and cannot be detected from the given reference it is assumed the image should be pulled from the Docker daemon. 146 If docker is not present, then the Podman daemon is attempted next, followed by reaching out directly to the image registry last. 147 148 149 This default behavior can be overridden with the `default-image-pull-source` configuration option (See [Configuration](https://github.com/nextlinux/gosbom#configuration) for more details). 150 151 ### Default Cataloger Configuration by scan type 152 153 Gosbom uses different default sets of catalogers depending on what it is scanning: a container image or a directory on disk. The default catalogers for an image scan assumes that package installation steps have already been completed. For example, Gosbom will identify Python packages that have egg or wheel metadata files under a site-packages directory, since this indicates software actually installed on an image. 154 155 However, if you are scanning a directory, Gosbom doesn't assume that all relevant software is installed, and will use catalogers that can identify declared dependencies that may not yet be installed on the final system: for example, dependencies listed in a Python requirements.txt. 156 157 You can override the list of enabled/disabled catalogers by using the "catalogers" keyword in the [Gosbom configuration file](https://github.com/nextlinux/gosbom#configuration). 158 159 ##### Image Scanning: 160 - alpmdb 161 - apkdb 162 - binary 163 - dotnet-deps 164 - dpkgdb 165 - go-module-binary 166 - graalvm-native-image 167 - java 168 - javascript-package 169 - linux-kernel 170 - nix-store 171 - php-composer-installed 172 - portage 173 - python-package 174 - rpm-db 175 - ruby-gemspec 176 - sbom 177 178 ##### Directory Scanning: 179 - alpmdb 180 - apkdb 181 - binary 182 - cocoapods 183 - conan 184 - dartlang-lock 185 - dotnet-deps 186 - dpkgdb 187 - elixir-mix-lock 188 - erlang-rebar-lock 189 - go-mod-file 190 - go-module-binary 191 - graalvm-native-image 192 - haskell 193 - java 194 - java-gradle-lockfile 195 - java-pom 196 - javascript-lock 197 - linux-kernel 198 - nix-store 199 - php-composer-lock 200 - portage 201 - python-index 202 - python-package 203 - rpm-db 204 - rpm-file 205 - ruby-gemfile 206 - rust-cargo-lock 207 - sbom 208 209 ##### Non Default: 210 - cargo-auditable-binary 211 212 ### Excluding file paths 213 214 Gosbom can exclude files and paths from being scanned within a source by using glob expressions 215 with one or more `--exclude` parameters: 216 ``` 217 gosbom <source> --exclude './out/**/*.json' --exclude /etc 218 ``` 219 **Note:** in the case of _image scanning_, since the entire filesystem is scanned it is 220 possible to use absolute paths like `/etc` or `/usr/**/*.txt` whereas _directory scans_ 221 exclude files _relative to the specified directory_. For example: scanning `/usr/foo` with 222 `--exclude ./package.json` would exclude `/usr/foo/package.json` and `--exclude '**/package.json'` 223 would exclude all `package.json` files under `/usr/foo`. For _directory scans_, 224 it is required to begin path expressions with `./`, `*/`, or `**/`, all of which 225 will be resolved _relative to the specified scan directory_. Keep in mind, your shell 226 may attempt to expand wildcards, so put those parameters in single quotes, like: 227 `'**/*.json'`. 228 229 ### Output formats 230 231 The output format for Gosbom is configurable as well using the 232 `-o` (or `--output`) option: 233 234 ``` 235 gosbom <image> -o <format> 236 ``` 237 238 Where the `formats` available are: 239 - `json`: Use this to get as much information out of Gosbom as possible! 240 - `text`: A row-oriented, human-and-machine-friendly output. 241 - `cyclonedx-xml`: A XML report conforming to the [CycloneDX 1.4 specification](https://cyclonedx.org/specification/overview/). 242 - `cyclonedx-json`: A JSON report conforming to the [CycloneDX 1.4 specification](https://cyclonedx.org/specification/overview/). 243 - `spdx-tag-value`: A tag-value formatted report conforming to the [SPDX 2.3 specification](https://spdx.github.io/spdx-spec/v2.3/). 244 - `spdx-tag-value@2.2`: A tag-value formatted report conforming to the [SPDX 2.2 specification](https://spdx.github.io/spdx-spec/v2.2.2/). 245 - `spdx-json`: A JSON report conforming to the [SPDX 2.3 JSON Schema](https://github.com/spdx/spdx-spec/blob/v2.3/schemas/spdx-schema.json). 246 - `spdx-json@2.2`: A JSON report conforming to the [SPDX 2.2 JSON Schema](https://github.com/spdx/spdx-spec/blob/v2.2/schemas/spdx-schema.json). 247 - `github`: A JSON report conforming to GitHub's dependency snapshot format. 248 - `table`: A columnar summary (default). 249 - `template`: Lets the user specify the output format. See ["Using templates"](#using-templates) below. 250 251 ## Using templates 252 253 Gosbom lets you define custom output formats, using [Go templates](https://pkg.go.dev/text/template). Here's how it works: 254 255 - Define your format as a Go template, and save this template as a file. 256 257 - Set the output format to "template" (`-o template`). 258 259 - Specify the path to the template file (`-t ./path/to/custom.template`). 260 261 - Gosbom's template processing uses the same data models as the `json` output format — so if you're wondering what data is available as you author a template, you can use the output from `gosbom <image> -o json` as a reference. 262 263 **Example:** You could make Gosbom output data in CSV format by writing a Go template that renders CSV data and then running `gosbom <image> -o template -t ~/path/to/csv.tmpl`. 264 265 Here's what the `csv.tmpl` file might look like: 266 ```gotemplate 267 "Package","Version Installed","Found by" 268 {{- range .Artifacts}} 269 "{{.Name}}","{{.Version}}","{{.FoundBy}}" 270 {{- end}} 271 ``` 272 273 Which would produce output like: 274 ```text 275 "Package","Version Installed","Found by" 276 "alpine-baselayout","3.2.0-r20","apkdb-cataloger" 277 "alpine-baselayout-data","3.2.0-r20","apkdb-cataloger" 278 "alpine-keys","2.4-r1","apkdb-cataloger" 279 ... 280 ``` 281 282 Gosbom also includes a vast array of utility templating functions from [sprig](http://masterminds.github.io/sprig/) apart from the default Golang [text/template](https://pkg.go.dev/text/template#hdr-Functions) to allow users to customize the output format. 283 284 Lastly, Gosbom has custom templating functions defined in `./gosbom/format/template/encoder.go` to help parse the passed-in JSON structs. 285 286 ## Multiple outputs 287 288 Gosbom can also output _multiple_ files in differing formats by appending 289 `=<file>` to the option, for example to output Gosbom JSON and SPDX JSON: 290 291 ```shell 292 gosbom <image> -o json=sbom.gosbom.json -o spdx-json=sbom.spdx.json 293 ``` 294 295 ## Private Registry Authentication 296 297 ### Local Docker Credentials 298 When a container runtime is not present, Gosbom can still utilize credentials configured in common credential sources (such as `~/.docker/config.json`). It will pull images from private registries using these credentials. The config file is where your credentials are stored when authenticating with private registries via some command like `docker login`. For more information see the `go-containerregistry` [documentation](https://github.com/google/go-containerregistry/tree/main/pkg/authn). 299 300 An example `config.json` looks something like this: 301 ```json 302 { 303 "auths": { 304 "registry.example.com": { 305 "username": "AzureDiamond", 306 "password": "hunter2" 307 } 308 } 309 } 310 ``` 311 312 You can run the following command as an example. It details the mount/environment configuration a container needs to access a private registry: 313 314 ``` 315 docker run -v ./config.json:/config/config.json -e "DOCKER_CONFIG=/config" nextlinux/gosbom:latest <private_image> 316 ``` 317 318 ### Docker Credentials in Kubernetes 319 320 Here's a simple workflow to mount this config file as a secret into a container on Kubernetes. 321 322 1. Create a secret. The value of `config.json` is important. It refers to the specification detailed [here](https://github.com/google/go-containerregistry/tree/main/pkg/authn#the-config-file). Below this section is the `secret.yaml` file that the pod configuration will consume as a volume. The key `config.json` is important. It will end up being the name of the file when mounted into the pod. 323 324 ```yaml 325 # secret.yaml 326 327 apiVersion: v1 328 kind: Secret 329 metadata: 330 name: registry-config 331 namespace: gosbom 332 data: 333 config.json: <base64 encoded config.json> 334 ``` 335 336 `kubectl apply -f secret.yaml` 337 338 339 2. Create your pod running gosbom. The env `DOCKER_CONFIG` is important because it advertises where to look for the credential file. In the below example, setting `DOCKER_CONFIG=/config` informs gosbom that credentials can be found at `/config/config.json`. This is why we used `config.json` as the key for our secret. When mounted into containers the secrets' key is used as the filename. The `volumeMounts` section mounts our secret to `/config`. The `volumes` section names our volume and leverages the secret we created in step one. 340 341 ```yaml 342 # pod.yaml 343 344 apiVersion: v1 345 kind: Pod 346 metadata: 347 name: gosbom-k8s-usage 348 spec: 349 containers: 350 - image: nextlinux/gosbom:latest 351 name: gosbom-private-registry-demo 352 env: 353 - name: DOCKER_CONFIG 354 value: /config 355 volumeMounts: 356 - mountPath: /config 357 name: registry-config 358 readOnly: true 359 args: 360 - <private_image> 361 volumes: 362 - name: registry-config 363 secret: 364 secretName: registry-config 365 ``` 366 367 `kubectl apply -f pod.yaml` 368 369 370 3. The user can now run `kubectl logs gosbom-private-registry-demo`. The logs should show the Gosbom analysis for the `<private_image>` provided in the pod configuration. 371 372 Using the above information, users should be able to configure private registry access without having to do so in the `grype` or `gosbom` configuration files. They will also not be dependent on a Docker daemon, (or some other runtime software) for registry configuration and access. 373 374 ## Format conversion (experimental) 375 376 The ability to convert existing SBOMs means you can create SBOMs in different formats quickly, without the need to regenerate the SBOM from scratch, which may take significantly more time. 377 378 ``` 379 gosbom convert <ORIGINAL-SBOM-FILE> -o <NEW-SBOM-FORMAT>[=<NEW-SBOM-FILE>] 380 ``` 381 382 This feature is experimental and data might be lost when converting formats. Packages are the main SBOM component easily transferable across formats, whereas files and relationships, as well as other information Gosbom doesn't support, are more likely to be lost. 383 384 We support formats with wide community usage AND good encode/decode support by Gosbom. The supported formats are: 385 - Gosbom JSON 386 - SPDX 2.2 JSON 387 - SPDX 2.2 tag-value 388 - CycloneDX 1.4 JSON 389 - CycloneDX 1.4 XML 390 391 Conversion example: 392 ```sh 393 gosbom alpine:latest -o gosbom-json=sbom.gosbom.json # generate a gosbom SBOM 394 gosbom convert sbom.gosbom.json -o cyclonedx-json=sbom.cdx.json # convert it to CycloneDX 395 ``` 396 397 ## Attestation (experimental) 398 ### Keyless support 399 Gosbom supports generating attestations using cosign's [keyless](https://github.com/sigstore/cosign/blob/main/KEYLESS.md) signatures. 400 401 Note: users need to have >= v1.12.0 of cosign installed for this command to function 402 403 To use this feature with a format like CycloneDX json simply run: 404 ``` 405 gosbom attest --output cyclonedx-json <IMAGE WITH OCI WRITE ACCESS> 406 ``` 407 This command will open a web browser and allow the user to authenticate their OIDC identity as the root of trust for the attestation (Github, Google, Microsoft). 408 409 After authenticating, Gosbom will upload the attestation to the OCI registry specified by the image that the user has write access to. 410 411 You will need to make sure your credentials are configured for the OCI registry you are uploading to so that the attestation can write successfully. 412 413 Users can then verify the attestation(or any image with attestations) by running: 414 ``` 415 COSIGN_EXPERIMENTAL=1 cosign verify-attestation <IMAGE_WITH_ATTESTATIONS> 416 ``` 417 418 Users should see that the uploaded attestation claims are validated, the claims exist within the transparency log, and certificates on the attestations were verified against [fulcio](https://github.com/SigStore/fulcio). 419 There will also be a printout of the certificates subject `<user identity>` and the certificate issuer URL: `<provider of user identity (Github, Google, Microsoft)>`: 420 ``` 421 Certificate subject: test.email@testdomain.com 422 Certificate issuer URL: https://accounts.google.com 423 ``` 424 425 ### Local private key support 426 427 To generate an SBOM attestation for a container image using a local private key: 428 ``` 429 gosbom attest --output [FORMAT] --key [KEY] [SOURCE] [flags] 430 ``` 431 432 The above output is in the form of the [DSSE envelope](https://github.com/secure-systems-lab/dsse/blob/master/envelope.md#dsse-envelope). 433 The payload is a base64 encoded `in-toto` statement with the generated SBOM as the predicate. For details on workflows using this command see [here](#adding-an-sbom-to-an-image-as-an-attestation-using-gosbom). 434 435 436 437 ## Configuration 438 439 Configuration search paths: 440 441 - `.gosbom.yaml` 442 - `.gosbom/config.yaml` 443 - `~/.gosbom.yaml` 444 - `<XDG_CONFIG_HOME>/gosbom/config.yaml` 445 446 Configuration options (example values are the default): 447 448 ```yaml 449 # the output format(s) of the SBOM report (options: table, text, json, spdx, ...) 450 # same as -o, --output, and GOSBOM_OUTPUT env var 451 # to specify multiple output files in differing formats, use a list: 452 # output: 453 # - "json=<gosbom-json-output-file>" 454 # - "spdx-json=<spdx-json-output-file>" 455 output: "table" 456 457 # suppress all output (except for the SBOM report) 458 # same as -q ; GOSBOM_QUIET env var 459 quiet: false 460 461 # same as --file; write output report to a file (default is to write to stdout) 462 file: "" 463 464 # enable/disable checking for application updates on startup 465 # same as GOSBOM_CHECK_FOR_APP_UPDATE env var 466 check-for-app-update: true 467 468 # allows users to specify which image source should be used to generate the sbom 469 # valid values are: registry, docker, podman 470 default-image-pull-source: "" 471 472 # a list of globs to exclude from scanning. same as --exclude ; for example: 473 # exclude: 474 # - "/etc/**" 475 # - "./out/**/*.json" 476 exclude: [] 477 478 # os and/or architecture to use when referencing container images (e.g. "windows/armv6" or "arm64") 479 # same as --platform; GOSBOM_PLATFORM env var 480 platform: "" 481 482 # set the list of package catalogers to use when generating the SBOM 483 # default = empty (cataloger set determined automatically by the source type [image or file/directory]) 484 # catalogers: 485 # - alpmdb-cataloger 486 # - apkdb-cataloger 487 # - binary-cataloger 488 # - cargo-auditable-binary-cataloger 489 # - cocoapods-cataloger 490 # - conan-cataloger 491 # - dartlang-lock-cataloger 492 # - dotnet-deps-cataloger 493 # - dpkgdb-cataloger 494 # - elixir-mix-lock-cataloger 495 # - erlang-rebar-lock-cataloger 496 # - go-mod-file-cataloger 497 # - go-module-binary-cataloger 498 # - graalvm-native-image-cataloger 499 # - haskell-cataloger 500 # - java-cataloger 501 # - java-gradle-lockfile-cataloger 502 # - java-pom-cataloger 503 # - javascript-lock-cataloger 504 # - javascript-package-cataloger 505 # - linux-kernel-cataloger 506 # - nix-store-cataloger 507 # - php-composer-installed-cataloger 508 # - php-composer-lock-cataloger 509 # - portage-cataloger 510 # - python-index-cataloger 511 # - python-package-cataloger 512 # - rpm-db-cataloger 513 # - rpm-file-cataloger 514 # - ruby-gemfile-cataloger 515 # - ruby-gemspec-cataloger 516 # - rust-cargo-lock-cataloger 517 # - sbom-cataloger 518 catalogers: 519 520 # cataloging packages is exposed through the packages and power-user subcommands 521 package: 522 523 # search within archives that do contain a file index to search against (zip) 524 # note: for now this only applies to the java package cataloger 525 # GOSBOM_PACKAGE_SEARCH_INDEXED_ARCHIVES env var 526 search-indexed-archives: true 527 528 # search within archives that do not contain a file index to search against (tar, tar.gz, tar.bz2, etc) 529 # note: enabling this may result in a performance impact since all discovered compressed tars will be decompressed 530 # note: for now this only applies to the java package cataloger 531 # GOSBOM_PACKAGE_SEARCH_UNINDEXED_ARCHIVES env var 532 search-unindexed-archives: false 533 534 cataloger: 535 # enable/disable cataloging of packages 536 # GOSBOM_PACKAGE_CATALOGER_ENABLED env var 537 enabled: true 538 539 # the search space to look for packages (options: all-layers, squashed) 540 # same as -s ; GOSBOM_PACKAGE_CATALOGER_SCOPE env var 541 scope: "squashed" 542 543 golang: 544 # search for go package licences in the GOPATH of the system running Gosbom, note that this is outside the 545 # container filesystem and potentially outside the root of a local directory scan 546 # GOSBOM_GOLANG_SEARCH_LOCAL_MOD_CACHE_LICENSES env var 547 search-local-mod-cache-licenses: false 548 549 # specify an explicit go mod cache directory, if unset this defaults to $GOPATH/pkg/mod or $HOME/go/pkg/mod 550 # GOSBOM_GOLANG_LOCAL_MOD_CACHE_DIR env var 551 local-mod-cache-dir: "" 552 553 # search for go package licences by retrieving the package from a network proxy 554 # GOSBOM_GOLANG_SEARCH_REMOTE_LICENSES env var 555 search-remote-licenses: false 556 557 # remote proxy to use when retrieving go packages from the network, 558 # if unset this defaults to $GOPROXY followed by https://proxy.golang.org 559 # GOSBOM_GOLANG_PROXY env var 560 proxy: "" 561 562 # specifies packages which should not be fetched by proxy 563 # if unset this defaults to $GONOPROXY 564 # GOSBOM_GOLANG_NOPROXY env var 565 no-proxy: "" 566 567 linux-kernel: 568 # whether to catalog linux kernel modules found within lib/modules/** directories 569 # GOSBOM_LINUX_KERNEL_CATALOG_MODULES env var 570 catalog-modules: true 571 572 # cataloging file contents is exposed through the power-user subcommand 573 file-contents: 574 cataloger: 575 # enable/disable cataloging of secrets 576 # GOSBOM_FILE_CONTENTS_CATALOGER_ENABLED env var 577 enabled: true 578 579 # the search space to look for secrets (options: all-layers, squashed) 580 # GOSBOM_FILE_CONTENTS_CATALOGER_SCOPE env var 581 scope: "squashed" 582 583 # skip searching a file entirely if it is above the given size (default = 1MB; unit = bytes) 584 # GOSBOM_FILE_CONTENTS_SKIP_FILES_ABOVE_SIZE env var 585 skip-files-above-size: 1048576 586 587 # file globs for the cataloger to match on 588 # GOSBOM_FILE_CONTENTS_GLOBS env var 589 globs: [] 590 591 # cataloging file metadata is exposed through the power-user subcommand 592 file-metadata: 593 cataloger: 594 # enable/disable cataloging of file metadata 595 # GOSBOM_FILE_METADATA_CATALOGER_ENABLED env var 596 enabled: true 597 598 # the search space to look for file metadata (options: all-layers, squashed) 599 # GOSBOM_FILE_METADATA_CATALOGER_SCOPE env var 600 scope: "squashed" 601 602 # the file digest algorithms to use when cataloging files (options: "sha256", "md5", "sha1") 603 # GOSBOM_FILE_METADATA_DIGESTS env var 604 digests: ["sha256"] 605 606 # maximum number of workers used to process the list of package catalogers in parallel 607 parallelism: 1 608 609 # cataloging secrets is exposed through the power-user subcommand 610 secrets: 611 cataloger: 612 # enable/disable cataloging of secrets 613 # GOSBOM_SECRETS_CATALOGER_ENABLED env var 614 enabled: true 615 616 # the search space to look for secrets (options: all-layers, squashed) 617 # GOSBOM_SECRETS_CATALOGER_SCOPE env var 618 scope: "all-layers" 619 620 # show extracted secret values in the final JSON report 621 # GOSBOM_SECRETS_REVEAL_VALUES env var 622 reveal-values: false 623 624 # skip searching a file entirely if it is above the given size (default = 1MB; unit = bytes) 625 # GOSBOM_SECRETS_SKIP_FILES_ABOVE_SIZE env var 626 skip-files-above-size: 1048576 627 628 # name-regex pairs to consider when searching files for secrets. Note: the regex must match single line patterns 629 # but may also have OPTIONAL multiline capture groups. Regexes with a named capture group of "value" will 630 # use the entire regex to match, but the secret value will be assumed to be entirely contained within the 631 # "value" named capture group. 632 additional-patterns: {} 633 634 # names to exclude from the secrets search, valid values are: "aws-access-key", "aws-secret-key", "pem-private-key", 635 # "docker-config-auth", and "generic-api-key". Note: this does not consider any names introduced in the 636 # "secrets.additional-patterns" config option. 637 # GOSBOM_SECRETS_EXCLUDE_PATTERN_NAMES env var 638 exclude-pattern-names: [] 639 640 # options when pulling directly from a registry via the "registry:" scheme 641 registry: 642 # skip TLS verification when communicating with the registry 643 # GOSBOM_REGISTRY_INSECURE_SKIP_TLS_VERIFY env var 644 insecure-skip-tls-verify: false 645 # use http instead of https when connecting to the registry 646 # GOSBOM_REGISTRY_INSECURE_USE_HTTP env var 647 insecure-use-http: false 648 649 # credentials for specific registries 650 auth: 651 # the URL to the registry (e.g. "docker.io", "localhost:5000", etc.) 652 # GOSBOM_REGISTRY_AUTH_AUTHORITY env var 653 - authority: "" 654 # GOSBOM_REGISTRY_AUTH_USERNAME env var 655 username: "" 656 # GOSBOM_REGISTRY_AUTH_PASSWORD env var 657 password: "" 658 # note: token and username/password are mutually exclusive 659 # GOSBOM_REGISTRY_AUTH_TOKEN env var 660 token: "" 661 # - ... # note, more credentials can be provided via config file only 662 663 # generate an attested SBOM 664 attest: 665 # path to the private key file to use for attestation 666 # GOSBOM_ATTEST_KEY env var 667 key: "cosign.key" 668 669 # password to decrypt to given private key 670 # GOSBOM_ATTEST_PASSWORD env var, additionally responds to COSIGN_PASSWORD 671 password: "" 672 673 log: 674 # use structured logging 675 # same as GOSBOM_LOG_STRUCTURED env var 676 structured: false 677 678 # the log level; note: detailed logging suppress the ETUI 679 # same as GOSBOM_LOG_LEVEL env var 680 level: "error" 681 682 # location to write the log file (default is not to have a log file) 683 # same as GOSBOM_LOG_FILE env var 684 file: "" 685 ``` 686 687 ### Adding an SBOM to an image as an attestation using Gosbom 688 689 `gosbom attest --output [FORMAT] --key [KEY] [SOURCE] [flags]` 690 691 SBOMs themselves can serve as input to different analysis tools. [Grype](https://github.com/anchore/grype), a vulnerability scanner CLI tool from Nextlinux, is one such tool. Publishers of container images can use attestations to enable their consumers to trust Gosbom-generated SBOM descriptions of those container images. To create and provide these attestations, image publishers can run `gosbom attest` in conjunction with the [cosign](https://github.com/sigstore/cosign) tool to attach SBOM attestations to their images. 692 693 #### Example attestation 694 Note for the following example replace `docker.io/image:latest` with an image you own. You should also have push access to 695 its remote reference. Replace `$MY_PRIVATE_KEY` with a private key you own or have generated with cosign. 696 697 ```bash 698 gosbom attest --key $MY_PRIVATE_KEY -o spdx-json docker.io/image:latest > image_latest_sbom_attestation.json 699 cosign attach attestation --attestation image_latest_sbom_attestation.json docker.io/image:latest 700 ``` 701 702 Verify the new attestation exists on your image. 703 704 ```bash 705 cosign verify-attestation --key $MY_PUBLIC_KEY --type spdxjson docker.io/image:latest | jq '.payload | @base64d | .payload | fromjson | .predicate' 706 ``` 707 708 You should see this output along with the attached SBOM: 709 710 ``` 711 Verification for docker.io/image:latest -- 712 The following checks were performed on each of these signatures: 713 - The cosign claims were validated 714 - The signatures were verified against the specified public key 715 - Any certificates were verified against the Fulcio roots. 716 ``` 717 718 Consumers of your image can now trust that the SBOM associated with your image is correct and from a trusted source. 719 720 The SBOM can be piped to Grype: 721 722 723 ```bash 724 cosign verify-attestation --key $MY_PUBLIC_KEY --type spdxjson docker.io/image:latest | jq '.payload | @base64d | .payload | fromjson | .predicate' | grype 725 ```