...

Installation and Configuration

In Windows, extract 'agent-4-github-enterprise-<version>.zip’ to an empty directory. In Linux, extract ‘agent-4-github-enterprise<version>.tar.gz’ to an empty directory.  
The extraction creates the following folders:

...

Modifying the Scanner Dockerfile 

See here for more information on which package managers are part of the scanner image as well as how to add additional package managers.

Build and Tag the Docker Images

There are three different ways of building the Docker images.

1. Using an Executable Script File

The suggested way to build all the Docker images is by running the 'build.bat' or 'build.sh' executable script file (Windows/Linux).
Both files are located in the root of the extracted agent-4-github-enterprise-<version>.zip or agent-4-github-enterprise-<version>.tar.gz files.

For Windows:

Run 'build.bat' file which is located in the main folder where you extracted the 'agent-4-github-enterprise' zip file.

In order to ensure that the build succeeded, run 'docker images' command and check if  'wss-ghe-app' and 'wss-scanner' and 'wss-remediate' images were created.

For Linux:

Run 'build.sh' file which is located in the main folder where you extracted the 'agent-4-github-enterprise' tar.gz file.

In order to ensure that the build succeeded, run 'docker images' command and check if  'wss-ghe-app' and 'wss-scanner' and 'wss-remediate' images were created.

2. Manually Build the Images

In case you want to run the steps of the 'build' file manually, you can run the following commands directly: (if you have already run the 'build' file, please skip these steps and continue to 'Target machine: Run the Images' step)

docker build -t wss-ghe-app:<version> wss-ghe-app/docker
docker build -t wss-scanner:<version> wss-scanner/docker
docker build -t wss-remediate:<version> wss-remediate/docker

# For example:
docker build -t wss-ghe-app:19.5.2 wss-ghe-app/docker
docker build -t wss-scanner:19.5.2 wss-scanner/docker
docker build -t wss-remediate:19.5.2 wss-remediate/docker

...

After executing the commands, you should be able to view the images in your registry.

Create a WhiteSource GitHub App

1. Go to your GitHub enterprise instance → Settings → Organization, and select 'GitHub Apps' from the Developer settings
2. Click the New GitHub app button.
   
3. Enter your GitHub Enterprise password.
4. The Register new GitHub App page is displayed. 
   
5. Fill in the fields according to these guidelines:
   1. GitHub App name: “WhiteSource App”. NOTE: name cannot contain underscore.
   2. Description: WhiteSource for GitHub Enterprise
   3. Homepage URL: “https://www.whitesourcesoftware.com”
   4. User authorization callback URL: empty
   5. Setup URL (optional): empty
   6. Webhook URL: A valid URL pattern. This is a temporary value that is changed at a later stage of the installation process.
   7. Webhook secret: Generate and enter a secret value (string) and make sure you copy this value somewhere. You will need it for later. 
   8. Permissions:
             NOTE: Permission fields that are not specified below should be left as is ("No access")
      1. Repository administration: Read-only
      2. Checks: Read & write
      3. Repository contents: Read & write
      4. Deployments: Read-only
      5. Issues: Read & write
      6. Repository metadata: Read-only
      7. Pages: Read & write
      8. Pull requests: Read & write
      9. Repository webhooks: Read-only
      10. Repository projects: Read & write
      11. Security vulnerability alerts: Read-only
      12. Commit statuses: Read & write
      13. Organization members: Read-only
      14. Organization projects: Read & write
      15. Organization hooks: Read-only
   9. Subscribe to events: Select the following events:
      i. Check run
      ii. Check suite
      iii. Issues
      iv. Member
      v. Membership
      vi. Organization
      vii. Pull request
      viii. Push
      ix. Team
      x. Team add
   10. Where can this GitHub App be installed? It is recommended to select 'Any account', so that any GitHub Organization can install this App. Alternatively, you can limit it to your own organization.
6. Click the Create GitHub App button. 
7. (Optional) Edit the GitHub App and upload a logo for your App. 

...

1. Navigate to the 'Integrate' page of the WhiteSource application. Expand the 'WhiteSource for GitHub Enterprise' bar to view the following fields:
   
   1. GitHub URL: Your GitHub Enterprise instance Destination URL. For example: https://GitHubEnterprisedev.com.
   2. GitHub API URL: The GitHub URL value plus '/api/v3' - <GitHub URL>/api/v3
   3. GitHub application id: From the GitHub Enterprise server UI, go to Settings > Organization Settings > WhiteSource > GitHub Apps. Click Edit next to the GHE icon. Scroll to the About section. Copy the GitHub ID value and paste it as the GitHub application id input field value.
      Leave this page open in Edit mode, as you will need it for the next field (Github webhook secret).
   4. Github webhook secret: Paste the webhook secret that you generated as part of the Install the GitHub Application step.
      
   5. GitHub application private key: In the Private key section, click Generate private key. Save the private_key.pem file that is generated. Open this file in any editor and copy its contents. Paste the contents in the GitHub application private key input field. NOTE: The key is encrypted and its value is not revealed to WhiteSource.
2. Click on Get Activation Key to generate your activation key. A new Service user is created for this integration inside the WhiteSource Application with a WS prefix.  NOTE: Do not remove this Service user and ensure this user remains part of the Admin group. 
3. Copy the generated Activation Key to the clipboard. You will need to use it in the next section.

...

1. Open the file index.html located inside the wss-configuration directory via a Chrome or Firefox Web browser. The WhiteSource Configuration Editor page is displayed.
2. Load the template JSON configuration file by clicking Choose File button 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 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.
   
5. Click Export, and save the JSON file with the name prop.json. This file will be used in the next sections.

...

Target Machine: Run the Containers

...

The wss-deployment folder consists of the following structure:

• helm
  • configs
  • templates
    • config.yaml
    • wssScmIntegration.yaml
  • Chart.yaml
  • values.yaml

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.

...

wsscanner:
  image: {image}
  version: {version}

wsscontroller:
  image: {image}
  version: {version}

wssremediate:
  image: {image}
  version: {version}

For each image declaration (wssscanner, wsscontroller, wssremediate), replace {image} and {version} with the actual built image name and version.  NOTE: For wsscontroller, use the name and version of the wss-ghe-app image.

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

configs/prop.json

In the helm folder, create a new folder named configs, and add to it the configuration properties JSON file (prop.json) that you previously edited and exported using the Configuration Editor.

...

NOTE: Do not edit this file.

templates/wssScmIntegration.yaml

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

NOTE: In this file, there are 3 dashes ("- - - ") that separate the services  Do not remove them.

In order for the webhook URL to be accessible publicly by the integration, a load balancer service must be added to the file. An example of such a service is provided below:

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

...

...

<!-- <INFO>{"projectToken":"8cd2d2a8651145c087609e0a43f783e95f7008cb908541498348fed529572e01"}</INFO> -->

Issue Settings (issueSettings)

Remediate Settings (remediateSettings)

Providing a Global .whitesource Configuration File

...

You can provide a custom .whitesource configuration file as part of the wss-ghe-app container, in order to apply it globally to all of your organization's repositories. Doing so will apply the file to all onboarding pull requests for newly-selected repos. Repos which were already selected and activated before this change will not be affected by this global configuration. Only newly onboarded repos will be affected. 

To apply this global change, do as follows:

1. Stop the wss-ghe-app container.
2. In the "wss-ghe-app/conf" folder, add your custom “.whitesource” file (where the prop.json file is located).
3. Start the  wss-ghe-app container.

Initiating a Scan

A WhiteSource scan is initiated via a valid GitHub push command . A valid push command meets at least one of the following requirements:

• One of the commits in the push command added/removed a source file(s) that has an extension supported by WhiteSource.
  Refer to the WhiteSource Languages page in order to find out whether or not a specific language and its extensions are supported. 

• One of the commits in the push command includes an addition/modification of the package manager dependency file(s).
  Refer to the list of supported dependency files to find out whether your dependency files are supported.
  
  

...

The security report displays all the vulnerabilities that were found in descending order according to the severity and CVSS score. The following information is displayed for each vulnerability:

• CVE: A link to the related CVE page for the vulnerability. Displayed in a collapsible format (click the arrow to expand/collapse for more information regarding the vulnerability).
• Severity: Overall score of the severity (High, Medium or Low).
• CVSS Score
• Vulnerable Library
• Suggested Fix 
• Issue - A link to the relevant issue generated by WhiteSource (when available)

Types of Indicators

The following Checks API status indicators are available as a feedback on the head commits:

...

• Success: No license policy violations were detected. 
• Failed: One or more license policy violations were detected during the WhiteSource scan.

Viewing Details in the WhiteSource UI

...

Initiating a Merge Policy

Overview

A merge policy utilizes the app's integration with GitHub Checks API. It enables the repository's administrator to approve the merging of a pull request with 'Failed' commit statuses to a target branch in the repository. 
For more information on Checks API, see the related GitHub Checks API introduction page.

NOTE: This integration supports merge policies for PRs created either from a branch in the same repository or originating from a different repository.

Adding a Branch Protection Rule 

...

1. Get the latest WhiteSource for GitHub Enterprise version from WhiteSource Support.
2. Build these three Docker images from the new version - see here.
   • wss-ghe-app
   • wss-scanner
   • remediate-server

3. Stop currently-running Docker containers from the previous version:

   Code Block
   docker stop <wss-ghe-app> <wss-scanner> <remediate-server>

   
   

4. Remove the Docker containers from the previous version:

   Code Block
   docker rm <wss-ghe-app> <wss-scanner> <remediate-server>

   
   

5. Fetch the activation key from the existing prop.json file (the propertyValue associated to the property "bolt.op.activation.key") and copy it to the clipboard.
6. Generate and save the new prop.json file by following the steps here and using the activation key value that was just copied. 
7. Run the containers - see here.
8. (Optional) If the new wss-ghe-app container has a different URL than the previous container, then follow the guidelines here to update the GitHub App webhook URL.

NOTE: From version 20.4.2. the remediate-db image and container are not required anymore. If you are upgrading from a previous version, you can stop the container and remove the image as part of step 3.

...

1. Go to the 'Applications' section of your GitHub's account settings, and click on the 'Configure' button next to the 'WhiteSource App' application.
2. The 'WhiteSource Bolt for GitHub' page opens. Scroll down in order to view the 'Uninstall WhiteSource App' button. 
3. Click on the 'Uninstall' button. Uninstalling WhiteSource App removes it from all your repositories.
4. Optionally, go to 'Authorized GitHub apps' tab, and click the 'Revoke' button next to the 'WhiteSource App' app.