Scan a Repository
Table of Contents
SD Elements has introduced Scan a Repository, a feature that allows users to connect their Git repositories, scan them for relevant data, and map these data points to survey answers, while also helping to generate diagram components.
Purpose
The main purpose of this feature is to streamline the SD Elements project onboarding process. This is done by using an external repository to help answer the SD Elements survey, thus ensuring that countermeasures are not only accurately generated, but can also stay in sync with the latest changes to the application code base.
This user guide will provide detailed instructions on how to connect and use the “Scan a Repository” feature within SD Elements. It covers everything from setting up connections, to scanning a repository and mapping the results to answers within a draft project survey.
Enable Scan a Repository
Before Scan a Repository becomes available to use within a project, administrators must enable the feature. In order to use this feature an administrator will need turn it on using either the UI or API by selecting the {ENABLE_SCAN_REPO} feature flag. The administrator will need to have the "Turn On Feature Flags" permission to do this.
Prerequisites:
-
The user has the permission Organization → Manage features.
Steps:
-
Navigate to the System (gear icon) tab.
-
Select Features.
-
Under Team Onboarding, Check the Scan a Repository checkbox.
-
Click Save.
The scan a repository feature will be activated and available for use in this SD Elements instance, both via UI and API.
Scan a Repository Permissions
Once the feature has been enabled within the SD Elements instance, only users with specific permissions will be able to manage this functionality. Users will require the permissions to manage a project and the survey.
Prerequisites:
-
The user has the permission Project role→Project Management→Edit project survey.
Git Access
If the end user has the appropriate permissions, they will be able to create a user-based connection to their desired Git platform, which can then be used for any given project.
Supported Git Connections
Scan a Repository currently supports connections to the following platforms:
-
GitHub (On Cloud & On Premise via API)
-
GitLab (On Cloud & On Premise via API)
GitHub Access
Users can connect to GitHub either via OAuth through the SD Elements Platform or using a Personal Access Token (PAT) via the API. These options are available for GitHub Cloud (https://github.com).
In order to connect to GitHub on Premise, please refer to the below section "Connecting via API".
Connecting via API
If connecting to GitHub via the API, an Access Token is required. This token must be a Personal Access Token (PAT) generated as a Classic Token. Ensure that the PAT has repository permissions like the following screenshot, as this allows our service to temporarily clone the repositories during the scan.
| PATs generated as Fine-Grained Tokens will not work with SD Elements due to insufficient permissions. |
To learn more about GitHub Connections via API, please refer to this resource found under GitHub.
GitLab Access
Users can connect to GitLab either via OAuth through the SD Elements Platform or using an access token via the API. These options are available for GitLab Cloud (https://gitlab.com).
In order to connect to GitLab on Premise, please refer to the below section "Connecting via API".
Connecting via API
If connecting to GitLab via the API, an access token is required. This token is obtained from Resource owner password credentials flow.
For connection to GitLab on Premise, an access token can be obtained via the above API using its private domain instead of accessing https://gitlab.com.
| Please refer to GitLab’s documentation on Resource owner password credentials flow to ensure the GitLab user account is eligible for this usage. |
Creating a Repository Connection
Before a user initiates a repository scan, they must authenticate and configure the connection details.
Connecting Git Account within a Project
-
Users should select "Scan a Repository" from the Getting Started Card.
-
Next, users should choose the platform they want to connect to (e.g., GitHub).
-
After selecting a platform, users will be prompted to authenticate and grant SD Elements permission to clone and read repositories.
-
Users can remove this connection via the Scan A Repository page at any point. Doing so will require the user to re-authenticate if they wish to run a subsequent scan or before running any new scans within other SD Elements projects.
Running a Scan within a Project
After establishing a connection for a user, they will be redirected to set up the repository and branch for the project.
-
Users will select a repository, which will then display the branches within the selected repository.
-
Once users have selected the repository and branch they can click the Scan button to initiate the scan, which will then redirect users to the survey.
-
While a scan is running, the project remains locked.
-
Once the scan is completed, users will need to click on the Unlock & Continue button to unlock the project and update the survey with the answers found during the scan. After doing this a user can make any manual modifications to the survey that they wish before continuing on.
To learn more about setting up a connection and trigger a scan via API, please refer to:
Limitations & Restrictions
-
Projects are locked during scans to ensure only one scan occurs at a time within a project.
-
The repository to scan size should be below 2 Gb
-
Limitations:
-
Currently, it supports GitHub and GitLab; future updates will Azure.
-
Unable to display a dynamic GitHub name within the connection; it will remain as the static "GitHub" to confirm the connection
-
-
Limitations on OSD until 2024.4:
-
The GitHub app only allows one callback URL, which complicates use for customers with custom URLs. We will provision a separate app for them in SDE with their domain.
-