GitLab Workflow Integration

The Veracode GitLab Workflow Integration allows you to automate security scanning for all of your GitLab repositories.

The integration repository includes the workflow templates required for the GitLab Workflow Integration to function properly. In addition, it includes the configuration file, veracode.yml, which stores the default settings for you to scan your repositories with Veracode. This document explains how to install the integration, configure Veracode scans, and view your scan results.

Language support

The GitLab Workflow Integration supports repository scanning for the following languages:

Language	Version	Package manager	Static support	SCA support
.NET	.NET 6, 7, 8	Not applicable	Yes	Yes
Java	Java 21 or later	Gradle 8.7	Yes	Yes
JavaScript and TypeScript	Not applicable	NPM, Yarn	Yes	Yes
Python	Python 3	pip	Yes	Yes

For Static Analysis, the GitLab Workflow Integration automatically compiles the repository by default. However, for some applications, you may need to provide specific compilation instructions in the original repository. See the packaging requirements for each language.

For SCA, see the agent-based scan support matrix for additional details.

GitLab support

The GitLab Workflow Integration is currently supported only on GitLab.com. It is not supported on GitLab Dedicated Server.

Prerequisites

Before you begin

Ensure you have:

• Enabled the integration for your Veracode account. To enable the integration, contact Veracode Technical Support.
• The Administrator or Security Lead role in the Veracode Platform.
• The Owner role in your GitLab account.
• Valid API credentials to run static scans.
• A valid SCA agent token to run SCA agent-based scans.
• On GitLab, created a personal access token from a service account that has access to all the groups targeted for scan. Ensure that you select the scope api when you create the personal access token. After you create the personal access token, save it to a secure location.

Install the GitLab Workflow Integration

Install the GitLab Workflow Integration from the Veracode Platform.

To complete this task:

1. Sign in to the Veracode Platform.
2. Select Repository Scan from the left menu.
3. If you have other integrations, from the top-right corner of the page, select ADD SCM INTEGRATION.
4. Select GitLab, and then select NEXT.
5. In PERSONAL ACCESS TOKEN, enter the personal access token you created in the prerequisites.
6. Select the disclaimer, then select NEXT. The Select Groups to Install section opens.
7. From the list of groups, select the groups where you want to install the integration. Then, select NEXT. The Configure Veracode API Keys and Secrets section opens. To select all the groups, select the Group Name checkbox.
8. In VERACODE API ID and VERACODE API KEY, enter the API credentials from the prerequisites. Optionally, to run SCA agent-based scans, in SRCCLR API TOKEN, enter the SCA agent token.
9. Select Install.

On successful installation, Veracode creates a veracode project in the selected groups and adds webhooks to all of them.

Configure a scan

In the veracode.yml file, configure options to fit your organization's workflow, such as:

• The types of scans to run
• The branches to target
• The Veracode security policy to apply
• The option to break the build in case of a failure
• Whether the scan should be triggered by a push or a pull

By default, the veracode.yml file triggers the following scans on any branch of a project within a group:

• Static pipeline scan on any push or merge activity on any branch
• SCA agent-based scan on any push or merge activity on any branch
• Veracode Container Security scan on any push or merge activity on any branch

If you set analysis_on_platform to true, these additional scans are run by default:

• Sandbox scan: Sends results to the Veracode Platform, when a pull request targets analysis_branch.
• Policy scan: Sends results to the Veracode Platform, after code is merged into analysis_branch.

To customize these settings for your own organization's workflow, edit the veracode.yml file.

Important

The GitLab Workflow Integration only supports jobs that run on Linux agents.

Specify groups or repositories to scan

By default, the GitLab Workflow Integration scans all repositories and groups in which it is installed, except for the veracode repository.

You can include and exclude specific groups or repositories from scans.

Exclude specific groups or repositories

To complete this task:

1. Open repo_list.yml in the veracode repository.
2. Under exclude_repos:, list the groups, subgroups or repositories you want to exclude. Each group or repository name must be enclosed in single quotes. For example: ‘group-A/*' or 'java_Repo'. Here 'group-A’ is the group name as displayed in the URL and not the actual group name.

Entering ‘group-A/*' excludes all the groups and repositories within ‘group-A/*'.

Include specific groups or repositories

To complete this task:

1. Open repo_list.yml in the veracode project.
2. Under include_repos:, list the groups, subgroups or repositories you want to include. Each group or repository name must be enclosed in single quotes. For example: ‘group-A/*' or 'java_Repo'. Here 'group-A’ is the group name as displayed in the URL and not the actual group name.

Entering ‘group-A/*' includes all the groups and repositories within ‘group-A/*'.

The Veracode configuration file

To customize the integration, configure the following values in your veracode.yml file.

Value	Description	Default value
push:trigger	If true, triggers a pipeline when you commit changes to a branch.	true
push:branches_to_run	Branches that trigger pipeline scans when you commit changes. If set to '*', all branches can trigger scans.	'*'
push:branches_to_exclude	Branches that do not trigger scans. Only applies if branches_to_run is set to '*'.
pull_request:trigger	If true, triggers a scan when you perform a pull request action.	true
pull_request:action	Pull request actions that trigger scans. Valid values are: opened, reopened, edited, synchronize, and closed.	opened and synchronize
pull_request:target_branch	Target branch that triggers scans when you perform pull request actions.	default_branch
analysis_branch	The branch submitted to the Veracode Platform for analysis. If you do not enter a valid branch name, Veracode uses the default branch.	default_branch
analysis_on_platform	If false, scans are not submitted to the Veracode Platform. If true, scans from the analysis_branch are submitted to the Platform, creating an application profile that has the repository's name.	false
break_build_policy_findings	If true, the build fails when the policy name is invalid.	true
error_message	Error message that appears when the build fails.	Veracode SAST scan faced a problem. Please contact your Veracode administrator for more information.
policy	The application security policy applied to your scan findings, if a policy is not already assigned to your application profile.	'Veracode Recommended Medium + SCA'
create_issue	If true, GitLab generates issues for scan findings.	false
issues:trigger	If true, triggers a scan when you create an issue containing the commands value or add a comment containing the commands value to an issue.	false
issues:commands	Text that triggers an on-demand scan when you add it to a GitLab issue.	"ENTER_COMMAND_TO_EXECUTE_SCAN"
filter_mitigated_flaws	If true, mitigated flaws are excluded from repository checks, the Issues tab, and the code scanning alerts.	true

See the following example veracode.yml file:

veracode_static_scan:
  push:
    trigger: true
    # Please only specify either branches_to_run or branches_to_exclude
    # Entering both will only execute branches_to_run
    # Leaving them both blank means this will never run
    branches_to_run:
      - '*'
    branches_to_exclude:
  pull_request:
    trigger: false
    action:
      - opened
      - synchronize
    target_branch:
      - default_branch
  # If the analysis_on_platform is set to true,
  # Veracode will save your last scan result on the default branch as an application profile with the same name as your scanned repository on the Veracode Platform. 
  # If the analysis_on_platform is set to false, scan results will not be saved to the Veracode platform.
  analysis_on_platform: false
  # If break_build_policy_findings is set to true, the build will break when findings violate the policy.
  break_build_policy_findings: true
  # If break_build_invalid_policy is set to true, the build will break when the policy name is invalid.
  break_build_invalid_policy: true
  # If the break_build_on_error is set to true, the build will break if the scan failed to complete in time or with an error and the error_message will be displayed.
  break_build_on_error: false
  error_message: "Veracode static scan faced a problem. Please contact your Veracode administrator for more information."
  # Default policy to be used if a policy isn't already assigned to the application profile.
  policy: 'Veracode Recommended Medium + SCA'
  # If the create_code_scanning_alert is set to true, GitLab security code scanning vulnerability alerts will be created for static findings.
  create_code_scanning_alert: false
  # If the create_issue is set to true, GitLab Issues will be created for static findings.
  create_issue: false
  # If the trigger is set to true, a scan is triggered when you create an issue containing the commands value or add a comment containing the commands value to an issue.
  # Syntax to be used - COMMANDS_VALUE [branch: BRANCH_NAME]
  issues:
    trigger: false
    commands:
      - "Veracode Static Scan"

veracode_sca_scan:
  push:
    trigger: false
    # Please only specify either branches_to_run or branches_to_exclude
    # Entering both will only execute branches_to_run
    # Leaving them both blank means this will never run
    branches_to_run:
      - '*'
    branches_to_exclude:
  pull_request:
    trigger: false
    action:
      - opened
      - synchronize
    target_branch:
      - default_branch
  # If the break_build_on_error is set to true, the build will break if the scan failed to complete or with an error, no libraries were found, 
  # or no build system was found and the error_message will be displayed.
  break_build_on_error: true
  error_message: "Veracode SCA scan faced a problem. Please contact your Veracode administrator for more information."
  # If the trigger is set to true, a scan is triggered when you create an issue containing the commands value or add a comment containing the commands value to an issue.
  # Syntax to be used - COMMANDS_VALUE [branch: BRANCH_NAME]
  issues:
    trigger: false
    commands:
      - "Veracode SCA Scan"
 

Configure integration for individual repositories

Adding a veracode.yml file to individual repositories lets you override specific scan settings defined in your organization's central veracode.yml file.

To overwrite the settings:

1. Add a veracode.yml file to the root of your developer repository.

2. Add the updated configuration to the file. All veracode.yml files must include the heading and the value that you want to overwrite. For example, this veracode.yml file overwrites the policy applied to Static Analysis scans and sets a custom workflow for the repository:

   veracode_static_scan:
    policy: 'Veracode Recommended Very High'

Trigger on-demand scanning with GitLab issues

You can trigger scans on demand using GitLab issues.

Before you begin:

Ensure you have:

• Permissions to create issues in GitLab.
• In your veracode.yml file, under issues:
  • Set trigger to true.
  • Set commands to the value that you will use as the description for your issues. If you want to trigger Static Analysis, SCA, and Container Security scans separately, you must assign different commands values.

To complete this task:

1. In your GitLab repository, select the Issues tab.
2. Enter a title.
3. In the Add a description field, enter the commands value from the veracode.yml file. For example, veracode-static-scan or veracode-sca-scan. By default, this triggers a policy scan on analysis branch, which is usually the main branch. To include multiple commands, enter a comma-separated list. To specify a branch to scan, add the branch in parentheses. For example, veracode-static-scan[branch:dev-patch-101].
4. To trigger additional scans for the same issue, enter the commands value in a comment on the issue.

View scan results

You can view Veracode scan results either in GitLab or from the Veracode Platform.

From GitLab

Static Analysis results are available in the pipeline console log.

To complete this task:

1. Open the veracode project.
2. Select Build, and then select Pipelines.
3. After the pipeline for a commit has passed, select , then select pipeline.

The results are displayed in the console log. Vulnerabilities, if any, are categorized based on the severity.

If vulnerabilities are detected during the scan, the following artifacts are generated in the directory named veracode-artifact:

• Scan results for the vulnerabilities in the project.
• One or more build files based on the number of languages scanned.

From Veracode Platform

If you set analysis_on_platform to true, you can view scan results in the Veracode Platform.

Static Analysis scans return a list of annotations describing each static flaw and a link to the Veracode Platform where you can view a full report of your results. If an application profile for a scanned repository does not already exist, Veracode automatically creates one using the repository name as the profile name.

For more information about reviewing Static Analysis findings, see Reviewing scan results.

SCA scans return a summary report of your open source security findings as well as a detailed list of libraries, vulnerabilities, and licenses. For more information about SCA findings, see Viewing agent-based scan results.

GitLab issues

If you have triggered on-demand scanning with GitLab issues, you can view your issues in GitLab from Issues.

Update credentials

If your Veracode API credentials or SCA agent token expires, you can update it.

Before you begin: Ensure you have:

• The Administrator or Security Lead role in the Veracode Platform.
• The Owner role in your GitLab account.
• Valid API credentials to run static scans.
• Valid SCA agent token to run SCA agent-based scans.
• On GitLab, created a personal access token from a service account that has access to all the groups targeted for scan. Ensure that you select the scope api when creating the personal access token. After you create the personal access token, save it to a secure location.

To complete this task:

1. In the Veracode Platform, select Repository Scan from the left menu. The Repository Scanning page opens.
2. Select GitLab, and then select Next. The GitLab Access Token section opens.
3. Select Update. In PERSONAL ACCESS TOKEN, enter the token you created in the prerequisites..
4. Select the disclaimer, then select NEXT. The Configure Veracode API Keys and Secrets section opens.
5. In VERACODE API ID and VERACODE API KEY, enter your API credentials. Optionally, to run SCA agent-based scans, enter the token in SRCCLR API TOKEN.
6. Select Update.

Veracode updates the new API credentials or SCA agent token in the installed application.

Uninstall the GitLab Workflow Integration

You might need to uninstall the GitLab Workflow Integration for one of the following reasons:

• The existing personal access token is unavailable.
• You want to delete the GitLab Workflow Integration.
• You want to reinstall the GitLab Workflow Integration.

Important

If you plan to reinstall the integration later, save your existing veracode.yml and repo_list.yml files locally. After reinstallation, replace these files in GitLab with the saved versions.

Manual uninstallation

To complete this task:

1. In GitLab, delete the veracode project.

2. For all the groups:

   • Open the group.
   • Select Settings, then select Webhooks.
   • Delete the group webhook that was created during installation.

Uninstall from the Veracode Platform

Before you begin Ensure you have:

• The Administrator or Security Lead role in the Veracode Platform.
• The Owner role in your GitLab account.
• Valid API credentials to run static scans.
• A valid SCA agent token to run SCA agent-based scans.
• On GitLab, created a personal access token from a service account that has access to all the groups targeted for scan. Ensure that you select the scope api when creating the personal access token. After you create the personal access token, save it to a secure location.

To complete this task:

1. In the Veracode Platform, select Repository Scan from the left menu. The Repository Scanning page opens.
2. Select GitLab, then select Next. The GitLab Access Token section opens.
3. Select Uninstall. In PERSONAL ACCESS TOKEN, enter the token you created in the prerequisites..
4. Select the disclaimer, then select NEXT. The Select Groups to Uninstall section opens.
5. From the list of groups, select the groups to uninstall. To select all groups, select the Group Name checkbox.
6. Select Uninstall.

Veracode uses the personal access token to remove the previously created webhooks and delete the 'veracode' project from the selected groups. This action securely removes all integration-specific access and data.