Endor Labs provides a GitHub App that continuously monitors users’ projects for security and operational risk. You can use the GitHub App to selectively scan your repositories for SCA, secrets, RSPM, or CI/CD tools.
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. If you don’t have the permissions, use the command line utility,
endorctl, while you wait for the approval. - 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.
Install the GitHub App
To automatically scan repositories using the GitHub App:
-
Sign in to Endor Labs.
-
Choose Projects and click Add Project.
-
From GITHUB, choose GitHub App
-
Click Install GitHub App.
You will be redirected to GitHub to install the GitHub App.
-
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.
-
Review the permissions required for Endor Labs and click Install and 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. Use the endorctl command line interface or select Install and Request to notify your organizational administrator of your request to install. -
Choose a namespace and click Next.
-
Based on your license, select and enable from the following list of available scanners.
- SCA- Perform software composition analysis.
- CI/CD - Scan the repository and identify all the CI/CD tools used in the repository.
- RSPM - Scan the repository for misconfigurations.
- Secret - Scan the repository for exposed secrets.
-
Click Continue. You have successfully installed the GitHub App.
Endor Labs GitHub App scans your repositories every 24 hours and reports any new findings or changes to release versions of your code.
Manage GitHub Apps on Endor Labs
You can edit or delete the GitHub App integrations.
To edit the GitHub App integration:
- Sign in to Endor Labs.
- Select Manage > Integrations from the left navigation menu.
- Click Manage next to GitHub under Source Control Managers.
- Click the ellipsis on the right side, and select Edit Integration.
- Based on your license, select and enable from the available list of scanners and click Save. The changes are applicable from the next scanning cycle.
- Use Reset to clear your selection.
To delete a GitHub App integration, click the ellipsis on the right side, and select Delete Integration.
To manually trigger a scan, click Rescan Org. Endor Labs GitHub App scans your repositories every 24 hours, use Rescan Org to manually schedule outside the 24-hour period.
Click Scan More Repositories to go to Projects page, from which you can add more repositories to scan through the GitHub App.
Set up package repositories
You can improve your experience with the GitHub App by setting up package repositories. This will help you create a complete bill of materials and perform static analysis. Without setting package repositories, you may not be able to get an accurate bill of materials. See Set up package manager integration for more information.
Technical limitations of the GitHub App
The Endor Labs GitHub App provides visibility across a GitHub organization, but it has technical limitations that do not account for the unique requirements of your application.
Here are some of these limitations.
Bill of materials variance
The Endor Labs GitHub App approximates software package builds to create a bill of materials and perform static analysis on your software dependencies. This requires building packages with specific versions of the package manager and runtime environment.
If there are differences in the build environment, it can result in variances in the bill of materials. For the most accurate information, use Endor Labs CLI as a post-build step in your software delivery process.
The following factors contribute to variances in the bill of materials:
- The time a software package was built.
- The version of a software package manager.
- The type of package manager being used.
- The version of the runtime environment on which a package is installed.
Custom package build steps
Endor Labs requires executing custom build steps outside of standard package manager commands to build software packages and get an accurate bill of materials and perform static analysis. Sometimes, a complete bill of materials may not be generated, or static analysis may not be performed.
Custom resource profiles
Large applications may require significant memory allocations to perform static analysis on a package. The services scanning the GitHub App use 16 GB of memory by default. Applications that require more memory may not obtain vulnerability prioritization information using the GitHub App. Scan large applications in a CI environment using a runner with sufficient resource allocations.
Authentication for private software components
Private software components hosted in an internal package repository may require authentication credentials to create a complete bill of materials or perform static analysis.
If your authentication information to your private package repository is hosted outside the repository, you will need to configure a package manager integration. See Set up package manager integration for more details.