This guide provides instructions to set up and configure Endor Labs to get started with your first project scan.
This is the multi-page printable view of this section. Click here to print.
Getting started
1 - Quick start
Log in to Endor Labs and select Getting Started page from the left navigation menu to view the options to get started.
You can choose to use the GitHub app or endorctl. You can also use GitHub Actions to scan demo projects and invite your teammates to try out Endor Labs.
1.1 - Quick start with GitHub App
This guide provides instructions on how to get started with Endor Labs using the Endor Labs GitHub App.
Prerequisites for GitHub App
Before installing and scanning projects with Endor Labs GitHub App, make sure you have:
- A GitHub cloud account and organization. If you don’t have one, create one at GitHub.
- Administrative permissions to your GitHub organization. Installing the Endor Labs GitHub App in your organization requires approval or permissions from your GitHub organizational administrator.
- Endor Labs GitHub App requires read permissions to Dependabot alerts, actions, administration, checks, code, commit statuses, issues, metadata, packages, pull requests, repository hooks, and security events. It does not need write access to any resources.
Quickstart with GitHub App
-
Log in to Endor Labs.
-
Select Getting Started from the left navigation menu.
-
Select SCAN WITH GITHUB APP.
-
Click Install GitHub App. Endor Labs GitHub App pages appears.
-
Click Install.
-
Select a user to authorize the app.
-
Select the organization in which you want to install the app.
-
Select whether to install and authorize Endor Labs on all your repositories or select the specific repositories that you wish to scan.
-
Click Install & Authorize.
If the button to install says **Install and Request** instead of **Install and Authorize**, you don't have permission to install the GitHub App. Select **Install and Request** to notify your organizational administrator of your request to install.
-
Select the Endor Labs namespace that you want to use and click Next.
-
Select the scanners that you wish to use and click Continue.
You will be redirected back to Endor Labs.
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.
1.2 - 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:
- Install Endor Labs on your local system
- Authenticate to Endor Labs
- Clone your repository
- Scan your first project
- 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
Tip
Replace https://github.com/username/repo-name.git with the actual URL of the Git repository you want to clone.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:
- Install software prerequisites
- Clone your repository
- Build your software
- Scan with Endor Labs for OSS risk
Tip
See the walkthrough on scanning an example repository usingendorctl
to learn how to perform a scan.
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.
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:
-
Clone the repository
https://github.com/OWASP-Benchmark/BenchmarkJava.git
git clone https://github.com/OWASP-Benchmark/BenchmarkJava.git
-
Navigate to the repository on your local system
cd BenchmarkJava
-
Build the repositories package with Maven:
mvn clean install
-
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:
-
Export your personal access token as an environment variable:
export GITHUB_TOKEN=<personal_access_token>
-
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.
2 - Log in to Endor Labs
You need an Endor Labs account and a tenant to use Endor Labs.
Tip
If you already have an Endor Labs account, sign in with your preferred authentication mechanism to get started.-
Visit https://app.endorlabs.com to access the login page.
-
If you already have an account, you can sign in with Google, GitHub, GitLab, your Enterprise SSO provider, or you can log in with an email link.
-
To start a free trial, click Sign up for a free trial and enter your email address. Make sure to enter a business email address. You can also choose to sign up with a Google Workspace account.
-
Check your email and open the complete sign up link in the same browser window.
-
Enter a name for your tenant and click Get Started. Tenant names can have a maximum of 32 characters and can contain lowercase letters (a-z), numbers (0-9) and the following characters (_ -).
-
Click Getting Started to see options available with your trial.
- Select Start Tour to take a guided tour of the application and understand its main features
- Select Explore Demo Sandbox to view Endor Labs capabilities and explore its features in a read-only tenant.
- Select SCAN WITH GITHUB APP to install the Endor Labs GitHub App.
- Select SCAN VIA GITHUB ACTIONS to scan a demo repository from GitHub and view findings.
- Select SCAN VIA CLI to set up your tenant and start scanning your repositories with the CLI.
-
See the quick start to set up with your first project scan.
3 - Endor Labs License Types
Endor Labs application is available as the following offerings:
Offering | Description |
---|---|
Endor Labs Supply Chain | Endor Labs Supply Chain is a single platform for open-source dependency management, CI/CD security, and compliance. |
Endor Labs Open Source Core | Endor Labs Open Source Core includes basic SCA and SBOM capabilities. |
Endor Labs Open Source Pro | Endor Labs Open Source Pro includes all components of Endor Labs Open Source Core with additional features. |
Endor Labs CI/CD | Endor Labs CI/CD includes components to strengthen the security posture of source code repositories and verify the integrity of your builds. |
Endor Labs SBOM Hub | Endor Labs SBOM Hub includes components to help manage your third-party SBOMs and generate findings. |
Endor Labs Secrets | Endor Labs Secrets includes components to help you detect and prevent secret leaks. |
For more details on Endor Labs’ offerings and the features they include, see pricing and packaging.
4 - Deploy Endor Labs
You can perform the following scans with the Endor Labs application.
You can start with Monitoring scans to gain the initial visibility and then advance to CI scans to achieve comprehensive and actionable results.
Monitoring or supervisory scans
Perform monitoring scans to gain fast and broad visibility over open source risks across the application portfolio without requiring integrations into application pipelines. These scans are conducted periodically and can also establish baselines that are subsequently used during CI scans.
-
GitHub App monitoring scan: You can perform this scan if you use GitHub. Use Endor Labs GitHub App to scan your GitHub organizations. It provides broad visibility over your GitHub organizations. Once installed, the GitHub App will automatically clone and scan all the repositories every 24 hours, providing continuous monitoring for open source vulnerabilities. These repositories are temporarily cloned and retained only during the scan. See Scan using the GitHub App.
-
Local monitoring scan: Perform periodic scans in your local environment. You must provide the necessary computing resources to run the scans. These scans are not restricted to GitHub and can support any type of Git repository. See Set up Jenkins pipeline for supervisory scans.
CI scans
CI Scans are used to focus teams’ attention and establish development workflows on the most actionable results, prioritizing the development team’s time. CI Scans can be triggered directly from automated CI/CD pipelines, looking for new vulnerabilities relative to the baseline established for the target branch. These CI Scans provide immediate feedback to developers in the form of PR comments and can also enforce policies to break builds, block PRs, send notifications, open tickets, and more. CI scans are the most actionable method to prevent vulnerabilities from entering your repositories.
Perform CI scans using:
- endorctl CLI
- Scan in GitLab pipeline
- Scan using GitHub Actions
- Scan with Circle CI
- Scan with Jenkins
See scanning strategies to learn techniques for effectively scanning and monitoring different versions of your projects with Endor Labs.
Scan from IDE
Use Endor Labs Visual Studio Plugin extension to perform early security reviews and mitigate the need for expensive fixes during later stages of development. The extension helps developers fix code at its origin phase and during the early stages of development without running the endorctl scan. See Scan from your IDE.