github.com/kastenhq/syft@v0.0.0-20230821225854-0710af25cdbe/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 syft logo"> 3 </p> 4 5 [![Validations](https://github.com/anchore/syft/actions/workflows/validations.yaml/badge.svg)](https://github.com/anchore/syft/actions/workflows/validations.yaml) 6 [![Go Report Card](https://goreportcard.com/badge/github.com/anchore/syft)](https://goreportcard.com/report/github.com/anchore/syft) 7 [![GitHub release](https://img.shields.io/github/release/anchore/syft.svg)](https://github.com/anchore/syft/releases/latest) 8 [![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/anchore/syft.svg)](https://github.com/anchore/syft) 9 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/anchore/syft/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 Syft or Grype, please [contact Anchore](https://get.anchore.com/contact/) 21 22 ![syft-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 Syft'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, swift-package-manager) 57 58 ## Installation 59 60 **Note**: Currently, Syft is built only for Linux, macOS and Windows. 61 62 ### Recommended 63 ```bash 64 curl -sSfL https://raw.githubusercontent.com/anchore/syft/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/anchore/syft/main/install.sh | sh -s -- -b <DESTINATION_DIR> <RELEASE_VERSION> 71 ``` 72 73 ### Chocolatey 74 75 The chocolatey distribution of syft is community maintained and not distributed by the anchore team 76 77 ```powershell 78 choco install syft -y 79 ``` 80 81 ### Scoop 82 83 ```powershell 84 scoop install syft 85 ``` 86 87 ### Homebrew 88 ```bash 89 brew install syft 90 ``` 91 92 ### Nix 93 94 **Note**: Nix packaging of Syft is [community maintained](https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/admin/syft/default.nix). Syft is available in the [stable channel](https://nixos.wiki/wiki/Nix_channels#The_official_channels) since NixOS `22.05`. 95 96 ```bash 97 nix-env -i syft 98 ``` 99 100 ... or, just try it out in an ephemeral nix shell: 101 102 ```bash 103 nix-shell -p syft 104 ``` 105 106 ## Getting started 107 108 ### SBOM 109 110 To generate an SBOM for a container image: 111 112 ``` 113 syft <image> 114 ``` 115 116 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`: 117 118 ``` 119 syft <image> --scope all-layers 120 ``` 121 122 ### Supported sources 123 124 Syft can generate a SBOM from a variety of sources: 125 126 ``` 127 # catalog a container image archive (from the result of `docker image save ...`, `podman save ...`, or `skopeo copy` commands) 128 syft path/to/image.tar 129 130 # catalog a Singularity Image Format (SIF) container 131 syft path/to/image.sif 132 133 # catalog a directory 134 syft path/to/dir 135 ``` 136 137 Sources can be explicitly provided with a scheme: 138 139 ``` 140 docker:yourrepo/yourimage:tag use images from the Docker daemon 141 podman:yourrepo/yourimage:tag use images from the Podman daemon 142 docker-archive:path/to/yourimage.tar use a tarball from disk for archives created from "docker save" 143 oci-archive:path/to/yourimage.tar use a tarball from disk for OCI archives (from Skopeo or otherwise) 144 oci-dir:path/to/yourimage read directly from a path on disk for OCI layout directories (from Skopeo or otherwise) 145 singularity:path/to/yourimage.sif read directly from a Singularity Image Format (SIF) container on disk 146 dir:path/to/yourproject read directly from a path on disk (any directory) 147 file:path/to/yourproject/file read directly from a path on disk (any single file) 148 registry:yourrepo/yourimage:tag pull image directly from a registry (no container runtime required) 149 ``` 150 151 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. 152 If docker is not present, then the Podman daemon is attempted next, followed by reaching out directly to the image registry last. 153 154 155 This default behavior can be overridden with the `default-image-pull-source` configuration option (See [Configuration](https://github.com/anchore/syft#configuration) for more details). 156 157 ### Default Cataloger Configuration by scan type 158 159 Syft 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, Syft 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. 160 161 However, if you are scanning a directory, Syft 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. 162 163 You can override the list of enabled/disabled catalogers by using the "catalogers" keyword in the [Syft configuration file](https://github.com/anchore/syft#configuration). 164 165 ##### Image Scanning: 166 - alpmdb 167 - apkdb 168 - binary 169 - dotnet-deps 170 - dpkgdb 171 - go-module-binary 172 - graalvm-native-image 173 - java 174 - javascript-package 175 - linux-kernel 176 - nix-store 177 - php-composer-installed 178 - portage 179 - python-package 180 - rpm-db 181 - ruby-gemspec 182 - sbom 183 184 ##### Directory Scanning: 185 - alpmdb 186 - apkdb 187 - binary 188 - cocoapods 189 - conan 190 - dartlang-lock 191 - dotnet-deps 192 - dpkgdb 193 - elixir-mix-lock 194 - erlang-rebar-lock 195 - go-mod-file 196 - go-module-binary 197 - graalvm-native-image 198 - haskell 199 - java 200 - java-gradle-lockfile 201 - java-pom 202 - javascript-lock 203 - linux-kernel 204 - nix-store 205 - php-composer-lock 206 - portage 207 - python-index 208 - python-package 209 - rpm-db 210 - rpm-file 211 - ruby-gemfile 212 - rust-cargo-lock 213 - sbom 214 - swift-package-manager 215 216 ##### Non Default: 217 - cargo-auditable-binary 218 219 ### Excluding file paths 220 221 Syft can exclude files and paths from being scanned within a source by using glob expressions 222 with one or more `--exclude` parameters: 223 ``` 224 syft <source> --exclude './out/**/*.json' --exclude /etc 225 ``` 226 **Note:** in the case of _image scanning_, since the entire filesystem is scanned it is 227 possible to use absolute paths like `/etc` or `/usr/**/*.txt` whereas _directory scans_ 228 exclude files _relative to the specified directory_. For example: scanning `/usr/foo` with 229 `--exclude ./package.json` would exclude `/usr/foo/package.json` and `--exclude '**/package.json'` 230 would exclude all `package.json` files under `/usr/foo`. For _directory scans_, 231 it is required to begin path expressions with `./`, `*/`, or `**/`, all of which 232 will be resolved _relative to the specified scan directory_. Keep in mind, your shell 233 may attempt to expand wildcards, so put those parameters in single quotes, like: 234 `'**/*.json'`. 235 236 ### Output formats 237 238 The output format for Syft is configurable as well using the 239 `-o` (or `--output`) option: 240 241 ``` 242 syft <image> -o <format> 243 ``` 244 245 Where the `formats` available are: 246 - `json`: Use this to get as much information out of Syft as possible! 247 - `text`: A row-oriented, human-and-machine-friendly output. 248 - `cyclonedx-xml`: A XML report conforming to the [CycloneDX 1.4 specification](https://cyclonedx.org/specification/overview/). 249 - `cyclonedx-json`: A JSON report conforming to the [CycloneDX 1.4 specification](https://cyclonedx.org/specification/overview/). 250 - `spdx-tag-value`: A tag-value formatted report conforming to the [SPDX 2.3 specification](https://spdx.github.io/spdx-spec/v2.3/). 251 - `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/). 252 - `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). 253 - `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). 254 - `github`: A JSON report conforming to GitHub's dependency snapshot format. 255 - `table`: A columnar summary (default). 256 - `template`: Lets the user specify the output format. See ["Using templates"](#using-templates) below. 257 258 ## Using templates 259 260 Syft lets you define custom output formats, using [Go templates](https://pkg.go.dev/text/template). Here's how it works: 261 262 - Define your format as a Go template, and save this template as a file. 263 264 - Set the output format to "template" (`-o template`). 265 266 - Specify the path to the template file (`-t ./path/to/custom.template`). 267 268 - Syft'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 `syft <image> -o json` as a reference. 269 270 **Example:** You could make Syft output data in CSV format by writing a Go template that renders CSV data and then running `syft <image> -o template -t ~/path/to/csv.tmpl`. 271 272 Here's what the `csv.tmpl` file might look like: 273 ```gotemplate 274 "Package","Version Installed","Found by" 275 {{- range .Artifacts}} 276 "{{.Name}}","{{.Version}}","{{.FoundBy}}" 277 {{- end}} 278 ``` 279 280 Which would produce output like: 281 ```text 282 "Package","Version Installed","Found by" 283 "alpine-baselayout","3.2.0-r20","apkdb-cataloger" 284 "alpine-baselayout-data","3.2.0-r20","apkdb-cataloger" 285 "alpine-keys","2.4-r1","apkdb-cataloger" 286 ... 287 ``` 288 289 Syft 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. 290 291 Lastly, Syft has custom templating functions defined in `./syft/format/template/encoder.go` to help parse the passed-in JSON structs. 292 293 ## Multiple outputs 294 295 Syft can also output _multiple_ files in differing formats by appending 296 `=<file>` to the option, for example to output Syft JSON and SPDX JSON: 297 298 ```shell 299 syft <image> -o json=sbom.syft.json -o spdx-json=sbom.spdx.json 300 ``` 301 302 ## Private Registry Authentication 303 304 ### Local Docker Credentials 305 When a container runtime is not present, Syft 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). 306 307 An example `config.json` looks something like this: 308 ```json 309 { 310 "auths": { 311 "registry.example.com": { 312 "username": "AzureDiamond", 313 "password": "hunter2" 314 } 315 } 316 } 317 ``` 318 319 You can run the following command as an example. It details the mount/environment configuration a container needs to access a private registry: 320 321 ``` 322 docker run -v ./config.json:/config/config.json -e "DOCKER_CONFIG=/config" anchore/syft:latest <private_image> 323 ``` 324 325 ### Docker Credentials in Kubernetes 326 327 Here's a simple workflow to mount this config file as a secret into a container on Kubernetes. 328 329 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. 330 331 ```yaml 332 # secret.yaml 333 334 apiVersion: v1 335 kind: Secret 336 metadata: 337 name: registry-config 338 namespace: syft 339 data: 340 config.json: <base64 encoded config.json> 341 ``` 342 343 `kubectl apply -f secret.yaml` 344 345 346 2. Create your pod running syft. 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 syft 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. 347 348 ```yaml 349 # pod.yaml 350 351 apiVersion: v1 352 kind: Pod 353 metadata: 354 name: syft-k8s-usage 355 spec: 356 containers: 357 - image: anchore/syft:latest 358 name: syft-private-registry-demo 359 env: 360 - name: DOCKER_CONFIG 361 value: /config 362 volumeMounts: 363 - mountPath: /config 364 name: registry-config 365 readOnly: true 366 args: 367 - <private_image> 368 volumes: 369 - name: registry-config 370 secret: 371 secretName: registry-config 372 ``` 373 374 `kubectl apply -f pod.yaml` 375 376 377 3. The user can now run `kubectl logs syft-private-registry-demo`. The logs should show the Syft analysis for the `<private_image>` provided in the pod configuration. 378 379 Using the above information, users should be able to configure private registry access without having to do so in the `grype` or `syft` configuration files. They will also not be dependent on a Docker daemon, (or some other runtime software) for registry configuration and access. 380 381 ## Format conversion (experimental) 382 383 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. 384 385 ``` 386 syft convert <ORIGINAL-SBOM-FILE> -o <NEW-SBOM-FORMAT>[=<NEW-SBOM-FILE>] 387 ``` 388 389 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 Syft doesn't support, are more likely to be lost. 390 391 We support formats with wide community usage AND good encode/decode support by Syft. The supported formats are: 392 - Syft JSON 393 - SPDX 2.2 JSON 394 - SPDX 2.2 tag-value 395 - CycloneDX 1.4 JSON 396 - CycloneDX 1.4 XML 397 398 Conversion example: 399 ```sh 400 syft alpine:latest -o syft-json=sbom.syft.json # generate a syft SBOM 401 syft convert sbom.syft.json -o cyclonedx-json=sbom.cdx.json # convert it to CycloneDX 402 ``` 403 404 ## Attestation (experimental) 405 ### Keyless support 406 Syft supports generating attestations using cosign's [keyless](https://github.com/sigstore/cosign/blob/main/KEYLESS.md) signatures. 407 408 Note: users need to have >= v1.12.0 of cosign installed for this command to function 409 410 To use this feature with a format like CycloneDX json simply run: 411 ``` 412 syft attest --output cyclonedx-json <IMAGE WITH OCI WRITE ACCESS> 413 ``` 414 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). 415 416 After authenticating, Syft will upload the attestation to the OCI registry specified by the image that the user has write access to. 417 418 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. 419 420 Users can then verify the attestation(or any image with attestations) by running: 421 ``` 422 COSIGN_EXPERIMENTAL=1 cosign verify-attestation <IMAGE_WITH_ATTESTATIONS> 423 ``` 424 425 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). 426 There will also be a printout of the certificates subject `<user identity>` and the certificate issuer URL: `<provider of user identity (Github, Google, Microsoft)>`: 427 ``` 428 Certificate subject: test.email@testdomain.com 429 Certificate issuer URL: https://accounts.google.com 430 ``` 431 432 ### Local private key support 433 434 To generate an SBOM attestation for a container image using a local private key: 435 ``` 436 syft attest --output [FORMAT] --key [KEY] [SOURCE] [flags] 437 ``` 438 439 The above output is in the form of the [DSSE envelope](https://github.com/secure-systems-lab/dsse/blob/master/envelope.md#dsse-envelope). 440 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-syft). 441 442 443 444 ## Configuration 445 446 Configuration search paths: 447 448 - `.syft.yaml` 449 - `.syft/config.yaml` 450 - `~/.syft.yaml` 451 - `<XDG_CONFIG_HOME>/syft/config.yaml` 452 453 Configuration options (example values are the default): 454 455 ```yaml 456 # the output format(s) of the SBOM report (options: table, text, json, spdx, ...) 457 # same as -o, --output, and SYFT_OUTPUT env var 458 # to specify multiple output files in differing formats, use a list: 459 # output: 460 # - "json=<syft-json-output-file>" 461 # - "spdx-json=<spdx-json-output-file>" 462 output: "table" 463 464 # suppress all output (except for the SBOM report) 465 # same as -q ; SYFT_QUIET env var 466 quiet: false 467 468 # same as --file; write output report to a file (default is to write to stdout) 469 file: "" 470 471 # enable/disable checking for application updates on startup 472 # same as SYFT_CHECK_FOR_APP_UPDATE env var 473 check-for-app-update: true 474 475 # allows users to specify which image source should be used to generate the sbom 476 # valid values are: registry, docker, podman 477 default-image-pull-source: "" 478 479 # a list of globs to exclude from scanning. same as --exclude ; for example: 480 # exclude: 481 # - "/etc/**" 482 # - "./out/**/*.json" 483 exclude: [] 484 485 # allows users to exclude synthetic binary packages from the sbom 486 # these packages are removed if an overlap with a non-synthetic package is found 487 exclude-overlap-by-ownership: true 488 489 # os and/or architecture to use when referencing container images (e.g. "windows/armv6" or "arm64") 490 # same as --platform; SYFT_PLATFORM env var 491 platform: "" 492 493 # set the list of package catalogers to use when generating the SBOM 494 # default = empty (cataloger set determined automatically by the source type [image or file/directory]) 495 # catalogers: 496 # - alpmdb-cataloger 497 # - apkdb-cataloger 498 # - binary-cataloger 499 # - cargo-auditable-binary-cataloger 500 # - cocoapods-cataloger 501 # - conan-cataloger 502 # - dartlang-lock-cataloger 503 # - dotnet-deps-cataloger 504 # - dpkgdb-cataloger 505 # - elixir-mix-lock-cataloger 506 # - erlang-rebar-lock-cataloger 507 # - go-mod-file-cataloger 508 # - go-module-binary-cataloger 509 # - graalvm-native-image-cataloger 510 # - haskell-cataloger 511 # - java-cataloger 512 # - java-gradle-lockfile-cataloger 513 # - java-pom-cataloger 514 # - javascript-lock-cataloger 515 # - javascript-package-cataloger 516 # - linux-kernel-cataloger 517 # - nix-store-cataloger 518 # - php-composer-installed-cataloger 519 # - php-composer-lock-cataloger 520 # - portage-cataloger 521 # - python-index-cataloger 522 # - python-package-cataloger 523 # - rpm-db-cataloger 524 # - rpm-file-cataloger 525 # - ruby-gemfile-cataloger 526 # - ruby-gemspec-cataloger 527 # - rust-cargo-lock-cataloger 528 # - sbom-cataloger 529 # - spm-cataloger 530 catalogers: 531 532 # cataloging packages is exposed through the packages and power-user subcommands 533 package: 534 535 # search within archives that do contain a file index to search against (zip) 536 # note: for now this only applies to the java package cataloger 537 # SYFT_PACKAGE_SEARCH_INDEXED_ARCHIVES env var 538 search-indexed-archives: true 539 540 # search within archives that do not contain a file index to search against (tar, tar.gz, tar.bz2, etc) 541 # note: enabling this may result in a performance impact since all discovered compressed tars will be decompressed 542 # note: for now this only applies to the java package cataloger 543 # SYFT_PACKAGE_SEARCH_UNINDEXED_ARCHIVES env var 544 search-unindexed-archives: false 545 546 cataloger: 547 # enable/disable cataloging of packages 548 # SYFT_PACKAGE_CATALOGER_ENABLED env var 549 enabled: true 550 551 # the search space to look for packages (options: all-layers, squashed) 552 # same as -s ; SYFT_PACKAGE_CATALOGER_SCOPE env var 553 scope: "squashed" 554 555 golang: 556 # search for go package licences in the GOPATH of the system running Syft, note that this is outside the 557 # container filesystem and potentially outside the root of a local directory scan 558 # SYFT_GOLANG_SEARCH_LOCAL_MOD_CACHE_LICENSES env var 559 search-local-mod-cache-licenses: false 560 561 # specify an explicit go mod cache directory, if unset this defaults to $GOPATH/pkg/mod or $HOME/go/pkg/mod 562 # SYFT_GOLANG_LOCAL_MOD_CACHE_DIR env var 563 local-mod-cache-dir: "" 564 565 # search for go package licences by retrieving the package from a network proxy 566 # SYFT_GOLANG_SEARCH_REMOTE_LICENSES env var 567 search-remote-licenses: false 568 569 # remote proxy to use when retrieving go packages from the network, 570 # if unset this defaults to $GOPROXY followed by https://proxy.golang.org 571 # SYFT_GOLANG_PROXY env var 572 proxy: "" 573 574 # specifies packages which should not be fetched by proxy 575 # if unset this defaults to $GONOPROXY 576 # SYFT_GOLANG_NOPROXY env var 577 no-proxy: "" 578 579 linux-kernel: 580 # whether to catalog linux kernel modules found within lib/modules/** directories 581 # SYFT_LINUX_KERNEL_CATALOG_MODULES env var 582 catalog-modules: true 583 584 python: 585 # when running across entries in requirements.txt that do not specify a specific version 586 # (e.g. "sqlalchemy >= 1.0.0, <= 2.0.0, != 3.0.0, <= 3.0.0"), attempt to guess what the version could 587 # be based on the version requirements specified (e.g. "1.0.0"). When enabled the lowest expressible version 588 # when given an arbitrary constraint will be used (even if that version may not be available/published). 589 guess-unpinned-requirements: false 590 591 # cataloging file contents is exposed through the power-user subcommand 592 file-contents: 593 cataloger: 594 # enable/disable cataloging of secrets 595 # SYFT_FILE_CONTENTS_CATALOGER_ENABLED env var 596 enabled: true 597 598 # the search space to look for secrets (options: all-layers, squashed) 599 # SYFT_FILE_CONTENTS_CATALOGER_SCOPE env var 600 scope: "squashed" 601 602 # skip searching a file entirely if it is above the given size (default = 1MB; unit = bytes) 603 # SYFT_FILE_CONTENTS_SKIP_FILES_ABOVE_SIZE env var 604 skip-files-above-size: 1048576 605 606 # file globs for the cataloger to match on 607 # SYFT_FILE_CONTENTS_GLOBS env var 608 globs: [] 609 610 # cataloging file metadata is exposed through the power-user subcommand 611 file-metadata: 612 cataloger: 613 # enable/disable cataloging of file metadata 614 # SYFT_FILE_METADATA_CATALOGER_ENABLED env var 615 enabled: true 616 617 # the search space to look for file metadata (options: all-layers, squashed) 618 # SYFT_FILE_METADATA_CATALOGER_SCOPE env var 619 scope: "squashed" 620 621 # the file digest algorithms to use when cataloging files (options: "md5", "sha1", "sha224", "sha256", "sha384", "sha512") 622 # SYFT_FILE_METADATA_DIGESTS env var 623 digests: ["sha256"] 624 625 # maximum number of workers used to process the list of package catalogers in parallel 626 parallelism: 1 627 628 # cataloging secrets is exposed through the power-user subcommand 629 secrets: 630 cataloger: 631 # enable/disable cataloging of secrets 632 # SYFT_SECRETS_CATALOGER_ENABLED env var 633 enabled: true 634 635 # the search space to look for secrets (options: all-layers, squashed) 636 # SYFT_SECRETS_CATALOGER_SCOPE env var 637 scope: "all-layers" 638 639 # show extracted secret values in the final JSON report 640 # SYFT_SECRETS_REVEAL_VALUES env var 641 reveal-values: false 642 643 # skip searching a file entirely if it is above the given size (default = 1MB; unit = bytes) 644 # SYFT_SECRETS_SKIP_FILES_ABOVE_SIZE env var 645 skip-files-above-size: 1048576 646 647 # name-regex pairs to consider when searching files for secrets. Note: the regex must match single line patterns 648 # but may also have OPTIONAL multiline capture groups. Regexes with a named capture group of "value" will 649 # use the entire regex to match, but the secret value will be assumed to be entirely contained within the 650 # "value" named capture group. 651 additional-patterns: {} 652 653 # names to exclude from the secrets search, valid values are: "aws-access-key", "aws-secret-key", "pem-private-key", 654 # "docker-config-auth", and "generic-api-key". Note: this does not consider any names introduced in the 655 # "secrets.additional-patterns" config option. 656 # SYFT_SECRETS_EXCLUDE_PATTERN_NAMES env var 657 exclude-pattern-names: [] 658 659 # options that apply to all scan sources 660 source: 661 # alias name for the source 662 # SYFT_SOURCE_NAME env var; --source-name flag 663 name: "" 664 665 # alias version for the source 666 # SYFT_SOURCE_VERSION env var; --source-version flag 667 version: "" 668 669 # options affecting the file source type 670 file: 671 # the file digest algorithms to use on the scanned file (options: "md5", "sha1", "sha224", "sha256", "sha384", "sha512") 672 digests: ["sha256"] 673 674 # options when pulling directly from a registry via the "registry:" scheme 675 registry: 676 # skip TLS verification when communicating with the registry 677 # SYFT_REGISTRY_INSECURE_SKIP_TLS_VERIFY env var 678 insecure-skip-tls-verify: false 679 680 # use http instead of https when connecting to the registry 681 # SYFT_REGISTRY_INSECURE_USE_HTTP env var 682 insecure-use-http: false 683 684 # credentials for specific registries 685 auth: 686 # the URL to the registry (e.g. "docker.io", "localhost:5000", etc.) 687 # SYFT_REGISTRY_AUTH_AUTHORITY env var 688 - authority: "" 689 # SYFT_REGISTRY_AUTH_USERNAME env var 690 username: "" 691 # SYFT_REGISTRY_AUTH_PASSWORD env var 692 password: "" 693 # note: token and username/password are mutually exclusive 694 # SYFT_REGISTRY_AUTH_TOKEN env var 695 token: "" 696 # - ... # note, more credentials can be provided via config file only 697 698 # generate an attested SBOM 699 attest: 700 # path to the private key file to use for attestation 701 # SYFT_ATTEST_KEY env var 702 key: "cosign.key" 703 704 # password to decrypt to given private key 705 # SYFT_ATTEST_PASSWORD env var, additionally responds to COSIGN_PASSWORD 706 password: "" 707 708 log: 709 # use structured logging 710 # same as SYFT_LOG_STRUCTURED env var 711 structured: false 712 713 # the log level; note: detailed logging suppress the ETUI 714 # same as SYFT_LOG_LEVEL env var 715 level: "error" 716 717 # location to write the log file (default is not to have a log file) 718 # same as SYFT_LOG_FILE env var 719 file: "" 720 ``` 721 722 ### Adding an SBOM to an image as an attestation using Syft 723 724 `syft attest --output [FORMAT] --key [KEY] [SOURCE] [flags]` 725 726 SBOMs themselves can serve as input to different analysis tools. [Grype](https://github.com/anchore/grype), a vulnerability scanner CLI tool from Anchore, is one such tool. Publishers of container images can use attestations to enable their consumers to trust Syft-generated SBOM descriptions of those container images. To create and provide these attestations, image publishers can run `syft attest` in conjunction with the [cosign](https://github.com/sigstore/cosign) tool to attach SBOM attestations to their images. 727 728 #### Example attestation 729 Note for the following example replace `docker.io/image:latest` with an image you own. You should also have push access to 730 its remote reference. Replace `$MY_PRIVATE_KEY` with a private key you own or have generated with cosign. 731 732 ```bash 733 syft attest --key $MY_PRIVATE_KEY -o spdx-json docker.io/image:latest > image_latest_sbom_attestation.json 734 cosign attach attestation --attestation image_latest_sbom_attestation.json docker.io/image:latest 735 ``` 736 737 Verify the new attestation exists on your image. 738 739 ```bash 740 cosign verify-attestation --key $MY_PUBLIC_KEY --type spdxjson docker.io/image:latest | jq '.payload | @base64d | .payload | fromjson | .predicate' 741 ``` 742 743 You should see this output along with the attached SBOM: 744 745 ``` 746 Verification for docker.io/image:latest -- 747 The following checks were performed on each of these signatures: 748 - The cosign claims were validated 749 - The signatures were verified against the specified public key 750 - Any certificates were verified against the Fulcio roots. 751 ``` 752 753 Consumers of your image can now trust that the SBOM associated with your image is correct and from a trusted source. 754 755 The SBOM can be piped to Grype: 756 757 758 ```bash 759 cosign verify-attestation --key $MY_PUBLIC_KEY --type spdxjson docker.io/image:latest | jq '.payload | @base64d | .payload | fromjson | .predicate' | grype 760 ```