SafeDep Documentation

Scanning package manifests is resource-intensive: vet must enrich each package by querying the Insights API. Because filtering and reporting can run many times on the same manifest, you can dump the enriched data as JSON once and reload it for subsequent operations.

Query Workflow

The BYOQ workflow consists of two main phases:

Data Collection

Scan and enrich package data, then dump to JSON files for reuse

Analysis & Reporting

Load enriched data for fast filtering, querying, and report generation

Phase 1: Dump Enriched JSON Manifests

Collect and enrich package data, then save to a directory for reuse:

# Single lockfile
vet scan --lockfiles /path/to/package-lock.json --json-dump-dir /tmp/dump

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

The JSON dump contains all enriched metadata including vulnerabilities, scorecard data, licenses, and project information.

Phase 2: Load and Query Enriched Metadata

Use the dumped data for fast filtering and reporting:

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

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

Security Guardrails with Filters

Implement security guardrails in CI/CD pipelines using the --filter-fail argument, which causes the command to fail if any package matches the given filter.

Example: Fail Build on Unmaintained Packages

vet query --from /path/to/json-dump \
    --filter 'scorecard.scores.Maintained == 0' \
    --filter-fail

When any package matches the filter, the command exits with a non-zero status:

echo $?
# Output: 255

Advanced Query Examples

Multi-Criteria Security Checks

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

License Compliance Checks

# 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

Risk Assessment Queries

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

Filtering

The CEL filter input schema and syntax.

Policy as Code

Turn these filters into reusable policy files.

Exceptions

Generate exception lists from query results.

SafeDep Cloud SQL

Query synced data across your org.

Query & Policy

API & Automation

Build Your Own Queries

Query Workflow

Phase 1: Dump Enriched JSON Manifests

Phase 2: Load and Query Enriched Metadata

Security Guardrails with Filters

Example: Fail Build on Unmaintained Packages

Advanced Query Examples

Multi-Criteria Security Checks

License Compliance Checks

Risk Assessment Queries

Filtering

Policy as Code

Exceptions

SafeDep Cloud SQL

​Query Workflow

​Phase 1: Dump Enriched JSON Manifests

​Phase 2: Load and Query Enriched Metadata

​Security Guardrails with Filters

​Example: Fail Build on Unmaintained Packages

​Advanced Query Examples

​Multi-Criteria Security Checks

​License Compliance Checks

​Risk Assessment Queries

Filtering

Policy as Code

Exceptions

SafeDep Cloud SQL

Query Workflow

Phase 1: Dump Enriched JSON Manifests

Phase 2: Load and Query Enriched Metadata

Security Guardrails with Filters

Example: Fail Build on Unmaintained Packages

Advanced Query Examples

Multi-Criteria Security Checks

License Compliance Checks

Risk Assessment Queries