api

• 1: create
• 2: delete
• 3: get
• 4: list
• 5: update

1 - create

Usage

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

endorctl api create -r [resource] [flags]

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.

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

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 the UUID, ‘62aa1cfadfa47d9ccb754d22’, that is no longer needed.

endorctl api delete -r Project --uuid 62aa1cfadfa47d9ccb754d22

3 - get

Usage

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

endorctl api get -r [resource] [flags]

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

4 - list

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:

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.

5 - update

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

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'