github.com/lineaje-labs/syft@v0.98.1-0.20231227153149-9e393f60ff1b/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 containerd:yourrepo/yourimage:tag use images from the Containerd daemon 143 docker-archive:path/to/yourimage.tar use a tarball from disk for archives created from "docker save" 144 oci-archive:path/to/yourimage.tar use a tarball from disk for OCI archives (from Skopeo or otherwise) 145 oci-dir:path/to/yourimage read directly from a path on disk for OCI layout directories (from Skopeo or otherwise) 146 singularity:path/to/yourimage.sif read directly from a Singularity Image Format (SIF) container on disk 147 dir:path/to/yourproject read directly from a path on disk (any directory) 148 file:path/to/yourproject/file read directly from a path on disk (any single file) 149 registry:yourrepo/yourimage:tag pull image directly from a registry (no container runtime required) 150 ``` 151 152 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. 153 If docker is not present, then the Podman daemon is attempted next, followed by reaching out directly to the image registry last. 154 155 156 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). 157 158 ### Default Cataloger Configuration by scan type 159 160 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. 161 162 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. 163 164 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). 165 166 ##### Image Scanning: 167 - alpmdb 168 - apkdb 169 - binary 170 - dotnet-deps 171 - dotnet-portable-executable 172 - dpkgdb 173 - go-module-binary 174 - graalvm-native-image 175 - java 176 - javascript-package 177 - linux-kernel 178 - nix-store 179 - php-composer-installed 180 - portage 181 - python-package 182 - rpm-db 183 - ruby-gemspec 184 - sbom 185 186 ##### Directory Scanning: 187 - alpmdb 188 - apkdb 189 - binary 190 - cocoapods 191 - conan 192 - dartlang-lock 193 - dotnet-deps 194 - dotnet-portable-executable 195 - dpkgdb 196 - elixir-mix-lock 197 - erlang-rebar-lock 198 - go-mod-file 199 - go-module-binary 200 - graalvm-native-image 201 - haskell 202 - java 203 - java-gradle-lockfile 204 - java-pom 205 - javascript-lock 206 - linux-kernel 207 - nix-store 208 - php-composer-lock 209 - portage 210 - python-index 211 - python-package 212 - rpm-db 213 - rpm-file 214 - ruby-gemfile 215 - rust-cargo-lock 216 - sbom 217 - swift-package-manager 218 219 ##### Non Default: 220 - cargo-auditable-binary 221 222 ### Excluding file paths 223 224 Syft can exclude files and paths from being scanned within a source by using glob expressions 225 with one or more `--exclude` parameters: 226 ``` 227 syft <source> --exclude './out/**/*.json' --exclude /etc 228 ``` 229 **Note:** in the case of _image scanning_, since the entire filesystem is scanned it is 230 possible to use absolute paths like `/etc` or `/usr/**/*.txt` whereas _directory scans_ 231 exclude files _relative to the specified directory_. For example: scanning `/usr/foo` with 232 `--exclude ./package.json` would exclude `/usr/foo/package.json` and `--exclude '**/package.json'` 233 would exclude all `package.json` files under `/usr/foo`. For _directory scans_, 234 it is required to begin path expressions with `./`, `*/`, or `**/`, all of which 235 will be resolved _relative to the specified scan directory_. Keep in mind, your shell 236 may attempt to expand wildcards, so put those parameters in single quotes, like: 237 `'**/*.json'`. 238 239 ### Output formats 240 241 The output format for Syft is configurable as well using the 242 `-o` (or `--output`) option: 243 244 ``` 245 syft <image> -o <format> 246 ``` 247 248 Where the `formats` available are: 249 - `syft-json`: Use this to get as much information out of Syft as possible! 250 - `syft-text`: A row-oriented, human-and-machine-friendly output. 251 - `cyclonedx-xml`: A XML report conforming to the [CycloneDX 1.4 specification](https://cyclonedx.org/specification/overview/). 252 - `cyclonedx-json`: A JSON report conforming to the [CycloneDX 1.4 specification](https://cyclonedx.org/specification/overview/). 253 - `spdx-tag-value`: A tag-value formatted report conforming to the [SPDX 2.3 specification](https://spdx.github.io/spdx-spec/v2.3/). 254 - `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/). 255 - `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). 256 - `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). 257 - `github-json`: A JSON report conforming to GitHub's dependency snapshot format. 258 - `syft-table`: A columnar summary (default). 259 - `template`: Lets the user specify the output format. See ["Using templates"](#using-templates) below. 260 261 ## Using templates 262 263 Syft lets you define custom output formats, using [Go templates](https://pkg.go.dev/text/template). Here's how it works: 264 265 - Define your format as a Go template, and save this template as a file. 266 267 - Set the output format to "template" (`-o template`). 268 269 - Specify the path to the template file (`-t ./path/to/custom.template`). 270 271 - Syft's template processing uses the same data models as the `syft-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 syft-json` as a reference. 272 273 **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`. 274 275 Here's what the `csv.tmpl` file might look like: 276 ```gotemplate 277 "Package","Version Installed","Found by" 278 {{- range .Artifacts}} 279 "{{.Name}}","{{.Version}}","{{.FoundBy}}" 280 {{- end}} 281 ``` 282 283 Which would produce output like: 284 ```text 285 "Package","Version Installed","Found by" 286 "alpine-baselayout","3.2.0-r20","apkdb-cataloger" 287 "alpine-baselayout-data","3.2.0-r20","apkdb-cataloger" 288 "alpine-keys","2.4-r1","apkdb-cataloger" 289 ... 290 ``` 291 292 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. 293 294 Lastly, Syft has custom templating functions defined in `./syft/format/template/encoder.go` to help parse the passed-in JSON structs. 295 296 ## Multiple outputs 297 298 Syft can also output _multiple_ files in differing formats by appending 299 `=<file>` to the option, for example to output Syft JSON and SPDX JSON: 300 301 ```shell 302 syft <image> -o syft-json=sbom.syft.json -o spdx-json=sbom.spdx.json 303 ``` 304 305 ## Private Registry Authentication 306 307 ### Local Docker Credentials 308 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). 309 310 An example `config.json` looks something like this: 311 ```json 312 { 313 "auths": { 314 "registry.example.com": { 315 "username": "AzureDiamond", 316 "password": "hunter2" 317 } 318 } 319 } 320 ``` 321 322 You can run the following command as an example. It details the mount/environment configuration a container needs to access a private registry: 323 324 ``` 325 docker run -v ./config.json:/config/config.json -e "DOCKER_CONFIG=/config" anchore/syft:latest <private_image> 326 ``` 327 328 ### Docker Credentials in Kubernetes 329 330 Here's a simple workflow to mount this config file as a secret into a container on Kubernetes. 331 332 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. 333 334 ```yaml 335 # secret.yaml 336 337 apiVersion: v1 338 kind: Secret 339 metadata: 340 name: registry-config 341 namespace: syft 342 data: 343 config.json: <base64 encoded config.json> 344 ``` 345 346 `kubectl apply -f secret.yaml` 347 348 349 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. 350 351 ```yaml 352 # pod.yaml 353 354 apiVersion: v1 355 kind: Pod 356 metadata: 357 name: syft-k8s-usage 358 spec: 359 containers: 360 - image: anchore/syft:latest 361 name: syft-private-registry-demo 362 env: 363 - name: DOCKER_CONFIG 364 value: /config 365 volumeMounts: 366 - mountPath: /config 367 name: registry-config 368 readOnly: true 369 args: 370 - <private_image> 371 volumes: 372 - name: registry-config 373 secret: 374 secretName: registry-config 375 ``` 376 377 `kubectl apply -f pod.yaml` 378 379 380 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. 381 382 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. 383 384 ## Format conversion (experimental) 385 386 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. 387 388 ``` 389 syft convert <ORIGINAL-SBOM-FILE> -o <NEW-SBOM-FORMAT>[=<NEW-SBOM-FILE>] 390 ``` 391 392 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. 393 394 We support formats with wide community usage AND good encode/decode support by Syft. The supported formats are: 395 - Syft JSON (```-o syft-json```) 396 - SPDX 2.2 JSON (```-o spdx-json```) 397 - SPDX 2.2 tag-value (```-o spdx-tag-value```) 398 - CycloneDX 1.4 JSON (```-o cyclonedx-json```) 399 - CycloneDX 1.4 XML (```-o cyclonedx-xml```) 400 401 Conversion example: 402 ```sh 403 syft alpine:latest -o syft-json=sbom.syft.json # generate a syft SBOM 404 syft convert sbom.syft.json -o cyclonedx-json=sbom.cdx.json # convert it to CycloneDX 405 ``` 406 407 ## Attestation (experimental) 408 ### Keyless support 409 Syft supports generating attestations using cosign's [keyless](https://github.com/sigstore/cosign/blob/main/KEYLESS.md) signatures. 410 411 Note: users need to have >= v1.12.0 of cosign installed for this command to function 412 413 To use this feature with a format like CycloneDX json simply run: 414 ``` 415 syft attest --output cyclonedx-json <IMAGE WITH OCI WRITE ACCESS> 416 ``` 417 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). 418 419 After authenticating, Syft will upload the attestation to the OCI registry specified by the image that the user has write access to. 420 421 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. 422 423 Users can then verify the attestation(or any image with attestations) by running: 424 ``` 425 COSIGN_EXPERIMENTAL=1 cosign verify-attestation <IMAGE_WITH_ATTESTATIONS> 426 ``` 427 428 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). 429 There will also be a printout of the certificates subject `<user identity>` and the certificate issuer URL: `<provider of user identity (Github, Google, Microsoft)>`: 430 ``` 431 Certificate subject: test.email@testdomain.com 432 Certificate issuer URL: https://accounts.google.com 433 ``` 434 435 ### Local private key support 436 437 To generate an SBOM attestation for a container image using a local private key: 438 ``` 439 syft attest --output [FORMAT] --key [KEY] [SOURCE] [flags] 440 ``` 441 442 The above output is in the form of the [DSSE envelope](https://github.com/secure-systems-lab/dsse/blob/master/envelope.md#dsse-envelope). 443 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). 444 445 446 447 ## Configuration 448 449 Configuration search paths: 450 451 - `.syft.yaml` 452 - `.syft/config.yaml` 453 - `~/.syft.yaml` 454 - `<XDG_CONFIG_HOME>/syft/config.yaml` 455 456 Configuration options (example values are the default): 457 458 ```yaml 459 # the output format(s) of the SBOM report (options: syft-table, syft-text, syft-json, spdx-json, ...) 460 # same as -o, --output, and SYFT_OUTPUT env var 461 # to specify multiple output files in differing formats, use a list: 462 # output: 463 # - "syft-json=<syft-json-output-file>" 464 # - "spdx-json=<spdx-json-output-file>" 465 output: "syft-table" 466 467 # suppress all output (except for the SBOM report) 468 # same as -q ; SYFT_QUIET env var 469 quiet: false 470 471 # same as --file; write output report to a file (default is to write to stdout) 472 file: "" 473 474 # enable/disable checking for application updates on startup 475 # same as SYFT_CHECK_FOR_APP_UPDATE env var 476 check-for-app-update: true 477 478 # allows users to specify which image source should be used to generate the sbom 479 # valid values are: registry, docker, podman 480 default-image-pull-source: "" 481 482 # a list of globs to exclude from scanning. same as --exclude ; for example: 483 # exclude: 484 # - "/etc/**" 485 # - "./out/**/*.json" 486 exclude: [] 487 488 # allows users to exclude synthetic binary packages from the sbom 489 # these packages are removed if an overlap with a non-synthetic package is found 490 exclude-binary-overlap-by-ownership: true 491 492 # os and/or architecture to use when referencing container images (e.g. "windows/armv6" or "arm64") 493 # same as --platform; SYFT_PLATFORM env var 494 platform: "" 495 496 # set the list of package catalogers to use when generating the SBOM 497 # default = empty (cataloger set determined automatically by the source type [image or file/directory]) 498 # catalogers: 499 # - alpm-db-cataloger 500 # - apkdb-cataloger 501 # - binary-cataloger 502 # - cargo-auditable-binary-cataloger 503 # - cocoapods-cataloger 504 # - conan-cataloger 505 # - dartlang-lock-cataloger 506 # - dotnet-deps-cataloger 507 # - dotnet-portable-executable-cataloger 508 # - dpkg-db-cataloger 509 # - elixir-mix-lock-cataloger 510 # - erlang-rebar-lock-cataloger 511 # - go-module-file-cataloger 512 # - go-module-binary-cataloger 513 # - graalvm-native-image-cataloger 514 # - haskell-cataloger 515 # - java-cataloger 516 # - java-gradle-lockfile-cataloger 517 # - java-pom-cataloger 518 # - javascript-lock-cataloger 519 # - javascript-package-cataloger 520 # - linux-kernel-cataloger 521 # - nix-store-cataloger 522 # - php-composer-installed-cataloger 523 # - php-composer-lock-cataloger 524 # - portage-cataloger 525 # - python-package-cataloger 526 # - python-installed-package-cataloger 527 # - rpm-db-cataloger 528 # - rpm-archive-cataloger 529 # - ruby-gemfile-cataloger 530 # - ruby-installed-gemspec-cataloger 531 # - rust-cargo-lock-cataloger 532 # - sbom-cataloger 533 # - spm-cataloger 534 catalogers: 535 536 537 # all format configuration 538 format: 539 540 # default value for all formats that support the "pretty" option (default is unset) 541 pretty: 542 543 # all syft-json format options 544 json: 545 546 # include space indention and newlines (inherits default value from 'format.pretty' or 'false' if parent is unset) 547 # note: inherits default value from 'format.pretty' or 'false' if parent is unset 548 pretty: false 549 550 # transform any syft-json output to conform to an approximation of the v11.0.1 schema. This includes: 551 # - using the package metadata type names from before v12 of the JSON schema (changed in https://github.com/anchore/syft/pull/1983) 552 # 553 # Note: this will still include package types and fields that were added at or after json schema v12. This means 554 # that output might not strictly be json schema v11 compliant, however, for consumers that require time to port 555 # over to the final syft 1.0 json output this option can be used to ease the transition. 556 # 557 # Note: long term support for this option is not guaranteed. 558 legacy: false 559 560 # all template format options 561 template: 562 # path to the template file to use when rendering the output with the `template` output format. 563 # Note that all template paths are based on the current syft-json schema. 564 # same as -t ; SYFT_TEMPLATE_PATH env var 565 path: "" 566 567 # all spdx-json format options 568 spdx-json: 569 570 # include space indention and newlines 571 # note: inherits default value from 'format.pretty' or 'false' if parent is unset 572 pretty: false 573 574 # all cyclonedx-json format options 575 cyclonedx-json: 576 577 # include space indention and newlines 578 # note: inherits default value from 'format.pretty' or 'false' if parent is unset 579 pretty: false 580 581 # all cyclonedx-xml format options 582 cyclonedx-xml: 583 584 # include space indention 585 # note: inherits default value from 'format.pretty' or 'false' if parent is unset 586 pretty: false 587 588 589 # cataloging packages is exposed through the packages and power-user subcommands 590 package: 591 592 # search within archives that do contain a file index to search against (zip) 593 # note: for now this only applies to the java package cataloger 594 # SYFT_PACKAGE_SEARCH_INDEXED_ARCHIVES env var 595 search-indexed-archives: true 596 597 # search within archives that do not contain a file index to search against (tar, tar.gz, tar.bz2, etc) 598 # note: enabling this may result in a performance impact since all discovered compressed tars will be decompressed 599 # note: for now this only applies to the java package cataloger 600 # SYFT_PACKAGE_SEARCH_UNINDEXED_ARCHIVES env var 601 search-unindexed-archives: false 602 603 cataloger: 604 # enable/disable cataloging of packages 605 # SYFT_PACKAGE_CATALOGER_ENABLED env var 606 enabled: true 607 608 # the search space to look for packages (options: all-layers, squashed) 609 # same as -s ; SYFT_PACKAGE_CATALOGER_SCOPE env var 610 scope: "squashed" 611 612 golang: 613 # search for go package licences in the GOPATH of the system running Syft, note that this is outside the 614 # container filesystem and potentially outside the root of a local directory scan 615 # SYFT_GOLANG_SEARCH_LOCAL_MOD_CACHE_LICENSES env var 616 search-local-mod-cache-licenses: false 617 618 # specify an explicit go mod cache directory, if unset this defaults to $GOPATH/pkg/mod or $HOME/go/pkg/mod 619 # SYFT_GOLANG_LOCAL_MOD_CACHE_DIR env var 620 local-mod-cache-dir: "" 621 622 # search for go package licences by retrieving the package from a network proxy 623 # SYFT_GOLANG_SEARCH_REMOTE_LICENSES env var 624 search-remote-licenses: false 625 626 # remote proxy to use when retrieving go packages from the network, 627 # if unset this defaults to $GOPROXY followed by https://proxy.golang.org 628 # SYFT_GOLANG_PROXY env var 629 proxy: "" 630 631 # specifies packages which should not be fetched by proxy 632 # if unset this defaults to $GONOPROXY 633 # SYFT_GOLANG_NOPROXY env var 634 no-proxy: "" 635 636 java: 637 maven-url: "https://repo1.maven.org/maven2" 638 max-parent-recursive-depth: 5 639 # enables Syft to use the network to fill in more detailed information about artifacts 640 # currently this enables searching maven-url for license data 641 # when running across pom.xml files that could have more information, syft will 642 # explicitly search maven for license information by querying the online pom when this is true 643 # this option is helpful for when the parent pom has more data, 644 # that is not accessible from within the final built artifact 645 use-network: false 646 647 linux-kernel: 648 # whether to catalog linux kernel modules found within lib/modules/** directories 649 # SYFT_LINUX_KERNEL_CATALOG_MODULES env var 650 catalog-modules: true 651 652 python: 653 # when running across entries in requirements.txt that do not specify a specific version 654 # (e.g. "sqlalchemy >= 1.0.0, <= 2.0.0, != 3.0.0, <= 3.0.0"), attempt to guess what the version could 655 # be based on the version requirements specified (e.g. "1.0.0"). When enabled the lowest expressible version 656 # when given an arbitrary constraint will be used (even if that version may not be available/published). 657 guess-unpinned-requirements: false 658 659 file-contents: 660 cataloger: 661 # enable/disable cataloging of file contents 662 # SYFT_FILE_CONTENTS_CATALOGER_ENABLED env var 663 enabled: true 664 665 # the search space to look for file contents (options: all-layers, squashed) 666 # SYFT_FILE_CONTENTS_CATALOGER_SCOPE env var 667 scope: "squashed" 668 669 # skip searching a file entirely if it is above the given size (default = 1MB; unit = bytes) 670 # SYFT_FILE_CONTENTS_SKIP_FILES_ABOVE_SIZE env var 671 skip-files-above-size: 1048576 672 673 # file globs for the cataloger to match on 674 # SYFT_FILE_CONTENTS_GLOBS env var 675 globs: [] 676 677 file-metadata: 678 cataloger: 679 # enable/disable cataloging of file metadata 680 # SYFT_FILE_METADATA_CATALOGER_ENABLED env var 681 enabled: true 682 683 # the search space to look for file metadata (options: all-layers, squashed) 684 # SYFT_FILE_METADATA_CATALOGER_SCOPE env var 685 scope: "squashed" 686 687 # the file digest algorithms to use when cataloging files (options: "md5", "sha1", "sha224", "sha256", "sha384", "sha512") 688 # SYFT_FILE_METADATA_DIGESTS env var 689 digests: ["sha256"] 690 691 # maximum number of workers used to process the list of package catalogers in parallel 692 parallelism: 1 693 694 # options that apply to all scan sources 695 source: 696 # alias name for the source 697 # SYFT_SOURCE_NAME env var; --source-name flag 698 name: "" 699 700 # alias version for the source 701 # SYFT_SOURCE_VERSION env var; --source-version flag 702 version: "" 703 704 # options affecting the file source type 705 file: 706 # the file digest algorithms to use on the scanned file (options: "md5", "sha1", "sha224", "sha256", "sha384", "sha512") 707 digests: ["sha256"] 708 709 # options when pulling directly from a registry via the "registry:" or "containerd:" scheme 710 registry: 711 # skip TLS verification when communicating with the registry 712 # SYFT_REGISTRY_INSECURE_SKIP_TLS_VERIFY env var 713 insecure-skip-tls-verify: false 714 715 # use http instead of https when connecting to the registry 716 # SYFT_REGISTRY_INSECURE_USE_HTTP env var 717 insecure-use-http: false 718 719 # filepath to a CA certificate (or directory containing *.crt, *.cert, *.pem) used to generate the client certificate 720 # SYFT_REGISTRY_CA_CERT env var 721 ca-cert: "" 722 723 # credentials for specific registries 724 auth: 725 # the URL to the registry (e.g. "docker.io", "localhost:5000", etc.) 726 # SYFT_REGISTRY_AUTH_AUTHORITY env var 727 - authority: "" 728 729 # SYFT_REGISTRY_AUTH_USERNAME env var 730 username: "" 731 732 # SYFT_REGISTRY_AUTH_PASSWORD env var 733 password: "" 734 735 # note: token and username/password are mutually exclusive 736 # SYFT_REGISTRY_AUTH_TOKEN env var 737 token: "" 738 739 # filepath to the client certificate used for TLS authentication to the registry 740 # SYFT_REGISTRY_AUTH_TLS_CERT env var 741 tls-cert: "" 742 743 # filepath to the client key used for TLS authentication to the registry 744 # SYFT_REGISTRY_AUTH_TLS_KEY env var 745 tls-key: "" 746 747 # - ... # note, more credentials can be provided via config file only (not env vars) 748 749 # generate an attested SBOM 750 attest: 751 # path to the private key file to use for attestation 752 # SYFT_ATTEST_KEY env var 753 key: "cosign.key" 754 755 # password to decrypt to given private key 756 # SYFT_ATTEST_PASSWORD env var, additionally responds to COSIGN_PASSWORD 757 password: "" 758 759 log: 760 # use structured logging 761 # same as SYFT_LOG_STRUCTURED env var 762 structured: false 763 764 # the log level; note: detailed logging suppress the ETUI 765 # same as SYFT_LOG_LEVEL env var 766 level: "error" 767 768 # location to write the log file (default is not to have a log file) 769 # same as SYFT_LOG_FILE env var 770 file: "" 771 ``` 772 773 ### Adding an SBOM to an image as an attestation using Syft 774 775 `syft attest --output [FORMAT] --key [KEY] [SOURCE] [flags]` 776 777 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. 778 779 #### Example attestation 780 Note for the following example replace `docker.io/image:latest` with an image you own. You should also have push access to 781 its remote reference. Replace `$MY_PRIVATE_KEY` with a private key you own or have generated with cosign. 782 783 ```bash 784 syft attest --key $MY_PRIVATE_KEY -o spdx-json docker.io/image:latest > image_latest_sbom_attestation.json 785 cosign attach attestation --attestation image_latest_sbom_attestation.json docker.io/image:latest 786 ``` 787 788 Verify the new attestation exists on your image. 789 790 ```bash 791 cosign verify-attestation --key $MY_PUBLIC_KEY --type spdxjson docker.io/image:latest | jq '.payload | @base64d | .payload | fromjson | .predicate' 792 ``` 793 794 You should see this output along with the attached SBOM: 795 796 ``` 797 Verification for docker.io/image:latest -- 798 The following checks were performed on each of these signatures: 799 - The cosign claims were validated 800 - The signatures were verified against the specified public key 801 - Any certificates were verified against the Fulcio roots. 802 ``` 803 804 Consumers of your image can now trust that the SBOM associated with your image is correct and from a trusted source. 805 806 The SBOM can be piped to Grype: 807 808 809 ```bash 810 cosign verify-attestation --key $MY_PUBLIC_KEY --type spdxjson docker.io/image:latest | jq '.payload | @base64d | .payload | fromjson | .predicate' | grype 811 ```