GitLab

GitLab is an open-source version control and collaboration platform. You can bring code projects, packages, repositories, user information, and other security data from GitLab into Brinqa to enhance your organization's security and risk management capabilities, thus strengthening your cybersecurity posture.

This document details the information you must provide for the connector to authenticate with GitLab and how to obtain that information from GitLab. See create a data integration for step-by-step instructions on setting up the integration.

Required connection settings

When setting up a data integration, select GitLab from the Connector drop-down. You must provide the following information to authenticate GitLab with Brinqa:

• ARL: The GitLab API Server URL. The default URL is https://gitlab.com.

• Access token: The personal access token associated with the GitLab account, which must have permissions to log in to the API server and return data.

Obtain a GitLab access token

For the GitLab connector to access the GitLab API, you must provide an access token. To obtain an access token, follow these steps:

1. Log in to your organization's GitLab portal as an administrator.

2. Navigate to the GitLab project that you want to integrate into the Brinqa Platform.

3. Navigate to Settings > Access Tokens.

4. Click Add new token.

   Complete the following fields:

   • Token name: Provide a name for the token.

   • Expiration date: Set an expiry date for the token.

   • Select a role: Click the drop-down and select the Reporter role, as this is the minimum level of access required to retrieve data from the GitLab API.

   • Select scopes: Select the following scopes, as these are the minimum scopes required to retrieve data from the GitLab API:

     • read_api
     • read_repository
     • read_registry

   

5. Click Create project access token.

   Your new access token displays. You can not view the token again. Copy and save it to a safe and secure location.

note

If you do not have permissions to create an access token, contact your GitLab administrator. For additional information, see GitLab documentation on Access Tokens and Permissions and Roles.

Types of data to retrieve

The GitLab connector can retrieve the following types of data from the GitLab API:

Table 1: Data retrieved from GitLab

Connector Object	Required	Maps to Data Model
Code Project	Yes	Code Project
Code Repository	Yes	Code Repository
Open Source Finding	Yes	Open Source Finding
Open Source Finding Definition	Yes	Open Source Finding Definition
Package	Yes	Package
Person	Yes	Person
Static Code Finding	Yes	Static Code Finding
Static Code Finding Definition	Yes	Static Code Finding Definition

note

For detailed steps on how to view the data retrieved from GitLab in the Brinqa Platform, see How to view your data.

Attribute mappings

Expand the sections below to view the mappings between the source and the Brinqa data model attributes:

Code Project

Table 2: Code Project attribute mappings

Source Field Name	Maps to Attribute
allow_merge_on_skipped_pipeline	Local variable
analytics_access_level	Local variable
archived	Local variable
auto_cancel_pending_pipelines	Local variable
auto_devops_deploy_strategy	Local variable
auto_devops_enabled	Local variable
autoclose_referenced_issues	Local variable
avatar_url	Local variable
build_timeout	Local variable
builds_access_level	Local variable
can_create_merge_request_in	Local variable
ci_allow_fork_pipelines_to_run_in_parent_project	Local variable
ci_config_path	Local variable
ci_default_git_depth	Local variable
ci_forward_deployment_enabled	Local variable
ci_forward_deployment_rollback_allowed	Local variable
ci_job_token_scope_enabled	Local variable
ci_restrict_pipeline_cancellation_role	Local variable
ci_separated_caches	Local variable
container_registry_access_level	Local variable
container_registry_enabled	Local variable
container_registry_image_prefix	Local variable
created_at	sourceCreatedDate
creator_id	Local variable
default_branch	Local variable
description	Local variable
empty_repo	Local variable
enforce_auth_checks_on_uploads	Local variable
external_authorization_classification_label	Local variable
forks_count	Local variable
forking_access_level	Local variable
group_runners_enabled	Local variable
http_url_to_repo	Local variable
id	uid
import_status	Local variable
issues_access_level	Local variable
issues_enabled	Local variable
job_enabled	Local variable
keep_latest_artifact	Local variable
last_activity_at	Local variable
links_cluster_agents	Local variable
links_events	Local variable
links_issues	Local variable
links_labels	Local variable
links_members	Local variable
links_merge_requests	Local variable
links_repo_branches	Local variable
links_self	Local variable
lfs_enabled	Local variable
merge_commit_template	Local variable
merge_method	Local variable
merge_requests_access_level	Local variable
merge_requests_enabled	Local variable
name	name
name_with_namespace	Local variable
namespace.full_Path	Local variable
namespace.kind	Local variable
namespace.name	Local variable
namespace.parent_Id	Local variable
namespace.path	Local variable
namespace.webUrl	Local variable
open_issues_count	Local variable
owner_id	Local variable
pages_access_level	Local variable
packages_enabled	Local variable
path	Local variable
path_with_namespace	Local variable
permission.group_access_level	Local variable
permission.group_notification_level	Local variable
permissions.project_access_level	Local variable
permissions.project_notification_level	Local variable
printing_merge_request_link_enabled	Local variable
public_jobs	Local variable
readme_url	Local variable
remove_source_branch_after_merge	Local variable
repository_access_level	Local variable
request_access_enabled	Local variable
resolve_outdated_diff_discussions	Local variable
security_and_compliance_access_level	Local variable
security_and_compliance_enabled	Local variable
shared_runners_enabled	Local variable
snippets_access_level	Local variable
snippets_enabled	Local variable
squash_commit_template	Local variable
squash_option	Local variable
ssh_url_to_repo	Local variable
star_count	Local variable
suggestion_commit_message	Local variable
topics	Local variable
updated_at	Local variable
visibility	Local variable
warn_about_potentially_unwanted_characters	Local variable
web_url	Local variable
wiki_access_level	Local variable
wiki_enabled	Local variable

Code Repository

Table 3: Code Repository attribute mappings

Source Field Name	Maps to Attribute
id	uid
mode	Local variable
name	name
path	Local variable
type	Local variable

Package

Table 4: Package attribute mappings

Source Field Name	Maps to Attribute
_links.web_path	Local variable
created_at	sourceCreatedDate
id	uid
last_downloaded_at	Local variable
name	name
package_type	categories
pipeline.created_at	Local variable
pipeline.id	Local variable
pipeline.iid	Local variable
pipeline.project_id	Local variable
pipeline.ref	Local variable
pipeline.sha	Local variable
pipeline.source	Local variable
pipeline.status	Local variable
pipeline.updated_at	Local variable
pipeline.user.id	Local variable
pipeline.user.username	Local variable
pipeline.web_url	Local variable
pipelines	Local variable
status	Local variable
tags	Local variable
version	latestVersion

Person

Table 5: Person attribute mappings

Source Field Name	Maps to Attribute
access_level	Local variable
avatar_url	Local variable
created_at	sourceCreatedDate
created_by.id	Local variable
created_by.username	owner
expires_at	Local variable
id	uid
locked	Local variable
membership_state	Local variable
name	name
state	Local variable
username	username
web_url	Local variable

Open Source Finding

Table 6: Open Source Finding attribute mappings

Source Field Name	Maps to Attribute
blob_path	Local variable
confidence	Local variable
create_jira_issue_url	Local variable
create_vulnerability_feedback_dismissal_path	Local variable
create_vulnerability_feedback_issue_path	Local variable
create_vulnerability_feedback_merge_request_path	Local variable
dismissal_feedback	Local variable
evidence	Local variable
evidence_source	Local variable
false_positive	Local variable
id	uid
identifiers.external_id	Local variable
identifiers.external_type	Local variable
identifiers.name	Local variable
identifiers.url	Local variable
location.class	Local variable
location.file	path
location.method	Local variable
location.start_line	Local variable
name	uid
project_fingerprint	Local variable
project.id	targets
report_type	categories
scan.build_id	Local variable
scan.created_at	Local variable
scan.findings_partition_number	Local variable
scan.id	Local variable
scan.pipeline_id	Local variable
scan.status	lastScanStatus
scan.type	Local variable
scan.updated_at	lastScanned
scanner.external_id	Local variable
scanner.name	Local variable
scanner.vendor	Local variable
severity	Local variable
state	status(normalize), statusCategory, sourceStatus
uuid	Local variable
vulnerable_package_name	Local variable
vulnerable_package_value	Local variable

Open Source Finding Definition

Table 7: Open Source Finding Definition attribute mappings

Source Field Name	Maps to Attribute
confidence	Local variable
description	description
dismissal_feedback	Local variable
evidence	Local variable
evidence_source	Local variable
false_positive	Local variable
id	uid
identifiers.external_id	Local variable
identifiers.external_type	Local variable
identifiers.name	Local variable
identifiers.url	Local variable
links	references
name	name,uid
report_type	categories
scanner.external_id	Local variable
scanner.name	Local variable
scanner.vendor	Local variable
severity	severity(normalize), sourceSeverity, severityScore
solution	recommendation
uuid	Local variable
vulnerable_package_name	Local variable
vulnerable_package_value	Local variable

Static Code Finding

Table 8: Static Code Finding attribute mappings

Source Field Name	Maps to Attribute
blob_path	Local variable
confidence	Local variable
create_jira_issue_url	Local variable
create_vulnerability_feedback_dismissal_path	Local variable
create_vulnerability_feedback_issue_path	Local variable
create_vulnerability_feedback_merge_request_path	Local variable
dismissal_feedback	Local variable
evidence	Local variable
evidence_source	Local variable
false_positive	Local variable
id	uid
identifiers.external_id	Local variable
identifiers.external_type	Local variable
identifiers.name	Local variable
identifiers.url	Local variable
location.class	Local variable
location.file	path
location.method	Local variable
location.start_line	Local variable
name	uid
project_fingerprint	Local variable
project.id	targets
report_type	categories
scan.build_id	Local variable
scan.created_at	Local variable
scan.findings_partition_number	Local variable
scan.id	Local variable
scan.pipeline_id	Local variable
scan.status	lastScanStatus
scan.type	Local variable
scan.updated_at	lastScanned
scanner.external_id	Local variable
scanner.name	Local variable
scanner.vendor	Local variable
severity	Local variable
state	status(normalize), statusCategory, sourceStatus
uuid	Local variable
vulnerable_package_name	Local variable
vulnerable_package_value	Local variable

Static Code Finding Definition

Table 9: Static Code Finding Definition attribute mappings

Source Field Name	Maps to Attribute
confidence	Local variable
description	description
dismissal_feedback	Local variable
evidence	Local variable
evidence_source	Local variable
false_positive	Local variable
id	uid
identifiers.external_id	Local variable
identifiers.external_type	Local variable
identifiers.name	Local variable
identifiers.url	Local variable
links	references
name	name,uid
report_type	categories
scanner.external_id	Local variable
scanner.name	Local variable
scanner.vendor	Local variable
severity	severity(normalize), sourceSeverity, severityScore
solution	recommendation
uuid	Local variable
vulnerable_package_name	Local variable
vulnerable_package_value	Local variable

info

Local variable indicates that the field is processed within a specific context, such as a particular workflow or calculation. Unlike other attributes, local variables aren't mapped to the unified data models. They only exist on the source data model.

Additional settings

The GitLab connector contains additional options for specific configuration:

• Page size: The maximum number of records to get per API request. The default setting is 100. It is not recommended to go over 100.

• Parallel requests: The maximum number of parallel API requests. The default setting is 4.

Operation options

The GitLab connector supports the following operation options. See connector operation options for information about how to apply them.

Table 10: GitLab connector operation options

Connector Object	Option	All Possible Values	Description	Example
Code Project	archived	true, false	Limit retrieved code projects by their archived status, as determined by GitLab.	Key: archived Value: true This key and value combination retrieves archived code projects.
	owned	true, false	Limit retrieved code projects by whether or not they have an owner, as determined by GitLab.	Key: owned Value: true. This key and value combination only retrieves code projects that have an owner.
	visibility	internal, public, private	A comma-separated list of code project visibility statuses. Limit retrieved code projects by their visibility status, as determined by GitLab.	Key: visibility Value: internal,private. This key and value combination only retrieves internal and private code projects.
Code Repository	path	Any code repository path	A comma-separated list of of code repository paths. Limit the retrieval of code repositories from the specified path(s).	Key: path Value: src/main,files/images. This key and value combination only retrieves code repositories with the src/main or files/images paths.
	recursive	true, false	Limit retrieved repository content to either a flat or recursive directory tree. Default is false.	Key: recursive Value: true. This key and value combination retrieves the content recursively within all subdirectories.
	ref	Any code repository branch or tag name	A comma-separated list of code repository branch or tag names. Limit retrieval of code projects by the specified ref.	Key: ref Value: main,new-pipeline,test-branch-1. This key and value combination only retrieves code repositories with the main, new-pipeline, or test-branch-1 branch or tag names.
Package	status	default, error, hidden, pending_destruction, processing	A comma separated list of package statuses, as determined by GitLab. Retrieve packages with the specified status(es).	Key: status Value: default,processing. This key and value combination only retrieves default and processing packages.
Open Source Finding, Open Source Finding Definition, Static Code Finding, Static Code Finding Definition	severity	info, unknown, low, medium, high, critical	A comma-separated list of vulnerability severities, as determined by GitLab. Retrieve vulnerabilities with the specified severity level(s).	Key: severity Value: high,critical. This key and value combination only retrieves high and critical vulnerabilities.

note

The option keys and values are case-sensitive as they are shown in this documentation.

APIs

The GitLab connector uses the GitLab REST API v4. Specifically, it uses the following endpoints:

Table 11: GitLab API Endpoints

Connector Object	API Endpoint
Code Project	GET /api/v4/projects?membership=true
Code Repository	GET /api/v4/projects
	GET /api/v4/projects/:id/repository/tree
Package	GET /api/v4/projects
	GET /api/v4/projects/:id/packages
Person	GET /api/v4/projects
	GET /api/v4/projects/:id/members/all
Open Source Finding	GET /api/v4/projects
	GET /api/v4/projects/:id/vulnerability_findings
Open Source Finding Definition	GET /api/v4/projects
	GET /api/v4/projects/:id/vulnerability_findings
Static Code Finding	GET /api/v4/projects
	GET /api/v4/projects/:id/vulnerability_findings
Static Code Finding Definition	GET /api/v4/projects
	GET /api/v4/projects/:id/vulnerability_findings

Changelog

The GitLab connector has undergone the following changes:

3.0.1

• Changed the CREATED_BY attribute type on the Person object from integer to string.

3.0.0

• Initial Integration+ release.