diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..7398c7c3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,86 @@ +# Contributing Guide + +You can contribute to `vet` and help make it better. Apart from bug fixes, +features, we particularly value contributions in the form of: + +- Documentation improvements +- Bug reports +- Using `vet` in your projects and providing feedback + +## How to contribute + +1. Fork the repository +2. Add your changes +3. Submit a pull request + +## How to report a bug + +Create a new issue and add the label "bug". + +## How to suggest a new feature + +Create a new issue and add the label "enhancement". + +## Development workflow + +When contributing changes to repository, follow these steps: + +1. Ensure tests are passing +2. Ensure you write test cases for new code +3. `Signed-off-by` line is required in commit message (use `-s` flag while committing) + +## Developer Setup + +### Requirements + +* Go 1.22+ + +### Install Dependencies + +* Install [ASDF](https://asdf-vm.com/) +* Install the development tools + +```bash +asdf install +``` + +* Install `lefthook` + +```bash +go install github.com/evilmartians/lefthook@latest +``` + +* Install git hooks + +```bash +$(go env GOPATH)/bin/lefthook install +``` + +### Build + +Install build tools + +```bash +make dev-setup +``` + +Generate code from API specs and build `vet` + +```bash +make +``` + +Quick build without regenerating code from API specs + +```bash +make quick-vet +``` + +### Run Tests + +```bash +go test -v ./... +``` + + + diff --git a/MAINTAINERS.txt b/MAINTAINERS.txt new file mode 100644 index 00000000..fa5123e3 --- /dev/null +++ b/MAINTAINERS.txt @@ -0,0 +1,9 @@ +vet is built and maintained by SafeDep with the help of the community. +https://safedep.io + +Abhisek Datta + Email: abhisek@safedep.io + GitHub username: @abhisek + Affiliation: SafeDep + + diff --git a/README.md b/README.md index dc7addb2..a76f86c6 100644 --- a/README.md +++ b/README.md @@ -15,11 +15,32 @@ [![Twitter](https://img.shields.io/twitter/follow/safedepio?style=social)](https://twitter.com/intent/follow?screen_name=safedepio) [![vet banner](docs/static/img/vet/vet-banner.png)](https://safedep.io/docs) + ## Automate Open Source Package Vetting in CI/CD `vet` is a tool for identifying risks in open source software supply chain. It -helps engineering and security teams to identify potential issues in their open -source dependencies and evaluate them against organizational policies. +goes beyond just vulnerabilities and provides visibility on OSS package risks +due to it's license, popularity, security hygiene, and more. `vet` is designed +with the goal of enabling trusted OSS package consumption by integrating with +CI/CD and `policy as code` as guardrails. + +* [🔥 vet in action](#-vet-in-action) +* [Getting Started](#getting-started) + * [Running Scan](#running-scan) + * [Scanning SBOM](#scanning-sbom) + * [Scanning Github Repositories](#scanning-github-repositories) + * [Scanning Github Organization](#scanning-github-organization) + * [Scanning Package URL](#scanning-package-url) + * [Available Parsers](#available-parsers) +* [CI/CD Integration](#ci/cd-integration) + * [📦 GitHub Action](#-github-action) + * [🚀 GitLab CI](#-gitlab-ci) +* [🛠️ Advanced Usage](#-advanced-usage) +* [📖 Documentation](#-documentation) +* [🎊 Community](#-community) +* [💻 Development](#-development) +* [Star History](#star-history) +* [🔖 References](#-references) ## 🔥 vet in action @@ -41,26 +62,22 @@ brew install safedep/tap/vet > Ensure $(go env GOPATH)/bin is in your $PATH ```bash -go install github.com/safedep/vet@main +go install github.com/safedep/vet@latest ``` -- Configure `vet` to use community mode for Insights API +- Also available as a container image ```bash -vet auth configure --community +docker run --rm -it ghcr.io/safedep/vet:latest version ``` -> Insights API is used to enrich OSS packages with metadata for rich query and policy decisions. - -- You can verify the configured key is successful by running the following command - -```bash -vet auth verify -``` +> **Note:** Container image is built for x86_64 Linux only. Use a +> [pre-built binary](https://github.com/safedep/vet/releases) or +> build from source for other platforms. ### Running Scan -- Run `vet` to identify risks +- Run `vet` to identify risks by scanning a directory ```bash vet scan -D /path/to/repository @@ -68,7 +85,7 @@ vet scan -D /path/to/repository ![vet scan directory](docs/static/img/vet/vet-scan-directory.png) -- You can also scan a specific (supported) package manifest +- Run `vet` to scan specific (supported) package manifests ```bash vet scan --lockfiles /path/to/pom.xml @@ -76,17 +93,15 @@ vet scan --lockfiles /path/to/requirements.txt vet scan --lockfiles /path/to/package-lock.json ``` -> [Example Security Gate](https://github.com/safedep/demo-client-java/pull/2) using `vet` to prevent introducing new OSS dependency risk in an application. - #### Scanning SBOM -- To scan an SBOM in [CycloneDX](https://cyclonedx.org/) format +- Scan an SBOM in [CycloneDX](https://cyclonedx.org/) format ```bash vet scan --lockfiles /path/to/cyclonedx-sbom.json --lockfile-as bom-cyclonedx ``` -- To scan an SBOM in [SPDX](https://spdx.dev/) format +- Scan an SBOM in [SPDX](https://spdx.dev/) format ```bash vet scan --lockfiles /path/to/spdx-sbom.json --lockfile-as bom-spdx @@ -133,78 +148,45 @@ vet scan --purl pkg:/gem/nokogiri@1.10.4 #### Available Parsers -- To list supported package manifest parsers including experimental modules +- List supported package manifest parsers including experimental modules ```bash vet scan parsers --experimental ``` -## 📖 Documentation - -- Refer to [https://safedep.io/docs](https://safedep.io/docs) for the detailed documentation - -[![vet docs](docs/static/img/vet-docs.png)](https://safedep.io/docs) - -## 🎊 Community - -First of all, thank you so much for showing interest in `vet`, we appreciate it ❤️ - -- Join the server using the link - [https://rebrand.ly/safedep-community](https://rebrand.ly/safedep-community) - -[![SafeDep Discord](docs/static/img/safedep-discord.png)](https://rebrand.ly/safedep-community) - -## 💻 Development - -## Requirements - -* Go 1.21+ +## CI/CD Integration -### Setup +### 📦 GitHub Action -* Install [ASDF](https://asdf-vm.com/) -* Install the development tools +- `vet` is available as a GitHub Action, refer to [vet-action](https://github.com/safedep/vet-action) -```bash -asdf install -``` +### 🚀 GitLab CI -* Install `lefthook` +- `vet` can be integrated with GitLab CI, refer to [vet-gitlab-ci](https://docs.safedep.io/integrations/gitlab-ci) -```bash -go install github.com/evilmartians/lefthook@latest -``` +## 🛠️ Advanced Usage -* Install git hooks +- [Threat Hunting with vet](https://docs.safedep.io/advanced/filtering) +- [Policy as Code](https://docs.safedep.io/advanced/polic-as-code) +- [Exceptions and Overrides](https://docs.safedep.io/advanced/exceptions) -```bash -$(go env GOPATH)/bin/lefthook install -``` - -### Build +## 📖 Documentation -Install build tools +- Refer to [https://safedep.io/docs](https://safedep.io/docs) for the detailed documentation -```bash -make dev-setup -``` +[![vet docs](docs/static/img/vet-docs.png)](https://safedep.io/docs) -Generate code from API specs and build `vet` +## 🎊 Community -```bash -make -``` +First of all, thank you so much for showing interest in `vet`, we appreciate it ❤️ -Quick build without regenerating code from API specs +- Join the Discord server using the link - [https://rebrand.ly/safedep-community](https://rebrand.ly/safedep-community) -```bash -make quick-vet -``` +[![SafeDep Discord](docs/static/img/safedep-discord.png)](https://rebrand.ly/safedep-community) -### Run Tests +## 💻 Development -```bash -go test -v ./... -``` +Refer to [CONTRIBUTING.md](CONTRIBUTING.md) ## Star History @@ -212,4 +194,7 @@ go test -v ./... ## 🔖 References -- [https://github.com/google/osv-scanner](https://github.com/google/osv-scanner) +- https://github.com/google/osv-scanner +- https://deps.dev/ +- https://securityscorecards.dev/ +- https://slsa.dev/ diff --git a/auth.go b/auth.go index fbcc8658..b8a9f911 100644 --- a/auth.go +++ b/auth.go @@ -80,7 +80,6 @@ func configureAuthCommand() *cobra.Command { "Use community API endpoint for Insights") return cmd - } func verifyAuthCommand() *cobra.Command { diff --git a/docs/docs/installation.mdx b/docs/docs/installation.mdx index ff887933..251488a4 100644 --- a/docs/docs/installation.mdx +++ b/docs/docs/installation.mdx @@ -28,19 +28,19 @@ import TabItem from '@theme/TabItem'; - curl -L https://github.com/safedep/vet/releases/download/v0.0.7-dev/vet_Linux_x86_64.tar.gz -o vet.tar.gz + curl -L https://github.com/safedep/vet/releases/download/v1.5.8/vet_Linux_x86_64.tar.gz -o vet.tar.gz - curl -L https://github.com/safedep/vet/releases/download/v0.0.7-dev/vet_Darwin_arm64.tar.gz -o vet.tar.gz + curl -L https://github.com/safedep/vet/releases/download/v1.5.8/vet_Darwin_arm64.tar.gz -o vet.tar.gz - curl -L https://github.com/safedep/vet/releases/download/v0.0.7-dev/vet_Darwin_x86_64.tar.gz -o vet.tar.gz + curl -L https://github.com/safedep/vet/releases/download/v1.5.8/vet_Darwin_x86_64.tar.gz -o vet.tar.gz @@ -54,7 +54,7 @@ import TabItem from '@theme/TabItem'; - Unpack the downloaded archive using the following command `tar -xvzf vet.tar.gz` - Make sure the binary has execution bit turned on `chmod +x ./vet` -- Move the binary in your system $PATH `mv ./vet /usr/local/bin/` +- Move the binary in your system $PATH `mv ./vet /usr/local/bin/` :::tip @@ -81,7 +81,7 @@ go install github.com/safedep/vet@latest - For scanning using vet container us the following command. Make sure to replace the `yourcode-in-host` with your local code directory which needs to be scanned ```bash -docker run --rm -it -v yourcode-in-host:/code -e VET_API_KEY=YOUR_API_KEY ghcr.io/safedep/vet scan -D /code +docker run --rm -it -v yourcode-in-host:/code ghcr.io/safedep/vet scan -D /code ``` ## Install using Package Manager @@ -102,26 +102,6 @@ brew update brew upgrade safedep/tap/vet ``` -### RHEL/CentOS - -TBD - -### Debian/Ubuntu - -TBD - -### Arch Linux - -TBD - -### MacPorts - -TBD - -### Nix/NixOS - -TBD - ## Install from source - You can install the vet from the source by cloning the official repository and building locally diff --git a/docs/docs/quick-start.md b/docs/docs/quick-start.md index 98bc368a..a0eb952a 100644 --- a/docs/docs/quick-start.md +++ b/docs/docs/quick-start.md @@ -9,42 +9,6 @@ title: 🚀 Quick Start ![vet Github Releases](/img/vet/vet-github-releases.png) -- Get an API key for the vet insights data access for performing the scan. - Alternatively, look at [configuration options](configure.md) for - instruction on using community mode without API key. - -```bash -vet auth trial --email john.doe@example.com -``` - -![vet register trial](/img/vet/vet-register-trial.png) - -:::info - -A time limited trial API key will be sent over email. - -::: - -- Configure `vet` to use API key to access the insights - -```bash -vet auth configure -``` - -![vet configure](/img/vet/vet-configure.png) - -:::tip - -Insights API is used to enrich OSS packages with metadata for rich query and policy decisions. Alternatively, the API key can be passed through environment variable `VET_API_KEY` - -::: - -- You can verify the configured key is successful by running the following command - -```bash -vet auth verify -``` - - Run `vet` to identify risks ```bash diff --git a/internal/auth/auth.go b/internal/auth/auth.go index 9c8cf5fc..cba8bbee 100644 --- a/internal/auth/auth.go +++ b/internal/auth/auth.go @@ -112,6 +112,12 @@ func CommunityMode() bool { return false } +// Set the runtime mode to community without +// persisting it to the configuration file +func SetRuntimeCommunityMode() { + os.Setenv(communityModeEnvKey, "true") +} + func loadConfiguration() error { path, err := os.UserHomeDir() if err != nil { diff --git a/scan.go b/scan.go index 5a18d0af..268c90f2 100644 --- a/scan.go +++ b/scan.go @@ -170,9 +170,10 @@ func startScan() { ControlPlaneApiUrl: auth.DefaultControlPlaneApiUrl(), }) + // We will fallback to community mode by default to provide + // a seamless user experience if err != nil { - failOnError("auth/verify", fmt.Errorf("failed to verify auth token: %v. "+ - "You may want to setup community mode using: vet auth configure --community", err)) + auth.SetRuntimeCommunityMode() } }