Skip to main content

πŸ”Ž Filtering

Filter command helps solve the problem of visibility for OSS dependencies in an application. To support various requirements, we adopt a generic expressions language for flexible filtering.

Example​

  • The scan will list only packages that use the MIT license.
vet scan -D /path/to/repo \
--report-summary=false \
--filter 'licenses.exists(p, p == "MIT")'
  • Find dependencies that seems not very popular
vet scan --lockfiles /path/to/pom.xml --report-summary=false \
--filter='projects.exists(x, x.stars < 10)'
  • Find dependencies with a critical vulnerability
vet scan --lockfiles /path/to/pom.xml --report-summary=false \
--filter='vulns.critical.exists_one(x, true)'

Input​

Filter expressions work on packages (aka. dependencies) and evaluates to a boolean result. The package is included in the results table if the expression evaluates to true.

  • Filter expressions get the following input data to work with
VariableContent
_The root variable, holding other variables
vulnsHolds a map of vulnerabiliteis by severity
scorecardHolds OpenSSF scorecard
projectsHolds a list of source projects associated with the package
licensesHolds a list of liceses in SPDX license code format
tip

Refer to filter input spec for detailed structure of input messages.

Expressions​

Expressions are CEL statements. While CEL internals are not required, an introductory knowledge of CEL will help formulating queries. Expressions are logical statements that evaluate to true or false.

Example Queries​

DescriptionQuery
Find packages with a critical vulnerabilityvulns.critical.exists(x, true)
Find unmaintained packages as per OpenSSF SCscorecard.scores.Maintained == 0
Find packages with low starsprojects.exists(x, x.stars < 10)
Find packages with GPL-2.0 licenselicenses.exists(x, x == "GPL-2.0")
tip

Refer to scorecard checks for a list of checks available from OpenSSF Scorecards project.

How does the filter input JSON look like?​

{
"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"
]
}