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

Return to the regular view of this page.

Quick start with endorctl

Get up and running quickly with endorctl.

This guide provides step-by-step instructions to set up and configure an Endor Labs tenant while getting started with your first project scan in your local system.

Use the following steps to scan your first project with Endor Labs:

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

Install Endor Labs on your local system

Install or update the Endor Labs CLI (endorctl) for your operating system.

macOS

brew tap endorlabs/tap
brew install endorctl
npm install -g endorctl

### Run the following command to get the npm global bin directory:
npm config get prefix

### Open your shell configuration file and insert the path you obtained with the above command:
export PATH="/path/to/npm/global/bin:$PATH"

### Reload your shell configuration and verify endorctl is installed:
endorctl --version

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

Linux

npm install -g endorctl

### Run the following command to get the npm global bin directory:
npm config get prefix

### Open your shell configuration file and insert the path you obtained with the above command:
export PATH="/path/to/npm/global/bin:$PATH"

### Reload your shell configuration and verify endorctl is installed:
endorctl --version
### 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"

Windows

npm install -g endorctl

### Run the following command to get the npm global bin directory:
npm config get prefix

### Add the path from the above command to the System property 'Path' in your Environment variable settings.

### Open a new Command prompt and verify endorctl is installed:
endorctl --version
### Download the latest CLI for Windows
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

For more details, see Install and configure endorctl

Authenticate to Endor Labs

To authenticate your client with Endor Labs, utilize the built-in command endorctl init along with an external identity provider. Endor Labs supports multiple identity providers, including Google, GitHub, GitLab, Email link authentication, and Custom Identity Provider through Enterprise SSO. Examples of such enterprise SSO solutions include Google, GitHub, GitLab, or your organization’s specific choice.

For more information, see Install and configure endorctl.

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>

Clone your repository

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

Finally, navigate to the repository you’ve cloned to complete the following steps:

cd <repo-name>

Run your first scan

Endor Labs supports three distinct scan types. See each section for instructions on how to run each scan type with Endor Labs.

Scan for OSS risk

Follow these steps to scan with Endor Labs for open source risk:

  1. Install software prerequisites
  2. Clone your repository
  3. Build your software
  4. Scan with Endor Labs for OSS risk

Install software prerequisites

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

For more information on supported languages, package managers and build systems and the requirements for each language, see their respective page.

Language Package Managers / Build Tool Manifest files Runtime Requirements
Java Maven pom.xml JDK version 11-22; Maven 3.6.1 and higher versions
Gradle build.gradle JDK version 11-22; Gradle 6.0.0 and higher versions
Bazel workspace, MODULE.bazel, BUILD.bazel JDK version 11-22; Bazel versions 5.x.x, 6.x.x, and 7.x.x
Kotlin Maven pom.xml JDK version 11-22; Maven 3.6.1 and higher versions
Gradle build.gradle JDK version 11-22; 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
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
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 1.0 and higher versions
Scala sbt build.sbt sbt 1.3 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
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.

Build your software

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 compileClasspath
./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
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
cargo build

Scan your project for OSS risk

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

endorctl scan

Scanning an example repository

To scan an example repository https://github.com/OWASP-Benchmark/BenchmarkJava.git, you must perform the following steps after successfully authenticating 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 repositories package with Maven:

    mvn clean install
    
  4. Scan the repository

    endorctl scan
    

Scanning for leaked secrets

The following procedure should be used to scan with Endor Labs for potential secrets leaked into your source code.

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

Scan for GitHub misconfigurations

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

Pre-requisites

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

Running a misconfiguration scan

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

Review the results of your project

Sign in to the Endor Labs user interface, click Projects on the left sidebar, and select your project to review the scan results.