Filters

Filters allow you to specify a subset of objects to be returned by a request, for example:

• endorctl
• curl
• HTTP

endorctl api list --resource Finding \
  --filter "meta.name==dependency_with_critical_vulnerabilities" \
  --count

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --data-urlencode "list_parameters.filter=meta.name==dependency_with_critical_vulnerabilities" \
  --data-urlencode "list_parameters.count=true" \
  https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings

@baseUrl = https://api.endorlabs.com
@token = <insert-access-token>
@namespace = <insert-namespace>

###
GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=meta.name==dependency_with_critical_vulnerabilities&list_parameters.count=true HTTP/1.1
Authorization: Bearer {{token}}

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 ore 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"

NOTE: 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])