2020-07-24 00:54:04 +00:00
# syft
2020-10-08 19:45:26 +00:00
[](https://github.com/anchore/syft/actions?query=workflow%3A%22Static+Analysis+%2B+Unit+%2B+Integration%22)
[](https://github.com/anchore/syft/actions?query=workflow%3AAcceptance)
2020-08-10 20:46:12 +00:00
[](https://goreportcard.com/report/github.com/anchore/syft)
[](https://github.com/anchore/syft/releases/latest)
2020-08-10 23:29:19 +00:00
[](https://github.com/anchore/syft/blob/main/LICENSE)
2020-08-10 20:46:12 +00:00
2020-08-04 19:22:34 +00:00
A CLI tool and go library for generating a Software Bill of Materials (SBOM) from container images and filesystems.
2020-08-14 17:58:45 +00:00
2020-08-04 19:22:34 +00:00
**Features**
- Catalog container images and filesystems to discover packages and libraries.
- Supports packages and libraries from various ecosystems (APK, DEB, RPM, Ruby Bundles, Python Wheel/Egg/requirements.txt, JavaScript NPM/Yarn, Java JAR/EAR/WAR, Jenkins plugins JPI/HPI, Go modules)
2020-08-12 18:57:22 +00:00
- Linux distribution identification (supports Alpine, BusyBox, CentOS/RedHat, Debian/Ubuntu flavored distributions)
2020-09-25 14:24:24 +00:00
- Supports Docker and OCI image formats
2020-08-04 19:22:34 +00:00
2020-10-08 19:30:50 +00:00
If you encounter an issue, please [let us know using the issue tracker ](https://github.com/anchore/syft/issues ).
2020-08-11 11:07:55 +00:00
2020-08-04 19:22:34 +00:00
## Getting started
2020-09-25 14:24:24 +00:00
To generate an SBOM for a Docker or OCI image:
2020-08-04 19:22:34 +00:00
```
syft < image >
```
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` :
```
syft < image > --scope all-layers
```
Syft can generate a SBOM from a variety of sources:
```
2020-09-25 14:24:24 +00:00
# catalog a container image archive (from the result of `docker image save ...`, `podman save ...`, or `skopeo copy` commands)
syft path/to/image.tar
2020-08-04 19:22:34 +00:00
# catalog a directory
2020-09-25 14:24:24 +00:00
syft path/to/dir
2020-08-04 19:22:34 +00:00
```
2020-09-25 14:24:24 +00:00
The output format for Syft is configurable as well:
2020-08-04 19:22:34 +00:00
```
2020-09-25 14:24:24 +00:00
syft < image > -o < format >
2020-08-04 19:22:34 +00:00
```
2020-09-25 14:24:24 +00:00
Where the `format` s available are:
- `json` : Use this to get as much information out of Syft as possible!
- `text` : A row-oriented, human-and-machine-friendly output.
- `cyclonedx` : A XML report conforming to the [CycloneDX 1.2 ](https://cyclonedx.org/ ) specification.
- `table` : A columnar summary (default).
2020-08-04 19:22:34 +00:00
## Installation
2020-11-06 18:40:31 +00:00
**Recommended (macOS and Linux)**
2020-08-04 19:22:34 +00:00
```bash
# install the latest version to /usr/local/bin
2020-08-10 23:29:19 +00:00
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin
2020-08-04 19:22:34 +00:00
# install a specific version into a specific dir
2020-10-09 15:04:53 +00:00
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b < SOME_BIN_PATH > < RELEASE_VERSION >
2020-08-04 19:22:34 +00:00
```
2020-11-06 18:40:31 +00:00
**Homebrew (macOS)**
2020-08-04 19:22:34 +00:00
```bash
brew tap anchore/syft
brew install syft
```
## Configuration
Configuration search paths:
- `.syft.yaml`
- `.syft/config.yaml`
- `~/.syft.yaml`
- `<XDG_CONFIG_HOME>/syft/config.yaml`
Configuration options (example values are the default):
```yaml
2020-12-10 03:20:53 +00:00
# the output format of the SBOM report (options: table, text, json)
# same as -o ; SYFT_OUTPUT env var
2020-08-04 19:22:34 +00:00
output: "table"
2020-12-10 03:20:53 +00:00
# suppress all output (except for the SBOM report)
# same as -q ; SYFT_QUIET env var
2020-08-04 19:22:34 +00:00
quiet: false
2020-12-10 03:20:53 +00:00
# enable/disable checking for application updates on startup
# same as SYFT_CHECK_FOR_APP_UPDATE env var
check-for-app-update: true
2021-03-18 12:53:31 +00:00
packages:
# the search space to look for packages (options: all-layers, squashed)
# same as -s ; SYFT_SCOPE env var
scope: "squashed"
file-metadata:
# enable/disable cataloging if file metadata
cataloging-enabled: true
# the search space to look for file metadata (options: all-layers, squashed)
scope: "squashed"
# the file digest algorithms to use when cataloging files (options: "sha256", "md5", "sha1")
digests: ["sha256"]
2020-08-04 19:22:34 +00:00
log:
# use structured logging
2020-12-10 03:20:53 +00:00
# same as SYFT_LOG_STRUCTURED env var
2020-08-04 19:22:34 +00:00
structured: false
# the log level; note: detailed logging suppress the ETUI
2020-12-10 03:20:53 +00:00
# same as SYFT_LOG_LEVEL env var
2020-08-04 19:22:34 +00:00
level: "error"
# location to write the log file (default is not to have a log file)
2020-12-10 03:20:53 +00:00
# same as SYFT_LOG_FILE env var
2020-08-04 19:22:34 +00:00
file: ""
2020-12-10 03:20:53 +00:00
anchore:
# (feature-preview) the Anchore Enterprise Host or URL to upload results to (supported on Enterprise 3.0+)
# same as -H ; SYFT_ANCHORE_HOST env var
host: ""
# (feature-preview) the path after the host to the Anchore External API (supported on Enterprise 3.0+)
# same as SYFT_ANCHORE_PATH env var
path: ""
# (feature-preview) the username to authenticate against Anchore Enterprise (supported on Enterprise 3.0+)
# same as -u ; SYFT_ANCHORE_USERNAME env var
username: ""
# (feature-preview) the password to authenticate against Anchore Enterprise (supported on Enterprise 3.0+)
# same as -p ; SYFT_ANCHORE_PASSWORD env var
password: ""
2020-08-11 11:07:55 +00:00
2020-12-10 03:20:53 +00:00
# (feature-preview) path to dockerfile to be uploaded with the syft results to Anchore Enterprise (supported on Enterprise 3.0+)
# same as -d ; SYFT_ANCHORE_DOCKERFILE env var
dockerfile: ""
2020-08-11 11:07:55 +00:00
2020-12-10 03:20:53 +00:00
```
