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. For more information, refer to GitLab webhooks.
api scope. You need to configure webhooks to complete the MR scans configuration. Webhooks configuration through cURL requires the personal access token of the group owner with the api scope or the group owner role needs to configure the webhook on the GitLab UI.
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.
-
Select Merge Request Scans under Merge Request Configuration.
-
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.
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.
-
Select Set up the webhook now under Webhook Settings.
-
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.
-
Sign in to GitLab and select the group for which you want to configure the webhook.
-
Select Settings > Webhooks from the left sidebar.
-
Click Add Webhook.
-
Configure the webhook in GitLab.
- Name: Name for the webhook.
- Description: Description for the webhook.
- URL: Enter
https://api.endorlabs.com/webhooks/gitlabas 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.
-
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.
- Key:
-
Select Merge request events under the Trigger section.
-
Ensure that Enable SSL verification is selected under the SSL verification section.
-
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
apiscope to configure the cURL command.-
Select cURL command to configure the webhook using the cURL command.
-
Replace
PRIVATE-TOKENwith the personal access token of the group owner with theapiscope. -
Copy the cURL command and run it on your system to register the webhook with GitLab.
-
- 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.
api scope for MR scans.
-
Sign in to Endor Labs and select Integrations from the left sidebar.
-
Click Manage in GitLab under Source Control Managers.
-
Click the three dots menu next to the GitLab installation that you want to update.
-
Select Edit Integration.
-
Select Merge Request Settings in Integration Settings.
-
Select Merge Request Scans.
-
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.
-
Select Merge Request Scans to enable MR scans.
-
Select Set up the webhook now under Webhook Settings.
-
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.
-
Sign in to GitLab and select the group for which you want to configure the webhook.
-
Select Settings > Webhooks from the left sidebar.
-
Click Add Webhook.
-
Configure the webhook in GitLab.
- Name: Name for the webhook.
- Description: Description for the webhook.
- URL: Enter
https://api.endorlabs.com/webhooks/gitlabas 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.
-
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.
- Key:
-
Select Merge request events under the Trigger section.
-
Ensure that Enable SSL verification is selected under the SSL verification section.
-
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.
Ensure that you have the personal access token of the group owner with the Select cURL command to configure the webhook using the cURL command. Replace Copy the cURL command and run it on your system to register the webhook with GitLab.
Configure the webhook using the cURL command
api scope to configure the cURL command.
PRIVATE-TOKEN with the personal access token of the group owner with the api scope.
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
Ensure that you have the group owner role to configure the webhook on GitLab.
-
Sign in to GitLab and select the group for which you want to configure the webhook.
-
Select Settings > Webhooks from the left sidebar.
-
Click Add Webhook.
-
Configure the webhook in GitLab.
- Name: Name for the webhook.
- Description: Description for the webhook.
- URL: Enter
https://api.endorlabs.com/webhooks/gitlabas 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.
-
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.
- Key:
-
Select Merge request events under the Trigger section.
-
Ensure that Enable SSL verification is selected under the SSL verification section.
-
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.
-
Select cURL command to configure the webhook using the cURL command.
-
Replace
PRIVATE-TOKENwith the personal access token of the group owner with theapiscope. -
Copy the cURL command and run it on your system to register the webhook with GitLab.
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
Endor Labs provides a default template for MR comments that you can use out-of-the-box. You can also create custom templates using Go Templates.
The following section shows the default template for MR comments.
{{- /* 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_
You can create your custom template by editing the default template and saving the changes.
The following specification shows the additional functions that you can use in your custom template. You can access these functions by using their corresponding keys.
// 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
},
}
To edit the default template:
-
Select Manage > Integrations from the left sidebar.
-
Click Edit Template next to GitLab under Template for PR Comments.
-
Update the template with the required changes.
-
Select Propagate this template to all child namespaces if you want to apply the template to all child namespaces.
- Click Save Template to save the changes.
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.
-
Sign in to Endor Labs and select Projects from the left sidebar.
-
Select the project for which you want to view the MR scan findings.
-
Select PR runs to view the MR scan findings.
-
Select the MR for which you want to view the findings.
-
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
-
Select Integrations from the left sidebar.
-
Click Manage in GitLab under Source Control Managers.
-
Click the three dots menu next to the GitLab installation that you want to update.
-
Select Edit Integration.
-
Select Merge Request Settings.
-
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.
-
Sign in to GitLab and select the group for which you want to update the webhook secret.
-
Select Settings > Webhooks from the left sidebar.
-
Click Edit next to the webhook that you want to update.
-
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.
\
The action policy that you create triggers the posting of comments on your merge request after a scan is complete. See Action policy for more information. You can create multiple action policies based on your requirements, which the MR scan can trigger. If you create action policy with the
Secrettemplate, you get an inline comment with the line number where the secret is detected.Ensure that you configure the following important settings in the action policy:
Choose an appropriate action policy template or create a custom action policy.
You can choose an action policy template like Vulnerabilities or create a custom action policy.
Under Action, select Enforce Policy, then choose:
Define the scope of the policy using tags. Only projects that match the specified tags will receive MR comments.
Select Propagate this policy to all child namespaces if you want to apply the policy to all child namespaces.