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

Return to the regular view of this page.

endorctl CLI

Install, configure, and authenticate with the Endor Labs command-line interface.

Table of Contents

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

Return to the regular view of this page.

Install, configure, and authenticate with the Endor Labs command-line interface.

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

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.

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

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.

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

    npm install -g endorctl

  2. Run the following command to get the npm global bin directory.

    npm config get prefix

  3. Edit your shell configuration file and insert the path you obtained from the previous command.

    export PATH="/path/to/npm/global/bin:$PATH"

  4. Reload your shell configuration and verify endorctl is installed.

    endorctl --version

  5. To update your version of endorctl, run the following command.

    npm update -g endorctl

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

To download the endorctl binary directly use the following commands:

## 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 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. Select Projects from the left sidebar.
  3. Click 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.

Users can authenticate to Endor Labs several ways:

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

To log in with your supported authentication provider:

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 log in with your supported authentication provider in environments without a browser you can use headless mode:

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

To log in with an API key you’ll need to set the following 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
Note
If you do not have any projects in your namespace you will get an empty json output, which means you are successfully authenticated.

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.

Upon successful authentication to Endor Labs using endorctl, proceed to clone the repository you intend to scan. If you prefer initiating with a dummy app for scanning, feel free to skip to the next step.

To clone a Git repository, use the git clone command followed by the clone link of the repository. You can find the URL on the repository’s page on a platform like GitHub or GitLab. For example,

git clone https://github.com/username/repo-name.git

Replace https://github.com/username/repo-name.git with the actual URL of the Git repository you want to clone.

Navigate to the repository you’ve cloned.

cd <repo-name>

The following prerequisites must be met to scan with Endor Labs:

Language Package Managers / Build Tools Manifest files Runtime Requirements
Java Maven pom.xml JDK version 11-25; Maven 3.6.1 and higher versions
Gradle build.gradle JDK version 11-25; Gradle 6.0.0 and higher versions
Bazel workspace, MODULE.bazel, BUILD.bazel JDK version 11-25; Bazel versions 5.x.x, 6.x.x, and 7.x.x
Kotlin Maven pom.xml JDK version 11-25; Maven 3.6.1 and higher versions
Gradle build.gradle JDK version 11-25; Gradle 6.0.0 and higher versions
Golang Go go.mod, go.sum Go 1.12 and higher versions
Bazel workspace, MODULE.bazel, BUILD.bazel Bazel versions 5.x.x, 6.x.x, and 7.x.x
Rust Cargo cargo.toml, cargo.lock Rust 1.63.0 and higher versions
JavaScript npm package-lock.json, package.json npm 6.14.18 and higher versions
TypeScript npm package-lock.json, package.json npm 6.14.18 and higher versions
Yarn yarn.lock, package.json Yarn all versions
Rush rush.json, package.json; lock file in common/config/rush/ Rush (version in rush.json); set ENDOR_RUSH_ENABLED=true
Python pip requirements.txt Python 3.6 and higher versions; pip 10.0.0 and higher versions
Poetry pyproject.toml, poetry.lock
PDM pyproject.toml, pdm.lock
UV pyproject.toml, uv.lock
PyPI setup.py, setup.cfg, pyproject.toml
Bazel workspace, MODULE.bazel Bazel versions 5.x.x, 6.x.x, and 7.x.x
.NET (C#) NuGet *.csproj, package.lock.json, projects.assets.json, Directory.Build.props, Directory.Packages.props, *.props .NET 5.0 and higher versions; .NET Core 1.0 and higher versions; .NET Framework 4.5 and higher versions. Call graphs are supported for .NET 7.0.1 and higher versions.
Scala sbt build.sbt sbt 1.3 and higher versions
Gradle build.gradle, build.gradle.kts JDK version 11-25; Gradle 6.0.0 and higher versions
Ruby Bundler Gemfile, *.gemspec, gemfile.lock Ruby 2.6 and higher versions
Swift/Objective-C CocoaPods Podfile, Podfile.lock CocoaPods 0.9.0 and higher versions
SwiftPM Package.swift SwiftPM 5.0.0 and higher versions
PHP Composer composer.json, composer.lock PHP 5.3.2 and higher versions; Composer 2.2.0 and higher versions

For more information, see endorctl commands and working with the API.

To run a complete and accurate scan with Endor Labs, ensure that the software can be successfully built, incorporating well-formatted manifest files. To maximize the benefits of an Endor Labs OSS scan, you should perform a comprehensive testing as a post-build step, either locally or in a CI pipeline. Use the following commands to verify that the software can be built successfully with well-formatted manifest files before initiating the scan.

mvn dependency:tree
mvn clean install

gradle dependencies --configuration runtimeClasspath
./gradlew assemble
# Use `gradle assemble` if you do not have a gradle wrapper in your repository

npm install

yarn install

export ENDOR_PNPM_ENABLED=true
pnpm install

export ENDOR_RUSH_ENABLED=true
rush install

dotnet restore
dotnet build

composer install

go mod tidy

python3 -m venv venv
source venv/bin/activate
venv/bin/python3 -m pip install

poetry install

bundler install

pod install

sbt projects
sbt compile
sbt dependencyTree

gradle dependencies --configuration runtimeClasspath
./gradlew assemble
# Use `gradle assemble` if you do not have a gradle wrapper in your repository

cargo build

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.

Scan using endorctl

Use endorctl to perform comprehensive security analysis across your codebase, enabling you to detect dependency vulnerabilities, identify insecure code patterns, uncover exposed secrets, and evaluate GitHub configuration against best practices.

To run your first scan with Endor Labs, complete the following steps:

  1. Install Endor Labs on your local system
  2. Authenticate to Endor Labs
  3. Clone your repository
  4. Scan your first project

Endor Labs supports four distinct scan types to identify open source risk, code issues, leaked secrets, and configuration gaps.

Default namespace and access
When you run a scan, you can specify a namespace. If you leave it unspecified, projects are created in the root namespace of the tenant. That matters when your account or token only has access to specific namespaces. See Namespaces in Endor Labs for details.

To scan and monitor all packages in a given repository from the root of the repository, run the following command:

endorctl scan

If your project contains multiple programming languages, you can specify them as a comma-separated list using the --languages flag:

endorctl scan --languages=<languages-list>

Where <languages-list> should be provided as a comma-separated list from the supported languages: c,c#,go,java,javascript,kotlin,php,python,ruby,rust,scala,swift,typescript,swifturl.

To scan the example repository https://github.com/OWASP-Benchmark/BenchmarkJava.git, follow these steps after you authenticate to Endor Labs:

  1. Clone the repository https://github.com/OWASP-Benchmark/BenchmarkJava.git

    git clone https://github.com/OWASP-Benchmark/BenchmarkJava.git

  2. Navigate to the repository on your local system

    cd BenchmarkJava

  3. Build the repository’s package with Maven:

    mvn clean install

  4. Scan the repository

    endorctl scan

To run a SAST scan from the project root to identify potential security weaknesses in your source code, run the following command:

endorctl scan --sast

To scan a different working directory, set --path:

endorctl scan --sast --path=/path/to/code

To enable AI triage of SAST findings (Code Pro license required), add --ai-sast-analysis=agent-fallback. For prerequisites, flags, and AI analysis behavior, see Run a SAST scan.

AI-assisted SAST triage
You can enable AI-assisted triage using --ai-sast-analysis=agent-fallback. See Run a SAST scan for details.

To scan for all potentially leaked secrets in the checked out branch of your repository, run the following command:

endorctl scan --secrets

Often, secrets are leaked outside the context of your repositories main branch and can be found in older branches or those that are under active development. To identify these, Endor Labs inspects the Git logs of the repository.

To scan for all potentially leaked secrets in all branches of your repository, run the following command:

endorctl scan --secrets --git-logs

See Scan for leaked secrets for additional configuration options and workflow details.

Endor Labs allows teams to scan their repository for configuration best practices in alignment with organizational policy.

To scan the GitHub repository, you must have:

  • The GitHub repository HTTPS clone URL
  • A personal access token with access administrative access to the repository. For help creating a personal access token see GitHub documentation.

If you are on a self-hosted GitHub Enterprise Server, you should also have:

  • The GitHub API URL (This is typically the FQDN of the GitHub server)
  • A local copy of the CA Certificate if the certificate is self-signed or from a private CA

To scan a GitHub repository for misconfigurations:

  1. Export your personal access token as an environment variable:

    export GITHUB_TOKEN=<personal_access_token>

  2. Scan the repository to retrieve configuration information and analyze the configuration against organizational policy or configuration best practices:

    endorctl scan --repository-http-clone-url=https://github.com/<organization>/<repository>.git --github

For source control systems on the GitHub Enterprise Server, you must set the --github-api-url flag to your GitHub Enterprise server domain name:

endorctl scan --github-api-url=https://<fully_qualified_domain_name_to_GitHub_Enterprise_Server> --repository-http-clone-url=https://<fully_qualified_domain_name_to_GitHub_Enterprise_Server>/<organization>/<repository>.git --github