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 Type Description
count ENDOR_API_COUNT boolean (default:false) Get the number of items in the list.
filter ENDOR_API_FILTER json Specify query parameters used to filter resources.
group-aggregation-paths ENDOR_API_GROUP_AGGREGATION_PATHS json Specify one or more fields to group resources by.
group-show-aggregation-uuids ENDOR_API_GROUP_SHOW_AGGREGATION_UUIDS boolean (default:false) 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 json Count the number of unique values, for these fields, in the group.
group-unique-value-paths ENDOR_API_GROUP_UNIQUE_VALUE_PATHS json Get the unique values, for these fields, in the group.
list-all ENDOR_API_LIST_ALL boolean (default:false) List all resources (use -tor --timeout to increase timeout for big queries).
page-id ENDOR_API_PAGE_ID string Set the page ID to start from.
page-size ENDOR_API_PAGE_SIZE integer Set the page size to limit the number of results returned (default is 100).
page-token ENDOR_API_PAGE_TOKEN string Set the page token to start from.
pr-uuid ENDOR_API_PR_UUID string (UUID format) Only list resources from a specific PR scan.
sort-order ENDOR_API_SORT_ORDER string Sort resources in the specified order, ascending or descending (default ascending).
sort-path ENDOR_API_SORT_PATH string Specify a field to sort resources by.
traverse ENDOR_API_TRAVERSE boolean (default:false) 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"

See Filters and Masks for more information on filters and field-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

See Use cases for more examples.