GitLab App MR scans

You can configure MR scans while creating a new GitLab App installation or for the existing GitLab App installations. Endor Labs uses group webhooks to scan your merge requests. These webhooks require the personal access token of the group owner with the api scope or requires the group owner role to configure the webhook on the GitLab UI. For more information, refer to GitLab webhooks.

You can also choose to receive MR comments on your merge requests. After you configure MR comments, Endor Labs posts a comment on the merge request if any issues are detected during the MR scan. See GitLab MR comments for more information.

Configure MR scans during a GitLab App installation

After you complete the initial installation of the GitLab App to install the GitLab App in Endor Labs, you can configure MR scans. At this point, the GitLab App will be operational.

You can also choose to configure the webhook for MR scans and apply it to specific projects through a scan profile. See Scan profiles for more information. Thereby, you can ensure that MR scans are only for selected projects rather than all the projects in the group.

1. Select Merge Request Scans under Merge Request Configuration.

   

2. Optionally, select Merge Request Comments to enable MR comments.

   When you enable MR comments, Endor Labs will post a comment on the merge request if any issues are detected during the MR scan. You need to set up MR comments in Endor Labs to receive the comments. See GitLab MR comments for more information.

   Enable MR scans for selected projects

   If you select the options to configure MR scans in your GitLab App installation, merge requests for all the projects in the groups and subgroups are scanned. Instead, you can choose to configure MR scans and MR comments for selected projects. Choose not to select Merge Request Scans but continue to set up the webhook for MR scans. Set up a scan profile to configure MR scans. Ensure that you select Pull Request Scans and optionally select under Developer Workflow when you create the scan profile.

   

   See Scan profiles for more information.

3. Select Set up the webhook now under Webhook Settings.

4. You can either configure the webhook on the GitLab UI or use the cURL command to set up the webhook.

   Configure the webhook on the GitLab UI

   Ensure that you have the group owner role to configure the webhook on GitLab.

   1. Sign in to GitLab and select the group for which you want to configure the webhook.

   2. Select Settings > Webhooks from the left sidebar.

   3. Click Add Webhook.

   4. Configure the webhook in GitLab.

      • Name: Name for the webhook.
      • Description: Description for the webhook.
      • URL: Enter https://api.endorlabs.com/webhooks/gitlab as the URL to access the Endor Labs webhook API.
      • Secret Token: The secret token from Endor Labs.

      You can copy the values from the Endor Labs user interface.

      

   5. Click Add Custom Header and enter the following values:

      • Key: X-Endor-Installation-ID
      • Value: The Custom Header Value from the Endor Labs user interface. It is the installation ID of the Endor Labs GitLab installation.

   6. Select Merge request events under the Trigger section.

   7. Ensure that Enable SSL verification is selected under the SSL verification section.

   8. Click Add Webhook to save the changes.

      You can create a webhook without SSL verification, but it is not recommended. Without SSL verification, the webhook is vulnerable to man-in-the-middle attacks.

   Configure the webhook using the cURL command

   Ensure that you have the personal access token of the group owner with the api scope to configure the cURL command.

   1. Select cURL command to configure the webhook using the cURL command.

      

   2. Replace PRIVATE-TOKEN with the personal access token of the group owner with the api scope.

   3. Copy the cURL command and run it on your system to register the webhook with GitLab.

   Save the webhook configuration

   Ensure that you complete the webhook configuration in GitLab and save the configuration in Endor Labs. Otherwise, the MR scans will not be enabled.

5. Click Save to save MR scan configuration.

Configure MR scans for existing GitLab installations

You can configure MR scans for existing GitLab installations or after the creation of a new GitLab installation.

1. Sign in to Endor Labs and select Integrations from the left sidebar.

2. Click Manage in GitLab under Source Control Managers.

3. Click the three dots menu next to the GitLab installation that you want to update.

4. Select Edit Integration.

5. Select Merge Request Settings in Integration Settings.

   

6. Select Merge Request Scans.

7. Optionally, select Merge Request Comments to enable MR comments.

   Ensure that you complete the MR comments configuration in Endor Labs to receive the comments. See GitLab MR comments for more information.

8. Select Merge Request Scans to enable MR scans.

9. Select Set up the webhook now under Webhook Settings.

10. You can either configure the webhook on the GitLab UI or use the cURL command to set up the webhook.

Configure webhook for GitLab App MR scans

GitLab MR scans require a webhook to be configured on GitLab. You can configure the webhook on the GitLab UI or use the cURL command to configure the webhook. For more information, refer to GitLab webhooks.

Configure the webhook on the GitLab UI

Configure the webhook using the cURL command

GitLab MR comments

MR comments are automated comments added to merge requests when Endor Labs detects policy violations or security issues during scans. When an MR is raised or updated, Endor Labs runs scans on the proposed changes and adds a comment if any violations are detected based on the configured action policies.

After you enable MR comments, you need to set up an action policy to allow comments to be posted on merge requests.

Configure action policy for MR comments

MR comments template

{{- /* Do not modify the placement of the CommentHeader.
It is being used to identify the comments generated by Endor Labs. */ -}}
{{ .CommentHeader.Value }}

{{ $policiesTriggeredNumber := len .PolicyFindingsMap }}

{{/* ALERT BANNER */}}
> [!WARNING]
> Endor Labs detected {{ $policiesTriggeredNumber }} policy violations associated with this merge request.

{{ $dataMap := .DataMap }}
{{ $findingsMap := .FindingsMap }}
{{ $packageVersionsMap := .PackageVersionsMap }}
{{ $apiURL := .ApiEndpoint.Value }}

### Please review the findings that caused the policy violations.

{{ range $policyUUID, $policyName := .PoliciesMap }}
{{ $policyFindings := index $dataMap $policyUUID }}
<details>
<summary>

{{/* POLICY HEADER */}}
### :clipboard: Policy: {{ $policyName }} ({{ getFindingsCountString $policyFindings }})</summary>

{{ range $packageVersionUUID, $packageVersionFindings := $policyFindings.PackageToDependencies }}
{{ if ne getOtherFindingsPackageMarker $packageVersionUUID }}
{{ $packageVersionObject := index $packageVersionsMap $packageVersionUUID }}
{{ if $packageVersionObject }}
<details>
<summary>

{{/* PACKAGE HEADER */}}
#### :inbox_tray: Package [{{ $packageVersionObject.Meta.Name.Value }}]({{ getPackageVersionURL $apiURL $packageVersionObject }})</summary>
{{ range $dependencyName, $dependencyFindings := $packageVersionFindings.DependencyToFindings }}
<details>
<summary>

{{/* DEPENDENCY HEADER */}}
##### :arrow_heading_down: Dependency: {{ $dependencyName }}</summary>

{{ range $findingCounter, $findingUUID := $dependencyFindings.Uuids }}
<details>
{{ $findingObj := index $findingsMap $findingUUID }}

{{/* FINDING HEADER */}}
<summary> :triangular_flag_on_post: {{ $findingObj.Meta.Description.Value }}</summary>

{{/* FINDING DETAILS */}}
[Details]({{ getFindingURL $apiURL $findingObj }})
- **Severity**: ` + "`" + `{{ enumToString $findingObj.Spec.Level }}` + "` " + `
- **Tags**: {{ range $i, $t := $findingObj.Spec.FindingTags }}` + "`" + `{{ enumToString $t }}` + "` " + `{{ end }}
- **Categories**: {{ range $i, $c := $findingObj.Spec.FindingCategories }}` + "`" + `{{ enumToString $c }}` + "` " + `{{ end }}
{{- with getFirstPartyReachableFunctions $findingObj }}
- **Reachable via**: ` + "`" + `{{ . }}` + "` " + `
{{- end }}
- **Remediation**: {{ fixBackticks $findingObj.Spec.Remediation.Value }}
</details>
{{ end }} {{/*range $findingCounter, $findingUUID...*/}}
</details>
{{ end }} {{/*range $dependencyName, $depend...*/}}
</details>
{{ end }}  {{/* if $packageVersionObject */}}
{{ else }} {{/* if ne getOtherFindingsPackageMarker... */}}
{{ $depMarker := getOtherFindingsDependencyMarker }}
{{ $otherFindings := index $packageVersionFindings.DependencyToFindings $depMarker }}
{{ $otherFindingsLen := len $otherFindings.Uuids }}
{{ if ne $otherFindingsLen 0 }}
<details>
<summary>

#### :mag: Findings</summary>
{{ range $findingCounter, $findingUUID := $otherFindings.Uuids }}
<details>
{{ $findingObj := index $findingsMap $findingUUID }}
<summary>:triangular_flag_on_post: {{ $findingObj.Meta.Description.Value }}</summary>

[Link To Finding]({{ getFindingURL $apiURL $findingObj }})
- **Severity**: ` + "`" + `{{ enumToString $findingObj.Spec.Level }}` + "` " + `
- **Tags**: {{ range $i, $t := $findingObj.Spec.FindingTags }}` + "`" + `{{ enumToString $t }}` + "` " + `{{ end }}
- **Categories**: {{ range $i, $c := $findingObj.Spec.FindingCategories }}` + "`" + `{{ enumToString $c }}` + "` " + `{{ end }}
- **Summary**: {{ $findingObj.Spec.Summary.Value }}
- **Remediation**: {{ fixBackticks $findingObj.Spec.Remediation.Value }}
{{- if hasFindingCategory $findingObj "SAST" }}
- **Location**: {{ getCustomLocation $findingObj }}
{{- if isNotEmptyString (getCustomCodeSnippet $findingObj) }}
- **Code Snippet**:
` + "```" + `
{{ getCustomCodeSnippet $findingObj }}
` + "```" + `
{{- end }}
{{- end }}
</details>
{{ end }} {{/*range $findingCounter, $findingUUID...*/}}
</details>
{{ end }} {{/*{{ if ne $otherFindingsLen 0*/}}
{{ end }} {{/* if ne getOtherFindingsPackageMarker... */}}
{{ end }} {{/* range $packageVersionUUID, $packageVersionFindings := $policyFindings */}}
</details>
{{ end}}  {{/* {{ range $policyUUID, $policyObj := .PoliciesMap */}}

{{ .CommentFooter.Value }}
_Scanned @ {{ now }} UTC_

// FuncMap contains additional template functions used in GitLab comment templates.
var FuncMap = template.FuncMap{
	"now":                              toTime,
	"enumToString":                     enumToString,
	"getFindingURL":                    getFindingURL,
	"getPackageVersionURL":             getPackageVersionURL,
	"getPullRequestURL":                getEndorLabsPullRequestRunURL,
	"getFindingsCountString":           getFindingsCountString,
	"hasOtherFindings":                 hasOtherFindings,
	"getOtherFindingsPackageMarker":    getOtherFindingsPackageMarker,
	"getOtherFindingsDependencyMarker": getOtherFindingsDependencyMarker,
	"fixBackticks":                     fixUnclosedBackticks,
	"getFirstPartyReachableFunctions":  getFirstPartyReachableFunctions,
	"hasFindingCategory":               hasFindingCategory,
	// isNotEmptyString checks if a string is not empty
	"isNotEmptyString": func(value string) bool {
		return value != ""
	},
	// getCustomLocation extracts the location from Custom field
	"getCustomLocation": func(finding *endorpb.Finding) string {
		return getCustomFieldValue(finding, "location")
	},
	// getCustomCodeSnippet extracts the code snippet from Custom field
	"getCustomCodeSnippet": func(finding *endorpb.Finding) string {
		return getCustomFieldValue(finding, "code_snippet")
	},
	// add returns the sum of two integers
	"add": func(n int, incr int) int {
		return n + incr
	},
}

MR scan comments in GitLab

After you enable MR comments, Endor Labs posts a comment on the merge request if any issues are detected during the MR scan based on the action policies.

The following example shows a comment on the merge request as a result of the action policy for identifying leaked secrets.

You can expand and view the details of the finding.

Click Link to Finding to view the details of the finding in Endor Labs.

For secrets, Endor Labs also generates a comment with the line number where the secret is detected.

View MR scan findings

When you create a new merge request, the Endor Labs GitLab App scans the merge request. Endor Labs generates findings based on the finding policy.

1. Sign in to Endor Labs and select Projects from the left sidebar.

2. Select the project for which you want to view the MR scan findings.

3. Select PR runs to view the MR scan findings.

   

4. Select the MR for which you want to view the findings.

   

5. Click View Details to view the findings on the MR.

   

See View Findings for more information on Findings in Endor Labs.

Update the webhook secret

You might want to update the webhook secret for rotation or because you have lost the secret.

Update the webhook secret on the Endor Labs GitLab App

1. Select Integrations from the left sidebar.

2. Click Manage in GitLab under Source Control Managers.

3. Click the three dots menu next to the GitLab installation that you want to update.

4. Select Edit Integration.

5. Select Merge Request Settings.

6. Enter the new Secret Token under Webhook Settings, and click Save to save the changes.

   

   The secret token can be any random string.

Update the webhook secret in GitLab

To update the webhook secret in GitLab UI, you need to log in with the group owner role.

1. Sign in to GitLab and select the group for which you want to update the webhook secret.

2. Select Settings > Webhooks from the left sidebar.

3. Click Edit next to the webhook that you want to update.

4. Enter the new Secret token, and click Save changes to save the changes.

   Ensure that you use the same secret token that you used in Endor Labs.