Versions Compared

Old Version 66

changes.mady.by.user Michelle Friedman

Saved on

compared with

New Version 67

changes.mady.by.user Michelle Friedman

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents

Overview

Before beginning the installation process, ensure that the guidelines described in Installation Prerequisites have been fulfilled.

NOTE: Follow all procedures in order as they are presented here.

Installing the GitLab Integration

Configure a System Hook

  1. Go to your GitLab instance and click Admin Area > System Hooks.

  2. Fill in the fields according to these guidelines:

    • URL: The WhiteSource Mend webhook handler URL. The URL should end with '/payload'. Enter the webhook URL in the following format: http://<docker-wss-gls-app-destinationURL>:5678/payload.

    • Secret Token: Secret token for payload validation

    • Trigger: All checkboxes except Tag push events must be marked

    • Enable SSL Verification: Yes

  3. Click Add system hook. Your system hook will appear in the System Hooks section at the bottom of the screen.

Creating a New GitLab User and a Personal Access Token

  1. Create a new and regular GitLab user and name it @whitesource. This user does not need to be an admin.
    NOTE: This user does not require a real email address. The Personal Access Token for the next step can be created by an admin impersonating the @whitesource user.

  2. Create a Personal Access Token for your new @whitesource user. Go to the @whitesource Settings > Access Tokens, and fill in the fields according to these guidelines:

    • Name: The name of your token, e.g. "WhiteSourceTokenMendToken"

    • Expires at (optional): The expiration date for your token

    • Scopes: All checkboxes should be marked.

  3. Click Create personal access token. Copy the generated Personal Access Token to the clipboard, to be used in the next section.

Creating an Activation Key

  1. Open a separate browser tab or window and log in to WhiteSourceMend.

  2. Navigate to the Integrate page of the WhiteSource Mend application. Expand the WhiteSource Mend for GitLab Server bar to view the following fields:

    • GitLab Server API URL: Your GitLab Server instance's API URL. For example: https://GitLabDevServer.com/api/v4

    • GitLab Webhook URL: The URL of the WhiteSource Mend webhook handler (the same URL as the system hook from Configure a System Hook).
      The webhook URL is used to create webhooks from GitLab projects the integration is installed for, to allow WhiteSource Mend Remediate to receive issue related events.
      NOTE: If this webhook URL is on a local server, make sure your GitLab server is configured to allow outbound requests to local servers in Admin Area > Settings > Network > Outbound Requests. Here you can allow outbound requests to your entire local network or simply whitelist the WhiteSource Mend webhook URL.

    • GitLab Webhook Secret: The webhook secret you entered when creating the system hook in Configure a System Hook.

    • GitLab Personal Access Token: The @whitesource user's personal access token created in the previous step.

  3. Click Get Activation Key to generate your activation key. A new Service user is created for this integration inside the WhiteSource Mend Application with a WS prefix.  NOTE: Do not remove this Service user and ensure this user remains part of the Admin group. 

  4. Copy the newly generated Activation Key (You will need it in the next procedure).

  5. If you want WhiteSource Mend Remediate to only open automatic fix MRs in specific scenarios, clicking Manage Workflow Ruleswill allow you to configure custom rules for when Remediate opens MRs.

Running the UI Configuration Tool

The UI Configuration tool enables you to configure the deployment file according to your specific configuration requirements. 

  1. Open index.html located inside the wss-configuration directory via a Chrome or Firefox Web browser. The WhiteSource Mend Configuration Editor page is displayed.

  2. Load the template JSON configuration file by clicking Choose File and selecting the file located at wss-configuration/config/prop.json. The General tab appears in the Editor.

  3. Click the General tab and enter the Activation Key which you copied in the previous section.

  4. To manage the creation of GitLab Issues or Commit Statuses globally across all of your organization's repositories, click the Issues tab. (The parameters in this tab are displayed in the table below.)

  5. To display the Proxy tab, click the Advanced Properties checkbox on the Home tab. Proxy fields that are not mandatory (e.g., user name and password) must be left blank. (The parameters in this tab are displayed in the table below.)

  6. Click Export, and save the JSON file with the name prop.json. This file will be used in the next sections.

Info

You can export the JSON file at any time, even if you did not finish editing it in order to save your configurations and to enable assigning the configuration of a specific section to the appropriate professional in your organization (e.g., data source section may be assigned to the DBA of your organization).
When exporting the configuration file, it is important to give it the filename “prop.json”

Details on Attributes of the Configuration File

Section

Label

Name

Type

Mandatory

Description

Sample Value

General

Activation Key

bolt.op.activation.key

String

yes

Your generated activation key in the WhiteSource Mend application


Proxy

HTTP Proxy Host

proxy.host

Host Address

no

HTTP proxy host. Leave blank to disable. Default value: Empty


Proxy

HTTP Proxy Port

proxy.port

Integer

no

HTTP proxy port. Leave blank to disable. Default value: Empty


Proxy

Proxy User

proxy.user

String

no

Proxy Username (if applicable)

user

Proxy

Proxy Password

proxy.password

String

no

Proxy Password (if applicable)

abc123

Advanced

Controller URL

controller.url

String

no

The ability to modify the App container URL in case its default name (wss-ghe-app) was modified. Default value: http://wss-ghe-app:5678

http://wss-ghe-app:5678

Issues

Should Create Issues

bolt4scm.create.issues

Boolean

no

The ability to globally enable/disable Issues creation across all of your organization's repositories.

Default value: true

(NOTE: Supported from version 20.5.1.3 only)


Issues

Should Update Commit Status

bolt4scm.create.check.runs

Boolean

no

The ability to globally enable/disable commit statuses across all of your organization's repositories.

Default value: true

(NOTE: Supported from version 20.5.1.3 only)


Uploading

...

Mend Scan Results to the GitLab Security Dashboard (ForGitLab UltimateUsers Only)

In order to upload the WhiteSource Mend scan results to the GitLab security dashboard, add the following YAML to your .gitlab-ci.yml file:

  1. Code Block
    whitesource-security-publisher:
  image: openjdk:8-jdk
  when: manual
  script: 
    - curl "{{WEBHOOK_URL}}/securityReport?repoId=$CI_PROJECT_ID&repoName=$CI_PROJECT_NAME&ownerName=$CI_PROJECT_NAMESPACE&branchName=$CI_COMMIT_REF_NAME&defaultBranchName=$CI_DEFAULT_BRANCH&commitId=$CI_COMMIT_SHA" -o gl-dependency-scanning-report-ws.json
  artifacts: 
    paths:
      - gl-dependency-scanning-report-ws.json
    reports:  
      dependency_scanning:
        - gl-dependency-scanning-report-ws.json
    expire_in: 30 days

  2. Replace {{WEBHOOK_URL}} with the GitLab Webhook URL from Creating an Activation Key (remove the “payload” part from the URL).
    NOTE: The CI job’s name must be whitesource-security-publisher in order for WhiteSource Mend to recognize and trigger it.

Running the Containers

Deploying Using Docker

Create a network bridge (this will create a private network between the different containers since all containers need to run within the same network):

...

Code Block
docker run --name remediate-server --restart=always --network my_bridge -e LOG_LEVEL=debug -p 8080:8080 -v <path/to/config/directory>/prop.json:/etc/usr/local/whitesource/conf/prop.json -v /tmp:/tmp wss-remediate:<version>

# For example:
docker run --name remediate-server --restart=always --network my_bridge -e LOG_LEVEL=debug -p 8080:8080 -v c:/tmp/gls/prop.json:/etc/usr/local/whitesource/conf/prop.json -v /tmp:/tmp wss-remediate:19.8.1


# NOTE: If port 8080 isn't available, you can use a different port by modifying the first port entry in the 'docker run' command. For example:
# docker run --name remediate-server --network my_bridge -e LOG_LEVEL=debug -p 8082:8080 -v c:/tmp/gls/prop.json:/etc/usr/local/whitesource/conf/prop.json -v /tmp:/tmp wss-remediate:19.8.1

Deploying Using Helm Charts

The wss-deployment folder consists of the following structure:

  • helm

    • configs

    • templates

      • config.yaml

      • wssScmIntegration.yaml

    • Chart.yaml

    • values.yaml

Chart.yaml

This file contains information about the chart.

NOTE: Do not edit this file.

Values.yaml

This file represents the WhiteSource Mend integration image names and versions.

...

An optional parameter, imagePullSecrets, can be added to this file in case Docker repository authentication is required.

configs/prop.json

Copy the helm folder from wss-deployment to your target environment. Inside the helm/configs folder, add the configuration properties JSON file (prop.json) that you previously edited and exported using the Configuration Editor.

templates/config.yaml

This is a configuration file pointing to the configs/prop.json file.

NOTE: Do not edit this file.

templates/wssScmIntegration.yaml

This is a configuration file containing all the parameters for deploying the integration.

...

Code Block
apiVersion: v1
kind: Service
metadata:
  name: lb1
  namespace: acme
  annotations:
    external-dns.alpha.kubernetes.io/hostname: helm.acme.io
    service.beta.kubernetes.io/aws-load-balancer-backend-protocol: http
    service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443"
    service.beta.kubernetes.io/aws-load-balancer-ssl-negotiation-policy: "ELBSecurityPolicy-TLS-1-2-2017-01"
    service.beta.kubernetes.io/aws-load-balancer-ssl-cert: arn:aws:acm:us-east-7:834027593108:certificate/4720e07a-a231-4fd5-9c4a-12ab1450567d
spec:
  type: LoadBalancer
  ports:
  - port: 443
    name: https
    targetPort: 5678
  selector:
    app: wss-controller

Selecting Repositories to Scan

  1. If you are integrating multiple repositories and want to apply global configurations, refer here before continuing in this procedure.

  2. Add the @whitesource user (the user you created during Creating a New GitLab User and a Personal Access Token) as a member with Maintainer permissions to the repositories you want WhiteSource Mend to scan. This is how WhiteSource Mend will determine which repositories will be scanned.

    If you would like WhiteSource Mend for GitLab to scan an entire GitLab group, add the @whitesource user to the group to enable WhiteSource Mend for GitLab for all of the projects within that group.
    NOTE: Adding the @whitesource user to a repository with any permissions less than Maintainer may create side-effects in the integration's functionality.

  3. Unless specified otherwise via the global configuration, an onboarding merge request is created for each repository to which the @whitesource user was added. This request contains a WhiteSource configuration Mend configuration file (.whitesource) that can be customized before merging the request. The initial PR must be merged to the base branch first. This will then initiate the installation and start the first scan. You can then define further settings (like selected branches) in the .whitesource file.

  4. In order to disable scanning for a repository, remove the @whitesource user from the repository members.

Accessing Scan Statistics via API

See here for more information.

Health Check APIs

See here for more information.

The .whitesourceFile

A WhiteSource Mend configuration file (.whitesource) is a JSON file added to each repository enabled for scanning. It provides configurable parameters for the WhiteSource Mend scan. The .whitesource file is only added in the default branch of the repository (unless modified, it is the master branch).

Code Block
{
  "scanSettings": {
    "configMode": "AUTO",
    "configExternalURL": "",
    "projectToken" : "",
    "baseBranches": []
  },
  "commitStatusSettings": {
    "displayMode": "diff",
    "vulnerableCommitStatus": "FAILED"
  },
  "issueSettings": {
    "minSeverityLevel": "LOW",
    "openConfidentialIssues": true
  }
}

Parameters

Global Settings

Parameter 

Type

Description

Required 

Default

settingsInheritedFrom

String

When the global configuration is enabled, this parameter will specify the location of the whitesource-config repository from which it will inherit its configuration. It must contain the GitLab user name, repository name and branch (optional) of the repo-config.json file location. The default branch is 'master', but can be modified according to the location of the repo-config.json file in the whitesource-config repo. 

NOTE: You can override specific parameters that are relevant only in the specific repository by adding these after this parameter. Parameters with type of array do not override the value from global configuration, but only add new values.

Examples:

Using only values defined in the global configuration:

Code Block
"settingsInheritedFrom": "whitesource-config/whitesource-config@master"

Using values defined in the global configuration and overriding the scan settings parameters:

Code Block
"settingsInheritedFrom": "whitesource-config/whitesource-config@master", 
"scanSettings": {
  "projectToken": "12345",
  "baseBranches": ["master","integration"]
}

No

N/A

overrideConfigAllowList

Array

When the global configuration is enabled, this parameter will regulate the ability of repositories that inherit their configuration from the whitesource-config repository to override the parameters locally. There are three options:

  • null ("overrideConfigAllowList": null) - All repositories that inherit configuration from this .whitesource file can override them locally.

  • Empty array ("overrideConfigAllowList": []) - All repositories that inherit configuration from this .whitesource file cannot override them locally.

  • Array with values ("overrideConfigAllowList": ["orgName1/repoName1", "orgName2/repoName2"]) - Only specified in the array repositories that inherit configuration from this .whitesource file can override them locally.

NOTE: This parameter must be used in the repo-config.json file of the whitesource-config repository.

No

null

Scan Settings (scanSettings)

Parameter 

Type

Description

Required 

Default

configMode

String

The configuration mode to be used for each scan. There are three options:

  • AUTO - Automatic mode. This will use the default WhiteSource Mend configuration. 

  • LOCAL - Local mode. This will look for a local 'whitesource.config' file to be provided in the root folder of the current repository. The configuration file should be in the same format as the Unified Agent configuration file. NOTE: Not supported in the Global Configuration.

  • EXTERNAL - External mode. This will look for a configuration file specified according to the configExternalURL parameter. 

No

Auto

configExternalURL

String

The URL of the external configuration file (you can choose any filename). The configuration file content should be in the same format as the Unified Agent configuration file.

The following protocols are supported: 'ftp://', 'http://', 'https://'.

For example: 'https://mydomain.com/whitesource-settings/wss-unified-agent.config'

NOTE: This parameter is relevant only if configMode was set to EXTERNAL.

No

Empty

projectToken

String

Adds the ability to map a GitLab repository to a WhiteSource Mend project. The parameter used needs to be the WhiteSource Mend project token.

NOTE: Not supported in the Global Configuration.

No

Empty

baseBranches

Array

Adds the ability to specify one or more base branches for which scanning results will be sent to a new WhiteSource Mend project.

Example usage: ["master", “integration"]

This will set both master and integration branches as base branches.

Note the following:

  • An Issue will only be created for the specified branch names.

  • For each specified branch, a WhiteSource Mend project will be created. The name of the project will contain a suffix "_branchname". For example, MyApp_dev. This suffix will not apply to the default branch.

NOTE: This parameter is available only from version 20.7.1.

No

Empty 

In this case, the base branch only consists of the default branch.

enableLicenseViolations

Boolean

When enabled, a new WhiteSource Mend License Check will be generated for each valid push.

NOTES:

  • The license check is dependent on the vulnerabilities check and will not be triggered if

    vulnerableCommitStatus is set to none.

  • This parameter is available only from version 20.11.2.

  • You must have it least one policy of match type By License Group defined with a Reject action in the WhiteSource Mend UI.

  • The policy name in the WhiteSource Mend UI must start with a “[License] “ prefix.
    For example, "[License] PolicyName".

No

false

Commit Status Settings (commitStatusSettings)

Parameter 

Type

Description

Required 

Default

displayMode

String

How to display WhiteSource Mend security information for a scan performed on a non-base branch:

  • When set to diff - Only the diff of detected vulnerabilities between the current commit and its base branch commit will be displayed. NOTE: This value is only supported when using the baseBranches configuration.

  • When set to baseline - A summary of all detected vulnerabilities in the full repository inventory will be displayed.

No

diff

vulnerableCommitStatus

String

Customizable commit status settings.

  • FAILED - If the WhiteSource Mend scan detects vulnerabilities in a repository, the commit status will show a "failure" indicating that vulnerabilities were detected.
    If no vulnerabilities were detected, the commit status shows a "success" indicator. (default option)

  • SUCCESS - The commit status will show a success indicator at the end of the scan regardless of whether the scan detected vulnerabilities in the repository.

  • NONE - The commit status will not be updated by WhiteSource Mend under any circumstances, not even to a "running" indicator while the scan is in progress.

No

FAILED

licenseCommitStatus

String

Customizable commit status settings.

NOTE: The license check is dependent on the vulnerabilities check and will not be triggered if vulnerableCommitStatus is set to none.

  • FAILED - If the WhiteSource Mend scan detects license policy violations in a repository, the commit status will show a "failure" indicating that license policy violations were detected.
    If no license policy violations were detected, the commit status shows a "success" indicator. (default option)

  • SUCCESS - The commit status will show a success indicator at the end of the scan regardless of whether the scan detected license policy violations in the repository.

  • NONE - The commit status will not be updated by WhiteSource Mend under any circumstances, not even to a "running" indicator while the scan is in progress.

No

FAILED

iacCommitStatus

String

Customizable commit status settings.

  • FAILED - If the WhiteSource Mend scan detects iac vulnerabilities in a repository, the commit status will show a "failure" indicating that iac vulnerabilities were detected.
    If no iac vulnerabilities were detected, the commit status shows a "success" indicator. (default option)

  • SUCCESS - The commit status will show a success indicator at the end of the scan regardless of whether the scan detected vulnerabilities in the repository.

  • NONE - The commit status will not be updated by WhiteSource Mend under any circumstances, not even to a "running" indicator while the scan is in progress.

No

FAILED

showWsInfo

Boolean

Whether to show additional WhiteSource Mend information such as the project token inside the WhiteSource Mend Commit Status (after the scan token).

WhiteSource Mend information is only displayed if the commit originated from a base branch.
If the commit exists in multiple branches, the WhiteSource Mend information displayed will only represent the origin base branch (i.e. where the baseBranches parameter was defined).

The following hidden JSON object will also be added inside the Commit Status when this parameter is enabled:

Code Block
<!-- <INFO>{"projectToken":"1cd2d2a8651145c087609e0a43f783e95f7008cb908541498348fed529572e01"}</INFO> -->

NOTE: Additional WhiteSource Mend data may be added inside the JSON object in the future.

No

false

Issue Settings (issueSettings)

Parameter 

Type

Description

Required 

Default

minSeverityLevel

String

Enables users to decide whether to open a new Issue only if a certain severity level is available on a detected vulnerability.

Available values for minSeverityLevel:

  • NONE - No Issues will be generated.

  • LOW - Any Low/Medium/High vulnerabilities found will generate an Issue.

  • MEDIUM - Any Medium/High vulnerabilities found will generate an Issue.

  • HIGH - Any High vulnerabilities found will generate an Issue.

NOTE: The WhiteSource The Mend Security Check summary is also affected by this parameter.

No

LOW

openConfidentialIssues

Boolean

Whether the GitLab issues opened by WhiteSource Mend will be confidential issues.

No

false

displayLicenseViolations

Boolean

Whether to generate an Issue for every detected license policy violation.

NOTE: This parameter is relevant only if enableLicenseViolations (scanSettings) is set to true.

No

true

(only if enableLicenseViolations (scanSettings) is set to true)

issueType

String

Defines the type of issue that will be created in the repository: VULNERABILITY (one for each vulnerability) or DEPENDENCY (one for each direct dependency).

No

DEPENDENCY

customLabels

Array

Setting that will define labels that will be added to the issues created after the scan.

Usage example:

Code Block
{
  "issueSettings": {
    "customLabels": ["label1","label2"]
  }
}

Following labels are not available for the use:

  • security vulnerability

  • license policy violation

  • IaC violation

  • configuration error

  • maintenance notice

No

Empty

Remediate Settings (remediateSettings)

Parameter 

Type

Description

Required 

Default

enableRenovate

Boolean

When enabled, Remediate will raise automated Merge Requests for outdated dependencies in addition to Merge Requests remediating vulnerable dependencies. Remediate will then perform all the functionality and support all the configuration options available in WhiteSource Mend Renovate.

See Renovate configuration options for all configuration options.

Refer here for parameter usage.

No

false

transitiveRemediation

Boolean

Whether to enable transitive remediation for NPM repos.

When npm v6 (npm v7 is not currently supported) is used with a package-lock.json file, and vulnerabilities are found within transitive dependencies in the file, then in most cases Remediate is able to successfully remediate the vulnerability. Sometimes it may not be possible to successfully remediate because a parent dependency does not yet have a new release that allows the necessary fixed-in version of the transitive dependency.

No

false

workflowRules

Object

This parameter is used to specify the rules that regulate when to open remediation pull requests.

Usage examples:

Code Block
   "remediateSettings": {
    "workflowRules": {
      "enabled": true,
      "minVulnerabilitySeverity": "LOW"
    }
  }
   "remediateSettings": {
    "workflowRules": {
      "enabled": true,
        "minVulnerabilityScore": 1.5,
        "maxVulnerabilityScore": 10
    }
  }

Yes

Code Block
    "workflowRules": {       
      "enabled": true    
    }

workflowRules.enabled

Boolean

Enables Workflow Rules being set from a .whitesource file.

Note: workflow rules can also be set in the WhiteSource Mend application in the Admin → Integration Workflow Rules. But if this parameter is set to true then Workflow Rules from the application are not being used.

Yes

true

workflowRules.minVulnerabilitySeverity

String

The minimal vulnerability severity level to automatically create remediation pull requests for. Allowed values - "LOW", "MEDIUM", "HIGH".

E.g. if set to "MEDIUM" then remediation pull requests of vulnerabilities with low severity will not be created - only for those with medium and high severity.

Note: if this parameter is used together with minVulnerabilityScore and maxVulnerabilityScore than only minVulnerabilitySeverity will have affect.

No

LOW

workflowRules.minVulnerabilityScore

Float

The minimal vulnerability CVSS 3 score to automatically create remediation pull requests for. Allowed values - floats with one decimal from 0 to 10.

For more information on CVSS 3 Scores, click here.

Note: if this parameter is used together with minVulnerabilitySeverity it will not have any effect.

No

0

workflowRules.maxVulnerabilityScore

Float

The maximal vulnerability CVSS 3 score to automatically create remediation pull requests for. Allowed values - floats with one decimal from 0 to 10.

For more information on CVSS 3 Scores, click here.

Note: if this parameter is used together with minVulnerabilitySeverity it will not have any effect.

No

10

Private Registry Settings (hostRules)

Parameter 

Type

Description

Required 

Default

matchHost

String

Defines where the credentials will be applied during the scan.

If you want to apply credentials only for a nested path within a host, then write matchHost as a base URL.
For example: https://registry.company.com/nested/path/.

If the same credentials apply to all paths on a host and not on any subdomains, configure matchHost with a protocol like https://registry.company.com.

Finally, to apply credentials to all hosts within the domain, use a matchHost value with no https:// prefix, e.g. company.com or registry.company.com, both of which would apply to a host like beta.registry.company.com.

No

Empty

hostType

String

Type of private registry. Supported values: npm (for both NPM and Yarn projects), maven, gradle, pypi, go , nuget, ruby.

Required if matchHost is used.

No

Empty

username

String

Used when credentials consist of username and password.

No

Empty

password

String

Used when credentials consist of username and password, should be encrypted by this instruction.

Encrypted secret that will be applied as a credential to the host set in the matchHost parameter. Must be included inside the encrypted parameter:

Code Block
      "encrypted": {
        "password": "3f832f2983yf89hsd98ahadsjfasdfjaslf............"
      }

No

Empty

token

String

Used when credentials consist of username and password, should be encrypted by this instruction.

Encrypted secret that will be applied as a credential to the host set in the matchHost parameter. Must be included inside the encrypted parameter:

Code Block
      "encrypted": {
        "token": "3f832f2983yf89hsd98ahadsjfasdfjaslf............"
      }

No

Empty

Providing a Global Configuration File

NOTE: Supported from version 20.5.1.3 only.

...

  1. Stop the wss-gls-app container.

  2. In the "wss-gls-app/conf" folder, add your custom “.whitesource” file (where the prop.json file is located).

  3. Start the wss-gls-app container.

Configuration Error Issues

Will alert the user on configuration errors that affects their scan by creating a configuration error issue and commit status. In case of such an error the following will occur:

  1. Stop the workflow. Do not create a scan or the WhiteSource Mend Security commit status.

  2. Create a “Configuration Failed” commit status.

  3. For each config file that failed parsing - create a new type of issue, titled Action Required: Fix WhiteSource Mend Configuration File - {fileName}. If the error originated from the repo-config.json or global-config.json files, then the issue will be created in the whitesource-config repo.

...

  • Error parsing the configuration files (.whitesource/repo-config.json/global-config.json json)

  • Missing repository and/or branch in the inheritance configuration

Handling Private Registries and Authenticated Repositories

Info

Private registries hosted on any platform that can be accessed with credentials are supported (Nexus, Artifactory, JFrog, etc.)

...

In order to scan dependencies from private registries and authenticated repositories, WhiteSource Mend must be provided with credentials, such as an NPM token. These credentials must be added as encrypted secrets to the .whitesource file, either per-repository or in the shared global config, if the secret scope is org-wide.

...

  1. Use GPG to generate a PGP Key. Use the command gpg --full-generate-key and follow the prompts to generate a key. Please note that at this time we do not support using a passphrase for decryption, so it is best to generate the keys without a passphrase. Name and email are not important.

    1. Copy the key ID from the output or run gpg --list-secret-keys if you forgot to take a copy. This is your public key.

    2. Run gpg --armor --export-secret-keys YOUR_NEW_KEY_ID > ws-private-key.asc to generate an armored (text-based) private key file

    3. Run gpg --armor --export YOUR_NEW_KEY_ID > ws-public-key.asc to generate an armored (text-based) public key file

  2. Provide the private key to the Controller, Remediate, and Scanner with environmental variable (learn more about environmental variables in the Advanced Technical Information documentation). There are two options for how to do it, but only one option should be used.

    1. WS_HOST_RULES_PRIVATE_KEY - the value of the private key itself.

    2. WS_HOST_RULES_PRIVATE_KEY_FILE_PATH - path to the file containing the private key. This file should be mapped to the running containers.

  3. Open index-enterprise.html in your favorite editor.

  4. Find and replace the text "COPY_YOUR_PUBLIC_PGP_KEY_HERE" with your newly generated public key and save the file.
    const publicKeyString = `COPY_YOUR_PUBLIC_PGP_KEY_HERE`;

  5. Generate a secret. There are the following fields on the encryption page:

    1. Organization\Group - required, your Gitlab group to which tokens secret be scoped.

    2. Repository - optional, your Gitlab repository to which secret should be scoped.

    3. Raw value - required, confidential values/secrets such as tokens or passwords.

    4. Encrypted value - the result of the encryption to be used in the integration.

  6. After the secret is created, please add it to the hostRules parameter of the .whitesource file.

...