Merge pull request #199 from safedep/refactor/docs-2024-04-02

chore: Update vet Documentation

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 ./...
+```
+
+
+

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
+
+

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
+goes beyond just vulnerabilities and provides visibility on OSS package risks
-source dependencies and evaluate them against organizational policies.
+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.
+> **Note:** Container image is built for x86_64 Linux only. Use a
-
+> [pre-built binary](https://github.com/safedep/vet/releases) or
-- You can verify the configured key is successful by running the following command
+> build from source for other platforms.
-
-```bash
-vet auth verify
-```
 
 ### 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,12 +148,28 @@ 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
 ```
 
+## CI/CD Integration
+
+### 📦 GitHub Action
+
+- `vet` is available as a GitHub Action, refer to [vet-action](https://github.com/safedep/vet-action)
+
+### 🚀 GitLab CI
+
+- `vet` can be integrated with GitLab CI, refer to [vet-gitlab-ci](https://docs.safedep.io/integrations/gitlab-ci)
+
+## 🛠️ Advanced Usage
+
+- [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)
+
 ## 📖 Documentation
 
 - Refer to [https://safedep.io/docs](https://safedep.io/docs) for the detailed documentation
@@ -149,62 +180,13 @@ vet scan parsers --experimental
 
 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)
+- Join the Discord 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
+Refer to [CONTRIBUTING.md](CONTRIBUTING.md)
-
-* Go 1.21+
-
-### Setup
-
-* 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 ./...
-```
 
 ## 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/

auth.go

@@ -80,7 +80,6 @@ func configureAuthCommand() *cobra.Command {
 		"Use community API endpoint for Insights")
 
 	return cmd
-
 }
 
 func verifyAuthCommand() *cobra.Command {

docs/docs/installation.mdx

@@ -28,19 +28,19 @@ import TabItem from '@theme/TabItem';
 
 <TabItem value="linux">
   <code>
-    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
   </code>
 </TabItem>
 
 <TabItem value="macm">
   <code>
-    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
   </code>
 </TabItem>
 
 <TabItem value="maci">
   <code>
-    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
   </code>
 </TabItem>
 
@@ -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

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

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 {

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. "+
+			auth.SetRuntimeCommunityMode()
-				"You may want to setup community mode using: vet auth configure --community", err))
 		}
 	}