Quick start 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

• Homebrew
• npm
• Apple Silicon Executable
• Intel Executable

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
• Executable

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
• Executable

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.

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

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
• Scan for leaked secrets
• Scan for GitHub misconfigurations

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:

• A local installation of Git or the ability to clone repositories in CI. See the Git documentation for instructions on installing Git
• A runtime environment and build tools for supported software development languages your team uses must be installed on any system used for testing. For more information, see Supported languages and frameworks.

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

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.

• Java (Maven)
• Java (Gradle)
• JavaScript (npm)
• JavaScript (yarn)
• JavaScript (pnpm)
• .NET (dotnet)
• PHP (composer)
• Golang
• Python (pip)
• Python (poetry)
• Ruby (bundler)
• Swift/Objective-C
• Scala (sbt)
• Rust (Cargo)

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.