Getting Started: Black Duck Security Bulk Onboarding

GitLab CI/CD variables setup

The generated workflow file, by default references variables, secrets and a GitLab Personal Access Token.

This section explains an overview for how to add variables, secrets and token at the workspace and repository level.

Before proceeding, ensure all requirements in the Black Duck Security Prerequisites are met.

Please refer to the appropriate platform documentation for an overview of the required secrets and variables:

• Black Duck® SCA
• Coverity
• Polaris

Group level configuration (recommended)

Variables specified for a group can be accessed from all projects that belong to the group. You must be an owner to manage group variables.

1. Go to GitLab.com
2. Click on the GitLab Home cog from the top left of the GitLab page.
3. Select Groups from the left navigation bar.
4. Select a particular group for which you want to onboard GitLab workflow.
5. Select CI/CD from the Settings dropdown menu.
6. From the Variables dropdown click on Add variable
   1. For adding a secret, use Masked or Masked and hidden option
   2. Uncheck Protect variable from the flags option
   3. Specify the Key and Value
   4. Click on Add Variable to save
      Note: A protected variable in GitLab CI/CD is only available to pipelines running on protected branches or protected tags.

      • If Protect variable is unchecked, the variable can be used by pipelines on any branch.
      • If Protect variable is checked, the variable will not be available in Merge Request pipelines and will only work on protected branches or tags.

Group variables can be overridden by subgroup/project variables.

Group variables can be accessed in the CI/CD pipeline by all users with the write access for any project (private or public).

You must be an owner of a group to manage variables.

Subgroup level configuration

CI/CD variables added at the subgroup level can be used by any user who has write access in the projects inside the subgroup. To access and configure the subgroup variables, the user must be an owner of that subgroup.

From the subgroup's settings, subgroup variables can be managed in Subgroup Settings > CI/CD > Variables > Add variable

Project level configuration

Pipeline variables added at the project level can be used by any user who has write access in the project. To access and configure the project variables, the user must be an owner/maintainer of that project.

From the project's settings, project variables can be managed in Project Settings > CI/C > Variables > Add variable.

Configure GitLab Personal Access Token

A GitLab Personal Access Token is required to enable the workflow to add Merge Request comments and raise Auto Fix Merge Requests. For details on the supported types of GitLab tokens see Configure GitLab User Token.

GitLab OAuth 2.0 authorization

When first accessing Black Duck Security Bulk Onboarding, a prompt will be displayed to authorize the following permissions:

• Read your personal information
• Access the API on your behalf

Click Authorize Black Duck Security to proceed.

s

Onboarding process

Take a moment to review the dashboard components:

• Select projects: Select the projects within a group or personal account where configured scans will be deployed to.
• Configure options: Configure scan options for specific Black Duck platforms such as Black Duck® SCA, Coverity and Polaris.
• Review product-ci.yml: Review a preview of the generated GitLab workflow that will be deployed to the selected projects for performing a Black Duck security scan.
  Note: When a product-ci.yml already exists in a project, it will replace the existing content. However, if a .gitlab-ci.yml exists, then the generated configuration will be merged into the existing yml file using an include reference of the product-ci.yml. If a .gitlab-ci.yml does not exist, a new .gitlab-ci.yml will be created along with the product-ci.yml file and submitted as a Merge Request.
• Summary: Summarizes the count of projects where the workflow will be deployed to. At this stage the workflow can be submitted for deployment.

Configure scan workflow

The Dashboard UI can be used to configure which projects within a group or personal account a workflow will be deployed to. A workflow can be configured for the following Black Duck platforms:

• Black Duck® SCA
• Coverity
• Polaris

Step 1: Select projects

Use the Select Projects screen to configure which projects within the group or personal account should be scanned.

1. Use the Group or Personal account drop down list to select the group or personal account.
   Note: The onboarding solution automatically discovers and displays projects based on the selected group or personal account.
2. Select the projects that the generated workflow should be configured and deployed to:
   Note: When a product-ci.yml already exists in a project, it will replace the existing content. However, if a .gitlab-ci.yml exists, then the generated configuration will be merged into the existing yml file using an include reference of the product-ci.yml. If a .gitlab-ci.yml does not exist, a new .gitlab-ci.yml will be created along with the product-ci.yml file and submitted as a Merge Request.
   1. All Projects: Configure and deploy the workflow to all projects within the group or personal account.
   2. Selected projects: Select the projects from a list. Use the following filter operations for assistance with project selection:
      • Search: Filter by repository name (at least 3 character should be specified).

Step 2: Configure scan options

The Dashboard can be used to automatically generate a GitLab workflow file based on scan options specified in the Configure Options screen. The generated GitLab workflow will be deployed to the selected repositories.

The screen illustrated above highlights that the following options can be configured:

• Branches: Scans can be configured to trigger in response to push events and when a Merge Request is created or updated. Use the push events and merge request text boxes to specify which branches will initiate scans for each type of event.
• Runner tag: Choose the environment for the GitLab runner. To generate runner OS specific scripts, select Mac/Linux or Windows from the Runner Configuration option. By default, a Mac/Linux (Bash) script will be generated. Runner tags are comma-separated, for example: docker,linux,group1-runner.
  Note: Please select only one type of runner tags (either Mac/Linux or Windows) for the selected projects. If you mix runner types, the workflow may fail because the scripts use different shells (bash vs. PowerShell).
• Platform: Select the Black Duck platform for scanning in the project. Supported platforms include Coverity, Black Duck® SCA and Polaris. Upon selection, the Dashboard UI will dynamically update to display platform scan-specific options and instructions, such as which GitLab CI/CD variables are required for the generated workflow to run successfully.
• Scan method: Choose between:
  • GitLab Template (recommended): Generate a scan workflow that uses Black Duck Security Scan Template.
  • CLI - Black Duck Bridge CLI: Generate a scan workflow that downloads the latest Bridge CLI and uses it directly to perform a security scan.
  Note: Ensure all required GitLab CI/CD variables are configured before clicking Next to proceed with generating a scan workflow for review and deployment.

Refer to the Black Duck platform documentation pages for further details of scan configuration options and prerequisites:

• Black Duck® SCA
• Coverity
• Polaris

Review workflow

The Review product-ci.yml screen allows a generated workflow to be previewed and edited before submission for deployment.

The Review blackducksca-ci.yml screen is illustrated below with an example generated workflow for Black Duck® SCA. Refer to the following documentation pages for sample workflow jobs generated for each Black Duck platform:

• Black Duck® SCA
• Coverity
• Polaris

The remainder of this section explains the workflow review process.

The Review blackducksca-ci.yml screen displays a GitLab workflow containing a single scan job, specifically added for selected Black Duck platforms.

The workflow is automatically generated for deployment to the selected projects and simplified to include only the minimum fields required (e.g., default values for the product scans are omitted unless specified). When a blackducksca-ci.yml already exists in a project, it will replace the existing content. However, if a .gitlab-ci.yml exists, then the generated configuration will be merged into the existing yml file using include reference of the blackducksca-ci.yml and if .gitlab-ci.yml does not exist, a new .gitlab-ci.yml will be created along with the blackducksca-ci.yml file and submitted as merge request.

Inline editing of the workflow is available by clicking the Edit button. The editor automatically validates the syntax, preventing saves if errors are detected. It also issues warnings for potential issues, such as hardcoded secrets or variables, which do not block saving.

1. Review and adjust the generated workflow as needed: Use the Edit button to make direct edits to the workflow.yml file, such as:
   • Modify trigger conditions, including which branches will trigger a scan.
   • Adjust scan configuration parameters.
   • Required credentials and tokens.
   • Add custom steps or integrations.
2. When required changes have been made, then perform one of the following options:
   1. Click the Previous button to configure scan options for a different Black Duck platform. Subsequently, when the Review blackducksca-ci.yml screen is revisited a scan job will be created or merged with the workflow for that platform. When a blackducksca-ci.yml already exists in a project, it will replace the existing content. However, if a .gitlab-ci.yml exists, then the generated configuration will be merged into the existing yml file using include reference of the blackducksca-ci.yml and if .gitlab-ci.yml does not exist, a new .gitlab-ci.yml will be created along with the blackducksca-ci.yml file and submitted as Merge Request.
      Note: After editing the workflow, if the Previous button is selected, the UI will warn that the edits you made will be lost permanently.
   2. Click the Next button to confirm that the workflow has been reviewed and all necessary amendments have been made.

Deploy workflow

The Summary screen displays the count of projects where the blackducksca-ci.yml will be deployed by raising a Merge Request.

Automatic Merge Request creation

Currently GitLab onboarding process is available through creating Merge Requests only. While creating Merge Requests, below approach is followed:

1. product-ci.yml
   • Already exists: The existing product-ci.yml will be replaced with the newly generated content.
   • Does not exist: A new product-ci.yml will be created.
2. .gitlab-ci.yml
   • Already exists: The pipeline setup will be merged into the existing file by adding:
     • an include reference that points to the generated product-ci.yml
     • a stage name blackduck_security in stages section to queue up the job specified in product-ci.yml
   • Does not exist: A new .gitlab-ci.yml file will be created and both files will then be submitted together as a merge request.
     Note: If the product-ci.yml is already referenced inside .gitlab-ci.yml, then there will be no modification in .gitlab-ci.yml file content and only product-ci.yml will be submitted as a merge request.

Troubleshooting and support