Skip to main content
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:

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

​
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 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 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'