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.
filter ENDOR_API_FILTER Specify query parameters used to filter resources.
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-id ENDOR_API_PAGE_ID Set the page id to start from.
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.
sort-order ENDOR_API_SORT_ORDER Sort resources in the specified order, ascending or descending (default ascending).
sort-path ENDOR_API_SORT_PATH Specify a field to sort resources by.
traverse ENDOR_API_TRAVERSE Get data from any child namespaces as well.

Examples

Use the --filter flag to customize your query and the --field-mask flag to limit the fields returned. For example, run the following command to list the description and the target dependency name for all findings in a given project:

endorctl api list \
  --resource Finding \
  --filter "spec.project_uuid==<uuid>" \
  --field-mask "meta.description,spec.target_dependency_package_name"

For more information on filters and field-masks, see Filters. and Masks.

Useful API commands

  • Get a count of the number of projects hosted in your Endor Labs tenant:
endorctl api list \
  --resource Project \
  --count \
  | jq -r '.count_response.count'
  • List all projects in the namespace and only return the name of each project:
endorctl api list \
  --resource Project \
  --list-all \
  --field-mask meta.name \
  | jq '.list.objects[].meta.name'
  • List all package versions at a given source code Git reference:
endorctl api list \
  --resource "PackageVersion" \
  --output-type "yaml" \
  --filter "spec.project_uuid==<uuid> and spec.source_code_reference.version.ref==<git-reference>"
  • List all direct dependencies of a specific package given its UUID.
endorctl api list \
  --resource DependencyMetadata \
  --filter "spec.importer_data.package_version_uuid==<UUID> and spec.dependency_data.direct==true"
  • Return a count of findings associated with the default branch for a given project:
endorctl api list \
  --resource Finding \
  --filter "context.type==CONTEXT_TYPE_MAIN and spec.project_uuid==<project-uuid>" \
  --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 for a given project:
endorctl api list \
  --resource Finding \
  --filter "context.type==CONTEXT_TYPE_MAIN and spec.project_uuid==<project-uuid> 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 \
  --resource ScanResult \
  --filter "context.id==default and meta.create_time >= date(2023-11-14)" \
  --count

For more examples, see Use cases.