With the Endor Labs GitHub App, you can enhance the security of your repository through the following types of scans.

Scan complete repository

The Endor Labs GitHub App automatically scans your repositories every 24 hours for potential security issues and operational risks, providing up-to-date information about your projects’ security posture.

• You can use the GitHub App to selectively scan your repositories for Software Composition Analysis (SCA), secrets, Repository Security Posture Management (RSPM), or CI/CD tools.
• While the automated scan happens every 24 hours, you can manually trigger a rescan outside this schedule from the Endor Labs user interface. See Rescan projects.
• After each scan, the GitHub App reports any new findings or changes to release versions of your code. Review the scan results from the Endor Labs user interface.

Scan PRs

After scanning the complete repository, it’s important to address the pull requests submitted by users. Administrators can enable a fully automated scanning process for all pull requests and merges initiated into the main branch.

To automatically scan the PRs, set the pull request preferences during the installing of the GitHub App or edit the integration preferences afterward.

Whenever a PR is created against a repository, the Endor Labs GitHub App performs an incremental scan to detect any changes in resolved dependencies that may introduce new vulnerabilities. These incremental scans are CI runs and are not monitored. You can see the results of the scan on GitHub.

Based on your preferences, it performs a quick scan or a full scan before merging the PRs into the main branch.

• Quick Scan performs dependency resolution but does not conduct reachability analysis to prioritize vulnerabilities. The quick scan enables users to swiftly identify potential vulnerabilities in dependencies, ensuring a smoother and more secure merge into the main branch.
• Full Scan performs dependency resolution, reachability analysis, and generate call graphs for supported languages and ecosystems. This scan enables users to get complete visibility and identifies all issues related to dependencies and call graph generation, before merging into the main branch. Full scans may take longer to complete, potentially delaying PR merges.

Endor Labs enables you to rescan your GitHub projects. When you make a code change or upgrade a dependency, rescanning your GitHub projects ensures the integrity and security of your software. If a project scan appears stalled or isn’t progressing, manually triggering a rescan can help restore normal scan activity.

To enable periodic scanning of your GitHub projects, install the GitHub App from Endor Labs. For more information, see Install the GitHub App.

Endor Labs automatically triggers a rescan of your GitHub projects every 24 hours. However, you can manually trigger a rescan. Follow these steps:

1. Sign in to Endor Labs and select Projects from the left sidebar.
2. Select a project configured for automated scanning using the GitHub App.
3. Click Rescan Project to start rescanning.

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.

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 if custom steps are required for your software to build. Applications that require custom build steps may need to be implemented in a CI environment to successfully get an accurate bill of materials.

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. If your package repository is inaccessible from the public internet, you can work with Endor Labs to evaluate options.

Endor Labs GitHub App (Pro) is an enhanced version of the Endor Labs GitHub App that supports PR remediation to fix vulnerabilities. See PR remediation for more information.

You can also make the findings generated by Endor Labs available to GitHub Advanced Security so that you can view the findings in the GitHub Advanced Security. Endor Labs exports the findings in the SARIF format and uploads them to GitHub. You can view the findings under Security > Vulnerability Alerts > Code Scanning in GitHub. See Export findings to GitHub Advanced Security for more information.

Prerequisites for GitHub App (Pro)

Before installing and scanning projects with Endor Labs GitHub App (Pro), make sure you have:

• Administrative permissions to your GitHub organization. Installing the Endor Labs GitHub App (Pro) 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 (Pro) requires the following permissions:
  • Read access to Dependabot alerts, actions, administration, checks, code, commit statuses, issues, metadata, packages, pull requests, repository hooks, and security events.
  • Read and write access to checks, contents, and pull requests.
  • Write access to code scanning alerts to upload findings to GitHub Advanced Security as SARIF files.

Install GitHub App (Pro)

To automatically scan repositories using the GitHub App and create automatic PRs to fix vulnerabilities:

1. Sign in to Endor Labs.

2. From the left sidebar, choose Projects and click Add Project.

3. From GitHub, choose GitHub App

4. Select Enable Automated Pull Requests.

   

5. Click Install GitHub App (Pro).

   You will be redirected to GitHub to install the Endor Labs App (Pro).

6. Click Install.

7. Select a user to authorize the app.

8. Select the organization in which you want to install the app.

9. Select whether to install and authorize Endor Labs on all your repositories or select the specific repositories that you wish to scan.

10. 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. If you select Install and Request your installation will not be active unless your organizational administrator approves the request to install GitHub App.

11. Choose a namespace and click Next.

    

12. Based on your license, select and enable the scanners.

    The following scanners are available:

    • SCA: Perform software composition analysis and discover AI models used in your repository.
    • RSPM: Scan the repository for misconfigurations. RSPM scans run every week on Sundays.
    • Secret: Scan the repository for exposed secrets.
    • CI/CD: Scan the repository and identify all the CI/CD tools used in the repository.
    • SAST: Scan your source code for weakness and generate SAST findings.

13. Select PULL REQUEST SCANS to set preferences for scanning pull requests submitted by users.

    

    • Select Pull Request Comments to enable GitHub Actions to comment on PRs for policy violations.

    • Select Include Archived Repositories to scan your archived repositories. By default, the GitHub archived repositories aren’t scanned.

    • In Define Scanning Preferences, select either:

      • Quick Scan to gain rapid visibility into your software composition. It performs dependency resolution but does not conduct reachability analysis to prioritize vulnerabilities. The quick scan enables users to swiftly identify potential vulnerabilities in dependencies, ensuring a smoother and more secure merge into the main branch.

      • Full Scan to perform dependency resolution, reachability analysis, and generate call graphs for supported languages and ecosystems. This scan enables users to get complete visibility and identifies all issues dependencies, call graph generation before merging into the main branch. Full scans may take longer to complete, potentially delaying PR merges.

      See GitHub scan options for more information on the scans that you can do with the GitHub App.

14. Click Continue. You have successfully installed the GitHub App (Pro).

Endor Labs GitHub App (Pro) scans your repositories every 24 hours and reports any new findings or changes to release versions of your code. It can also raise a PR with a fix based on your remediation policy. Ensure that you configure automated PR scans in your environment. See Automated PR scans for more information.

Manage GitHub Apps on Endor Labs

You can edit or delete the GitHub App integrations.

Edit GitHub App (Pro)

To edit the GitHub App integration:

1. Sign in to Endor Labs.
2. Select Manage > Integrations from the left sidebar.
3. Click Manage next to GitHub under Source Control Managers.
4. Click the three verticals dots on the right side of the GitHub App (Pro) that you want to edit, and select Edit Integration.
5. Based on your license, select and enable from the available list of scanners. You can also choose to update the pull request scan options.
6. Click Save. The changes are applicable from the next scanning cycle.
7. Use Reset to clear your selection.

Migrate GitHub App

You can migrate your GitHub App (Pro) to standard GitHub App (or from standard to Pro).

1. Sign in to Endor Labs.

2. Select Manage > Integrations from the left sidebar.

3. Click Manage next to GitHub under Source Control Managers.

4. Click the three vertical dots on the right side of the GitHub App (Pro) that you want to edit, and select Migrate To Standard App.

5. Click Migrate.

   You will be redirected to GitHub.

6. Click Configure.

7. Select a user to authorize the app.

8. Select Configure in the organization in which you want to migrate the app.

9. Select whether to install and authorize Endor Labs on all your repositories or select the specific repositories that you wish to scan.

   Warning

   When you migrate from one app to the other, select the same set of repositories as before to preserve the currently scanned projects and findings after the migration.

10. Choose the namespace and click Next.

    Warning

    You must choose the same namespace as your existing GitHub App installation.

11. Select and enable the scanners you require.

12. Select the preferences for scanning pull requests, if required.

13. Click Continue.

Delete GitHub App (Pro)

To delete a GitHub App integration, click the three vertical dots on the right side, and select Delete Integration.

You are to taken to the GitHub App page, where you can uninstall the app from your GitHub organization.

Manually trigger scans

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.

Add more GitHub repositories

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 (Pro)

The Endor Labs GitHub App (Pro) has the same limitations as the GitHub App. See Limitations for more information.

You can export the findings generated by Endor Labs to GitHub Advanced Security so that you can view the findings in the GitHub. Endor Labs exports the findings in the SARIF format and uploads them to GitHub. You can view the findings under Security > Vulnerability Alerts > Code Scanning in GitHub.

Prerequisites

Ensure that you meet the following prerequisites before exporting findings to GitHub Advanced Security:

• Endor Labs GitHub App (Pro) installed in your GitHub repository. See Deploy Endor Labs GitHub App (Pro) for more information.
• Code scanning feature is enabled in your GitHub repository. Refer to Enabling code scanning for more information.
• Download and install endorctl. See Install endorctl for more information.

Create a GHAS SARIF exporter

GHAS SARIF exporter allows you to export the findings generated by Endor Labs in the SARIF format.

You can create a GHAS SARIF exporter using the Endor Labs API.

Run the following command to create a GHAS SARIF exporter.

endorctl api create -n <namespace> -r Exporter -d '{
  "meta": {
    "name": "<exporter-name>"
  },
  "tenant_meta": {
    "namespace": "<namespace>"
  },
  "spec": {
    "exporter_type": "EXPORTER_TYPE_GHAS",
    "message_type_configs": [
      {
        "message_type": "MESSAGE_TYPE_FINDING",
        "message_export_format": "MESSAGE_EXPORT_FORMAT_SARIF"
      }
    ]
  },
  "propagate": true
}'

For example, to create a GHAS SARIF exporter named ghas-exporter in the namespace doe.deer, run the following command.

endorctl api create -n doe.deer -r Exporter -d '{
  "meta": {
    "name": "ghas-exporter"
  },
  "tenant_meta": {
    "namespace": "doe.deer"
  },
  "spec": {
    "exporter_type": "EXPORTER_TYPE_GHAS",
    "message_type_configs": [
      {
        "message_type": "MESSAGE_TYPE_FINDING",
        "message_export_format": "MESSAGE_EXPORT_FORMAT_SARIF"
      }
    ]
  },
  "propagate": true
}'

Configure scan profile and project to use the GHAS SARIF exporter

You can configure the scan profile to use the GHAS SARIF exporter and associate it with your project. You can also set the scan profile as the default scan profile so that all the projects in the namespace use the scan profile by default. See Scan profiles for more information.

Configure the scan profile

Ensure that you select the GHAS SARIF exporter in the Export section of the scan profile.

1. Select Settings from the left sidebar.

2. Select Scan Profiles.

3. Select the scan profile you want to configure and click Edit Scan Profile.

4. Select the GHAS SARIF exporter under Exporters and click Save Scan Profile.

   

Configure the project to use the scan profile

Ensure that you choose the scan profile with the GHAS SARIF exporter for the project.

1. Go to the Projects page and select the project you want to configure.

2. Select Settings and select the scan profile you want to use under Scan Profile.

   

Scan projects to use the GHAS SARIF exporter

After the configuration is complete, your subsequent scans will export the findings in the SARIF format and upload them to GitHub. You can use the rescan ability to scan the project immediately instead of waiting for the next scheduled scan. See Rescan projects for more information.

If you have enabled pull request scans in your GitHub App, the GHAS SARIF exporter exports the findings for each pull request.

View findings in GitHub

1. Navigate to your GitHub repository.

2. Select Security

3. Select Code scanning under Vulnerability Alerts.

   

   You can use the search bar to filter the findings. You can also view findings for a specific branch and other filter criteria. You can also view the findings specific to a pull request if you have enabled pull request scans. You can filter the findings by the pull request number and view findings associated with the pull request. You can select a finding and view the commit history behind the finding.