Scan a Repository

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 help 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.

Canvas controls

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:

  1. Navigate to the System (gear icon) tab.

  2. Select Features.

  3. Under Team Onboarding, Check the Scan a Repository checkbox.

    Canvas controls

  4. 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 Premise & Cloud)

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 both GitHub On Premise and GitHub Cloud.

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.

Canvas controls
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:

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

  1. Users should select "Scan a Repository" from the Getting Started Card.

  2. Next, users should choose the platform they want to connect to (e.g., GitHub).

  3. After selecting a platform, users will be prompted to authenticate and grant SD Elements permission to clone and read repositories.

    Canvas controls

  4. 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.

    Canvas controls

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.

  1. Users will select a repository, which will then display the branches within the selected repository.

  2. 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.

    Canvas Control

  3. While a scan is running, the project remains locked.

    Canvas controls

  4. 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.

    Canvas controls

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.

  • Limitations that are being addressed in 2024.3:

    • This feature does not currently have Cross Site Request Forgery (CSRF) protection implemented

    • Currently supports GitHub only; future updates will support GitLab and Azure.

    • Unable to scan a survey directly from the survey page (Only API).

    • Unable to distinguish between answers derived from a repository scan and those selected manually in the summary.

    • 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.

results matching ""

    No results matching ""