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

chore: Update vet Documentation
safedep · Apr 2, 2024 · d3c0d7c · d3c0d7c
2 parents b5c2b14 + ebe5411
commit d3c0d7c
Show file tree

Hide file tree

Showing 8 changed files with 165 additions and 135 deletions.
diff --git a/CONTRIBUTING.md 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
@@ -0,0 +1,9 @@
+vet is built and maintained by SafeDep with the help of the community.
+https://safedep.io
+
+Abhisek Datta
+	Email: [email protected]
+	GitHub username: @abhisek
+	Affiliation: SafeDep
+
+
diff --git 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,52 +62,46 @@ 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
 ```
 
 ![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
 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,83 +148,53 @@ vet scan --purl pkg:/gem/[email protected]
 
 #### 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
 
 [![Star History Chart](https://api.star-history.com/svg?repos=safedep/vet&type=Date)](https://star-history.com/#safedep/vet&Date)
 
 ## 🔖 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
@@ -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
@@ -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
-Original file line number
+Diff line change
@@ Expand Up / @@ -80,7 +80,6 @@ func configureAuthCommand() *cobra.Command { @@
     		"Use community API endpoint for Insights")
     	return cmd
     }
     func verifyAuthCommand() *cobra.Command {
@@ Expand Down @@