This guide will explain how to connect repositories in a source control management system (GitHub, GitLab, Bitbucket, etc) to Nexus Lifecycle and scan those repositories for policy violations.
Table of Contents
- Easy SCM Onboarding
- Step 1: Configuring Source Control
- Step 2: Importing applications
- Step 3: Reviewing Scan Results
- Next Steps & Additional Resources
Before you can scan applications from source control you’ll need the following:
- An account with a supported source control system. Currently we support GitHub, GitLab, and Bitbucket
- A repository in that source control system
- An access token for your source control management system
- An installation of Nexus Lifecycle version 109 or later
- To set up a local instance of Lifecycle, follow the installation steps in the Lifecycle Quickstart guide. This should primarily be used for testing purposes prior to integrating Lifecycle into your development environment.
- Information about deploying Lifecycle into your production SDLC can be found in the help documentation
- Permission to change the root organization in your instance of Lifecycle
Easy SCM Onboarding
Nexus Lifecycle can now scan repositories in a supported source control management system. Lifecycle identifies an application’s dependencies and checks for policy violations, giving you a report about your application’s risk with minimal configuration. By scanning applications from source control, Lifecycle can evaluate applications without modifying any code or continuous integration (CI) build processes. Be aware that Nexus Lifecycle will scan all folders in a repository, even if that repository contains more than one application. All violations for this repository will be listed in the scan report. For fine-grained scan control and binary analysis, we recommend integrating Lifecycle with your CI pipeline.
Lifecycle can continue to provide information to your source control repositories. Using status checks, Lifecycle can prevent a pull request from merging until the PR meets the organization’s policy standards. New and remediated violations can be indicated with a comment on the pull request.
The Easy SCM Onboarding features shift security left, giving developers information and policy enforcement tools inside their source control system. This gives developers ongoing feedback during the software development process.
Step 1: Configuring source control
The first step to scanning an application with Lifecycle is to configure your source control access token. We strongly recommend setting your source control token in the Root organization. If an application requires a different source control account that access token can be changed in the organization settings. For onboarding we recommend starting with a single token until you are familiar with the process. We also suggest disabling pull requests to prevent Lifecycle from overwhelming your repositories with status checks and automated PRs during onboarding.
- Navigate to your instance of Nexus Lifecycle and login as an administrator
Select Orgs & Policies from the menu bar and scroll to the Source Control Panel.
Click Source Control Not Configured
Select your source control provider from the Access Token Provider dropdown
Set the ‘Pull Requests’ option to ‘Disabled’. This prevents your developers from being overwhelmed with automated remediation pull requests until you’re ready to address the feedback from Lifecycle. This setting can be changed at any time.
Enter the default branch for your applications. This is the branch Lifecycle will monitor, send status updates, and create pull requests on. It is also the branch used as the comparison for feature branch pull request comments. The default branch can be overridden at the organization level. Repositories with a different default branch than the root organization should be imported to an organization configured to use that repository’s default branch.
⚠️ No Scan Results
There will be no scan results if:
- The repository does not have the default branch
- There are no dependencies or binaries for Lifecycle to scan
- Save your settings by clicking Create
Step 2: Importing applications
- Select the organization from the sidebar you want to connect with source control repositories
- Click Import Applications. This will bring you to the Application Import Tool
Note: The Import Applications screens can also be accessed by clicking SCM Onboarding in the Settings Cog
Add all relevant projects to your organization. The arrows next to each category will sort the applications in ascending or descending alphabetical order for that category. Each input box can be used to filter for a specific keyword or name. The All checkbox will select all application on the current page. Only visible applications can be selected. Any application hidden by a filter or not visible on the current page will be deselected.
Click the Import Repositories button at the bottom. You may need to scroll to see this button
Click the Go To Reports button on the upper right side of the screen. This will take you to the reports section. This can also be accessed from the Reporting button on the main navigation bar. Your report will be automatically generated after completing this step.
Step 3: Reviewing the Scan Results
To view the scan results for your imported applications, navigate to the Reports page in Lifecycle. Select an application and click the View Report link in the Source Violations Column. This will direct you to the Application Composition Report (ACR).
Application Composition Report
The Application Composition Report provides an overview about the components in your application and any policy violations. It contains the following sections:
- The Summary section is located at the top of the screen and provides a high-level overview of the violations identified by Nexus Lifecycle. The section shows a breakdown of policy violations by severity, the total number of components, and grandfathered violations.
- The Violations Table shows a complete list of scanned components ordered by policy violation severity
- The Filter sidebar is located on lefthand of the screen and provides tools for viewing specific groups of components
- Vulnerabilities list can be viewed from the Options menu and shows a list of all vulnerabilities that violate a policy. Clicking on the vulnerability ID links to the Vulnerability Lookup Page
The Component Information Panel
Component Information Panel (CIP) provides information about an individual component. You can access the CIP by clicking on a component from the ACR. Here you can find information about version popularity, policy threats, license information and vulnerability details. Violations can be waived under the policy section.
Security and license violations can be remediated using one of the three general strategies listed below:
- Upgrade a component to a version of the same component without the violation. This is usually the best option as it is the easiest way to remediate a violation.
- Select a new component without the violation. Not all components have a secure version. In these situations we recommend replacing the risky component with a similar one without the violation. This option involves research and possibly some rework to implement a different component with the same functionality.
- Request a policy waiver for the violation. If it’s impossible to upgrade or replace a component the final option is to waive the violation. This is the last resort as it accrues technical debt and does not reduce risk.
Enforcing Policy through Source Control
Nexus Lifecycle can use automated commit feedback to enforce policy. When Lifecycle scans an application in source control, it will send a status update to the SCM with those scan results. This status check can block pull requests from being merged if the evaluation results fail to meet your organization’s policy standards. Status checks can also be informational. Lifecycle can also comment on a pull request, detailing new or remediated violations. Repositories using status checks to enforce policy or pull request comments must be private. For more information check out the links below.
Next Steps & Additional Resources
Once you’ve reviewed your scan results, the next step is to begin integrating Nexus Lifecycle into your continuous integration build pipeline. This will allow Nexus Lifecycle to enforce policy actions during your builds and allow precise control over what Lifecycle scans and evaluates.
Check out the resources below for more information:
- Getting Started with Nexus Lifecycle Documentation
- Organization Management in Nexus Lifecycle
- Lifecycle Quickstart Guide for an introduction to Nexus Lifecycle
- Courses and learning paths are available at learn.sonatype.com
- Visit My Sonatype for documentation, guides, support, and more