This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

api

Use the api command to interact with the Endor Labs API

The endorctl api command allows you to interact with the Endor Labs API directly through the command line interface.

Usage

The syntax of the endorctl api command is:

endorctl api [subcommand] [flags]

The following subcommands are supported:

  • create creates a specified object in a namespace.
  • delete deletes a specified object in a namespace.
  • get gets a specified object in a namespace.
  • list lists a specified group of objects in a namespace.
  • update updates a specified object in a namespace.

Flags and variables

The following flags are supported for all endorctl api subcommands, unless specified otherwise:

Flag Environment Variable Description
data ENDOR_API_DATA Define the object you want to create or update in json format.
field-mask ENDOR_API_FIELD_MASK Specify a list of fields to return or update.
filter ENDOR_API_FILTER Specify the query parameters for a list command.
header ENDOR_API_HEADER Specify request header information in the following format: key:value
interactive ENDOR_API_INTERACTIVE Create or update an object interactively. Requires the environment variable EDITOR to be set (e.g. export EDITOR=vim).
name ENDOR_API_NAME Specify the name of the resource that you want to interact with.
output-type ENDOR_API_OUTPUT_TYPE Specify the output format of the response. The default output type is json, but can also be set to yaml or table.
resource ENDOR_API_RESOURCE Specify the resource type that you want to interact with. See commonly used resource types below for a list of supported resource types.
timeout ENDOR_API_TIMEOUT Specify the timeout limit for the command. The default is 30s, but larger and/or more complicated requests may require more time (resulting in a “context deadline exceeded” error).
uuid ENDOR_API_UUID Specify the UUID of the resource that you want to interact with.

Commonly used resource types

The following table lists resource types that are commonly used in the API. See the API documentation to get a full list of resource types.

Resource Kind Description
Project A project represents a configuration for ingesting source control repositories. List all projects by calling endorctl api list -r Project.
Repository A repository represents information about a source control repository where source code is hosted. List all repositories for a project by filtering on meta.parent_uuid==<uuid>.
RepositoryVersion A repository version represents information about a specific version of code in source control, such as commit SHAs, tags or branches. List all repository versions for a project by filtering on meta.parent_uuid==<uuid>.
PackageVersion A package version represents information about a named version of a package. List all package versions for a project by filtering on spec.project_uuid==<uuid>.
DependencyMetadata A dependency metadata object represents the relationship between the root package version (importer) and a given dependency. List all dependency metadata objects for a project by filtering on spec.importer_data.project_uuid==<uuid>.
Metric A metric object contains the output of a given analytic. List all metric objects for a project by filtering on spec.project_uuid==<uuid>.
Finding A finding represents a result of an evaluation method used to evaluate code against a rule. List all findings for a project by filtering on spec.project_uuid==<uuid>.
ScanResult A scan result contains metadata about a particular scan (configuration, results etc.). List all scan results for a project by filtering on meta.parent_uuid==<uuid>.
AuthorizationPolicy An authorization policy represents a policy for access control. List all authorization policies by calling endorctl api list -r AuthorizationPolicy.

Example

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"

Useful API commands

  • 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>"
  • Get a specific package version:
endorctl api get --resource "PackageVersion" --name "<ecosystem>://<name>@<version>"
  • Get a count of the number of projects hosted in your Endor Labs tenant:
endorctl api list --resource Project --count
  • 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 of the 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"

1 - create

Use the create command to create a specified resource through the API

Usage

The endorctl api create command creates an object of a specified resource type.

endorctl api create -r [resource] [flags]

Examples

To create a package manager integration that uses the repository https://example.replaceme.com for dependency resolution in Python with the top priority for dependency resolution use the following command:

endorctl api create -r PackageManager \
    --data '{"meta":{"name":"pypi PackageManager"},"spec":{"pypi":{"url":"https://example.replaceme.com ","priority":0}}}'

2 - delete

Use the delete command to delete a specified resource through the API

Usage

The endorctl api delete command deletes a given object of a specified resource type.

endorctl api delete -r [resource] [flags]

Examples

Use the following command to delete the project with UUID ‘62aa1cfadfa47d9ccb754d22’ that is no longer needed.

endorctl api delete -r Project --uuid 62aa1cfadfa47d9ccb754d22

3 - get

Use the get command to retrieve a specified resource through the API

Usage

The endorctl api get command retrieves a given object of a specified resource type.

endorctl api get -r [resource] [flags]

Examples

To get a specific project by its UUID:

endorctl api get -r Project --uuid <uuid>

4 - 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

5 - update

Use the update command to update an API object.

Usage

endorctl api update -r [resource] [flags]

Interactive Mode

  • Use --interactive or -i to update an object with an interactive code editor.
    • Define your editor using export EDITOR=<editor> where the editor is defined as the command used to edit files. For example, export EDITOR=vi allows you to edit in vi and export EDITOR=code opens the file with the code command in VScode.

Examples

To interactively update a project with the UUID of 6549886f0dd828140b4a477b:

endorctl api update -r Project -i --uuid 6549886f0dd828140b4a477b

To add a tag “CrownJewel” to a project named https://github.com/endorlabs/github-action use the following command:

endorctl api update -r Project \
  --name https://github.com/endorlabs/github-action \
  --data "{ \"meta\": {\"tags\": [ \"CrownJewel\" ] }}" \
  --field-mask 'meta.tags'