SafeDep

https://docs.safedep.io/
Admin
SafeDep is a platform that continuously scans open source packages for malicious code using static...
Tokens:27,899
Snippets:230
Trust Score:7.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Quickstart SafeDep Cloud Onboarding with vet CLI

Source: https://docs.safedep.io/cloud/quickstart

Initiates the quickstart process for SafeDep Cloud using the vet CLI. This command guides the user through the necessary steps for initial setup and connection.

```bash
vet cloud quickstart
```

--------------------------------

### Verify PMG Installation

Source: https://docs.safedep.io/pmg/quickstart

Checks if the SafeDep PMG installation is working correctly by displaying its version number. This command is useful for troubleshooting and confirming successful setup.

```bash
pmg version
```

--------------------------------

### Install PMG using Go Install

Source: https://docs.safedep.io/pmg/quickstart

Installs the latest version of SafeDep PMG directly using the Go toolchain. This method requires Go to be installed on your system.

```bash
go install github.com/safedep/pmg@latest
```

--------------------------------

### Install vet CLI using Homebrew

Source: https://docs.safedep.io/cloud/quickstart

Installs the vet CLI tool, a prerequisite for interacting with SafeDep Cloud. This command uses Homebrew to tap the safedep repository and then install the vet package.

```bash
brew tap safedep/tap
brew install safedep/tap/vet
```

--------------------------------

### Log in to SafeDep Cloud CLI

Source: https://docs.safedep.io/cloud/quickstart

Logs the vet CLI into your SafeDep Cloud tenant, which is required before executing any cloud queries. Replace `<your-tenant-domain>` with your actual tenant domain.

```bash
vet cloud login --tenant <your-tenant-domain>
```

--------------------------------

### Install PMG using Homebrew

Source: https://docs.safedep.io/pmg/quickstart

Installs the SafeDep PMG package manager guard using the Homebrew package manager. This is the recommended installation method.

```bash
brew install safedep/tap/pmg
```

--------------------------------

### Install xBom using Homebrew

Source: https://docs.safedep.io/xbom/quickstart

Installs the xBom tool on macOS and Linux systems using the Homebrew package manager. Ensure Homebrew is installed before running this command.

```bash
# Installation on macOS & Linux
brew install safedep/tap/xbom
```

--------------------------------

### Display PMG Help Information

Source: https://docs.safedep.io/pmg/quickstart

Shows all available commands and options for the SafeDep PMG tool. This command is essential for understanding the full capabilities of PMG and its various configurations.

```bash
pmg --help
```

--------------------------------

### Install SafeDep Vet via Container Image

Source: https://docs.safedep.io/quickstart

Installs and runs the SafeDep vet tool using a Docker container. This command pulls the latest version of the vet image and executes the 'version' command.

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

--------------------------------

### Automated PMG Setup

Source: https://docs.safedep.io/pmg/quickstart

Automatically installs shell aliases for SafeDep PMG, enabling seamless integration with your package manager. This command creates configuration files and modifies shell startup scripts for bash, zsh, and fish.

```bash
pmg setup install
```

--------------------------------

### Manual PMG Usage with pip

Source: https://docs.safedep.io/pmg/quickstart

Manually invokes the SafeDep PMG command to install a package using pip. This approach is used when automated setup is not employed and requires prepending 'pmg' to pip commands.

```bash
pmg pip install <package-name>
```

--------------------------------

### Execute SQL Query to List All Projects in SafeDep Cloud

Source: https://docs.safedep.io/cloud/quickstart

Executes a SQL-like query against SafeDep Cloud to retrieve the names and versions of all projects. This is useful for an overview of your managed projects.

```bash
vet cloud query execute --sql "select projects.name, projects.version from projects"
```

--------------------------------

### Manual PMG Usage with npm

Source: https://docs.safedep.io/pmg/quickstart

Manually invokes the SafeDep PMG command to install a package using npm. This bypasses the automated setup and requires explicitly prefixing package manager commands with 'pmg'.

```bash
pmg npm install <package-name>
```

--------------------------------

### Clone and Start DefectDojo using Docker

Source: https://docs.safedep.io/guides/defect-dojo-integration

These commands clone the DefectDojo repository and start the DefectDojo services using Docker Compose. Ensure Docker and Docker Compose are installed and running.

```bash
git clone https://github.com/DefectDojo/django-DefectDojo.git --depth 1
cd django-DefectDojo
docker compose up -d
```

--------------------------------

### Configure vet CLI Authentication with SafeDep Cloud Tenant

Source: https://docs.safedep.io/cloud/quickstart

Sets up the vet CLI to authenticate with a specific SafeDep Cloud tenant. The command prompts for the Tenant Domain and securely collects the API key.

```bash
vet auth configure --tenant <tenant-domain>
```

--------------------------------

### Verify vet CLI Authentication with SafeDep Cloud

Source: https://docs.safedep.io/cloud/quickstart

Confirms that the vet CLI is successfully authenticated with the configured SafeDep Cloud tenant. This is a crucial step to ensure connectivity before syncing data.

```bash
vet auth verify
```

--------------------------------

### Manual PMG Usage with pnpm

Source: https://docs.safedep.io/pmg/quickstart

Manually invokes the SafeDep PMG command to add a package using pnpm. This method is an alternative to automated setup and requires prefixing 'pnpm' commands with 'pmg'.

```bash
pmg pnpm add <package-name>
```

--------------------------------

### Sync vet Findings to SafeDep Cloud

Source: https://docs.safedep.io/cloud/quickstart

Enables the reporting module in the vet CLI to sync scan findings to SafeDep Cloud. It allows specifying project name and version for better organization and tracking.

```bash
vet scan -M /path/to/package-lock.json --report-sync \
  --report-sync-project my-project \
  --report-sync-project-version my-project-version
```

--------------------------------

### Execute SQL Query to Find Critical Vulnerabilities in SafeDep Cloud

Source: https://docs.safedep.io/cloud/quickstart

Executes a SQL-like query to find critical vulnerabilities across projects in SafeDep Cloud. It filters results to show project name, package name, version, and CVE ID for critical risks.

```bash
vet cloud query execute --sql "
  select projects.name, packages.name, packages.version, vulnerabilities.cve_id 
  from projects
  where projects.version = 'main' and vulnerabilities.risk = 'CRITICAL'
"
```

--------------------------------

### View SafeDep Cloud Data Schema using CLI

Source: https://docs.safedep.io/cloud/quickstart

Retrieves and displays the complete data schema for SafeDep Cloud using the vet CLI. This information is essential for constructing custom queries and understanding the available data.

```bash
vet cloud query schema
```

--------------------------------

### Manifest File Installation Commands (Bash)

Source: https://docs.safedep.io/pmg/concepts/about

Examples of commands for installing packages from manifest files (lockfiles and requirements.txt). PMG adapts its resolution strategy based on the manifest type.

```bash
npm install          # Uses package-lock.json/pnpm-lock.yaml
pip install -r requirements.txt
```

--------------------------------

### Execute SQL Query to Identify Policy Violations in SafeDep Cloud

Source: https://docs.safedep.io/cloud/quickstart

Executes a SQL-like query to identify policy violations within projects in SafeDep Cloud. It lists project name, package name, version, and the specific policy rule that was violated.

```bash
vet cloud query execute --sql "
  select projects.name, packages.name, packages.version, policy_violations.rule_name 
  from projects
  where projects.version = 'main'
"
```

--------------------------------

### Execute SQL Query and Export Results to CSV in SafeDep Cloud

Source: https://docs.safedep.io/cloud/quickstart

Executes a SQL-like query against SafeDep Cloud and exports the results directly to a CSV file. This is useful for offline analysis or sharing query outcomes.

```bash
vet cloud query execute \
  --csv results.csv \
  --sql "select projects.name, projects.version from projects"
```

--------------------------------

### Run PMG with Verbose Output

Source: https://docs.safedep.io/pmg/quickstart

Executes a SafeDep PMG command with the --verbose flag to display detailed information about package detection. This is helpful for diagnosing false positives or understanding blocking behavior.

```bash
pmg --verbose <command>
```

--------------------------------

### Example Workflow: Python Project Analysis with Vet

Source: https://docs.safedep.io/guides/code-analysis

This example demonstrates a complete workflow for analyzing a Python project using Vet. It first builds the code analysis database for the project and then runs an enhanced scan using that database.

```bash
vet code scan --app ./src \
    --db ./analysis/code.db \
    --lang python
```

```bash
vet scan -D . \
    --code ./analysis/code.db \
    --report-json results.json
```

--------------------------------

### Direct Package Installation Commands (Bash)

Source: https://docs.safedep.io/pmg/concepts/about

Examples of direct package installation commands for npm, pip, and pnpm. These commands are intercepted by PMG for threat analysis.

```bash
npm install express
pip install requests
pnpm add lodash
```

--------------------------------

### Generate BOM for Source Code

Source: https://docs.safedep.io/xbom/quickstart

Generates a Software Bill of Materials (SBOM) in CycloneDX v1.6 JSON format for a given directory. It requires specifying the source code directory and the output BOM file path. The tool detects AI components and other supported elements.

```bash
# Generate BOM for your source code
xbom generate --dir /path/to/your/code --bom /path/to/output/bom.cdx.json
```

--------------------------------

### Python SBOM Generation and Scan with vet

Source: https://docs.safedep.io/guides/dependency-inventory

Steps to install and use the 'cyclonedx-python' library to generate an SBOM for Python projects, followed by scanning the generated SBOM with 'vet'. This includes installation via pip and command-line execution for SBOM generation.

```bash
# Install
pip install cyclonedx-bom

# Generate SBOM
cyclonedx-py -o sbom.json

# Scan with vet
vet scan --lockfiles sbom.json --lockfile-as bom-cyclonedx
```

--------------------------------

### JWT-Based Access with 'vet' CLI Examples

Source: https://docs.safedep.io/cloud/authentication

Provides examples of using the 'vet' CLI with JWT authentication for Control Plane operations. This includes logging in, executing SQL queries against SafeDep Cloud data, and checking the current authentication status.

```bash
# Login with device code flow
vet cloud login --tenant your-company

# Query aggregated data
vet cloud query execute --sql "SELECT * FROM projects"

# Check authentication status
vet cloud whoami
```

--------------------------------

### Scan a Directory with SafeDep Vet

Source: https://docs.safedep.io/quickstart

Performs a security scan on a specified directory, auto-discovering manifest files. This is the primary command for scanning a project's dependencies.

```bash
vet scan -D /path/to/dir
```

--------------------------------

### Initialize TypeScript Project

Source: https://docs.safedep.io/guides/insights-api-using-typescript

Sets up a new TypeScript project by initializing npm and installing necessary development dependencies like TypeScript and Node.js types.

```bash
npm init -y
npm install --save-dev typescript @types/node
```

--------------------------------

### Install SafeDep API SDKs

Source: https://docs.safedep.io/guides/insights-api-using-typescript

Installs the required SafeDep API libraries for ConnectRPC, enabling the application to interact with the SafeDep Insights API.

```bash
npm install --save @buf/safedep_api.connectrpc_es@latest
```

--------------------------------

### Scan and Sync Data with SafeDep Cloud

Source: https://docs.safedep.io/cloud/faq

Example commands for scanning a project and synchronizing the report data to SafeDep Cloud. This helps in resolving 'Missing Data' issues by ensuring the correct flags and project information are used.

```bash
vet scan -D . --report-sync \
  --report-sync-project "your-project" \
  --report-sync-project-version "main"
```

```bash
vet auth verify
```

--------------------------------

### Python Requirements File Example (Python)

Source: https://docs.safedep.io/pmg/concepts/about

An example of a Python requirements.txt file, demonstrating various ways dependencies can be specified, including version ranges, exact versions, and packages with extras. Git URLs and local paths are noted as unsupported for analysis.

```python
# requirements.txt example
requests>=2.25.0,<3.0.0
django==4.2.7
# -e git+https://github.com/user/repo.git  # Git URLs skipped
flask[async]  # Extra dependencies resolved
```

--------------------------------

### Scan an OCI Image with SafeDep Vet

Source: https://docs.safedep.io/quickstart

Scans an OCI (Open Container Initiative) image for vulnerable dependencies. This is useful for scanning containerized applications.

```bash
vet scan --image ghcr.io/safedep/vet:latest
```

--------------------------------

### Scan a Java JAR File with SafeDep Vet

Source: https://docs.safedep.io/quickstart

Scans a Java JAR file for security vulnerabilities. This command treats the JAR file as a manifest to analyze its dependencies.

```bash
vet scan -M /path/to/my-app.jar
```

--------------------------------

### Multi-Criteria Security Checks with SafeDep CLI

Source: https://docs.safedep.io/advanced/build-your-own-queries

Perform multi-criteria security checks using 'vet query' with multiple filters. This example demonstrates failing the build if there are critical vulnerabilities OR unmaintained packages.

```bash
# Fail on critical vulnerabilities OR unmaintained packages
vet query --from /tmp/dump \
    --filter 'vulns.critical.size() > 0 || scorecard.scores.Maintained == 0' \
    --filter-fail
```

--------------------------------

### Scan with a Policy Suite File and Fail with SafeDep Vet

Source: https://docs.safedep.io/quickstart

Performs a security scan using a predefined policy suite file (YAML format) and fails if the policy is violated. This enables opinionated policy-as-code enforcement.

```bash
vet scan -D /path/to/dir \
  --filter-suite /path/to/policy.yml \
  --filter-fail
```

--------------------------------

### Scan a PURL (Package URL) with SafeDep Vet

Source: https://docs.safedep.io/quickstart

Scans a dependency specified by its Package URL (PURL). This allows for scanning individual packages without needing local source code.

```bash
vet scan --purl pkg:npm/express@4.18.2
```

--------------------------------

### Scan a Single Manifest File with SafeDep Vet

Source: https://docs.safedep.io/quickstart

Scans a specific manifest file (e.g., package-lock.json) for security risks. This is useful for targeted scans or when auto-discovery might not be sufficient.

```bash
vet scan -M package-lock.json
```

--------------------------------

### Basic API Key Usage with 'vet' CLI

Source: https://docs.safedep.io/cloud/authentication

This example shows how to set API credentials as environment variables and then use the 'vet' CLI to perform a scan and sync reports to SafeDep Cloud, utilizing Data Plane authentication.

```bash
# Set credentials
export SAFEDEP_API_KEY=sk_your_api_key
export SAFEDEP_TENANT_ID=your-company

# Use with vet
vet scan -D . --report-sync \
  --report-sync-project myproject \
  --report-sync-project-version main
```

--------------------------------

### PMG Integration Patterns (Bash)

Source: https://docs.safedep.io/pmg/concepts/about

Illustrates integration patterns for the PMG tool, showing commands for one-time automated setup and manual per-command usage for package management.

```bash
# One-time automated setup
pmg setup install

# Manual per-command usage
pmg npm install lodash
```

--------------------------------

### Sign SBOM for Integrity Verification with cosign

Source: https://docs.safedep.io/guides/cyclonedx-sbom

An example command using `cosign` to sign a CycloneDX SBOM file, creating a signed bundle for integrity verification.

```bash
# Example with cosign
cosign sign-blob --bundle sbom.cdx.json.bundle sbom.cdx.json
```

--------------------------------

### Vet Policy Filtering Examples

Source: https://docs.safedep.io/faq

These examples show how to use CEL (Common Expression Language) for filtering in vet policies. The first example filters for critical vulnerabilities, and the subsequent ones illustrate correct and incorrect syntax for boolean logic and data structure checks.

```bash
--filter 'vulns.critical.size() > 0'
```

```bash
vulns.critical.size() > 0
```

```bash
vulns.critical.length() > 0  # Use size(), not length()
```

```bash
licenses.exists(p, p == "MIT")
```

```bash
licenses
```

--------------------------------

### GitHub Actions Integration

Source: https://docs.safedep.io/cloud/authentication

Example configuration for integrating SafeDep Cloud authentication into GitHub Actions workflows using the vet-action.

```APIDOC
## GitHub Actions Integration

### Description
This snippet shows how to configure the `safedep/vet-action` within a GitHub Actions workflow to authenticate with SafeDep Cloud. It utilizes secrets for API keys and tenant IDs.

### Method
CI/CD Workflow Step

### Endpoint
N/A (Action within GitHub Actions)

### Parameters
#### Action Inputs
- **cloud** (boolean) - Required - Set to `true` to enable cloud integration.
- **cloud-key** (string) - Required - Your SafeDep Cloud API key or JWT token, stored as a GitHub secret.
- **cloud-tenant** (string) - Required - Your SafeDep Cloud tenant ID, stored as a GitHub secret.

#### Environment Variables
- **GITHUB_TOKEN** (string) - Required - Provided by GitHub Actions, used for interactions with GitHub.

### Request Example
```yaml
- name: SafeDep Cloud Integration
  uses: safedep/vet-action@v1
  with:
    cloud: true
    cloud-key: ${{ secrets.SAFEDEP_CLOUD_API_KEY }}
    cloud-tenant: ${{ secrets.SAFEDEP_CLOUD_TENANT }}
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

### Response
N/A (Action performs tasks based on configuration)

#### Response Example
N/A
```

--------------------------------

### Load and Query Enriched Metadata with SafeDep CLI

Source: https://docs.safedep.io/advanced/build-your-own-queries

Load previously dumped enriched metadata using the 'vet query' command for fast filtering and reporting. Examples include generating summary reports and applying custom filters.

```bash
# Generate summary report
vet query --from /tmp/dump --report-summary

# Apply custom filters
vet query --from /tmp/dump --filter 'scorecard.scores.Maintained == 0'
```

--------------------------------

### Data Plane - API Key Authentication Example

Source: https://docs.safedep.io/cloud/authentication

Demonstrates how to authenticate with the Data Plane using an API Key, commonly used for tool integrations and automated access.

```APIDOC
## Data Plane - API Key Authentication

### Description
This endpoint demonstrates the usage of API Key authentication for the Data Plane, suitable for tool integrations and automated access.

### Method
POST (example endpoint)

### Endpoint
https://api.safedep.io/v2/insights/packages

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token in the format 'Bearer sk_your_api_key'
- **X-Tenant-ID** (string) - Required - Your SafeDep Cloud tenant ID

### Request Example
```bash
curl -H "Authorization: Bearer sk_your_api_key" \
     -H "X-Tenant-ID: your-tenant" \
     https://api.safedep.io/v2/insights/packages
```

### Response
#### Success Response (200)
- **packages** (array) - List of package insights.
- **version** (string) - API version.

#### Response Example
```json
{
  "packages": [
    {
      "name": "example-package",
      "version": "1.0.0"
    }
  ],
  "version": "v2"
}
```
```

--------------------------------

### npm/Node.js SBOM Generation and Scan with vet

Source: https://docs.safedep.io/guides/dependency-inventory

Instructions for integrating the CycloneDX npm plugin to generate an SBOM for Node.js projects and then scanning it with 'vet'. This involves global installation of the plugin, generating the SBOM, and then running the 'vet scan' command.

```bash
# Install globally
npm install -g @cyclonedx/cyclonedx-npm

# Generate SBOM
cyclonedx-npm --output-file sbom.json

# Scan with vet
vet scan --lockfiles sbom.json --lockfile-as bom-cyclonedx
```

--------------------------------

### Risk Assessment Queries with SafeDep CLI

Source: https://docs.safedep.io/advanced/build-your-own-queries

Conduct risk assessments by applying multiple criteria filters with 'vet query'. This example finds high-risk packages based on vulnerabilities, scorecard scores, and project stars.

```bash
# Find high-risk packages (multiple criteria)
vet query --from /tmp/dump \
    --filter 'vulns.high.size() > 0 && scorecard.scores.Security < 5 && projects.exists(p, p.stars < 100)'
```

--------------------------------

### Protected Package Installation Commands (Bash)

Source: https://docs.safedep.io/pmg/concepts/about

Demonstrates how PMG intercepts package installation commands. It shows a clean package being installed normally and a malicious package being blocked.

```bash
# After pmg setup, these commands are automatically protected:
npm install express        #  Clean package - installs normally
npm install malicious-pkg  #  Blocked - malicious package detected
```

--------------------------------

### Enforce SBOM Policies with Open Policy Agent (OPA)

Source: https://docs.safedep.io/guides/cyclonedx-sbom

Shows an example of how to use Open Policy Agent (OPA) to evaluate policies against a CycloneDX SBOM. Assumes a `policy.rego` file exists.

```bash
# Example with Open Policy Agent (OPA)
opa eval --data policy.rego --input sbom.cdx.json "data.sbom.allow"
```

--------------------------------

### Scan and Fail on High-Risk Vulnerabilities with SafeDep Vet

Source: https://docs.safedep.io/quickstart

Runs a security scan and fails the process if critical or high-risk vulnerabilities are detected. It uses CEL (Common Expression Language) for filtering.

```bash
vet scan -D /path/to/dir \
  --filter '(vulns.critical.size() > 0) || (vulns.high.size() > 0)' \
  --filter-fail
```

--------------------------------

### Query Synced Data using SafeDep Cloud CLI

Source: https://docs.safedep.io/cloud/sync

These examples demonstrate how to query synchronized data from SafeDep Cloud using the `vet cloud query execute` command. They show SQL queries for listing projects, finding critical vulnerabilities, and exporting project security summaries to a CSV file.

```bash
# List all synced projects
vet cloud query execute --sql "SELECT DISTINCT name, version FROM projects"

# Find critical vulnerabilities across projects
vet cloud query execute --sql "
  SELECT projects.name, packages.name, vulnerabilities.cve_id 
  FROM projects 
  WHERE vulnerabilities.severity = 'CRITICAL'
"

# Export project security summary
vet cloud query execute \
  --sql "SELECT * FROM projects WHERE name = 'my-project'" \
  --csv my-project-summary.csv

```

--------------------------------

### Example Input JSON Structure for Filtering

Source: https://docs.safedep.io/advanced/filtering

This JSON structure represents package information, vulnerabilities, scorecard results, project details, and licenses. It serves as the input for filtering operations.

```json
{
  "pkg": {
    "ecosystem": "npm",
    "name": "lodash.camelcase",
    "version": "4.3.0"
  },
  "vulns": {
    "all": [],
    "critical": [],
    "high": [],
    "medium": [],
    "low": []
  },
  "scorecard": {
    "scores": {
      "Binary-Artifacts": 10,
      "Branch-Protection": 0,
      "CII-Best-Practices": 0,
      "Code-Review": 8,
      "Dangerous-Workflow": 10,
      "Dependency-Update-Tool": 0,
      "Fuzzing": 0,
      "License": 10,
      "Maintained": 0,
      "Packaging": -1,
      "Pinned-Dependencies": 9,
      "SAST": 0,
      "Security-Policy": 10,
      "Signed-Releases": -1,
      "Token-Permissions": 0,
      "Vulnerabilities": 10
    }
  },
  "projects": [
    {
      "name": "lodash/lodash",
      "type": "GITHUB",
      "stars": 55518,
      "forks": 6787,
      "issues": 464
    }
  ],
  "licenses": ["MIT"]
}
```

--------------------------------

### CEL Example: Checking Specific Licenses

Source: https://docs.safedep.io/advanced/policy-as-code

An example of a CEL expression to check if a package has specific license identifiers like GPL-3.0 or AGPL-3.0. It uses the `exists` function for checking array membership.

```cel
licenses.exists(p, p in ["GPL-3.0", "AGPL-3.0"])

```

--------------------------------

### Environment-Specific Exclusions for Vet Scan

Source: https://docs.safedep.io/advanced/path-exclusion

This example shows how to apply different exclusion patterns based on the environment (development or production). It allows for tailored scans that fit specific build or deployment needs.

```bash
# Development environment
vet scan -D . \
    --exclude 'dev-tools/*' \
    --exclude 'local-config/*' \
    --exclude '.*\.dev\..*' 

# Production build
vet scan -D . \
    --exclude 'test/*' \
    --exclude 'examples/*' \
    --exclude 'dev-dependencies/*'
```

--------------------------------

### GitHub Actions Security Scan with Exceptions (YAML)

Source: https://docs.safedep.io/advanced/exceptions

Integrate SafeDep's security scanning into a GitHub Actions workflow. This example demonstrates how to use the `safedep/vet-action` to scan code and apply exceptions defined in a local file.

```yaml
name: Security Scan with Exceptions
on: [push, pull_request]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run security scan
        uses: safedep/vet-action@v1
        with:
          exception-file: '.github/vet/exceptions.yml'

      - name: Check for expired exceptions
        run: |
          # Custom script to check for exceptions expiring soon
          python scripts/check-exception-expiry.py .github/vet/exceptions.yml
```

--------------------------------

### Control Plane - JWT Authentication Example

Source: https://docs.safedep.io/cloud/authentication

Illustrates how to authenticate with the Control Plane using a JWT token, providing programmatic access with higher privileges.

```APIDOC
## Control Plane - JWT Authentication

### Description
This endpoint demonstrates the usage of JWT authentication for the Control Plane, suitable for programmatic access and querying aggregated data.

### Method
GET (example endpoint)

### Endpoint
https://cloud.safedep.io/api/v1/projects

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token in the format 'Bearer your_jwt_token'
- **X-Tenant-ID** (string) - Required - Your SafeDep Cloud tenant ID

### Request Example
```bash
# First, obtain JWT token via 'vet cloud login --tenant your-company'
# Then use the token in the curl command:
curl -H "Authorization: Bearer your_jwt_token" \
     -H "X-Tenant-ID: your-tenant" \
     https://cloud.safedep.io/api/v1/projects
```

### Response
#### Success Response (200)
- **projects** (array) - List of projects.
- **total** (integer) - Total number of projects.

#### Response Example
```json
{
  "projects": [
    {
      "name": "myproject",
      "version": "main"
    }
  ],
  "total": 1
}
```
```

--------------------------------

### Multi-Stage Pipeline with Security Scanning

Source: https://docs.safedep.io/guides/gitlab-dependency-scanning

Integrate the 'vet' security scan into a multi-stage GitLab pipeline. This example shows the security stage running before the build and deploy stages, with specific inputs for cloud-based scanning.

```yaml
stages:
  - security
  - build
  - deploy

include:
  - component: gitlab.com/safedep/ci-components/vet/scan@v1.5.1
    inputs:
      stage: security
      policy: '.gitlab/security-policy.yml'
      cloud: true
      cloud-key: $SAFEDEP_CLOUD_KEY
      cloud-tenant: $SAFEDEP_CLOUD_TENANT

build:
  stage: build
  script:
    - echo "Building application..."
  needs: ["vet"]
```

--------------------------------

### Validate and Convert CycloneDX SBOM using CLI

Source: https://docs.safedep.io/guides/cyclonedx-sbom

Demonstrates how to validate a CycloneDX SBOM file and convert it to XML format using the `cyclonedx-cli` tool, which needs to be installed globally via npm.

```bash
# Using cyclonedx-cli (install via npm)
npm install -g @cyclonedx/cli

# Validate SBOM
cyclonedx validate --input-file sbom.cdx.json

# Convert to other formats
cyclonedx convert --input-file sbom.cdx.json --output-file sbom.xml --output-format xml
```

--------------------------------

### Integrate Code Analysis into GitHub Actions (YAML)

Source: https://docs.safedep.io/guides/code-analysis

Automate code analysis as part of your CI/CD workflow using GitHub Actions. This example demonstrates building a code analysis database and then performing an enhanced security scan using the generated database.

```yaml
# GitHub Actions example
- name: Build Code Analysis DB
  run: vet code scan --app ./src --db ./code-analysis.db

- name: Enhanced Security Scan
  run: vet scan -D . --code ./code-analysis.db --report-sarif security.sarif
```

--------------------------------

### Example Filter Suite Definition (YAML)

Source: https://docs.safedep.io/advanced/policy-as-code

Defines a comprehensive enterprise security policy using YAML format. It includes filters for critical and high vulnerabilities, license compliance, maintenance score, and security score, leveraging CEL expressions for evaluation.

```yaml
name: Enterprise Security Policy
description: Comprehensive security policy for open source components
filters:
  - name: critical-vulnerabilities
    value: |
      vulns.critical.size() > 0
    
  - name: high-vulnerabilities
    value: |
      vulns.high.size() > 5
    
  - name: approved-licenses
    value: |
      !licenses.exists(p, p in ["MIT", "Apache-2.0", "BSD-3-Clause", "ISC"])
    
  - name: minimum-maintenance
    value: |
      scorecard.scores.Maintained < 5
    
  - name: security-score
    value: |
      scorecard.Score < 3
  

```

--------------------------------

### Disable xBom Telemetry Collection

Source: https://docs.safedep.io/xbom/quickstart

Disables the collection of anonymous telemetry data by setting the XBOM_DISABLE_TELEMETRY environment variable to 'true'. This is useful for users who prefer to opt out of data collection.

```bash
export XBOM_DISABLE_TELEMETRY=true
```

--------------------------------

### Custom Policy Suite for DefectDojo Integration

Source: https://docs.safedep.io/guides/defect-dojo-integration

This is an example of a YAML structure for a custom policy suite file. This file would be used with the '--filter-suite' option in the 'vet scan' command to define specific policies that 'vet' should enforce and report to DefectDojo. The exact structure and content depend on the 'vet' tool's policy definition format.

```yaml
rules:
  - name: "Disallow specific vulnerable package"
    match:
      package: "vulnerable-package"
      version: ">=1.0.0"
    status: "vulnerable"

  - name: "Require specific license"
    match:
      package: "*"
    condition: "license != 'MIT'"
    status: "non-compliant"

```

--------------------------------

### Batch Package Analysis with SafeDep API

Source: https://docs.safedep.io/guides/insights-api-using-typescript

Provides an advanced example for analyzing multiple packages concurrently. The `analyzePackages` function iterates through a list of packages, fetches insights for each using `getPackageVersionInsight`, and aggregates the results. Error handling is included for individual package analysis.

```typescript
async function analyzePackages(packages: Array<{ecosystem: Ecosystem, name: string, version: string}>) {
  const client = createPromiseClient(InsightService, transport);
  const results = [];

  for (const pkg of packages) {
    try {
      const res = await client.getPackageVersionInsight({
        packageVersion: {
          package: {
            ecosystem: pkg.ecosystem,
            name: pkg.name,
          },
          version: pkg.version,
        }
      });
      results.push({
        package: `${pkg.name}@${pkg.version}`,
        insights: res.toJson()
      });
    } catch (error) {
      console.error(`Error analyzing ${pkg.name}@${pkg.version}:`, error);
    }
  }

  return results;
}

// Usage
const packagesToAnalyze = [
  { ecosystem: Ecosystem.NPM, name: "express", version: "4.18.2" },
  { ecosystem: Ecosystem.NPM, name: "react", version: "18.2.0" },
  { ecosystem: Ecosystem.PYPI, name: "requests", version: "2.31.0" }
];

analyzePackages(packagesToAnalyze).then(results => {
  console.log("Analysis results:", JSON.stringify(results, null, 2));
});
```

--------------------------------

### Sync Multiple Manifests with vet CLI

Source: https://docs.safedep.io/cloud/sync

Synchronizes scan results from multiple manifest files within a monorepo structure to SafeDep Cloud. This command utilizes the `--report-sync` flag and allows for specific project and version identification, ideal for complex project setups.

```bash
vet scan -D /path/to/monorepo \
  --report-sync \
  --report-sync-project monorepo-backend \
  --report-sync-project-version v2.1.0
```

--------------------------------

### PMG Operating Modes (Bash)

Source: https://docs.safedep.io/pmg/concepts/about

Demonstrates various command-line operating modes for the PMG tool, including silent, verbose, dry run, and debug, along with examples of their usage with npm install.

```bash
# Silent mode - minimal output
pmg --silent npm install express

# Verbose mode - detailed analysis information
pmg --verbose npm install express

# Dry run - analyze without installing
pmg --dry-run npm install express

# Debug mode - comprehensive logging
pmg --debug --log /tmp/pmg.log npm install express
```

--------------------------------

### Scan Project and Report to DefectDojo

Source: https://docs.safedep.io/guides/defect-dojo-integration

This command initiates a project scan using the 'vet' tool and reports the findings to DefectDojo. It specifies the GitHub repository to scan, a path to a policy suite file for filtering, enables DefectDojo reporting, provides the DefectDojo host URL, and the product ID within DefectDojo. Replace placeholders like '<your-policy-suite.yml>' and '<your-product-id>' with actual values.

```bash
vet scan --github https://github.com/safedep/demo-client-python \
  --filter-suite /path/to/your/policy-suite.yml \
  --report-defect-dojo \
  --defect-dojo-host-url http://localhost:8080/ \
  --defect-dojo-product-id <your-product-id>
```

--------------------------------

### CEL Example: Checking Critical Vulnerabilities

Source: https://docs.safedep.io/advanced/policy-as-code

An example of a CEL expression to identify packages with critical vulnerabilities. This expression is typically used within a filter definition.

```cel
vulns.critical.size() > 0

```

--------------------------------

### GitHub Actions for Dependency Inventory Scan

Source: https://docs.safedep.io/guides/dependency-inventory

A GitHub Actions workflow to automate dependency scanning. It checks out code, sets up Java, generates an SBOM using Gradle, scans the SBOM with the 'vet-action', and uploads the SBOM as an artifact.

```yaml
name: Dependency Inventory Scan
on: [push, pull_request]

jobs:
  inventory-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up JDK
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
          
      - name: Generate SBOM
        run: ./gradlew cyclonedxBom
        
      - name: Scan SBOM with vet
        uses: safedep/vet-action@v1
        with:
          scan-dir: 'build/reports'
          lockfile-as: 'bom-cyclonedx'
          
      - name: Upload SBOM
        uses: actions/upload-artifact@v4
        with:
          name: sbom
          path: build/reports/bom.json
```

--------------------------------

### CEL Example: Checking High Severity Vulnerabilities

Source: https://docs.safedep.io/advanced/policy-as-code

An example CEL expression to detect packages with critical or high-severity vulnerabilities. This is useful for enforcing stricter security standards.

```cel
vulns.critical.size() > 0 || vulns.high.size() > 0

```

--------------------------------

### Configure Tenant with vet CLI

Source: https://docs.safedep.io/cloud/faq

Commands to configure or log in to a specific tenant domain using the vet CLI. This is useful for resolving 'Tenant Not Found' errors by ensuring correct tenant configuration.

```bash
vet auth configure --tenant <tenant-domain>
```

```bash
vet cloud login --tenant <tenant-domain>
```

```bash
# Shows available tenants
vet cloud login
vet cloud whoami
```

--------------------------------

### Direct Package Installation Dependency Tree (npm)

Source: https://docs.safedep.io/pmg/concepts/about

Illustrates how PMG resolves transitive dependencies for a direct npm package installation. It shows a tree structure indicating resolved and blocked packages based on security analysis.

```tree
Your Package Request: express@^4.18.0
├── PMG Resolves Transitive Dependencies
│   ├── accepts@~1.3.8 (Clean)
│   ├── array-flatten@1.1.1 (Clean)
│   ├── body-parser@1.20.1 (Clean)
│   │   ├── bytes@3.1.2 (Clean)
│   │   ├── content-type@~1.0.4 (Clean)
│   │   └── debug@2.6.9 (Malicious - BLOCKED!)
│   └── cookie-signature@1.0.6 (Clean)
└── All packages analyzed before installation
```

--------------------------------

### Safedep Vet Action Debugging Commands

Source: https://docs.safedep.io/cloud/faq

A collection of bash commands for debugging and managing the Safedep Vet Action. These commands cover checking authentication status, verifying API configuration, testing cloud connectivity, clearing configuration, re-authenticating, and enabling detailed logging.

```bash
vet cloud whoami
```

```bash
vet auth verify
```

```bash
vet cloud query execute --sql "SELECT 1"
```

```bash
vet auth logout
rm -rf ~/.config/vet/
```

```bash
vet cloud login --tenant your-tenant
```

```bash
vet --log-level debug scan -D . --report-sync
```

--------------------------------

### Update Vet via Homebrew

Source: https://docs.safedep.io/faq

This command updates the vet tool using the Homebrew package manager on macOS and Linux systems. Ensure you have Homebrew installed and the SafeDep tap added.

```bash
brew upgrade safedep/tap/vet
```

--------------------------------

### Configure 'vet' CLI with API Key

Source: https://docs.safedep.io/cloud/authentication

Demonstrates how to configure the 'vet' command-line tool to use an API key for authentication with SafeDep Cloud. This is typically used for Data Plane operations.

```bash
vet auth configure --tenant your-tenant-domain
```

--------------------------------

### Generate SBOMs with Gradle

Source: https://docs.safedep.io/guides/dependency-inventory

A command-line instruction to generate SBOM artifacts using Gradle. This command performs a clean build of the project and then executes the `cyclonedxBom` task, creating the SBOM files in the configured output directory.

```bash
gradle clean build cyclonedxBom
```

--------------------------------

### Configure GitHub Action for SafeDep - YAML

Source: https://docs.safedep.io/faq

Ensure your GitHub Actions are using the latest stable version of the `safedep/vet-action`. This is crucial for accessing the newest features and bug fixes.

```yaml
uses: safedep/vet-action@v1  # Use latest stable
```

--------------------------------

### Get Package Version Insight

Source: https://docs.safedep.io/guides/insights-api-using-typescript

Retrieves detailed security insights for a specific package version, including vulnerabilities, licenses, and scorecard metrics. This is the primary endpoint for package analysis.

```APIDOC
## POST /api/package/insights

### Description
Retrieves security insights for a given package version.

### Method
POST

### Endpoint
/api/package/insights

### Parameters
#### Request Body
- **ecosystem** (string) - Required - The package ecosystem (e.g., NPM, PYPI, MAVEN).
- **name** (string) - Required - The name of the package.
- **version** (string) - Required - The version of the package.

### Request Example
```json
{
  "ecosystem": "NPM",
  "name": "react",
  "version": "18.2.0"
}
```

### Response
#### Success Response (200)
- **insights** (object) - Contains detailed security insights including vulnerabilities, licenses, scorecard, malware, and metadata.

#### Response Example
```json
{
  "vulnerabilities": [
    {
      "severity": "HIGH",
      "description": "A critical vulnerability in the X dependency.",
      "cvss": 8.0
    }
  ],
  "licenses": [
    {
      "licenseId": "MIT",
      "osiApproved": true
    }
  ],
  "scorecard": {
    "score": 7.5
  },
  "metadata": {
    "downloads": 1000000,
    "stars": 50000
  }
}
```
```

--------------------------------

### Excluding Version Control and Dependencies

Source: https://docs.safedep.io/advanced/path-exclusion

This example shows how to exclude directories commonly used for version control systems and package dependencies. This is crucial for ensuring that only project source code is scanned.

```bash
vet scan -D . \
    --exclude '.git/*' \
    --exclude 'node_modules/*' \
    --exclude 'vendor/*' \
    --exclude '.venv/*' \
    --exclude '__pycache__/*'
```

--------------------------------

### GitLab CI for SBOM Generation and Security Scan

Source: https://docs.safedep.io/guides/dependency-inventory

A GitLab CI pipeline configuration for generating an SBOM and performing a security scan. It includes stages for build and security, generates the SBOM using Gradle, and then uses the 'vet' Docker image to scan the SBOM, reporting findings.

```yaml
stages:
  - build
  - security

generate-sbom:
  stage: build
  script:
    - ./gradlew clean build cyclonedxBom
  artifacts:
    paths:
      - build/reports/bom.json
    expire_in: 1 hour

security-scan:
  stage: security
  image: ghcr.io/safedep/vet:latest
  script:
    - vet scan --lockfiles build/reports/bom.json 
               --lockfile-as bom-cyclonedx
               --report-json security-report.json
  dependencies:
    - generate-sbom
  artifacts:
    reports:
      security: security-report.json
```

--------------------------------

### Dump Enriched JSON Manifests with SafeDep CLI

Source: https://docs.safedep.io/advanced/build-your-own-queries

Collect and enrich package data using the 'vet scan' command and dump it to a specified directory for reuse. This is useful for both single manifest files and entire repositories.

```bash
# Single manifest file
vet scan --lockfile /path/to/package-lock.json --json-dump-dir /tmp/dump

# Entire repository
vet scan -D /path/to/repository --json-dump-dir /tmp/dump-many
```

--------------------------------

### License Compliance Checks with SafeDep CLI

Source: https://docs.safedep.io/advanced/build-your-own-queries

Check for license compliance by filtering packages with non-approved licenses using 'vet query'. The results can be reported in JSON format.

```bash
# Find packages with non-approved licenses
vet query --from /tmp/dump \
    --filter '!licenses.exists(p, p in ["MIT", "Apache-2.0", "BSD-3-Clause"])' \
    --report-json compliance-violations.json
```

--------------------------------

### Scanning Multiple Projects with DefectDojo

Source: https://docs.safedep.io/guides/defect-dojo-integration

Demonstrates how to scan individual projects and report them to separate products within DefectDojo. This is useful for organizations managing multiple distinct projects, ensuring findings are categorized correctly by specifying a unique product ID for each scan.

```bash
# Project A
vet scan -D ./project-a \
  --report-defect-dojo \
  --defect-dojo-product-id 1

# Project B  
vet scan -D ./project-b \
  --report-defect-dojo \
  --defect-dojo-product-id 2
```

--------------------------------

### Configure and Login to SafeDep Cloud CLI

Source: https://docs.safedep.io/cloud/authentication

Commands to configure authentication with a specific tenant and log in to SafeDep Cloud. Useful for setting up CLI access and managing tenant-specific configurations.

```bash
vet auth configure --tenant <tenant-domain>
vet cloud login --tenant <tenant-domain>
```

--------------------------------

### CI/CD Integration: GitHub Actions for DefectDojo Scan

Source: https://docs.safedep.io/guides/defect-dojo-integration

Automates security scanning and reports findings to DefectDojo using GitHub Actions. This workflow checks out code, runs the 'vet scan' command with specified policy filters, and sends the report to DefectDojo using provided secrets for authentication and product identification.

```yaml
name: Security Scan to DefectDojo
on: [push, pull_request]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Run vet security scan
        run: |
          vet scan -D . \
            --filter-suite .github/security-policy.yml \
            --report-defect-dojo \
            --defect-dojo-host-url ${{ secrets.DEFECT_DOJO_URL }}
            --defect-dojo-product-id ${{ secrets.DEFECT_DOJO_PRODUCT_ID }}
        env:
          DEFECT_DOJO_APIV2_KEY: ${{ secrets.DEFECT_DOJO_API_KEY }}
```

--------------------------------

### CEL Example: Checking Scorecard Maintenance Score

Source: https://docs.safedep.io/advanced/policy-as-code

A CEL expression to evaluate the OpenSSF Scorecard's 'Maintained' metric, flagging packages with a score below 7. This helps identify projects that may not be actively maintained.

```cel
scorecard.scores.Maintained < 7

```

--------------------------------

### Module References for Usage Evidence

Source: https://docs.safedep.io/guides/dependency-usage-identification

Shows how references to specific classes and methods from imported modules in Java are tracked as usage evidence. This provides granular detail on the interaction with external libraries.

```java
// Java example
import org.apache.commons.lang3.StringUtils;
String result = StringUtils.capitalize(input);
```
Tokens:
Raw