GitLab Integration¶

Faraday's GitLab integration allows you to export vulnerabilities as GitLab issues and maintain bidirectional status synchronization via webhooks. When a vulnerability status changes in Faraday, the linked GitLab issue updates automatically — and vice versa.

Availability: Commercial feature (requires licensed Faraday instance).

Verified against: Faraday Server v5.19.0 codebase, wiki doc dated 2024-07-02.

Overview¶

Status Mapping¶

Changes flow in both directions: closing a GitLab issue sets the linked Faraday vulnerability to Closed, and closing/risk-accepting a vulnerability in Faraday closes the GitLab issue.

Prerequisites¶

• A running Faraday Server instance (commercial edition)
• A GitLab account (gitlab.com or self-hosted) with project access
• A GitLab Personal Access Token with the API scope
• Network connectivity between Faraday Server and GitLab (for webhook callbacks)

Step 1: Configure GitLab¶

Create a Personal Access Token¶

1. Log in to GitLab.
2. Navigate to Settings > Access Tokens (https://gitlab.com/-/profile/personal_access_tokens).
3. Create a new Personal Access Token:
4. Name: Choose a descriptive name (e.g., faraday-integration)
5. Scopes: Select API (full API access)
6. Expiration: Set as appropriate for your security policy
7. Click Create personal access token.
8. Copy and save the token immediately — it will not be shown again.

Select a GitLab Project¶

1. Navigate to your Projects dashboard.
2. Note the project name (or namespace/project path) of the project you want to connect with Faraday.

Step 2: Configure Faraday¶

Connect Faraday to GitLab¶

1. Log in to the Faraday Web UI.
2. Click your username at the top-right corner and select Settings.
3. Navigate to Ticketing Tools and select GitLab from the dropdown.
4. Fill in the required fields:

1. Click the green Save button.
2. A success notification confirms the connection.

SSL Certificate (Self-Hosted GitLab)¶

For self-hosted GitLab instances using custom SSL certificates, you can configure the certificate path in server.ini:

[gitlab_integration]
ssl_cert_path = /path/to/ca-bundle.pem

Note: The [gitlab_integration] INI section is only available in commercial editions. Community edition config.py only parses 5 INI sections (database, faraday_server, storage, logger, limiter) and silently ignores other sections.

Step 3: Configure the Issue Template¶

Templates are stored on the Faraday Server at:

~/.faraday/integrations_templates/

(Default: /home/faraday/.faraday/integrations_templates/)

Select a template from the dropdown in the Ticketing Tools configuration, or create a custom Jinja2 template.

Template Variables¶

The following vulnerability fields are available in templates via the vuln object:

Template Configuration Directives¶

Templates should include these configuration directives at the top:

{% set issuetracker_config = 'gitlab' %}
{% set http_size_config = 4096 %}

• issuetracker_config: Must be 'gitlab' for GitLab integration
• http_size_config: Maximum character length for HTTP request/response fields (truncated with |truncate() filter)

Example Template¶

{# This is a Template for Faraday GitLab Integration #}
{# Pre-Flight Adjustments #}
{% set issuetracker_config = 'gitlab' %}
{% set http_size_config = 4096 %}
{% if 'med' in vuln.severity %}
{% set corrected_severity = 'Medium' %}
{% else %}
{% set corrected_severity = vuln.severity %}
{% endif %}

{# Issue template structure #}
{% if 'VulnerabilityWeb' in vuln.type %}
# [{{ corrected_severity | capitalize }}] {{ vuln.name }} - ({{ vuln.path }})
{% else %}
# [{{ corrected_severity | capitalize }}] {{ vuln.name }}
{% endif %}

## Description
{{ vuln.desc }}

#### This issue has been rated as: `{{ corrected_severity | capitalize }}`

Affected Asset: {{ vuln.target }}
{% if vuln.website %}
Affected URL: {{ vuln.website }}{{ vuln.path }}
{% endif %}

{% if vuln.hostnames %}
#### Hostnames
{% for hostname in vuln.hostnames %}
- {{ hostname }}
{% endfor %}
{% endif %}

## Recommendations
{{ vuln.resolution }}
{% for ref in vuln.refs %}
- {{ ref }}
{% endfor %}

{% if vuln.easeofresolution %}
#### Estimated ease of resolution
{{ vuln.easeofresolution | capitalize }}
{% endif %}

### Technical Details
{% if vuln.data %}
#### Proof of Concept
{{ vuln.data }}
{% endif %}

{% if vuln.request %}
#### Request
{{ vuln.request | truncate(http_size_config, False, '...', 0) }}
{% endif %}

{% if vuln.response %}
#### Response
{{ vuln.response | truncate(http_size_config, False, '...', 0) }}
{% endif %}

## Issue [{{ vuln.id }}] {{ vuln.name }} [{{ vuln.status }}]
{# A vulnerability might be associated with more than one issuetracker id #}
{% for key, value in vuln.issuetracker_json.items() %}
{% if issuetracker_config in key %}
This issue has already been reported in this platform:
- {{ key | capitalize }}
{% for line in value %}
- Issue: {{ line.url }}
{% endfor %}
{% endif %}
source: created by {{ vuln.owner or "faraday" }} using {{ vuln.tool }} - {{ vuln.external_id }} - {{ vuln.date }}
{% endfor %}
{# end of file #}

Step 4: Export Vulnerabilities to GitLab¶

1. In the Faraday Web UI, go to Manage > Vulns.
2. Click the Add columns dropdown and add the issuetracker column to see integration status.
3. Select one or more vulnerabilities to export.
4. Click Tools > GitLab.
5. Confirm the export by clicking Ok.
6. The word GitLab appears in the issuetracker column for exported vulnerabilities. Click it to open the created GitLab issue directly.

What Happens During Export¶

• Faraday renders the Jinja2 template with the vulnerability data.
• A new GitLab issue is created in the configured project via the GitLab API.
• The vulnerability's issuetracker field is updated with a reference to the GitLab issue URL.
• The vulnerability's external_id field may store the GitLab issue identifier.

Step 5: Set Up Bidirectional Status Sync (Webhooks)¶

Webhooks enable automatic status synchronization between Faraday and GitLab. When configured, closing or reopening an issue in GitLab automatically updates the linked vulnerability in Faraday, and vice versa.

Create a Faraday User Token (GitLab Scope)¶

1. In the Faraday Web UI, go to Settings > Access Tokens.
2. Click Add Token.
3. Configure the token:
4. Scope: Select GitLab
5. Alias: Descriptive name (e.g., gitlab-webhook)
6. Expiration: Set duration or leave empty for non-expiring
7. Click Create.
8. Copy the token immediately — it is displayed only once.

Token Details: GitLab-scoped tokens are stored in the user_token table with scope='gitlab'. They support optional expiration (expires_at field) and can be revoked from the Access Tokens settings. See [[token-lifecycle]] for internals.

Configure the GitLab Webhook¶

1. Go to your GitLab project.
2. Navigate to Settings > Webhooks.
3. Configure the webhook:

1. Click Save changes.
2. Test the webhook: Open the Test dropdown and select Issues events. You should receive a successful response.

How Webhook Sync Works¶

GitLab Issue Status Change
  ├─ GitLab sends webhook POST to Faraday
  ├─ Faraday validates the secret token
  ├─ Faraday looks up the linked vulnerability via issuetracker data
  └─ Faraday updates the vulnerability status per the mapping table

Faraday Vulnerability Status Change
  ├─ Faraday detects status change on a linked vulnerability
  ├─ Faraday calls GitLab API to update the issue status
  └─ GitLab issue reflects the new status

Permissions¶

GitLab integration access is controlled by Faraday's role-based permission system.

Users must have the appropriate role with integrations group permissions to configure and use the GitLab integration.

Data Model¶

Vulnerability Fields Used by Integration¶

UserToken Model¶

Tokens for GitLab webhook authentication:

Configuration Storage¶

Integration settings are stored in the configuration database table:

CREATE TABLE configuration (
    id        INTEGER PRIMARY KEY,
    key       VARCHAR UNIQUE NOT NULL,
    value     JSONB NOT NULL,
    create_date  TIMESTAMP,
    update_date  TIMESTAMP,
    creator_id   INTEGER,
    update_user_id INTEGER
);

GitLab integration configuration is stored under the key gitlab_integration as a JSON object.

Troubleshooting¶

Common Issues¶

Checking Integration Status¶

• Issuetracker column: Add the issuetracker column in the vulnerability table to see which vulnerabilities have been exported.
• Access Tokens: Navigate to Settings > Access Tokens to verify token status, scope, and expiration.
• Server logs: Check Faraday Server logs for webhook processing errors.

API Reference¶

Webhook Endpoint¶

POST /_api/v3/integrations/gitlab/issues/update

Authentication: GitLab secret token (Faraday User Token with GitLab scope)

Triggered by: GitLab webhook on issue state changes

Payload: Standard GitLab webhook payload for issue events

Integration Configuration¶

Integration settings are managed through the Faraday Web UI under Settings > Ticketing Tools > GitLab. The configuration is stored in the configuration database table and can also be managed via the settings API.

Changelog¶

Source References¶

• Wiki source: repos/faraday-wiki/docs/integration-gitlab.md
• Permission definitions: faraday/server/utils/permissions.py
• UserToken model: faraday/server/models.py (line ~2636)
• Configuration model: faraday/server/models.py (line ~3641)
• Vulnerability schema: faraday/server/api/modules/vulns_base.py
• Gap audit: [[audit-settings-gaps]] MED-23 — [gitlab_integration] section is commercial-only