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.

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.

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.

   Do not use! Draft content. Development in progress.

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

   The following table lists the configuration options required to create the GitLab group webhook.

   | |

   Run the command on your system to register the webhook with GitLab.

   curl --location '<gitlab_base_url>/api/v4/groups/<group_path>/hooks' \
      --header 'content-type: application/json' \
      --header 'PRIVATE-TOKEN: <group_owner_api_pat_here>' \
      --data '{
        "name": "Endor Labs MR Security Scanner",
        "description": "Group webhook for GitLab MR scanning with Endor Labs.",
        "url": "https://api.endorlabs.com/webhooks/gitlab",
        "token": "<webhook_secret_token>",
        "enable_ssl_verification": true,
        "push_events": false,
        "merge_requests_events": true,
        "custom_headers": [
          {
            "key": "X-Endor-Installation-ID",
            "value": "<installation_uuid>"
          }
        ]
      }'
      

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 vertical three dots 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.

curl --location '<gitlab_base_url>/api/v4/groups/<group_path>/hooks' \
   --header 'content-type: application/json' \
   --header 'PRIVATE-TOKEN: <group_owner_api_pat_here>' \
   --data '{
     "name": "Endor Labs MR Security Scanner",
     "description": "Group webhook for GitLab MR scanning with Endor Labs.",
     "url": "https://api.endorlabs.com/webhooks/gitlab",
     "token": "<webhook_secret_token>",
     "enable_ssl_verification": true,
     "push_events": false,
     "merge_requests_events": true,
     "custom_headers": [
       {
         "key": "X-Endor-Installation-ID",
         "value": "<installation_uuid>"
       }
     ]
   }'
   

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

curl --location '<gitlab_base_url>/api/v4/groups/<group_path>/hooks' \
--header 'content-type: application/json' \
--header 'PRIVATE-TOKEN: <group_owner_api_pat_here>' \
--data '{
  "name": "Endor Labs MR Security Scanner",
  "description": "Group webhook for GitLab MR scanning with Endor Labs.",
  "url": "https://api.endorlabs.com/webhooks/gitlab",
  "token": "<webhook_secret_token>",
  "enable_ssl_verification": true,
  "push_events": false,
  "merge_requests_events": true,
  "custom_headers": [
    {
      "key": "X-Endor-Installation-ID",
      "value": "<installation_uuid>"
    }
  ]
}'

</div>

curl --location '<gitlab_base_url>/api/v4/groups/<group_path>/hooks' \
   --header 'content-type: application/json' \
   --header 'PRIVATE-TOKEN: <group_owner_api_pat_here>' \
   --data '{
     "name": "Endor Labs MR Security Scanner",
     "description": "Group webhook for GitLab MR scanning with Endor Labs.",
     "url": "https://api.endorlabs.com/webhooks/gitlab",
     "token": "<webhook_secret_token>",
     "enable_ssl_verification": true,
     "push_events": false,
     "merge_requests_events": true,
     "custom_headers": [
       {
         "key": "X-Endor-Installation-ID",
         "value": "<installation_uuid>"
       }
     ]
   }'
   

</div>

</div>

curl --location '<gitlab_base_url>/api/v4/groups/<group_path>/hooks' \
   --header 'content-type: application/json' \
   --header 'PRIVATE-TOKEN: <group_owner_api_pat_here>' \
   --data '{
     "name": "Endor Labs MR Security Scanner",
     "description": "Group webhook for GitLab MR scanning with Endor Labs.",
     "url": "https://api.endorlabs.com/webhooks/gitlab",
     "token": "<webhook_secret_token>",
     "enable_ssl_verification": true,
     "push_events": false,
     "merge_requests_events": true,
     "custom_headers": [
       {
         "key": "X-Endor-Installation-ID",
         "value": "<installation_uuid>"
       }
     ]
   }'
   

</div>

curl --location '<gitlab_base_url>/api/v4/groups/<group_path>/hooks' \
--header 'content-type: application/json' \
--header 'PRIVATE-TOKEN: <group_owner_api_pat_here>' \
--data '{
  "name": "Endor Labs MR Security Scanner",
  "description": "Group webhook for GitLab MR scanning with Endor Labs.",
  "url": "https://api.endorlabs.com/webhooks/gitlab",
  "token": "<webhook_secret_token>",
  "enable_ssl_verification": true,
  "push_events": false,
  "merge_requests_events": true,
  "custom_headers": [
    {
      "key": "X-Endor-Installation-ID",
      "value": "<installation_uuid>"
    }
  ]
}'

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":                              utils.ToTime,
	"enumToString":                     utils.EnumToString,
	"getFindingURL":                    utils.GetFindingURL,
	"getPackageVersionURL":             utils.GetPackageVersionURL,
	"getPullRequestURL":                getEndorLabsPullRequestRunURL,
	"getFindingsCountString":           utils.GetFindingsCountString,
	"hasOtherFindings":                 hasOtherFindings,
	"getOtherFindingsPackageMarker":    getOtherFindingsPackageMarker,
	"getOtherFindingsDependencyMarker": getOtherFindingsDependencyMarker,
	"fixBackticks":                     utils.FixUnclosedBackticks,
	"getFirstPartyReachableFunctions":  utils.GetFirstPartyReachableFunctions,
	"hasFindingCategory":               utils.HasFindingCategory,
	// isNotEmptyString checks if a string is not empty
	"isNotEmptyString": utils.IsNotEmptyString,
	// getCustomLocation extracts the location from Custom field
	"getCustomLocation": func(finding *endorpb.Finding) string {
		return utils.GetCustomFieldValue(finding, "location")
	},
	// getCustomCodeSnippet extracts the code snippet from Custom field
	"getCustomCodeSnippet": func(finding *endorpb.Finding) string {
		return utils.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. 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 vertical three dots 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.

You can make changes to the GitLab App integrations or delete them. You can view the activity logs for the GitLab App and rescan your GitLab projects on demand.

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

2. Click Manage next to GitLab under Source Control Managers.

   

3. Click the three vertical dots next to the integration.

   You can choose from the following options:

   • Edit Integration
   • Delete Integration
   • View Sync Log

Edit GitLab App integration

To edit the GitLab App integration:

1. Click the three vertical dots next to the integration, and select Edit Integration.

2. You can update your personal access token and choose the scanners.

3. Select Merge Request Settings to edit the MR scans configuration.

   See GitLab App MR scans for more information.

4. Click Save.

   The changes are applicable from the next scanning cycle.

Delete Endor Labs GitLab App

To delete a GitLab App integration, click the three vertical dots next to the integration, and select Delete Integration.

When you delete the integration, it will also delete all child namespaces, projects and references associated with the auto-generated root group namespace. It also deletes any manually created namespaces and projects under auto-generated namespace.

View sync logs

Endor Labs detects and reports installation and synchronization errors during organization sync. These include expired tokens, insufficient permissions, invalid host configurations, and certificate issues. Sync logs report those errors that you can resolve.

To view sync logs, click the three vertical dots next to the integration, and select View Sync Logs.

The sync logs display details of synchronization attempts, including timestamps, error types, and diagnostic messages. These logs help identify issues such as authentication failures or configuration problems.

Types of errors

The sync logs detect and display the following categories of sync failures:

• Expired or invalid Personal Access Tokens (PATs): The PAT used for authentication has expired or is no longer valid. Edit the integration and provide a valid token.
• Insufficient PAT permissions: The PAT does not have the required scopes, such as repository read access. You must generate and provide a PAT with the correct access.
• Certificate related access issues: The certificates required to connect to the SCM are invalid, outdated, or untrusted. This error occurs in self-hosted GitLab instances that use custom SSL certificates. Update the certificate configuration or ensure the certificate chain is properly trusted to resolve the issue.
• Incorrect or invalid host URLs: The configured URL is incorrect or unreachable. Since you cannot edit the host URL, you need to delete and reinstall the integration using the correct URL.

After you resolve the issue, the error is automatically cleared during the next successful scan. You can manually re-trigger the scan using Rescan Org to verify the resolution immediately.

Do not use! Draft content. Development in progress.

You can make changes to the GitLab App integrations or delete them. You can view the activity logs for the GitLab App and rescan your GitLab projects on demand.

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

2. Click Manage next to GitLab under Source Control Managers.

3. Click the three vertical dots next to the integration.

   You can choose from the following options:

   • Update Credentials
   • Edit Integration
   • Delete Integration
   • View Sync Log

Update Credentials

To update the GitLab App credentials:

1. Click the three vertical dots next to the integration, and select Update Credentials.
2. You can update your Personal Access Token.
3. Click Save.

Note

You cannot update the GitLab organization URL. To monitor a different GitLab path, create a new installation.

Edit GitLab App integration

To edit the GitLab App integration:

1. Click the three vertical dots next to the integration, and select Edit Integration.
2. You can update the scanners.
3. Select Merge Request Settings to edit the MR scans configuration. See GitLab App MR scans for more information.

Scope of the Personal Access Token

Replace the personal access token with the personal access token of a project developer (minimum) role with the api scope for MR scans.

4. Click Start Scanning Repositories. The changes are applicable from the next scanning cycle.

Delete Endor Labs GitLab App

To delete a GitLab App integration, click the three vertical dots next to the integration, and select Delete Integration.

When you delete the integration, it will also delete all child namespaces, projects and references associated with the auto-generated root group namespace. It also deletes any manually created namespaces and projects under auto-generated namespace.

View sync logs

Endor Labs detects and reports installation and synchronization errors during organization sync. These include expired tokens, insufficient permissions, invalid host configurations, and certificate issues. Sync logs report those errors that you can resolve.

To view sync logs, click the three vertical dots next to the integration, and select View Sync Logs.

The sync logs display details of synchronization attempts, including timestamps, error types, and diagnostic messages. These logs help identify issues such as authentication failures or configuration problems.

Types of errors

The sync logs detect and display the following categories of sync failures:

• Expired or invalid Personal Access Tokens (PATs): The PAT used for authentication has expired or is no longer valid. Edit the integration and provide a valid token.
• Insufficient PAT permissions: The PAT does not have the required scopes, such as repository read access. You must generate and provide a PAT with the correct access.
• Certificate related access issues: The certificates required to connect to the SCM are invalid, outdated, or untrusted. This error occurs in self-hosted GitLab instances that use custom SSL certificates. Update the certificate configuration or ensure the certificate chain is properly trusted to resolve the issue.
• Incorrect or invalid host URLs: The configured URL is incorrect or unreachable. Since you cannot edit the host URL, you need to delete and reinstall the integration using the correct URL.

After you resolve the issue, the error is automatically cleared during the next successful scan. You can manually re-trigger the scan using Rescan Org to verify the resolution immediately.

Manually rescan GitLab projects

The GitLab App scans your repositories every 24 hours. Click Rescan Org to manually trigger a scan outside the 24-hour period.

Add more GitLab projects to scan

Click Scan More Repositories to go to Projects, where you can add more projects to scan through the GitLab App.