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 endorctl api command supports the following subcommands:

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 endorctl api subcommands support the following flags, unless specified otherwise:

Commonly used resource types

The following table lists resource types that are commonly used in the API. See resource kind for more information.

Resource kinds are case sensitive.

endorctl api create

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

endorctl api create -r [resource] [flags]

endorctl api create interactive mode

Use --interactive or -i to create an object with an interactive code editor.
- Define your editor using export EDITOR=<editor> where the editor is the command you use 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 VS Code.

endorctl api create 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}}}'

endorctl api delete

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

endorctl api delete -r [resource] [flags]

endorctl api delete example

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

endorctl api delete -r Project --uuid 62aa1cfadfa47d9ccb754d22

endorctl api get

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

endorctl api get -r [resource] [flags]

endorctl api get examples

Get a specific project by its UUID.

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

Get a specific package version.

endorctl api get --resource "PackageVersion" --name "<ecosystem>://<name>@<version>"

endorctl api list

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]

endorctl api list flags and variables

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

endorctl api list 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. 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 in non-test dependencies for a given project. Filters to vulnerabilities with an upstream patch available and a reachable function.

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 date.

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

See Use cases for more examples.

endorctl api update

endorctl api update -r [resource] [flags]

endorctl api update 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 the command you use 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 VS Code.
- Specify which fields you want to update using the --field-mask parameter. If this is not set, endorctl will try to update all fields.

endorctl api update examples

To interactively update a project with the UUID 6549886f0dd828140b4a477b.

endorctl api update -r Project -i --uuid 6549886f0dd828140b4a477b --field-mask meta.tags

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'

Developers & API

endorctl CLI

REST API

Usage

Flags and variables

Commonly used resource types

endorctl api create

endorctl api create interactive mode

endorctl api create examples

endorctl api delete

endorctl api delete example

endorctl api get

endorctl api get examples

endorctl api list

endorctl api list flags and variables

endorctl api list examples

endorctl api update

endorctl api update interactive mode

endorctl api update examples

​Usage

​Flags and variables

​Commonly used resource types

​endorctl api create

​endorctl api create interactive mode

​endorctl api create examples

​endorctl api delete

​endorctl api delete example

​endorctl api get

​endorctl api get examples

​endorctl api list

​endorctl api list flags and variables

​endorctl api list examples

​endorctl api update

​endorctl api update interactive mode

​endorctl api update examples

Usage

Flags and variables

Commonly used resource types

endorctl api create

endorctl api create interactive mode

endorctl api create examples

endorctl api delete

endorctl api delete example

endorctl api get

endorctl api get examples

endorctl api list

endorctl api list flags and variables

endorctl api list examples

endorctl api update

endorctl api update interactive mode

endorctl api update examples