list

Use the list command to retrieve a filtered or unfiltered list of a specified resource through the API

Usage

The endorctl api list command lists all objects of a specified resource type, based on the specified filters, field-masks and/or other options.

endorctl api list -r [resource] [flags]

Flags and variables

The endorctl api list command supports the following additional flags and environment variables:

Flag Environment Variable Description
count ENDOR_API_COUNT Get the number of items in the list.
group-aggregation-paths ENDOR_API_GROUP_AGGREGATION_PATHS Specify one or more fields to group resources by.
group-show-aggregation-uuids ENDOR_API_GROUP_SHOW_AGGREGATION_UUIDS Get the uuids of the resources in each group as specified by --group-aggregation-paths.
group-unique-count-paths ENDOR_API_GROUP_UNIQUE_COUNT_PATHS Count the number of unique values, for these fields, in the group.
group-unique-value-paths ENDOR_API_GROUP_UNIQUE_VALUE_PATHS Get the unique values, for these fields, in the group.
list-all ENDOR_API_LIST_ALL List all resources (use -t/--timeout to increase timeout for big queries).
page-size ENDOR_API_PAGE_SIZE Set the page size to limit the number of results returned (default 100).
page-token ENDOR_API_PAGE_TOKEN Set the page token to start from.
pr-uuid ENDOR_API_PR_UUID Only list resources from a specific PR scan.
traverse ENDOR_API_TRAVERSE Get data from any child namespaces as well.

Filtering

The following operators are supported for filters:

  • == - Matches objects where a specified filter criteria is equal.
  • != - Matches objects where a specified filter criteria is NOT equal.
  • < - Matches objects where a specified filter criteria less than a specified value.
  • <= - Matches objects where a specified filter criteria less than or equal to a specified value.
  • > - Matches objects where a specified filter criteria greater than to a specified value.
  • contains - Matches objects where a specified filter contains a value in an array.
  • matches - Matches objects that match an exact or specified regex pattern.
  • exists - Matches objects where a specified field in a json payload exists.

Examples

Return a list of all projects in the namespace:

endorctl api list -r Project

List all projects in the namespace and only return the name of each project:

endorctl api list -r Project --list-all --field-mask meta.name

Return a count of findings associated with the default branch:

endorctl api list -r Finding --filter 'context.type==CONTEXT_TYPE_MAIN' --count

Return a count of unique vulnerabilities found in non-test dependencies where there is an upstream patch available and the function associated with the vulnerability is reachable in the context of the application:

endorctl api list -r Finding \
    --filter 'context.type==CONTEXT_TYPE_MAIN and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY] and spec.finding_tags contains [FINDING_TAGS_NORMAL] and spec.finding_tags contains [FINDING_TAGS_REACHABLE_FUNCTION] and spec.finding_tags contains [FINDING_TAGS_FIX_AVAILABLE]' \
    --group-aggregation-paths 'spec.finding_metadata.vulnerability.meta.name'

Return the count of the number of scans run on the default branch since a given point in time:

endorctl api list -r ScanResult -f "context.id==default and meta.create_time >= date(2023-11-14)" --count