SafeDep Documentation

Vet filters dependencies with CEL expressions. A filter is a boolean expression evaluated against each package; a package is included in the results when the expression evaluates to true. This page is the reference for the filter input and CEL syntax. For the concept, see CEL.

The vet scan --filter examples below use Vet’s original filter interface. Vet also ships a newer --policy engine with a different input schema; see the Vet repository for its format.

Running a filter

Filter a scan directly, or filter cached results from a JSON dump:

# Filter a scan
vet scan -D /path/to/repo --filter 'vulns.critical.size() > 0'

# Filter cached results
vet query --from /tmp/dump --filter 'licenses.exists(p, p == "GPL-3.0")'

Add --filter-fail to exit non-zero when any package matches, for CI/CD gating.

Filter input

Each expression receives these variables:

Variable	Content
`_`	Root variable holding the others
`pkg`	Package info: `pkg.ecosystem`, `pkg.name`, `pkg.version`
`vulns`	Vulnerabilities by severity: `vulns.all`, `vulns.critical`, `vulns.high`, `vulns.medium`, `vulns.low`
`scorecard`	OpenSSF Scorecard: `scorecard.score`, `scorecard.scores["Check-Name"]`
`projects`	Source projects, each with `stars`, `forks`, `issues`, `type`
`licenses`	SPDX license codes

See the filter input specification for the full message structure.

Input example

A filter sees each package as a structured input:

{
  "pkg": { "ecosystem": "npm", "name": "lodash.camelcase", "version": "4.3.0" },
  "vulns": { "all": [], "critical": [], "high": [], "medium": [], "low": [] },
  "scorecard": { "scores": { "Maintained": 0, "Dangerous-Workflow": 10, "Token-Permissions": 0 } },
  "projects": [ { "name": "lodash/lodash", "type": "GITHUB", "stars": 55518, "forks": 6787, "issues": 464 } ],
  "licenses": ["MIT"]
}

CEL syntax

Functions: size() (array or map length), exists(var, condition) (any element matches), in (membership), contains(), startsWith() / endsWith(). Operators: == != < <= > >= (comparison), && || ! (logical), + - * / (arithmetic). Types: booleans (true / false), double-quoted strings, numbers, arrays (["a", "b"]), and maps ({"key": "value"}).

Example expressions

# Any critical or high vulnerability
vulns.critical.size() > 0 || vulns.high.size() > 0

# Unmaintained per OpenSSF Scorecard
scorecard.scores.Maintained == 0

# Not an approved license
!licenses.exists(p, p in ["MIT", "Apache-2.0", "BSD-3-Clause"])

# Low-popularity GitHub project
projects.exists(x, x.type == "GITHUB" && x.stars < 100)

# Missing license information
licenses.size() == 0

CEL

What CEL is and how SafeDep uses it.

Policy as Code

Combine expressions into reusable policy files.

Build Your Own Queries

Filter cached scan data with the query workflow.

OpenSSF Scorecard

The scorecard checks referenced in scores.

Query & Policy

API & Automation

Filtering

Running a filter

Filter input

Input example

CEL syntax

Example expressions

CEL

Policy as Code

Build Your Own Queries

OpenSSF Scorecard

​Running a filter

​Filter input

​Input example

​CEL syntax

​Example expressions

CEL

Policy as Code

Build Your Own Queries

OpenSSF Scorecard

Running a filter

Filter input

Input example

CEL syntax

Example expressions