Created and maintained by https://safedep.io with contributions from the community 🚀

🔍 vet

vet is a tool for protecting against open source software supply chain attacks. To adapt to organizational needs, it uses an opinionated policy expressed as Common Expressions Language and extensive package security metadata including

• Code Analysis to guard against risks that actually matter
• Vulnerabilities from OSV
• Popularity based guardrails to prevent unvetted or risky packages
• Maintenance status of the package
• Extended License Attributes based compliance
• OpenSSF Scorecard based 3rd party OSS risk management
• Direct and Transitive dependency analysis for coverage

🐞 Malicious Code Analysis

vet is integrated with SafeDep Cloud for real time protection against malicious open source packages through active code scanning and analysis. vet-action seamlessly integrates vet in GitHub Action for proactive guardrails against malicious code from open sources.

🎯 Policy as Code

vet is built for users who intend to enforce guardrails against open source supply chain attacks using their opinionated policies. Security guardrails can be built by expressing policies as CEL which vet enforces in CI/CD.

🔥 vet in action

🚀 Let's go!

• 🔍 vet
  • 🐞 Malicious Code Analysis
  • 🎯 Policy as Code
  • 🔥 vet in action
• 🚀 Let's go!
  • Getting Started
    • Running Scan
      • Scanning Binary Artifacts
      • Scanning SBOM
      • Scanning Github Repositories
      • Scanning Github Organization
      • Scanning Package URL
      • Available Parsers
  • Policy as Code
    • Vulnerability
    • License
    • Scorecard
  • Query Mode
  • Reporting
  • CI/CD Integration
    • 📦 GitHub Action
    • 🚀 GitLab CI
  • 🐙 Malicious Package Analysis
    • 🔍 Scanning Visual Studio Code Extensions
    • 🔍 Scanning GitHub Actions (or any other GitHub repository)
  • 🛠️ Advanced Usage
  • 📖 Documentation
  • 🎊 Community
  • 💻 Development
  • Support
  • Star History
  • 🔖 References

Getting Started

• Download the binary file for your operating system / architecture from the Official GitHub Releases

• You can also install vet using homebrew in MacOS and Linux

brew tap safedep/tap
brew install safedep/tap/vet

• Alternatively, build from source

Ensure $(go env GOPATH)/bin is in your $PATH

go install github.com/safedep/vet@latest

• Also available as a container image

docker run --rm -it ghcr.io/safedep/vet:latest version

Note: Container image is built for x86_64 Linux only. Use a pre-built binary or build from source for other platforms.

Running Scan

• Run vet to identify risks by scanning a directory

vet scan -D /path/to/repository

• Run vet to scan specific (supported) package manifests

vet scan -M /path/to/pom.xml
vet scan -M /path/to/requirements.txt
vet scan -M /path/to/package-lock.json

Note: --lockfiles is generalized to -M or --manifests to support additional types of package manifests or other artifacts in future.

Scanning Binary Artifacts

• Scan a Java JAR file

vet scan -M /path/to/app.jar

Suitable for scanning bootable JARs with embedded dependencies

• Scan a directory with JAR files

vet scan -D /path/to/jars --type jar

Scanning SBOM

• Scan an SBOM in CycloneDX format

vet scan -M /path/to/cyclonedx-sbom.json --type bom-cyclonedx

• Scan an SBOM in SPDX format

vet scan -M /path/to/spdx-sbom.json --type bom-spdx

Note: --type is a generalized version of --lockfile-as to support additional artifact types in future.

Note: SBOM scanning feature is currently in experimental stage

Scanning Github Repositories

• Setup github access token to scan private repo

vet connect github

Alternatively, set GITHUB_TOKEN environment variable with Github PAT

• To scan remote Github repositories, including private ones

vet scan --github https://github.com/safedep/vet

Note: You may need to enable Dependency Graph at repository or organization level for Github repository scanning to work.

Scanning Github Organization

You must setup the required access for scanning private repositories before scanning organizations

vet scan --github-org https://github.com/safedep

Note: vet will block and wait if it encounters Github secondary rate limit.

Scanning Package URL

• To scan a purl

vet scan --purl pkg:/gem/[email protected]

Available Parsers

• List supported package manifest parsers including experimental modules

vet scan parsers --experimental

Policy as Code

vet uses Common Expressions Language (CEL) as the policy language. Policies can be defined to build guardrails preventing introduction of insecure components.

Vulnerability

• Run vet and fail if a critical or high vulnerability was detected

vet scan -D /path/to/code \
    --filter 'vulns.critical.exists(p, true) || vulns.high.exists(p, true)' \
    --filter-fail

License

• Run vet and fail if a package with a specific license was detected

vet scan -D /path/to/code \
    --filter 'licenses.exists(p, "GPL-2.0")' \
    --filter-fail

Note: Using licenses.contains_license(...) is recommended for license matching due to its support for SPDX expressions.

• vet supports SPDX License Expressions at package license and policy level

vet scan -D /path/to/code \
    --filter 'licenses.contains_license("LGPL-2.1+")' \
    --filter-fail

Scorecard

• Run vet and fail based on OpenSSF Scorecard attributes

vet scan -D /path/to/code \
    --filter 'scorecard.scores.Maintained == 0' \
    --filter-fail

For more examples, refer to documentation

Query Mode

• Run scan and dump internal data structures to a file for further querying

vet scan -D /path/to/code --json-dump-dir /path/to/dump

• Filter results using query command

vet query --from /path/to/dump \
    --filter 'vulns.critical.exists(p, true) || vulns.high.exists(p, true)'

• Generate report from dumped data

vet query --from /path/to/dump --report-json /path/to/report.json

Reporting

vet supports generating reports in multiple formats during scan or query execution.

Format	Description
Markdown	Human readable report for vulnerabilities, licenses, and more
CSV	Export data to CSV format for manual slicing and dicing
JSON	Machine readable JSON format following internal schema (maximum data)
SARIF	Useful for integration with Github Code Scanning and other tools
Graph	Dependency graph in DOT format for risk and package relationship visualization
Summary	Default console report with summary of vulnerabilities, licenses, and more

CI/CD Integration

📦 GitHub Action

• vet is available as a GitHub Action, refer to vet-action

🚀 GitLab CI

• vet can be integrated with GitLab CI, refer to vet-gitlab-ci

🐙 Malicious Package Analysis

vet supports scanning for malicious packages using SafeDep Cloud API which requires an API key.

• To setup an API key for malicious package scanning

vet cloud quickstart

• Run a scan and check for malicious packages

vet scan -D /path/to/code --malware

Note: vet will submit identified packages to SafeDep Cloud for analysis and wait for a timeout period for response. Not all package analysis may be completed within the timeout period. However, subsequent scans will fetch the results if available and lead to increased coverage over time. Adjust the timeout using --malware-analysis-timeout flag.

🔍 Scanning Visual Studio Code Extensions

• Auto-discover and scan Visual Studio Code extensions in the local system

vet scan --vsx --malware

🔍 Scanning GitHub Actions (or any other GitHub repository)

• Scan a single GitHub Actions workflow using inspect command

vet inspect malware --purl pkg:github/safedep/vet-action@v1

• The same convention can be used to inspect any GitHub repository reference

vet inspect malware --purl pkg:github/safedep/[email protected]

• Scan all GitHub Actions workflows in a repository

vet scan -D .github/workflows --malware

Note: vet will resolve the commit hash for the given version and use it for malware analysis. This is because GitHub repository tags are mutable and can be changed.

🛠️ Advanced Usage

• Threat Hunting with vet
• Policy as Code
• Exceptions and Overrides

📖 Documentation

• Refer to https://safedep.io/docs for the detailed documentation

🎊 Community

First of all, thank you so much for showing interest in vet, we appreciate it ❤️

• Join the Discord server using the link - https://rebrand.ly/safedep-community

💻 Development

Refer to CONTRIBUTING.md

Support

SafeDep provides enterprise support for vet deployments. Check out SafeDep Cloud for large scale deployment and management of vet in your organization.

Star History

🔖 References

• https://github.com/google/osv-scanner
• https://github.com/anchore/syft
• https://deps.dev/
• https://securityscorecards.dev/
• https://slsa.dev/