From 4b7217f0523d72ab2e2952ac3d849d0f830eec17 Mon Sep 17 00:00:00 2001 From: Dan Luhring Date: Mon, 4 Oct 2021 09:29:27 -0400 Subject: [PATCH] Improve documentation (#525) * Make installation methods more obvious Signed-off-by: Dan Luhring * Create linkable section headers Signed-off-by: Dan Luhring * Add badge for joining Slack Signed-off-by: Dan Luhring * Document requirement for signed commits Signed-off-by: Dan Luhring --- CONTRIBUTING.md | 17 +++++++++++------ README.md | 48 ++++++++++++++++++++++++++++++------------------ 2 files changed, 41 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5ec28ec1f..81eeee7b4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,12 @@ -# Contributing to `syft` +# Contributing to Syft -If you are looking to contribute to this project and want to open a Github pull request ("PR"), there are a few guidelines of what we are looking for in patches. Make sure you go through this document and ensure that your code proposal is aligned. +If you are looking to contribute to this project and want to open a GitHub pull request ("PR"), there are a few guidelines of what we are looking for in patches. Make sure you go through this document and ensure that your code proposal is aligned. -## Sign your work +## Sign off your work The `sign-off` is an added line at the end of the explanation for the commit, certifying that you wrote it or otherwise have the right to submit it as an open-source patch. By submitting a contribution, you agree to be bound by the terms of the DCO Version 1.1 and Apache License Version 2.0. -Signing a commit certifies the below Developer's Certificate of Origin (DCO): +Signing off a commit certifies the below Developer's Certificate of Origin (DCO): ```text Developer's Certificate of Origin 1.1 @@ -51,13 +51,13 @@ $ git config --global user.name "John Doe" $ git config --global user.email "john.doe@example.com" ``` -Creating a signed commit is then possible with `-s`: +Creating a signed-off commit is then possible with `-s` or `--signoff`: ```text $ git commit -s -m "this is a commit message" ``` -To double check if the commit was signed, look at the log output: +To double-check that the commit was signed-off, look at the log output: ```text $ git log -1 @@ -82,6 +82,11 @@ Date: Mon Aug 1 11:27:13 2020 -0400 [//]: # (TODO: PR title and description) +## Sign your commits + +To ensure the authenticity and integrity of code contributions, **we require that all commits are signed**. Signing commits proves that your commits were truly created by you, as the holder of a private key. + +Configuring git to sign your commits is a straightforward process. To get set up, see [GitHub's documentation on signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits). ## Test your changes diff --git a/README.md b/README.md index bf969f131..9d5e81dd7 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,9 @@ [![Validations](https://github.com/anchore/syft/actions/workflows/validations.yaml/badge.svg)](https://github.com/anchore/syft/actions/workflows/validations.yaml) [![Go Report Card](https://goreportcard.com/badge/github.com/anchore/syft)](https://goreportcard.com/report/github.com/anchore/syft) [![GitHub release](https://img.shields.io/github/release/anchore/syft.svg)](https://github.com/anchore/syft/releases/latest) -[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/anchore/syft/blob/main/LICENSE) [![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/anchore/syft.svg)](https://github.com/anchore/syft) +[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/anchore/syft/blob/main/LICENSE) +[![Slack Invite](https://img.shields.io/badge/Slack-Join-blue?logo=slack)](https://anchore.com/slack) 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 tool like [Grype](https://github.com/anchore/grype). @@ -28,6 +29,27 @@ We’ll have free swag, giveaways, snacks, and sips. Space will be limited, so m If you encounter an issue, please [let us know using the issue tracker](https://github.com/anchore/syft/issues). +## Installation + +### Recommended +```bash +curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin +``` + +...or, you can specify a release version and destination directory for the installation: + +``` +curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b +``` + +### Homebrew +```bash +brew tap anchore/syft +brew install syft +``` + +**Note**: Currently, Syft is built only for macOS and Linux. + ## Getting started To generate an SBOM for a Docker or OCI image: @@ -47,7 +69,10 @@ To include software from all image layers in the SBOM, regardless of its presenc syft packages --scope all-layers ``` +### Supported sources + Syft can generate a SBOM from a variety of sources: + ``` # catalog a container image archive (from the result of `docker image save ...`, `podman save ...`, or `skopeo copy` commands) syft packages path/to/image.tar @@ -57,6 +82,7 @@ syft packages path/to/dir ``` Sources can be explicitly provided with a scheme: + ``` docker:yourrepo/yourimage:tag use images from the Docker daemon docker-archive:path/to/yourimage.tar use a tarball from disk for archives created from "docker save" @@ -66,7 +92,10 @@ dir:path/to/yourproject read directly from a path on disk (any di registry:yourrepo/yourimage:tag pull image directly from a registry (no container runtime required) ``` +### Output formats + The output format for Syft is configurable as well: + ``` syft packages -o ``` @@ -79,23 +108,6 @@ Where the `format`s available are: - `spdx-json`: A JSON report conforming to the [SPDX 2.2 JSON Schema](https://github.com/spdx/spdx-spec/blob/v2.2/schemas/spdx-schema.json). - `table`: A columnar summary (default). -## Installation - -**Recommended (macOS and Linux)** -```bash -# install the latest version to /usr/local/bin -curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin - -# install a specific version into a specific dir -curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b -``` - -**Homebrew (macOS)** -```bash -brew tap anchore/syft -brew install syft -``` - ## Configuration Configuration search paths: