Endor Labs CLI

• 1: Install and configure endorctl
• 2: Commands
• 2.1: api
• 2.1.1: create
• 2.1.2: delete
• 2.1.3: get
• 2.1.4: list
• 2.1.5: update
• 2.2: artifact sign
• 2.3: completion
• 2.4: help
• 2.5: host-check
• 2.6: init
• 2.7: sbom
• 2.7.1: export
• 2.7.2: import
• 2.8: scan
• 2.9: sync-org
• 2.10: validate policy
• 3: Global flags and environment variables

1 - Install and configure endorctl

Perform software composition analysis, dependency management, or detect secrets in your code using Endor Labs.

Download and install endorctl

Use one of the following methods to download and install endorctl on your local system. After you install endorctl, you must authenticate. Then you can start scanning your code.

Install endorctl with Homebrew

Use Homebrew to efficiently install endorctl on macOS and Linux operating systems making it easy to manage dependencies, and track installed packages with their versions.

Install endorctl from the Endor Labs tap with Homebrew by running the following commands. The tap is updated regularly with the latest endorctl release.

brew tap endorlabs/tap
brew install endorctl

Install endorctl with npm

Use npm to efficiently install endorctl on macOS, Linux, and Windows operating systems making it easy to manage dependencies, track and update installed packages and their versions.

Make sure that you have npm installed in your local environment and use the following command to install endorctl using npm.

npm install -g endorctl

endorctl is available as an npm package and is updated regularly with the latest endorctl release.

Download and install the endorctl binary directly

To download the endorctl binary directly use the following commands:

• Linux
• Mac OS
• Windows

## Download the latest CLI for Linux amd64
curl https://api.endorlabs.com/download/latest/endorctl_linux_amd64 -o endorctl

## Verify the checksum of the binary
echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_linux_amd64)  endorctl" | sha256sum -c

## Modify the permissions of the binary to ensure it is executable
chmod +x ./endorctl

## Create an alias endorctl of the binary to ensure it is available in other directory
alias endorctl="$PWD/endorctl"

### Download the latest CLI for MacOS ARM64
curl https://api.endorlabs.com/download/latest/endorctl_macos_arm64 -o endorctl

### Verify the checksum of the binary
echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_macos_arm64)  endorctl" | shasum -a 256 -c

### Modify the permissions of the binary to ensure it is executable
chmod +x ./endorctl

### Create an alias endorctl of the binary to ensure it is available in other directory
alias endorctl="$PWD/endorctl"

### Download the latest CLI for MacOS AMD64
curl https://api.endorlabs.com/download/latest/endorctl_macos_amd64 -o endorctl

### Verify the checksum of the binary
echo "$(curl -s https://api.endorlabs.com/sha/latest/endorctl_macos_amd64)  endorctl" | shasum -a 256 -c

### Modify the permissions of the binary to ensure it is executable
chmod +x ./endorctl

### Create an alias endorctl of the binary to ensure it is available in other directory
alias endorctl="$PWD/endorctl"

## Download the latest CLI for Windows amd64
curl -O https://api.endorlabs.com/download/latest/endorctl_windows_amd64.exe
## Check the expected checksum of the binary file
curl https://api.endorlabs.com/sha/latest/endorctl_windows_amd64.exe
## Verify the expected checksum and the actual checksum of the binary match
certutil -hashfile .\endorctl_windows_amd64.exe SHA256
## Rename the binary file
ren endorctl_windows_amd64.exe endorctl.exe

You can also view these instructions via the Endor Labs application user interface:

1. Sign in to Endor Labs.
2. Navigate to the Projects list
3. Select Add Project
4. Choose CLI
5. Follow the on-screen instructions to download and install the appropriate version and architecture of endorctl for your system.

You can download all versions from endorctl versions. To install endorctl you must select the appropriate version and architecture for your machine.

Authenticate to Endor Labs

Users can authenticate to Endor Labs several ways:

1. Using the init command
2. With an API token

Login with the init command

To login with your supported authentication provider:

• Google
• GitHub
• GitLab
• Email
• SSO

endorctl init --auth-mode=google

endorctl init --auth-mode=github

endorctl init --auth-mode=gitlab

endorctl init --auth-email=<insert_email_address>

endorctl init --auth-mode=sso --auth-tenant=<insert-your-tenant>

To login with your supported authentication provider in environments without a browser you can use headless mode:

• Google
• GitHub
• GitLab
• Email
• SSO

endorctl init --auth-mode=google --headless-mode

endorctl init --auth-mode=github --headless-mode

endorctl init --auth-mode=gitlab --headless-mode

endorctl init --auth-email=<insert_email_address> --headless-mode

endorctl init --auth-mode=sso --auth-tenant=<insert-your-tenant> --headless-mode

Login with an API Key

To login with an API key you’ll need to set several environment variables:

• ENDOR_API_CREDENTIALS_KEY - The API key used to authenticate against the Endor Labs API.
• ENDOR_API_CREDENTIALS_SECRET - The API key secret used to authenticate against the Endor Labs API.
• ENDOR_NAMESPACE - The Endor Labs namespace you would like to scan against. You can locate the namespace from the top left hand corner of the screen under the Endor Labs logo on the Endor Labs application.

To get an API Key and secret for use with endorctl, see Managing API Keys.

To set your environment variables run the following commands and replace each example with the appropriate value:

export ENDOR_API_CREDENTIALS_KEY=<example-api-key>
export ENDOR_API_CREDENTIALS_SECRET=<example-api-key-secret>
export ENDOR_NAMESPACE=<example-tenant-namespace>

Once you’ve exported your environment variables you can test successful authentication by running the following command to list projects in your namespace:

endorctl api list -r Project --page-size=1

Print your access token

Once you have successfully initialized endorctl, you can print your access token with the following command:

endorctl auth --print-access-token

The token has an expiration time of 4 hours.

Persistently set environment variables for endorctl

To persistently set an environment variable, append the environment variable and the value to ~/.endorctl/config.yaml. This configuration file is for CLI usage.

For example, if your GitHub Enterprise Server URL was https://api.github.com you can set the variable to persist in your configuration using the following command:

echo ENDOR_SCAN_SOURCE_GITHUB_API_URL=https://api.github.com >> ~/.endorctl/config.yaml

See endorctl commands for all supported commands and environment variables.

2 - Commands

2.1 - 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:

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.

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"

2.1.1 - create

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

endorctl api delete -r Project --uuid 62aa1cfadfa47d9ccb754d22

2.1.3 - get

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>

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

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

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

2.2 - artifact sign

Use the artifact [ sign \| verify ] command to sign and verify container images and other build artifacts.

Usage

To sign an artifact, use the following command:

endorctl artifact sign --name <artifact> --source-repository-ref <ref> --certificate-oidc-issuer <issuer>

To verify a signed artifact, use the following command:

endorctl verify --name <artifact> --certificate-oidc-issuer <issuer>`

To revoke a signature, use the following command:

endorctl artifact revoke-signature --name <artifact> --source-repository-ref <ref>

Options

You can use the following flags and environment variables:

For endorctl artifact sign

For endorctl artifact verify

For endorctl artifact [revoke-signature ]

2.3 - completion

The completion command for endorctl outputs a completion script that may be added to your local environment. Once run this script will enable tab autocompletion for endorctl.

Supported command completion environments are zsh, powershell, bash and fish.

Command completion for zsh shells

To enable command completion for a MacOS based zsh environment:

echo "source $(endorctl completion zsh)" >> ~/.zshrc
source ~/.zshrc

You will need to start a new shell for this setup to take effect.

Command completion for bash shells

To enable command completion for a Linux bash based shell:

echo "source $(endorctl completion zsh)" >> ~/.bashrc
source ~/.bashrc

You will need to start a new shell for this setup to take effect.

Command completion for Powershell

To load completions in your current shell session:

endorctl completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command to your powershell profile.

Command completion for Fish shells

To load completions in your current shell session:

endorctl completion fish | source

To load completions for every new session, execute once:

endorctl completion fish > ~/.config/fish/completions/endorctl.fish

You will need to start a new shell for this setup to take effect.

Usage

There are no flags that apply to endorctl completion.

2.4 - help

The help command lists all available commands for endorctl scan.

Examples

endorctl help

Usage

endorctl help
Endorctl is a command-line tool that allows you to scan and monitor your projects, import and export SBOMs, and interact with the API. Using endorctl you can connect to your Endor Labs tenant and integrate it into your CI pipeline.

Usage:
  endorctl [flags]
  endorctl [command]

Available Commands:
  api         Interact with the Endor Labs API
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  host-check  Validate host machine environment and configuration
  init        Initialize or reinitialize endorctl
  recommend   Recommendations for dependency maintenance
  sbom        SBOM operations
  scan        Scan a source code repository
  sync-org    Sync GitHub repositories for a specified organization
  validate    Validate a policy

Flags:
  -a, --api string                   Set the API URL for the Endor Labs Application (default "https://api.endorlabs.com")
      --api-key string               Set the API key used to authenticate with Endor Labs
      --api-secret string            Set the secret corresponding to the API key used to authenticate with Endor Labs
      --aws-role-arn string          Set the target role ARN for AWS based authentication. AWS authentication is only enabled if this flag is set
      --bypass-host-check            Bypass the check that verifies that the host machine is correctly setup to use endorctl
      --config-path string           Set the local filesystem path to the endor config directory containing your endor environment variables
      --enable-github-action-token   Enable keyless authentication using Github action OIDC tokens
      --gcp-service-account string   Set the target service account for GCP based authentication. GCP authentication is only enabled if this flag is set
  -h, --help                         help for endorctl
      --log-level string             Set the log level (default "info")
  -n, --namespace string             Set to the namespace of the project that you are working with
      --pre-commit-checks            Perform Git pre-commit checks on the changeset about to be committed
      --token string                 Set the authentication token used to authenticate with Endor Labs
      --verbose                      Enable verbose logging
  -v, --version                      version for endorctl

Use "endorctl [command] --help" for more information about a command.

2.5 - host-check

The command endorctl host-check allows you to quickly verify if your system is setup with the appropriate tools to perform a successful scan.

Usage

To verify that your local host is appropriately configured to scan a given repository:

1. Clone the repository you’d like to verify system setup for. The following instructions should be updated to the repository of your selection.

git clone https://github.com/endorlabs/app-java-demo.git

2. Navigate to the root of the repository you’ve cloned:

cd ./app-java-demo

3. Run the host check command:

endorctl host-check

To verify that your local host is appropriately configured with AI reccomendations on how to address any issues perform the following procedure and add the --droid-gpt flag to the host check command:

endorctl host-check --droid-gpt

Options

The endorctl host-check command uses the following flags and environment variables:

2.6 - init

The command endorctl init allows you to quickly authenticate your client to Endor Labs using an external identity provider.

Supported authentication providers for endorctl init are:

• google - Used to create an API key and API key secret when you sign in with Google Workspaces as your external identity provider.
• github - Used to create an API key and API key secret when you sign in with GitHub Cloud as your external identity provider.
• gitlab - Used to create an API key and API key secret when you sign in with GitLab Cloud as your external identity provider.
• email - Used to create an API key and API key secret when you sign in with an email lin.
• sso - Used to sign in with a Custom Enterprise Identity Provider, such as Okta.

Usage

To login with your supported authentication provider:

• Google
• GitHub
• GitLab
• Email
• SSO

endorctl init --auth-mode=google

endorctl init --auth-mode=github

endorctl init --auth-mode=gitlab

endorctl init --auth-email=<insert_email_address>

endorctl init --auth-mode=sso --auth-tenant=<insert-your-tenant>

To login with your supported authentication provider in environments without a browser you can use headless mode:

• Google
• GitHub
• GitLab
• Email
• SSO

endorctl init --auth-mode=google --headless-mode

endorctl init --auth-mode=github --headless-mode

endorctl init --auth-mode=gitlab --headless-mode

endorctl init --auth-email=<insert_email_address> --headless-mode

endorctl init --auth-mode=sso --auth-tenant=<insert-your-tenant> --headless-mode

Once you’ve issued the command in headless mode please navigate to an internet/browser accessible computer and follow the instructions provided in your terminal.

Options

The following flags and environment variables are available for the init command.

2.7 - sbom

The endorctl sbom command allows you to import or export SBOMs to or from Endor Labs.

Usage

The syntax of endorctl sbom is as follows:

endorctl sbom [subcommand] [flags]

The following subcommands are supported as part of endorctl api:

• endorctl sbom import imports an SBOM to be managed by Endor Labs.
• endorctl sbom export allows you to export an SBOM from Endor Labs.

Options

2.7.1 - export

The sbom export command allows you to export an SBOM for a specified package from Endor Labs.

Usage

To export an SBOM for a specified package version named “go://github.com/Dreamacro/clash@master” in Endor Labs.

endorctl sbom export --package-version-name=go://github.com/Dreamacro/clash@master

To export an SBOM for a specified package version given its UUID with the UUID of “653c625cd44ec559e19349dc” to a file called “sbom.json”

endorctl sbom export --package-version-uuid=653c625cd44ec559e19349dc >> sbom.json

Options

2.7.2 - import

The sbom import command allows you to import SBOMs to Endor Labs to track your third party risk.

Usage

To import an SBOM to Endor Labs use the following command:

• CycloneDX Format
• SPDX Format

endorctl sbom import --sbom-file-path=/path/to/your/sbom.json

endorctl sbom import --format=spdx --sbom-file-path=/path/to/your/sbom.json

Options

2.8 - scan

Use the scan command to perform scans against a repository.

Usage

To perform a full scan including reachability analysis for the open source software of the packages you build in a repository and monitor the checked out version of your code run the command:

endorctl scan

To scan leaked secrets and monitor all results in the checked out version of your repository:

endorctl scan --secrets

To scan for leaked secrets in all branches of your repository use the command:

endorctl scan --secrets --git-logs

To scan for misconfigurations in a GitHub repository (i.e https://github.com/endorlabs/app-java-demo):

export GITHUB_TOKEN=<insert-your-github-token>
endorctl scan --github --repository-http-clone-url=https://github.com/endorlabs/app-java-demo

To scan for CI/CD tools run the following command:

export GITHUB_TOKEN=<insert-your-github-token-with-read:org-access>
endorctl scan --tools --github

To include GitHub application data you must also set the --github flag and provide a GitHub token with read:org access.

To run a scan as a test in a pull request without monitoring the version of your code over time run the command:

endorctl scan --pr

To scan and discover GitHub action workflows (Beta) in your ci-cd pipeline run the command:

endorctl scan --ghactions

Along with performing the regular dependency analysis on your repository, it discovers the GitHub actions configured in your CI/CD pipeline and maps them as GitHub action dependencies in your package.

To scan binaries and artifacts run the following command:

endorctl scan --package --path --project-name

You must provide the path of your file using --path and specify a name for your project using --project-name.

Options

The command endorctl scan uses the following flags and environment variables:

2.9 - sync-org

Use the endorctl sync-org command to create projects for all the unscanned repositories in your GitHub organization. This does not automatically scan the projects. It creates projects in Endor Labs, measures scan coverage across a GitHub organization, and gives you visibility into your source control repository.

Usage

To sync your GitHub organization to Endor Labs:

• Export a GitHub token that can read all projects in your GitHub organization. To run the sync-org command you need at least repo and read:org permissions.

export GITHUB_TOKEN=<insert-github-token>

• Run the sync-org command

endorctl sync-org --name=endorlabs

Options

The endorctl sync-org command uses the following flags and environment variables:

2.10 - validate policy

Use the command endorctl validate policy to validate a rego policy against data for a specified project.

Usage

To verify that a rego policy is correctly formatted:

1. First, select a rego policy. Lets take the example policy below that searches for dependencies with an Endor Labs overall score of less than 7. You can save this as test_policy.rego.

package example

match_package_version[result] {
  some i, j
  data.resources.Metric[i].meta.name == "package_version_scorecard"
  data.resources.Metric[i].meta.parent_kind == "PackageVersion"
  data.resources.Metric[i].meta.parent_uuid == data.resources.PackageVersion[_].uuid
  score := data.resources.Metric[i].spec.metric_values["scorecard"].score_card.overall_score
  score < 7

  result = {
    "Endor": {
      "PackageVersion": data.resources.Metric[i].meta.parent_uuid,
    },
    "Score": sprintf("%v", [score])
  }
}

2. Next validate that the policy is correctly formatted.

endorctl validate policy --policy test_policy.rego

To validate the policy against real data:

endorctl validate policy --policy test_policy.rego --query "data.example.match_package_version" --uuid $PROJECT_UUID

Options

The endorctl validate policy command uses the following flags and environment variables:

3 - Global flags and environment variables

Every command-line flag has a corresponding environment variable that can be set instead of the flag, either directly in your environment or in a dedicated configuration file.

See config-path description in Global Flags and Variables and Set environment variables for details.

To set a command-line flag on the endorctl scan command you can specify the flag with a leading -- for full flag names or a leading - for short flag aliases. If applicable, input arguments are specified after the flag and separated from it with either a blank space or a = character. For example, to set the output-type specify --output-type json or -o=json. If the input argument is a list, then the list elements are separated by a , character, for example --languages=go,python.

Global flags and variables

The following Global flags are supported and configurable for any endorctl command:

Set endorctl environment variables

To set an environment variable run the following command:

export <environment variable>=<value>

For example to set the environment variable ENDOR_TOKEN to “mytoken” run the following command:

export ENDOR_TOKEN=mytoken