Overview

The Immersive GitHub integration allows you to link Immersive content assignments to your GitHub repositories and include the assignment completion status for individual users in your GitHub checks. You can configure these checks to be required before merging any code changes. This integration ensures that your teams complete required secure coding and application security training before they are allowed to merge code changes to the selected source code repositories.

We also offer content suggestions for GitHub pull requests and issues based on Common Weakness Enumeration (CWE) references and common phrases associated with code vulnerabilities. Labs are automatically recommended based on code findings, streamlining the remediation of vulnerabilities and enhancing the vulnerability management process. 

Integration Setup

Permissions

• Only an organization manager can add, configure, and remove integrations on the platform. This user also needs to be the corresponding GitHub organization's owner in order to install the GitHub app across their organization.
• Team managers on the platform can see the installed integrations, but they cannot add, configure or remove them.
• Any other users cannot view or manage integrations.

Installing the GitHub Integration

The GitHub integration is installed from the Platform Settings area of the Immersive platform. 

To install the integration:

1. From the navigation menu, click Manage > Platform Settings, and then click Integrations.

   

2. On the Integrations page, under Source Code Management, click GitHub.
3. In the Sync your repositories group, click Add Repositories. Note that you must be connected to the GitHub application before you can complete the next steps.

4. From the Install Immersive page, select the repositories that you want to grant access to the Immersive integration:

   • All repositories: Select this option to allow access to all current and future repositories owned by the resource owner. This also includes public repositories (read-only).
   • Only select repositories: Select this option to specify which repositories will be included in the integration. You must select at least one repository.

   

5. Click Install to begin the installation.

6. You can now see the installed integration on the Immersive platform:

   

In the Repositories column, you can click the View button to see the integrated GitHub repositories. 

Editing integration settings

An organization manager can toggle an integration to enable or disable its features. To edit your settings to enable or disable features for the GitHub integration:

1. On the GitHub page in the Immersive platform, in the row associated with the organization, click ..., and then click Edit settings.
2. Toggle the features on or off as desired.
   • The Code access control toggle determines whether or not an option will be available when assigning required content to block code changes in the selected repository if the assignment is not completed by the due date.
   • The Content suggestion toggle determines whether or not the Immersive app suggests relevant content in GitHub  when a vulnerability is mentioned in pull requests or issues. See CWE Content Suggestions.
3. Close the dialog box. 

Removing an integration

An organization manager can remove an integration, which also removes any associated configuration such as the linked repositories from the platform and triggers the GitHub app installation removal on GitHub's side.

To remove the integration:

1. On the GitHub page in the Immersive platform, in the row associated with the organization, click ..., and then click Delete.
2. On the Delete Integration window, click Delete Integration to uninstall the application for the selected organization. 
   

Assigning Required Content

Once an organization manager installs the GitHub app as part of the SCM integration setup and enables the integration, an organization or team manager creating or editing an assignment can then select the repositories where an Immersive content completion check should be performed.

Permissions

A team manager or an organization manager can configure an assignment to be required.

Assignment configuration

When creating or editing an assignment on the platform, the team or organization manager can select the option to require the content to be completed before making code changes, as well as select which repositories the check should apply to.

To do so, when assigning a collection:

1. In the Set assignment duration group, make sure to specify an End date for the assignment. An end date is required to block merges with an assignment. This is to allow users time to complete the assigned content before blocking their code changes.

2. In the Associate code repositories group, turn on the Block merges until content completed toggle. 

   

3. In the Repositories column, click View.
4. Click the Add button in the rows for the repositories that you want to add. 

Assignment completion

Once a user whose code changes are blocked due to incomplete required content completes the assignment, any checks that previously failed due to that assignment are retried automatically and will now pass. 

Change Blocking

Once an organization manager installs the GitHub app as part of the SCM integration setup and enables the integration, any new commits pushed to the corresponding GitHub organization will trigger Immersive required assigned content checks.

Initial check run

The initial check for each GitHub user in the organization will fail due to requiring the user to authorize the app to act on their behalf. This is required in order for us to be able to retrieve private user email address data to lookup accounts on our system and the required assigned content progress.

The failed check run output will include a link to authorize the app.

Authorization link

Following the authorization link will present the user with a summary of permissions being requested from the user. Click Authorize Immersive to proceed. 

If access is denied, the user will see an error informing them of the issue.

If access is granted, the user is returned to the Details page in GitHub. This will also request the check run to be rerun in the background, which will clear the previous check's status and conclusion and populate it again based on the user's required assigned content completion status (Content complete or Content incomplete). 

Subsequent check runs

Any new check runs triggered after the user authorizes the app will use a cached user access token and associated refresh token to retrieve the user's details for required assigned content checks. The cached access token is valid for 8 hours, and the associated refresh token is valid for 6 months. Once the refresh token expires, or if the user revokes access, the next check run will require the user to reauthorize the app:

Branch protection rules

In order for the Immersive check to block changes from being merged, customers will need to include the Immersive check in their branch protection rule configuration.

Repositories on GitHub can be configured to have protected branches. This enables a branch such as main to require certain conditions before merging can take place, for example:

• A pull request to be made
• A specified status check to pass

GitHub documentation on branch protection has more in-depth and up to date information but the steps outlined below give an overview of setting this up for the Immersive check.

Repository settings

Visit the repository page on GitHub where you want to set up change blocking.

1. Navigate to the Settings page.

   

2. In the lefthand pane, select the Branches section.

   

3. In the Branch protection rules area, click Add rule, or select an existing rule to edit.
4. Enter a Branch name pattern field.

5. Search for the name of the status change under Require status checks to pass before merging and select the matching check.

   

6. At the bottom of the page, click Create or Save changes.

7. Your branch protection rule will now be visible in the Branches section of the repository's settings page:

   

   Merges against the branches matching the new rule will require the Immersive check to pass:

   

The example above also requires pull requests before merging. While this is not necessary, it helps clarify why the merge is blocked.

Content Suggestions

Common Weakness Enumeration (CWE) is a community-developed list of common security weaknesses in software and hardware systems. Each weakness in the list is identified by a unique CWE number and description, providing a standardized way to categorize and describe vulnerabilities and security issues. When integrated into applications, CWE numbers facilitate easier identification, communication, and remediation of security weaknesses in software systems.

When the Content suggestion toggle is turned on for GitHub, we offer content suggestions for GitHub pull requests and issues based on CWE references and common phrases associated with code vulnerabilities. The CWE content suggestion feature lets you seamlessly integrate Immersive into your CI/CD pipelines and vulnerability management programs. GitHub extracts the CWE numbers from SAST/DAST tool comments. 

Labs have a GraphQL API endpoint that enables efficient lab searches via tags. As a result, we automatically recommend labs based on code findings, streamlining the remediation of vulnerabilities and enhancing the vulnerability management process.