mirror of
https://github.com/safedep/vet.git
synced 2025-12-10 00:22:08 -06:00
Updated vet README.md
This commit is contained in:
Madhu Akula
parent
bf2dbe0f1b
commit
abf6e71499
197
README.md
197
README.md
@ -1,77 +1,62 @@
|
||||
# vet
|
||||
<h1 align="center">
|
||||
vet
|
||||
</h1>
|
||||
<p align="center">
|
||||
🙌 Refer to <b><a href="https://safedep.io/docs/">https://safedep.io/docs</a></b> for the documentation 📖
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
[](https://api.securityscorecards.dev/projects/github.com/safedep/vet)
|
||||
[](https://github.com/safedep/vet/actions/workflows/codeql.yml)
|
||||
[](https://github.com/safedep/vet/actions/workflows/scorecard.yml)
|
||||
|
||||
**🙌 Refer to [https://safedep.io/docs](https://safedep.io/docs) for the documentation 📖**
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
[](https://api.securityscorecards.dev/projects/github.com/safedep/vet)
|
||||
[](https://github.com/safedep/vet/actions/workflows/codeql.yml)
|
||||
[](https://github.com/safedep/vet/actions/workflows/scorecard.yml)
|
||||
## 🔥 vet in action
|
||||
|
||||
## Demo
|
||||
|
||||
|
||||
|
||||
## TL;DR
|
||||
|
||||
Scan a repository for OSS dependency risks with auto-detection of package
|
||||
manifests
|
||||
|
||||
```bash
|
||||
vet scan -D /path/to/repo
|
||||
```
|
||||
|
||||
|
||||
|
||||
[Example Security Gate](https://github.com/safedep/demo-client-java/pull/2)
|
||||
using `vet` to prevent introducing new OSS dependency risk in an application.
|
||||
|
||||
|
||||
## Getting Started
|
||||
|
||||
> Ensure `$(go env GOPATH)/bin` is in your `$PATH`
|
||||
- Download the binary file for your operating system/architecture from the [Official GitHub Releases](https://github.com/safedep/vet/releases)
|
||||
|
||||
Install using `go get`
|
||||
|
||||
```bash
|
||||
go install github.com/safedep/vet@latest
|
||||
```
|
||||
|
||||
Alternatively, look at [Releases](https://github.com/safedep/vet/releases) for
|
||||
a pre-built binary for your platform. [SLSA Provenance](https://slsa.dev/provenance/v0.1) is published
|
||||
along with each binary release.
|
||||
|
||||
Get an API key for [Insights API](https://safedep.io/docs/concepts/raya-data-platform-overview) access
|
||||
- Get an API key for the vet insights data access for performing the scan
|
||||
|
||||
```bash
|
||||
vet auth trial --email john.doe@example.com
|
||||
```
|
||||
|
||||
> A time limited API key will be sent over email.
|
||||
|
||||
|
||||
Configure `vet` to use API Key to access [Insights API](https://safedep.io/docs/concepts/raya-data-platform-overview)
|
||||
> 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
|
||||
```
|
||||
|
||||
> 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`
|
||||
|
||||
|
||||
Verify authentication token is valid
|
||||
> 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`
|
||||
|
||||
```bash
|
||||
vet auth verify
|
||||
```
|
||||
|
||||
Run `vet` to identify risks in a source repository
|
||||
- Run `vet` to identify risks
|
||||
|
||||
```bash
|
||||
vet scan -D /path/to/repository
|
||||
```
|
||||
|
||||
or scan a specific (supported) package manifest
|
||||
|
||||
|
||||
- You can also scan a specific (supported) package manifest
|
||||
|
||||
```bash
|
||||
vet scan --lockfiles /path/to/pom.xml
|
||||
@ -79,125 +64,23 @@ vet scan --lockfiles /path/to/requirements.txt
|
||||
vet scan --lockfiles /path/to/package-lock.json
|
||||
```
|
||||
|
||||
or scan a supported package manifest with a non-standard name
|
||||
> [Example Security Gate](https://github.com/safedep/demo-client-java/pull/2) using `vet` to prevent introducing new OSS dependency risk in an application.
|
||||
|
||||
```bash
|
||||
vet scan --lockfiles /path/to/gradle-compileOnly.lock --lockfile-as gradle.lockfile
|
||||
```
|
||||
|
||||
> Use `vet scan parsers` to list supported package manifest parsers
|
||||
## 📖 Documentation
|
||||
|
||||
The default scan uses an opinionated [Summary Reporter](#) which presents
|
||||
a consolidated summary of findings. Thats NOT about it. Read more for
|
||||
expression based filtering and policy evaluation.
|
||||
- Refer to [https://safedep.io/docs](https://safedep.io/docs) for the detailed documentation
|
||||
|
||||
## Policy Control
|
||||
[](https://safedep.io/docs)
|
||||
|
||||
Policies are written using a DSL. A group of policies can be applied using
|
||||
`vet` to build a security gate in CI/CD.
|
||||
## 🎊 Community
|
||||
|
||||
Start by copying a sample policy
|
||||
First of all, thank you so much for showing interest in `vet`, we appreciate it ❤️
|
||||
|
||||
```bash
|
||||
curl -LO https://raw.githubusercontent.com/safedep/vet/main/samples/filter-suites/fs-generic.yml
|
||||
```
|
||||
- Join the server using the link - [https://rebrand.ly/safedep-community](https://rebrand.ly/safedep-community)
|
||||
|
||||
Run a scan with policies and configure the scanner to fail in case of policy
|
||||
violation
|
||||
[](https://rebrand.ly/safedep-community)
|
||||
|
||||
```bash
|
||||
vet scan -D /path/to/dir --filter-suite fs-generic.yml --filter-fail
|
||||
```
|
||||
|
||||
Read more about underlying capability using which policy control is implemented
|
||||
in [filtering guide](docs/filtering.md)
|
||||
|
||||
## Exceptions Management
|
||||
|
||||
Projects may have legacy libraries that will fail any reasonable security policy.
|
||||
Legacy libraries can be added as time bounded exceptions to the policies to place
|
||||
strict control on any new library while legacy library can be upgraded over
|
||||
time.
|
||||
|
||||
Exception rules can be generated using the `query` workflow to temporarily
|
||||
ignore (or snooze) existing issues when using `vet` for the first time. This
|
||||
helps in establishing security gating to prevent introduction of new security
|
||||
issues while existing issues are being remediated.
|
||||
|
||||
Use exception rules during scan to ignore specific packages
|
||||
|
||||
```bash
|
||||
vet scan -D /path/to/repo -e /path/to/exceptions.yml
|
||||
```
|
||||
|
||||
For more information on generating exceptions,
|
||||
refer to [exceptions guide](docs/exceptions.md)
|
||||
|
||||
The generated exceptions file, when combined with policy control, can be used
|
||||
to setup a security gate to prevent introducing new issues while ignoring the
|
||||
existing backlog for a period of time.
|
||||
|
||||
```bash
|
||||
vet scan -D /path/to/dir \
|
||||
--filter-suite fs-generic.yml --filter-fail
|
||||
-e /path/to/exceptions.yml
|
||||
```
|
||||
|
||||
## Exploring OSS Risks using Filters
|
||||
|
||||
Find dependencies that seems not very popular
|
||||
|
||||
```bash
|
||||
vet scan --lockfiles /path/to/pom.xml --report-summary=false \
|
||||
--filter='projects.exists(x, x.stars < 10)'
|
||||
```
|
||||
|
||||
Find dependencies with a critical vulnerability
|
||||
|
||||
```bash
|
||||
vet scan --lockfiles /path/to/pom.xml --report-summary=false \
|
||||
--filter='vulns.critical.exists_one(x, true)'
|
||||
```
|
||||
|
||||
> Use filtering along with `query` command for offline slicing and dicing of
|
||||
> enriched package manifests. Read [filtering guide](docs/filtering.md)
|
||||
|
||||
Learn more about [filtering with vet](docs/filtering.md).
|
||||
Look at [filter input spec](api/filter_input_spec.proto) on attributes
|
||||
available to the filter expression.
|
||||
|
||||
## FAQ
|
||||
|
||||
### How do I disable the stupid banner?
|
||||
|
||||
Set environment variable `VET_DISABLE_BANNER=1`
|
||||
|
||||
### Can I use this tool without an API Key for Insight Service?
|
||||
|
||||
Probably no. All useful data (enrichments) for a detected package comes from
|
||||
a backend service. The service is rate limited with quotas to prevent abuse.
|
||||
|
||||
Look at `api/insights-v1.yml`. It contains the contract expected for Insights
|
||||
API. You can perhaps consider rolling out your own to avoid dependency with our
|
||||
backend.
|
||||
|
||||
### Something is wrong! How do I debug this thing?
|
||||
|
||||
Run without the eye candy UI and enable log to file or to `stdout`.
|
||||
|
||||
Log to `stdout`:
|
||||
|
||||
```bash
|
||||
vet scan -D /path/to/repo -s -l- -v
|
||||
```
|
||||
|
||||
Log to file:
|
||||
|
||||
```bash
|
||||
vet scan -D /path/to/repo -l /tmp/vet.log -v
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
* https://github.com/google/osv-scanner
|
||||
## 🔖 References
|
||||
|
||||
- [https://github.com/google/osv-scanner](https://github.com/google/osv-scanner)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user