GitHub Enterprise integration

Snyk GitHub Enterprise integration lets you:

• Continuously perform security scanning across all the integrated repositories

• Detect vulnerabilities in your open-source components

• Provide automated fixes and upgrades

Setting up a GitHub Enterprise integration

The process to connect Snyk with your GitHub Enterprise repositories includes the following steps. Note that using a service account is recommended but not required.

1. Create a dedicated service account in GitHub Enterprise with write level or higher permissions for the repos you want to monitor with Snyk permissions. See Types of GitHub accounts and Required permissions scope for the GitHub integration for details.

2. Generate a personal access token for that account with the following permissions: - repo (all) - admin:read:org - admin:repo_hooks (read & write) If you are using fine-grained personal access tokens, the following scope is required: - Account permissions: None - Admin: Read-only - Commit Status: Read and write - Contents: Read and write - Metadata: Read-only - Pull requests: Read and write - Webhooks: Read and write See the GitHub Enterprise documentation for details.

3. Authorize your personal access token and Enable SSO:

   1. In Snyk, go to the Integrations page and click the GitHub Enterprise card.

   2. Enter your Github Enterprise URL and the personal access token (PAT) for the service account you created, and Save your changes. Snyk connects to your GitHub Enterprise instance. When the connection succeeds, the list of available repositories is displayed. Note: To use this integration to integrate with your GitHub Enterprise Cloud instance, provide the following URL: https://api.github.com.

   3. If your GitHub Enterprise organization enforces SAML/SSO, select Configure SSO next to the PAT in GitHub after the PAT has been created. Note: Occasionally, SSO is enforced in your GitHub Enterprise organizations after a PAT and Integration are configured. If this happens, any Projects that have already been imported show in Snyk but retests, PR Checks, and so on will not be performed. If this happens, check the Configure SSO settings here to ensure that the GitHub Enterprise organization is Authorized. On occasion, an organization shows as Authorized, but the retests and PR checks do not work. If this happens, de-authorizing the organization and then re-authorizing it may help.

4. Select the repositories you want to import to Snyk and click Add selected repositories.

Snyk starts scanning the selected repositories for dependency files, such as package.json, in the entire directory tree and imports them to Snyk as Projects.

The imported Projects appear on your Projects page and are continuously checked for vulnerabilities.

GitHub Enterprise Broker startup script

For the script and instructions, see GitHub Enterprise - install and configure using Docker.

GitHub Enterprise integration features

After the integration is set up, you can use the capabilities explained in the sections that follow.

Project-level security reports

Snyk produces advanced security reports, allowing you to explore the vulnerabilities found in your repositories and fix them by opening a fix pull request directly to your repository with the required upgrades or patches.

The example that follows shows a Project-level security report.

Project monitoring and automatic fix pull requests

Snyk scans your Projects on either a daily or a weekly basis. When new vulnerabilities are found, Snyk notifies you by email and opens an automated pull request with fixes for your repositories.

The example that follows shows a fix pull request opened by Snyk.

To review and update the automatic fix pull request settings:

1. In Snyk, go to Settings > Integrations > Source control > GitHub Enterprise, and select Edit Settings.

2. Scroll to the Automatic fix pull requests section, then select options as required:

Pull request testing

The PR Checks feature enables Snyk to test any newly-created pull requests in your repositories for security vulnerabilities and sends a status check to GitHub Enterprise. This allows you to see, directly from GitHub Enterprise, whether the pull request introduces new security issues.

The example that follows shows how Snyk pull request checks appear on the GitHub Enterprise Pull Request page.

To review and adjust the pull request tests settings: In Snyk, go to Organization Settings > Integrations > Source control > GitHub Enterprise, and select Edit Settings.

1. Scroll to Snyk PR status checks; see Configure PR Checks for details.

Required permissions scope for the GitHub integration

All the operations, whether triggered manually or automatically, are performed for a GitHub service account that has its token configured in the integrations settings page. This shows the required access scopes for the configured token: