Skip to main content
Filters allow you to specify a subset of objects to be returned by a request, for example: 
endorctl api list --resource Finding \
  --filter "meta.name==dependency_with_critical_vulnerabilities" \
  --count

​
Keys

A filter key is used to specify the field of the object to match against using a dot-delimited path. For example, given an object: 
{
  "uuid": "63ef202d090b62ecf3f6655b",
  "meta": {
    "name": "Example Object",
    "tags": ["dev"]
  },
  "spec": {
    "dependencies": [
      {
        "name": "mvn://org.slf4j:slf4j-api@2.0.0",
      },
      {
        "name": "mvn://ch.qos.logback:logback-access@1.3.0",
      }
    ],
    "version": {
      "ref": "v1.6.333",
      "timestamp": "2024-05-31TT21:04:55.799Z"
    }
  }
}
  • uuid specifies the root field with the value "63ef202d090b62ecf3f6655b"
  • meta.name specifies the nested field with the value "Example Object"
  • meta.tags specifies the nested list field containing the values ["dev"]
  • spec.dependencies.name specifies the nested fields within the list with the values: "mvn://org.slf4j:slf4j-api@2.0.0" and "mvn://ch.qos.logback:logback-access@1.3.0"
  • spec.version.ref specifies the nested field with the value "v1.6.333"
For more information, see Data model.

​
Operators

The following filter operators are supported.

​
Contains

Use contains or not contains to filter on the content of a list field. Multiple values are treated as an OR operation, for example:
  • To get all findings for vulnerabilities that have a fix available OR are in a reachable function use: spec.finding_tags contains [FINDING_TAGS_FIX_AVAILABLE, FINDING_TAGS_REACHABLE_FUNCTION]
  • To get all findings for vulnerabilities that have a fix available AND are in a reachable function use: spec.finding_tags contains [FINDING_TAGS_FIX_AVAILABLE] and spec.finding_tags contains [FINDING_TAGS_REACHABLE_FUNCTION]
  • To get all projects that do not have the meta tags “sanity” or “test” use: meta.tags not contains [sanity, test]

​
In

Use in or not in to filter on the value of a field against one or more given values. Multiple values are treated as an OR operation, for example:
  • To get all findings with a “Critical” or “High” severity level use: spec.finding_level in [FINDING_LEVEL_CRITICAL, FINDING_LEVEL_HIGH]
  • To get all findings that are not from the “Maven” or “npm” ecosystems use: spec.ecosystem not in [ECOSYSTEM_MAVEN, ECOSYSTEM_NPM]

​
Matches

Use matches to filter on a regex pattern. Due to the nature of regex evaluation, this is much slower than using for example == or !=. Also due to the nature of regex evaluation, not matches is not supported.

​
Exists

If a field does not exist then it can’t be equal to anything, so we use exists and not exists instead of != null or == null. This also covers {}, [], etc.

​
Values

A filter value is used in combination with the operator to match against the values at the specified field. Use double quotes to escape string or regex values in a filter, for example:
  • uuid in ["64a3b8326dda5fb62bfcceea", "658323c91aa208f231cc7eff", "658323c963ca516ef02d1b02"]
  • meta.name matches "validation bypass"
Filters are case-sensitive by default.
To filter with case-insentive values a regex modifier may be used, for example:
  • meta.description matches "(?i)django"

​
Date/Time Values

Use date to encode date values in a filter, for example:
  • To filter for objects created after a given date, use a date value with the format YYYY-MM-DD: meta.update_time >= date(2024-05-01)
  • To filter for objects created between specific times, use a timestamp values with the RFC 3339 format: meta.create_time >= date(2024-05-01T13:30:00.000Z) and meta.create_time < date(2024-05-01T23:30:00.000Z)
Use now to encode relative date values in a filter by a given duration offset, for example:
  • To filter for objects created in the last 15 minutes, use: meta.create_time >= now(-12h)
  • To filter for objects created in the last 72 hours, use: meta.create_time >= now(-72h)

​
Combinations

Use and or or to combine multiple filters, for example:
  • spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY] and meta.create_time >= date(2024-05-31)
  • meta.name==archived_source_code_repo or meta.name==outdated_release

​
Nesting filters

Multiple filters may also be nested together into a single filter with the use of parentheses (), for example:
  • (spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY] and spec.level==FINDING_LEVEL_CRITICAL) or (spec.finding_categories contains [FINDING_CATEGORY_SECRETS] and spec.level in [FINDING_LEVEL_CRITICAL, FINDING_LEVEL_HIGH])